diff options
Diffstat (limited to 'docs')
50 files changed, 1954 insertions, 5432 deletions
diff --git a/docs/Atomics.rst b/docs/Atomics.rst index 705d73f..1243f34 100644 --- a/docs/Atomics.rst +++ b/docs/Atomics.rst @@ -211,7 +211,7 @@ Notes for code generation never stored. A normal load or store instruction is usually sufficient, but note that an unordered load or store cannot be split into multiple instructions (or an instruction which does multiple memory operations, like - ``LDRD`` on ARM). + ``LDRD`` on ARM without LPAE, or not naturally-aligned ``LDRD`` on LPAE ARM). Monotonic --------- diff --git a/docs/CMake.rst b/docs/CMake.rst index 6eab04b..c9fe538 100644 --- a/docs/CMake.rst +++ b/docs/CMake.rst @@ -87,7 +87,7 @@ names are case-sensitive. Example: .. code-block:: console - $ cmake -G "Visual Studio 9 2008" path/to/llvm/source/root + $ cmake -G "Visual Studio 10" path/to/llvm/source/root For a given development platform there can be more than one adequate generator. If you use Visual Studio "NMake Makefiles" is a generator you can use @@ -168,8 +168,8 @@ LLVM-specific variables **LLVM_TARGETS_TO_BUILD**:STRING Semicolon-separated list of targets to build, or *all* for building all - targets. Case-sensitive. For Visual C++ defaults to *X86*. On the other cases - defaults to *all*. Example: ``-DLLVM_TARGETS_TO_BUILD="X86;PowerPC"``. + targets. Case-sensitive. Defaults to *all*. Example: + ``-DLLVM_TARGETS_TO_BUILD="X86;PowerPC"``. **LLVM_BUILD_TOOLS**:BOOL Build LLVM tools. Defaults to ON. Targets for building each tool are generated @@ -204,7 +204,7 @@ LLVM-specific variables tests. **LLVM_APPEND_VC_REV**:BOOL - Append version control revision info (svn revision number or git revision id) + Append version control revision info (svn revision number or Git revision id) to LLVM version string (stored in the PACKAGE_VERSION macro). For this to work cmake must be invoked before the build. Defaults to OFF. @@ -271,6 +271,15 @@ LLVM-specific variables **LLVM_USE_INTEL_JITEVENTS**:BOOL Enable building support for Intel JIT Events API. Defaults to OFF +**LLVM_ENABLE_ZLIB**:BOOL + Build with zlib to support compression/uncompression in LLVM tools. + Defaults to ON. + +**LLVM_USE_SANITIZER**:STRING + Define the sanitizer used to build LLVM binaries and tests. Possible values + are ``Address``, ``Memory`` and ``MemoryWithOrigins``. Defaults to empty + string. + Executing the test suite ======================== @@ -413,6 +422,5 @@ Microsoft Visual C++ **LLVM_COMPILER_JOBS**:STRING Specifies the maximum number of parallell compiler jobs to use per project - when building with msbuild or Visual Studio. Only supported for Visual Studio - 2008 and Visual Studio 2010 CMake generators. 0 means use all - processors. Default is 0. + when building with msbuild or Visual Studio. Only supported for the Visual + Studio 2010 CMake generator. 0 means use all processors. Default is 0. diff --git a/docs/CodeGenerator.rst b/docs/CodeGenerator.rst index b5d4180..1f2dc6c 100644 --- a/docs/CodeGenerator.rst +++ b/docs/CodeGenerator.rst @@ -1038,6 +1038,24 @@ for your target. It has the following strengths: are used to manipulate the input immediate (in this case, take the high or low 16-bits of the immediate). +* When using the 'Pat' class to map a pattern to an instruction that has one + or more complex operands (like e.g. `X86 addressing mode`_), the pattern may + either specify the operand as a whole using a ``ComplexPattern``, or else it + may specify the components of the complex operand separately. The latter is + done e.g. for pre-increment instructions by the PowerPC back end: + + :: + + def STWU : DForm_1<37, (outs ptr_rc:$ea_res), (ins GPRC:$rS, memri:$dst), + "stwu $rS, $dst", LdStStoreUpd, []>, + RegConstraint<"$dst.reg = $ea_res">, NoEncode<"$ea_res">; + + def : Pat<(pre_store GPRC:$rS, ptr_rc:$ptrreg, iaddroff:$ptroff), + (STWU GPRC:$rS, iaddroff:$ptroff, ptr_rc:$ptrreg)>; + + Here, the pair of ``ptroff`` and ``ptrreg`` operands is matched onto the + complex operand ``dst`` of class ``memri`` in the ``STWU`` instruction. + * 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. @@ -1770,12 +1788,12 @@ Here is the table: :raw-html:`<th>Feature</th>` :raw-html:`<th>ARM</th>` :raw-html:`<th>Hexagon</th>` -:raw-html:`<th>MBlaze</th>` :raw-html:`<th>MSP430</th>` :raw-html:`<th>Mips</th>` :raw-html:`<th>NVPTX</th>` :raw-html:`<th>PowerPC</th>` :raw-html:`<th>Sparc</th>` +:raw-html:`<th>SystemZ</th>` :raw-html:`<th>X86</th>` :raw-html:`<th>XCore</th>` :raw-html:`</tr>` @@ -1784,26 +1802,26 @@ Here is the table: :raw-html:`<td><a href="#feat_reliable">is generally reliable</a></td>` :raw-html:`<td class="yes"></td> <!-- ARM -->` :raw-html:`<td class="yes"></td> <!-- Hexagon -->` -:raw-html:`<td class="no"></td> <!-- MBlaze -->` :raw-html:`<td class="unknown"></td> <!-- MSP430 -->` :raw-html:`<td class="yes"></td> <!-- Mips -->` :raw-html:`<td class="yes"></td> <!-- NVPTX -->` :raw-html:`<td class="yes"></td> <!-- PowerPC -->` :raw-html:`<td class="yes"></td> <!-- Sparc -->` +:raw-html:`<td class="yes"></td> <!-- SystemZ -->` :raw-html:`<td class="yes"></td> <!-- X86 -->` -:raw-html:`<td class="unknown"></td> <!-- XCore -->` +:raw-html:`<td class="yes"></td> <!-- XCore -->` :raw-html:`</tr>` :raw-html:`<tr>` :raw-html:`<td><a href="#feat_asmparser">assembly parser</a></td>` :raw-html:`<td class="no"></td> <!-- ARM -->` :raw-html:`<td class="no"></td> <!-- Hexagon -->` -:raw-html:`<td class="yes"></td> <!-- MBlaze -->` :raw-html:`<td class="no"></td> <!-- MSP430 -->` :raw-html:`<td class="no"></td> <!-- Mips -->` :raw-html:`<td class="no"></td> <!-- NVPTX -->` :raw-html:`<td class="no"></td> <!-- PowerPC -->` :raw-html:`<td class="no"></td> <!-- Sparc -->` +:raw-html:`<td class="yes"></td> <!-- SystemZ -->` :raw-html:`<td class="yes"></td> <!-- X86 -->` :raw-html:`<td class="no"></td> <!-- XCore -->` :raw-html:`</tr>` @@ -1812,54 +1830,54 @@ Here is the table: :raw-html:`<td><a href="#feat_disassembler">disassembler</a></td>` :raw-html:`<td class="yes"></td> <!-- ARM -->` :raw-html:`<td class="no"></td> <!-- Hexagon -->` -:raw-html:`<td class="yes"></td> <!-- MBlaze -->` :raw-html:`<td class="no"></td> <!-- MSP430 -->` :raw-html:`<td class="no"></td> <!-- Mips -->` :raw-html:`<td class="na"></td> <!-- NVPTX -->` :raw-html:`<td class="no"></td> <!-- PowerPC -->` +:raw-html:`<td class="yes"></td> <!-- SystemZ -->` :raw-html:`<td class="no"></td> <!-- Sparc -->` :raw-html:`<td class="yes"></td> <!-- X86 -->` -:raw-html:`<td class="no"></td> <!-- XCore -->` +:raw-html:`<td class="yes"></td> <!-- XCore -->` :raw-html:`</tr>` :raw-html:`<tr>` :raw-html:`<td><a href="#feat_inlineasm">inline asm</a></td>` :raw-html:`<td class="yes"></td> <!-- ARM -->` :raw-html:`<td class="yes"></td> <!-- Hexagon -->` -:raw-html:`<td class="yes"></td> <!-- MBlaze -->` :raw-html:`<td class="unknown"></td> <!-- MSP430 -->` :raw-html:`<td class="no"></td> <!-- Mips -->` :raw-html:`<td class="yes"></td> <!-- NVPTX -->` :raw-html:`<td class="yes"></td> <!-- PowerPC -->` :raw-html:`<td class="unknown"></td> <!-- Sparc -->` +:raw-html:`<td class="yes"></td> <!-- SystemZ -->` :raw-html:`<td class="yes"></td> <!-- X86 -->` -:raw-html:`<td class="unknown"></td> <!-- XCore -->` +:raw-html:`<td class="yes"></td> <!-- XCore -->` :raw-html:`</tr>` :raw-html:`<tr>` :raw-html:`<td><a href="#feat_jit">jit</a></td>` :raw-html:`<td class="partial"><a href="#feat_jit_arm">*</a></td> <!-- ARM -->` :raw-html:`<td class="no"></td> <!-- Hexagon -->` -:raw-html:`<td class="no"></td> <!-- MBlaze -->` :raw-html:`<td class="unknown"></td> <!-- MSP430 -->` :raw-html:`<td class="yes"></td> <!-- Mips -->` :raw-html:`<td class="na"></td> <!-- NVPTX -->` :raw-html:`<td class="yes"></td> <!-- PowerPC -->` :raw-html:`<td class="unknown"></td> <!-- Sparc -->` +:raw-html:`<td class="yes"></td> <!-- SystemZ -->` :raw-html:`<td class="yes"></td> <!-- X86 -->` -:raw-html:`<td class="unknown"></td> <!-- XCore -->` +:raw-html:`<td class="no"></td> <!-- XCore -->` :raw-html:`</tr>` :raw-html:`<tr>` :raw-html:`<td><a href="#feat_objectwrite">.o file writing</a></td>` :raw-html:`<td class="no"></td> <!-- ARM -->` :raw-html:`<td class="no"></td> <!-- Hexagon -->` -:raw-html:`<td class="yes"></td> <!-- MBlaze -->` :raw-html:`<td class="no"></td> <!-- MSP430 -->` :raw-html:`<td class="no"></td> <!-- Mips -->` :raw-html:`<td class="na"></td> <!-- NVPTX -->` :raw-html:`<td class="no"></td> <!-- PowerPC -->` :raw-html:`<td class="no"></td> <!-- Sparc -->` +:raw-html:`<td class="yes"></td> <!-- SystemZ -->` :raw-html:`<td class="yes"></td> <!-- X86 -->` :raw-html:`<td class="no"></td> <!-- XCore -->` :raw-html:`</tr>` @@ -1868,26 +1886,26 @@ Here is the table: :raw-html:`<td><a hr:raw-html:`ef="#feat_tailcall">tail calls</a></td>` :raw-html:`<td class="yes"></td> <!-- ARM -->` :raw-html:`<td class="yes"></td> <!-- Hexagon -->` -:raw-html:`<td class="no"></td> <!-- MBlaze -->` :raw-html:`<td class="unknown"></td> <!-- MSP430 -->` :raw-html:`<td class="no"></td> <!-- Mips -->` :raw-html:`<td class="no"></td> <!-- NVPTX -->` :raw-html:`<td class="yes"></td> <!-- PowerPC -->` :raw-html:`<td class="unknown"></td> <!-- Sparc -->` +:raw-html:`<td class="no"></td> <!-- SystemZ -->` :raw-html:`<td class="yes"></td> <!-- X86 -->` -:raw-html:`<td class="unknown"></td> <!-- XCore -->` +:raw-html:`<td class="no"></td> <!-- XCore -->` :raw-html:`</tr>` :raw-html:`<tr>` :raw-html:`<td><a href="#feat_segstacks">segmented stacks</a></td>` :raw-html:`<td class="no"></td> <!-- ARM -->` :raw-html:`<td class="no"></td> <!-- Hexagon -->` -:raw-html:`<td class="no"></td> <!-- MBlaze -->` :raw-html:`<td class="no"></td> <!-- MSP430 -->` :raw-html:`<td class="no"></td> <!-- Mips -->` :raw-html:`<td class="no"></td> <!-- NVPTX -->` :raw-html:`<td class="no"></td> <!-- PowerPC -->` :raw-html:`<td class="no"></td> <!-- Sparc -->` +:raw-html:`<td class="no"></td> <!-- SystemZ -->` :raw-html:`<td class="partial"><a href="#feat_segstacks_x86">*</a></td> <!-- X86 -->` :raw-html:`<td class="no"></td> <!-- XCore -->` :raw-html:`</tr>` diff --git a/docs/CodingStandards.rst b/docs/CodingStandards.rst index 4d66ad7..9418680 100644 --- a/docs/CodingStandards.rst +++ b/docs/CodingStandards.rst @@ -796,7 +796,9 @@ In general, names should be in camel case (e.g. ``TextFileReader`` and As an exception, classes that mimic STL classes can have member names in STL's style of lower-case words separated by underscores (e.g. ``begin()``, -``push_back()``, and ``empty()``). +``push_back()``, and ``empty()``). Classes that provide multiple +iterators should add a singular prefix to ``begin()`` and ``end()`` +(e.g. ``global_begin()`` and ``use_begin()``). Here are some examples of good and bad names: diff --git a/docs/CommandGuide/FileCheck.rst b/docs/CommandGuide/FileCheck.rst index fce63ba..6be5fc3 100644 --- a/docs/CommandGuide/FileCheck.rst +++ b/docs/CommandGuide/FileCheck.rst @@ -18,7 +18,8 @@ using :program:`grep`, but it is optimized for matching multiple different inputs in one file in a specific order. The ``match-filename`` file specifies the file that contains the patterns to -match. The file to verify is always read from standard input. +match. The file to verify is read from standard input unless the +:option:`--input-file` option is used. OPTIONS ------- @@ -44,7 +45,7 @@ OPTIONS By default, FileCheck canonicalizes input horizontal whitespace (spaces and tabs) which causes it to ignore these differences (a space will match a tab). The :option:`--strict-whitespace` argument disables this behavior. End-of-line - sequences are canonicalized to UNIX-style '\n' in all modes. + sequences are canonicalized to UNIX-style ``\n`` in all modes. .. option:: -version @@ -194,6 +195,106 @@ can be used: ; CHECK: ret i8 } +The "CHECK-DAG:" directive +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If it's necessary to match strings that don't occur in a strictly sequential +order, "``CHECK-DAG:``" could be used to verify them between two matches (or +before the first match, or after the last match). For example, clang emits +vtable globals in reverse order. Using ``CHECK-DAG:``, we can keep the checks +in the natural order: + +.. code-block:: c++ + + // RUN: %clang_cc1 %s -emit-llvm -o - | FileCheck %s + + struct Foo { virtual void method(); }; + Foo f; // emit vtable + // CHECK-DAG: @_ZTV3Foo = + + struct Bar { virtual void method(); }; + Bar b; + // CHECK-DAG: @_ZTV3Bar = + + +With captured variables, ``CHECK-DAG:`` is able to match valid topological +orderings of a DAG with edges from the definition of a variable to its use. +It's useful, e.g., when your test cases need to match different output +sequences from the instruction scheduler. For example, + +.. code-block:: llvm + + ; CHECK-DAG: add [[REG1:r[0-9]+]], r1, r2 + ; CHECK-DAG: add [[REG2:r[0-9]+]], r3, r4 + ; CHECK: mul r5, [[REG1]], [[REG2]] + +In this case, any order of that two ``add`` instructions will be allowed. + +``CHECK-NOT:`` directives could be mixed with ``CHECK-DAG:`` directives to +exclude strings between the surrounding ``CHECK-DAG:`` directives. As a result, +the surrounding ``CHECK-DAG:`` directives cannot be reordered, i.e. all +occurrences matching ``CHECK-DAG:`` before ``CHECK-NOT:`` must not fall behind +occurrences matching ``CHECK-DAG:`` after ``CHECK-NOT:``. For example, + +.. code-block:: llvm + + ; CHECK-DAG: BEFORE + ; CHECK-NOT: NOT + ; CHECK-DAG: AFTER + +This case will reject input strings where ``BEFORE`` occurs after ``AFTER``. + +The "CHECK-LABEL:" directive +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Sometimes in a file containing multiple tests divided into logical blocks, one +or more ``CHECK:`` directives may inadvertently succeed by matching lines in a +later block. While an error will usually eventually be generated, the check +flagged as causing the error may not actually bear any relationship to the +actual source of the problem. + +In order to produce better error messages in these cases, the "``CHECK-LABEL:``" +directive can be used. It is treated identically to a normal ``CHECK`` +directive except that FileCheck makes an additional assumption that a line +matched by the directive cannot also be matched by any other check present in +``match-filename``; this is intended to be used for lines containing labels or +other unique identifiers. Conceptually, the presence of ``CHECK-LABEL`` divides +the input stream into separate blocks, each of which is processed independently, +preventing a ``CHECK:`` directive in one block matching a line in another block. +For example, + +.. code-block:: llvm + + define %struct.C* @C_ctor_base(%struct.C* %this, i32 %x) { + entry: + ; CHECK-LABEL: C_ctor_base: + ; CHECK: mov [[SAVETHIS:r[0-9]+]], r0 + ; CHECK: bl A_ctor_base + ; CHECK: mov r0, [[SAVETHIS]] + %0 = bitcast %struct.C* %this to %struct.A* + %call = tail call %struct.A* @A_ctor_base(%struct.A* %0) + %1 = bitcast %struct.C* %this to %struct.B* + %call2 = tail call %struct.B* @B_ctor_base(%struct.B* %1, i32 %x) + ret %struct.C* %this + } + + define %struct.D* @D_ctor_base(%struct.D* %this, i32 %x) { + entry: + ; CHECK-LABEL: D_ctor_base: + +The use of ``CHECK-LABEL:`` directives in this case ensures that the three +``CHECK:`` directives only accept lines corresponding to the body of the +``@C_ctor_base`` function, even if the patterns match lines found later in +the file. Furthermore, if one of these three ``CHECK:`` directives fail, +FileCheck will recover by continuing to the next block, allowing multiple test +failures to be detected in a single invocation. + +There is no requirement that ``CHECK-LABEL:`` directives contain strings that +correspond to actual syntactic labels in a source or output language: they must +simply uniquely match a single line in the file being verified. + +``CHECK-LABEL:`` directives cannot contain variable definitions or uses. + FileCheck Pattern Matching Syntax ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/CommandGuide/index.rst b/docs/CommandGuide/index.rst index ac8a944..d50542d 100644 --- a/docs/CommandGuide/index.rst +++ b/docs/CommandGuide/index.rst @@ -21,7 +21,6 @@ Basic Commands lli llvm-link llvm-ar - llvm-ranlib llvm-nm llvm-prof llvm-config @@ -50,3 +49,4 @@ Developer Tools tblgen lit llvm-build + llvm-readobj diff --git a/docs/CommandGuide/lit.rst b/docs/CommandGuide/lit.rst index 40c7646..a4681fb 100644 --- a/docs/CommandGuide/lit.rst +++ b/docs/CommandGuide/lit.rst @@ -283,7 +283,7 @@ executed, two important global variables are predefined: discover and run tests in the test suite. Generally this will be a builtin test format available from the *lit.formats* module. - **test_src_root** The filesystem path to the test suite root. For out-of-dir + **test_source_root** The filesystem path to the test suite root. For out-of-dir builds this is the directory that will be scanned for tests. **test_exec_root** For out-of-dir builds, the path to the test suite root inside @@ -316,11 +316,15 @@ executed, two important global variables are predefined: *on_clone* function will generally modify), and (3) the test path to the new directory being scanned. + **pipefail** Normally a test using a shell pipe fails if any of the commands + on the pipe fail. If this is not desired, setting this variable to false + makes the test fail only if the last command in the pipe fails. + TEST DISCOVERY ~~~~~~~~~~~~~~ Once test suites are located, :program:`lit` recursively traverses the source -directory (following *test_src_root*) looking for tests. When :program:`lit` +directory (following *test_source_root*) looking for tests. When :program:`lit` enters a sub-directory, it first checks to see if a nested test suite is defined in that directory. If so, it loads that test suite recursively, otherwise it instantiates a local test config for the directory (see diff --git a/docs/CommandGuide/llc.rst b/docs/CommandGuide/llc.rst index 70354b0..02ad798 100644 --- a/docs/CommandGuide/llc.rst +++ b/docs/CommandGuide/llc.rst @@ -69,6 +69,14 @@ End-user Options llvm-as < /dev/null | llc -march=xyz -mcpu=help +.. option:: -filetype=<output file type> + + Specify what kind of output ``llc`` should generated. Options are: ``asm`` + for textual assembly ( ``'.s'``), ``obj`` for native object files (``'.o'``) + and ``null`` for not emitting anything (for performance testing). + + Note that not all targets support all options. + .. option:: -mattr=a1,+a2,-a3,... Override or control specific attributes of the target, such as whether SIMD @@ -133,24 +141,24 @@ Tuning/Configuration Options .. option:: --regalloc=<allocator> - Specify the register allocator to use. The default ``allocator`` is *local*. + Specify the register allocator to use. Valid register allocators are: - *simple* + *basic* - Very simple "always spill" register allocator + Basic register allocator. - *local* + *fast* - Local register allocator + Fast register allocator. It is the default for unoptimized code. - *linearscan* + *greedy* - Linear scan global register allocator + Greedy register allocator. It is the default for optimized code. - *iterativescan* + *pbqp* - Iterative scan global register allocator + Register allocator based on 'Partitioned Boolean Quadratic Programming'. .. option:: --spiller=<spiller> diff --git a/docs/CommandGuide/lli.rst b/docs/CommandGuide/lli.rst index 7cc1284..a9aaf31 100644 --- a/docs/CommandGuide/lli.rst +++ b/docs/CommandGuide/lli.rst @@ -50,7 +50,7 @@ GENERAL OPTIONS -**-load**\ =\ *puginfilename* +**-load**\ =\ *pluginfilename* Causes **lli** to load the plugin (shared object) named *pluginfilename* and use it for optimization. diff --git a/docs/CommandGuide/llvm-ar.rst b/docs/CommandGuide/llvm-ar.rst index 8ff4192..d3ee993 100644 --- a/docs/CommandGuide/llvm-ar.rst +++ b/docs/CommandGuide/llvm-ar.rst @@ -21,64 +21,24 @@ LLVM program. However, the archive can contain any kind of file. By default, only the symbol table needs to be consulted, not each individual file member of the archive. -The **llvm-ar** command can be used to *read* both SVR4 and BSD style archive -files. However, it cannot be used to write them. While the **llvm-ar** command -produces files that are *almost* identical to the format used by other ``ar`` -implementations, it has two significant departures in order to make the -archive appropriate for LLVM. The first departure is that **llvm-ar** only -uses BSD4.4 style long path names (stored immediately after the header) and -never contains a string table for long names. The second departure is that the -symbol table is formated for efficient construction of an in-memory data -structure that permits rapid (red-black tree) lookups. Consequently, archives -produced with **llvm-ar** usually won't be readable or editable with any -``ar`` implementation or useful for linking. Using the ``f`` modifier to flatten -file names will make the archive readable by other ``ar`` implementations -but not for linking because the symbol table format for LLVM is unique. If an +The **llvm-ar** command can be used to *read* SVR4, GNU and BSD style archive +files. However, right now it can only write in the GNU format. If an SVR4 or BSD style archive is used with the ``r`` (replace) or ``q`` (quick -update) operations, the archive will be reconstructed in LLVM format. This -means that the string table will be dropped (in deference to BSD 4.4 long names) -and an LLVM symbol table will be added (by default). The system symbol table -will be retained. +update) operations, the archive will be reconstructed in GNU format. Here's where **llvm-ar** departs from previous ``ar`` implementations: *Symbol Table* - Since **llvm-ar** is intended to archive bitcode files, the symbol table - won't make much sense to anything but LLVM. Consequently, the symbol table's - format has been simplified. It consists simply of a sequence of pairs - of a file member index number as an LSB 4byte integer and a null-terminated - string. - + Since **llvm-ar** supports bitcode files. The symbol table it creates + is in GNU format and includes both native and bitcode files. *Long Paths* - Some ``ar`` implementations (SVR4) use a separate file member to record long - path names (> 15 characters). **llvm-ar** takes the BSD 4.4 and Mac OS X - approach which is to simply store the full path name immediately preceding - the data for the file. The path name is null terminated and may contain the - slash (/) character. - - - -*Directory Recursion* - - Most ``ar`` implementations do not recurse through directories but simply - ignore directories if they are presented to the program in the *files* - option. **llvm-ar**, however, can recurse through directory structures and - add all the files under a directory, if requested. - - - -*TOC Verbose Output* - - When **llvm-ar** prints out the verbose table of contents (``tv`` option), it - precedes the usual output with a character indicating the basic kind of - content in the file. A blank means the file is a regular file. A 'B' means - the file is an LLVM bitcode file. An 'S' means the file is the symbol table. - + Currently **llvm-ar** can read GNU and BSD long file names, but only writes + archives with the GNU format. @@ -124,20 +84,19 @@ m[abi] -p[k] +p - Print files to the standard output. The *k* modifier applies to this - operation. This operation simply prints the *files* indicated to the - standard output. If no *files* are specified, the entire archive is printed. - Printing bitcode files is ill-advised as they might confuse your terminal - settings. The *p* operation never modifies the archive. + Print files to the standard output. This operation simply prints the + *files* indicated to the standard output. If no *files* are + specified, the entire archive is printed. Printing bitcode files is + ill-advised as they might confuse your terminal settings. The *p* + operation never modifies the archive. -q[Rf] +q - Quickly append files to the end of the archive. The *R*, and *f* - modifiers apply to this operation. This operation quickly adds the + Quickly append files to the end of the archive. This operation quickly adds the *files* to the archive without checking for duplicates that should be removed first. If no *files* are specified, the archive is not modified. Because of the way that **llvm-ar** constructs the archive file, its dubious @@ -145,9 +104,9 @@ q[Rf] -r[Rabfu] +r[abu] - Replace or insert file members. The *R*, *a*, *b*, *f*, and *u* + Replace or insert file members. The *a*, *b*, and *u* modifiers apply to this operation. This operation will replace existing *files* or insert them at the end of the archive if they do not exist. If no *files* are specified, the archive is not modified. @@ -201,37 +160,12 @@ section (above) to determine which modifiers are applicable to which operations. -[f] - - Normally, **llvm-ar** stores the full path name to a file as presented to it on - the command line. With this option, truncated (15 characters max) names are - used. This ensures name compatibility with older versions of ``ar`` but may also - thwart correct extraction of the files (duplicates may overwrite). If used with - the *R* option, the directory recursion will be performed but the file names - will all be flattened to simple file names. - - - [i] A synonym for the *b* option. -[k] - - Normally, **llvm-ar** will not print the contents of bitcode files when the - *p* operation is used. This modifier defeats the default and allows the - bitcode members to be printed. - - - -[N] - - This option is ignored by **llvm-ar** but provided for compatibility. - - - [o] When extracting files, this option will cause **llvm-ar** to preserve the @@ -239,22 +173,6 @@ section (above) to determine which modifiers are applicable to which operations. -[P] - - use full path names when matching - - - -[R] - - This modifier instructions the *r* option to recursively process directories. - Without *R*, directories are ignored and only those *files* that refer to - files will be added to the archive. When *R* is used, any directories specified - with *files* will be scanned (recursively) to find files to be added to the - archive. Any file whose name begins with a dot will not be added. - - - [u] When replacing existing files in the archive, only replace those files that have @@ -283,8 +201,7 @@ The modifiers below may be applied to any operation. This modifier requests that an archive index (or symbol table) be added to the archive. This is the default mode of operation. The symbol table will contain all the externally visible functions and global variables defined by all the - bitcode files in the archive. Using this modifier is more efficient that using - llvm-ranlib|llvm-ranlib which also creates the symbol table. + bitcode files in the archive. @@ -401,14 +318,6 @@ fmag - char[2] utility in identifying archive files that have been corrupted. - -The LLVM symbol table has the special name "#_LLVM_SYM_TAB_#". It is presumed -that no regular archive member file will want this name. The LLVM symbol table -is simply composed of a sequence of triplets: byte offset, length of symbol, -and the symbol itself. Symbols are not null or newline terminated. Here are -the details on each of these items: - - offset - vbr encoded 32-bit integer The offset item provides the offset into the archive file where the bitcode @@ -455,4 +364,4 @@ SEE ALSO -------- -llvm-ranlib|llvm-ranlib, ar(1) +ar(1) diff --git a/docs/CommandGuide/llvm-link.rst b/docs/CommandGuide/llvm-link.rst index e4f2228..3bcfa68 100644 --- a/docs/CommandGuide/llvm-link.rst +++ b/docs/CommandGuide/llvm-link.rst @@ -1,5 +1,5 @@ -llvm-link - LLVM linker -======================= +llvm-link - LLVM bitcode linker +=============================== SYNOPSIS -------- @@ -13,23 +13,9 @@ DESCRIPTION into a single LLVM bitcode file. It writes the output file to standard output, unless the :option:`-o` option is used to specify a filename. -:program:`llvm-link` attempts to load the input files from the current -directory. If that fails, it looks for each file in each of the directories -specified by the :option:`-L` options on the command line. The library search -paths are global; each one is searched for every input file if necessary. The -directories are searched in the order they were specified on the command line. - OPTIONS ------- -.. option:: -L directory - - Add the specified ``directory`` to the library search path. When looking for - libraries, :program:`llvm-link` will look in path name for libraries. This - option can be specified multiple times; :program:`llvm-link` will search - inside these directories in the order in which they were specified on the - command line. - .. option:: -f Enable binary output on terminals. Normally, :program:`llvm-link` will refuse @@ -48,8 +34,8 @@ OPTIONS .. option:: -d - If specified, :program:`llvm-link` prints a human-readable version of the output - bitcode file to standard error. + If specified, :program:`llvm-link` prints a human-readable version of the + output bitcode file to standard error. .. option:: -help @@ -67,8 +53,4 @@ EXIT STATUS If :program:`llvm-link` succeeds, it will exit with 0. Otherwise, if an error occurs, it will exit with a non-zero value. -SEE ALSO --------- - -gccld diff --git a/docs/CommandGuide/llvm-ranlib.rst b/docs/CommandGuide/llvm-ranlib.rst deleted file mode 100644 index 6658818..0000000 --- a/docs/CommandGuide/llvm-ranlib.rst +++ /dev/null @@ -1,61 +0,0 @@ -llvm-ranlib - Generate index for LLVM archive -============================================= - - -SYNOPSIS --------- - - -**llvm-ranlib** [--version] [-help] <archive-file> - - -DESCRIPTION ------------ - - -The **llvm-ranlib** command is similar to the common Unix utility, ``ranlib``. It -adds or updates the symbol table in an LLVM archive file. Note that using the -**llvm-ar** modifier *s* is usually more efficient than running **llvm-ranlib** -which is only provided only for completness and compatibility. Unlike other -implementations of ``ranlib``, **llvm-ranlib** indexes LLVM bitcode files, not -native object modules. You can list the contents of the symbol table with the -``llvm-nm -s`` command. - - -OPTIONS -------- - - - -*archive-file* - - Specifies the archive-file to which the symbol table is added or updated. - - - -*--version* - - Print the version of **llvm-ranlib** and exit without building a symbol table. - - - -*-help* - - Print usage help for **llvm-ranlib** and exit without building a symbol table. - - - - -EXIT STATUS ------------ - - -If **llvm-ranlib** succeeds, it will exit with 0. If an error occurs, a non-zero -exit code will be returned. - - -SEE ALSO --------- - - -llvm-ar|llvm-ar, ranlib(1) diff --git a/docs/CommandGuide/llvm-readobj.rst b/docs/CommandGuide/llvm-readobj.rst new file mode 100644 index 0000000..b1918b5 --- /dev/null +++ b/docs/CommandGuide/llvm-readobj.rst @@ -0,0 +1,86 @@ +llvm-readobj - LLVM Object Reader +================================= + +SYNOPSIS +-------- + +:program:`llvm-readobj` [*options*] [*input...*] + +DESCRIPTION +----------- + +The :program:`llvm-readobj` tool displays low-level format-specific information +about one or more object files. The tool and its output is primarily designed +for use in FileCheck-based tests. + +OPTIONS +------- + +If ``input`` is "``-``" or omitted, :program:`llvm-readobj` reads from standard +input. Otherwise, it will read from the specified ``filenames``. + +.. option:: -help + + Print a summary of command line options. + +.. option:: -version + + Display the version of this program + +.. option:: -file-headers, -h + + Display file headers. + +.. option:: -sections, -s + + Display all sections. + +.. option:: -section-data, -sd + + When used with ``-sections``, display section data for each section shown. + +.. option:: -section-relocations, -sr + + When used with ``-sections``, display relocations for each section shown. + +.. option:: -section-symbols, -st + + When used with ``-sections``, display symbols for each section shown. + +.. option:: -relocations, -r + + Display the relocation entries in the file. + +.. option:: -symbols, -t + + Display the symbol table. + +.. option:: -dyn-symbols + + Display the dynamic symbol table (only for ELF object files). + +.. option:: -unwind, -u + + Display unwind information. + +.. option:: -expand-relocs + + When used with ``-relocations``, display each relocation in an expanded + multi-line format. + +.. option:: -dynamic-table + + Display the ELF .dynamic section table (only for ELF object files). + +.. option:: -needed-libs + + Display the needed libraries (only for ELF object files). + +.. option:: -program-headers + + Display the ELF program headers (only for ELF object files). + +EXIT STATUS +----------- + +:program:`llvm-readobj` returns 0. diff --git a/docs/CommandGuide/llvm-symbolizer.rst b/docs/CommandGuide/llvm-symbolizer.rst index 73babb1..e03be9b 100644 --- a/docs/CommandGuide/llvm-symbolizer.rst +++ b/docs/CommandGuide/llvm-symbolizer.rst @@ -22,6 +22,8 @@ EXAMPLE a.out 0x4004f4 /tmp/b.out 0x400528 /tmp/c.so 0x710 + /tmp/mach_universal_binary:i386 0x1f84 + /tmp/mach_universal_binary:x86_64 0x100000f24 $ llvm-symbolizer < addr.txt main /tmp/a.cc:4 @@ -38,6 +40,12 @@ EXAMPLE main /tmp/source.cc:8 + _main + /tmp/source_i386.cc:8 + + _main + /tmp/source_x86_64.cc:8 + OPTIONS ------- @@ -59,6 +67,14 @@ OPTIONS If a source code location is in an inlined function, prints all the inlnied frames. Defaults to true. +.. option:: -default-arch + + If a binary contains object files for multiple architectures (e.g. it is a + Mach-O universal binary), symbolize the object file for a given architecture. + You can also specify architecture by writing ``binary_name:arch_name`` in the + input (see example above). If architecture is not specified in either way, + address will not be symbolized. Defaults to empty string. + EXIT STATUS ----------- diff --git a/docs/CommandGuide/tblgen.rst b/docs/CommandGuide/tblgen.rst index 1858ee4..1c46828 100644 --- a/docs/CommandGuide/tblgen.rst +++ b/docs/CommandGuide/tblgen.rst @@ -23,6 +23,8 @@ file to read as input. OPTIONS ------- +.. program:: tblgen + .. option:: -help Print a summary of command line options. @@ -56,7 +58,7 @@ OPTIONS .. option:: -print-enums - Print enumeration values for a class + Print enumeration values for a class. .. option:: -print-sets diff --git a/docs/CommandLine.rst b/docs/CommandLine.rst index 073958b..4c84d23 100644 --- a/docs/CommandLine.rst +++ b/docs/CommandLine.rst @@ -2,6 +2,9 @@ CommandLine 2.0 Library Manual ============================== +.. contents:: + :local: + Introduction ============ @@ -615,6 +618,55 @@ would yield the help output: -help - display available options (-help-hidden for more) -o <filename> - Specify output filename +.. _grouping options into categories: + +Grouping options into categories +-------------------------------- + +If our program has a large number of options it may become difficult for users +of our tool to navigate the output of ``-help``. To alleviate this problem we +can put our options into categories. This can be done by declaring option +categories (`cl::OptionCategory`_ objects) and then placing our options into +these categories using the `cl::cat`_ option attribute. For example: + +.. code-block:: c++ + + cl::OptionCategory StageSelectionCat("Stage Selection Options", + "These control which stages are run."); + + cl::opt<bool> Preprocessor("E",cl::desc("Run preprocessor stage."), + cl::cat(StageSelectionCat)); + + cl::opt<bool> NoLink("c",cl::desc("Run all stages except linking."), + cl::cat(StageSelectionCat)); + +The output of ``-help`` will become categorized if an option category is +declared. The output looks something like :: + + OVERVIEW: This is a small program to demo the LLVM CommandLine API + USAGE: Sample [options] + + OPTIONS: + + General options: + + -help - Display available options (-help-hidden for more) + -help-list - Display list of available options (-help-list-hidden for more) + + + Stage Selection Options: + These control which stages are run. + + -E - Run preprocessor stage. + -c - Run all stages except linking. + +In addition to the behaviour of ``-help`` changing when an option category is +declared, the command line option ``-help-list`` becomes visible which will +print the command line options as uncategorized list. + +Note that Options that are not explicitly categorized will be placed in the +``cl::GeneralCategory`` category. + .. _Reference Guide: Reference Guide @@ -873,12 +925,13 @@ This section describes the basic attributes that you can specify on options. .. code-block:: c++ - cl::opt<**bool**> Quiet("quiet"); + cl::opt<bool> Quiet("quiet"); .. _cl::desc(...): * The **cl::desc** attribute specifies a description for the option to be - shown in the ``-help`` output for the program. + shown in the ``-help`` output for the program. This attribute supports + multi-line descriptions with lines separated by '\n'. .. _cl::value_desc: @@ -943,6 +996,11 @@ This section describes the basic attributes that you can specify on options. of the usual modifiers on multi-valued options (besides ``cl::ValueDisallowed``, obviously). +.. _cl::cat: + +* The **cl::cat** attribute specifies the option category that the option + belongs to. The category should be a `cl::OptionCategory`_ object. + Option Modifiers ---------------- @@ -1212,6 +1270,57 @@ 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. +.. _cl::getRegisteredOptions: + +The ``cl::getRegisteredOptions`` function +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The ``cl::getRegisteredOptions`` function is designed to give a programmer +access to declared non positional command line options so that how they appear +in ``-help`` can be modified prior to calling `cl::ParseCommandLineOptions`_. +Note this method should not be called during any static initialisation because +it cannot be guaranteed that all options will have been initialised. Hence it +should be called from ``main``. + +This function can be used to gain access to options declared in libraries that +the tool writter may not have direct access to. + +The function retrieves a :ref:`StringMap <dss_stringmap>` that maps the option +string (e.g. ``-help``) to an ``Option*``. + +Here is an example of how the function could be used: + +.. code-block:: c++ + + using namespace llvm; + int main(int argc, char **argv) { + cl::OptionCategory AnotherCategory("Some options"); + + StringMap<cl::Option*> Map; + cl::getRegisteredOptions(Map); + + //Unhide useful option and put it in a different category + assert(Map.count("print-all-options") > 0); + Map["print-all-options"]->setHiddenFlag(cl::NotHidden); + Map["print-all-options"]->setCategory(AnotherCategory); + + //Hide an option we don't want to see + assert(Map.count("enable-no-infs-fp-math") > 0); + Map["enable-no-infs-fp-math"]->setHiddenFlag(cl::Hidden); + + //Change --version to --show-version + assert(Map.count("version") > 0); + Map["version"]->setArgStr("show-version"); + + //Change --help description + assert(Map.count("help") > 0); + Map["help"]->setDescription("Shows help"); + + cl::ParseCommandLineOptions(argc, argv, "This is a small program to demo the LLVM CommandLine API"); + ... + } + + .. _cl::ParseCommandLineOptions: The ``cl::ParseCommandLineOptions`` function @@ -1382,6 +1491,29 @@ For example: cl::extrahelp("\nADDITIONAL HELP:\n\n This is the extra help\n"); +.. _cl::OptionCategory: + +The ``cl::OptionCategory`` class +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The ``cl::OptionCategory`` class is a simple class for declaring +option categories. + +.. code-block:: c++ + + namespace cl { + class OptionCategory; + } + +An option category must have a name and optionally a description which are +passed to the constructor as ``const char*``. + +Note that declaring an option category and associating it with an option before +parsing options (e.g. statically) will change the output of ``-help`` from +uncategorized to categorized. If an option category is declared but not +associated with an option then it will be hidden from the output of ``-help`` +but will be shown in the output of ``-help-hidden``. + .. _different parser: .. _discussed previously: diff --git a/docs/CompilerWriterInfo.rst b/docs/CompilerWriterInfo.rst index 87add67..6110d0b 100644 --- a/docs/CompilerWriterInfo.rst +++ b/docs/CompilerWriterInfo.rst @@ -20,11 +20,17 @@ ARM * `ABI <http://www.arm.com/products/DevTools/ABI.html>`_ +* `ABI Addenda and Errata <http://infocenter.arm.com/help/topic/com.arm.doc.ihi0045d/IHI0045D_ABI_addenda.pdf>`_ + +* `ARM C Language Extensions <http://infocenter.arm.com/help/topic/com.arm.doc.ihi0053a/IHI0053A_acle.pdf>`_ + AArch64 ------- * `ARMv8 Instruction Set Overview <http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.genc010197a/index.html>`_ +* `ARM C Language Extensions <http://infocenter.arm.com/help/topic/com.arm.doc.ihi0053a/IHI0053A_acle.pdf>`_ + Itanium (ia64) -------------- @@ -60,12 +66,28 @@ Other documents, collections, notes * `PowerPC64 alignment of long doubles (from GCC) <http://gcc.gnu.org/ml/gcc-patches/2003-09/msg00997.html>`_ * `Long branch stubs for powerpc64-linux (from binutils) <http://sources.redhat.com/ml/binutils/2002-04/msg00573.html>`_ +R600 +---- + +* `AMD R6xx shader ISA <http://developer.amd.com/wordpress/media/2012/10/R600_Instruction_Set_Architecture.pdf>`_ +* `AMD R7xx shader ISA <http://developer.amd.com/wordpress/media/2012/10/R700-Family_Instruction_Set_Architecture.pdf>`_ +* `AMD Evergreen shader ISA <http://developer.amd.com/wordpress/media/2012/10/AMD_Evergreen-Family_Instruction_Set_Architecture.pdf>`_ +* `AMD Cayman/Trinity shader ISA <http://developer.amd.com/wordpress/media/2012/10/AMD_HD_6900_Series_Instruction_Set_Architecture.pdf>`_ +* `AMD Southern Islands Series ISA <http://developer.amd.com/wordpress/media/2012/12/AMD_Southern_Islands_Instruction_Set_Architecture.pdf>`_ +* `AMD GPU Programming Guide <http://developer.amd.com/download/AMD_Accelerated_Parallel_Processing_OpenCL_Programming_Guide.pdf>`_ +* `AMD Compute Resources <http://developer.amd.com/tools/heterogeneous-computing/amd-accelerated-parallel-processing-app-sdk/documentation/>`_ + SPARC ----- * `SPARC resources <http://www.sparc.org/resource.htm>`_ * `SPARC standards <http://www.sparc.org/standards.html>`_ +SystemZ +------- + +* `z/Architecture Principles of Operation (registration required, free sign-up) <http://www-01.ibm.com/support/docview.wss?uid=isg2b9de5f05a9d57819852571c500428f9a>`_ + X86 --- @@ -94,12 +116,16 @@ Other relevant lists ABI === +* `System V Application Binary Interface <http://www.sco.com/developers/gabi/latest/contents.html>`_ +* `Itanium C++ ABI <http://mentorembedded.github.io/cxx-abi/>`_ + Linux ----- * `PowerPC 64-bit ELF ABI Supplement <http://www.linuxbase.org/spec/ELF/ppc64/>`_ * `Procedure Call Standard for the AArch64 Architecture <http://infocenter.arm.com/help/topic/com.arm.doc.ihi0055a/IHI0055A_aapcs64.pdf>`_ * `ELF for the ARM 64-bit Architecture (AArch64) <http://infocenter.arm.com/help/topic/com.arm.doc.ihi0056a/IHI0056A_aaelf64.pdf>`_ +* `System z ELF ABI Supplement <http://legacy.redhat.com/pub/redhat/linux/7.1/es/os/s390x/doc/lzsabi0.pdf>`_ OS X ---- @@ -107,6 +133,17 @@ OS X * `Mach-O Runtime Architecture <http://developer.apple.com/documentation/Darwin/RuntimeArchitecture-date.html>`_ * `Notes on Mach-O ABI <http://www.unsanity.org/archives/000044.php>`_ +Windows +------- + +* `Microsoft PE/COFF Specification <http://www.microsoft.com/whdc/system/platform/firmware/pecoff.mspx>`_ + +NVPTX +===== + +* `CUDA Documentation <http://docs.nvidia.com/cuda/index.html>`_ includes the PTX + ISA and Driver API documentation + Miscellaneous Resources ======================= diff --git a/docs/DeveloperPolicy.rst b/docs/DeveloperPolicy.rst index 43bdc85..0655559 100644 --- a/docs/DeveloperPolicy.rst +++ b/docs/DeveloperPolicy.rst @@ -260,7 +260,7 @@ quality patches. If you would like commit access, please send an email to from, e.g. "J. Random Hacker <hacker@yoyodyne.com>". #. 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 + 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. @@ -269,17 +269,17 @@ Once you've been granted commit access, you should be able to check out an LLVM tree with an SVN URL of "https://username@llvm.org/..." instead of the normal anonymous URL of "http://llvm.org/...". The first time you commit you'll have to type in your password. Note that you may get a warning from SVN about an -untrusted key, you can ignore this. To verify that your commit access works, +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 +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 - <http://lists.cs.uiuc.edu/mailman/listinfo/llvm-commits>`_. When approved + <http://lists.cs.uiuc.edu/mailman/listinfo/llvm-commits>`_. When approved, you may commit it yourself. #. You are allowed to commit patches without approval which you think are @@ -291,7 +291,7 @@ If you have recently been granted commit access, these policies apply: #. 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 + 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 @@ -300,7 +300,7 @@ If you have recently been granted commit access, these policies apply: 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. +to do so. .. _discuss the change/gather consensus: diff --git a/docs/ExtendingLLVM.rst b/docs/ExtendingLLVM.rst index 3d8e9ee..60cbf01 100644 --- a/docs/ExtendingLLVM.rst +++ b/docs/ExtendingLLVM.rst @@ -45,7 +45,7 @@ function and then be turned into an instruction if warranted. 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``: +#. ``llvm/include/llvm/IR/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 @@ -281,12 +281,12 @@ Adding a derived type add ability to parse in the type from text assembly -#. ``llvm/lib/BitCode/Writer/Writer.cpp``: +#. ``llvm/lib/Bitcode/Writer/Writer.cpp``: modify ``void BitcodeWriter::outputType(const Type *T)`` to serialize your type -#. ``llvm/lib/BitCode/Reader/Reader.cpp``: +#. ``llvm/lib/Bitcode/Reader/Reader.cpp``: modify ``const Type *BitcodeReader::ParseType()`` to read your data type diff --git a/docs/Extensions.rst b/docs/Extensions.rst new file mode 100644 index 0000000..78ff874 --- /dev/null +++ b/docs/Extensions.rst @@ -0,0 +1,93 @@ +=============== +LLVM Extensions +=============== + +.. contents:: + :local: + +.. toctree:: + :hidden: + +Introduction +============ + +This document describes extensions to tools and formats LLVM seeks compatibility +with. + +Machine-specific Assembly Syntax +================================ + +X86/COFF-Dependent +------------------ + +Relocations +^^^^^^^^^^^ + +The following additional relocation type is supported: + +**@IMGREL** (AT&T syntax only) generates an image-relative relocation that +corresponds to the COFF relocation types ``IMAGE_REL_I386_DIR32NB`` (32-bit) or +``IMAGE_REL_AMD64_ADDR32NB`` (64-bit). + +.. code-block:: gas + + .text + fun: + mov foo@IMGREL(%ebx, %ecx, 4), %eax + + .section .pdata + .long fun@IMGREL + .long (fun@imgrel + 0x3F) + .long $unwind$fun@imgrel + + +``.linkonce`` Directive +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Syntax: + + ``.linkonce [ comdat type [ section identifier ] ]`` + +Supported COMDAT types: + +``discard`` + Discards duplicate sections with the same COMDAT symbol. This is the default + if no type is specified. + +``one_only`` + If the symbol is defined multiple times, the linker issues an error. + +``same_size`` + Duplicates are discarded, but the linker issues an error if any have + different sizes. + +``same_contents`` + Duplicates are discarded, but the linker issues an error if any duplicates + do not have exactly the same content. + +``associative`` + Links the section if a certain other COMDAT section is linked. This other + section is indicated by its section identifier following the comdat type. + The following restrictions apply to the associated section: + + 1. It must be the name of a section already defined. + 2. It must differ from the current section. + 3. It must be a COMDAT section. + 4. It cannot be another associative COMDAT section. + +``largest`` + Links the largest section from among the duplicates. + +``newest`` + Links the newest section from among the duplicates. + + +.. code-block:: gas + + .section .text$foo + .linkonce + ... + + .section .xdata$foo + .linkonce associative .text$foo + ... diff --git a/docs/GarbageCollection.rst b/docs/GarbageCollection.rst index 5c3a1af..b722277 100644 --- a/docs/GarbageCollection.rst +++ b/docs/GarbageCollection.rst @@ -764,8 +764,8 @@ The following can be used as a template: .. code-block:: c++ - #include "llvm/Module.h" - #include "llvm/IntrinsicInst.h" + #include "llvm/IR/Module.h" + #include "llvm/IR/IntrinsicInst.h" bool MyGC::initializeCustomLowering(Module &M) { return false; @@ -915,10 +915,10 @@ map for the entire module, and may access the ``GCFunctionInfo`` using its own .. code-block:: c++ #include "llvm/CodeGen/AsmPrinter.h" - #include "llvm/Function.h" - #include "llvm/Target/TargetMachine.h" - #include "llvm/DataLayout.h" + #include "llvm/IR/Function.h" + #include "llvm/IR/DataLayout.h" #include "llvm/Target/TargetAsmInfo.h" + #include "llvm/Target/TargetMachine.h" void MyGCPrinter::beginAssembly(std::ostream &OS, AsmPrinter &AP, const TargetAsmInfo &TAI) { diff --git a/docs/GettingStarted.rst b/docs/GettingStarted.rst index 539c75e..40dfc45 100644 --- a/docs/GettingStarted.rst +++ b/docs/GettingStarted.rst @@ -81,7 +81,7 @@ Here's the short story for getting up and running quickly with LLVM: * ``make [-j]`` --- The ``-j`` specifies the number of jobs (commands) to run simultaneously. This builds both LLVM and Clang for Debug+Asserts mode. - The ``--enabled-optimized`` configure option is used to specify a Release + The ``--enable-optimized`` configure option is used to specify a Release build. * ``make check-all`` --- This run the regression tests to ensure everything @@ -229,6 +229,8 @@ uses the package and provides other details. +--------------------------------------------------------------+-----------------+---------------------------------------------+ | `libtool <http://savannah.gnu.org/projects/libtool>`_ | 1.5.22 | Shared library manager\ :sup:`4` | +--------------------------------------------------------------+-----------------+---------------------------------------------+ +| `zlib <http://zlib.net>`_ | >=1.2.3.4 | Compression library\ :sup:`5` | ++--------------------------------------------------------------+-----------------+---------------------------------------------+ .. note:: @@ -243,6 +245,8 @@ uses the package and provides other details. #. If you want to make changes to the configure scripts, you will need GNU autoconf (2.60), and consequently, GNU M4 (version 1.4 or higher). You will also need automake (1.9.6). We only use aclocal from that package. + #. Optional, adds compression/uncompression capabilities to selected LLVM + tools. Additionally, your compilation host is expected to have the usual plethora of Unix utilities. Specifically: @@ -521,13 +525,13 @@ By placing it in the ``llvm/projects``, it will be automatically configured by the LLVM configure script as well as automatically updated when you run ``svn update``. -GIT mirror +Git Mirror ---------- -GIT mirrors are available for a number of LLVM subprojects. These mirrors sync +Git mirrors are available for a number of LLVM subprojects. These mirrors sync automatically with each Subversion commit and contain all necessary git-svn marks (so, you can recreate git-svn metadata locally). Note that right now -mirrors reflect only ``trunk`` for each project. You can do the read-only GIT +mirrors reflect only ``trunk`` for each project. You can do the read-only Git clone of LLVM via: .. code-block:: console @@ -538,10 +542,23 @@ If you want to check out clang too, run: .. code-block:: console - % git clone http://llvm.org/git/llvm.git % cd llvm/tools % git clone http://llvm.org/git/clang.git +If you want to check out compiler-rt too, run: + +.. code-block:: console + + % cd llvm/projects + % git clone http://llvm.org/git/compiler-rt.git + +If you want to check out the Test Suite Source Code (optional), run: + +.. code-block:: console + + % cd llvm/projects + % git clone http://llvm.org/git/test-suite.git + Since the upstream repository is in Subversion, you should use ``git pull --rebase`` instead of ``git pull`` to avoid generating a non-linear history in your clone. To configure ``git pull`` to pass ``--rebase`` by default on the @@ -626,8 +643,10 @@ To set up clone from which you can submit code using ``git-svn``, run: % git config svn-remote.svn.fetch :refs/remotes/origin/master % git svn rebase -l +Likewise for compiler-rt and test-suite. + To update this clone without generating git-svn tags that conflict with the -upstream git repo, run: +upstream Git repo, run: .. code-block:: console @@ -638,39 +657,26 @@ upstream git repo, run: git checkout master && git svn rebase -l) +Likewise for compiler-rt and test-suite. + This leaves your working directories on their master branches, so you'll need to ``checkout`` each working branch individually and ``rebase`` it on top of its parent branch. -For those who wish to be able to update an llvm repo in a simpler fashion, -consider placing the following git script in your path under the name -``git-svnup``: - -.. code-block:: bash - - #!/bin/bash - - STATUS=$(git status -s | grep -v "??") - - if [ ! -z "$STATUS" ]; then - STASH="yes" - git stash >/dev/null - fi - - git fetch - OLD_BRANCH=$(git rev-parse --abbrev-ref HEAD) - git checkout master 2> /dev/null - git svn rebase -l - git checkout $OLD_BRANCH 2> /dev/null +For those who wish to be able to update an llvm repo/revert patches easily using +git-svn, please look in the directory for the scripts ``git-svnup`` and +``git-svnrevert``. - if [ ! -z $STASH ]; then - git stash pop >/dev/null - fi +To perform the aforementioned update steps go into your source directory and +just type ``git-svnup`` or ``git svnup`` and everything will just work. -Then to perform the aforementioned update steps go into your source directory -and just type ``git-svnup`` or ``git svnup`` and everything will just work. +If one wishes to revert a commit with git-svn, but do not want the git hash to +escape into the commit message, one can use the script ``git-svnrevert`` or +``git svnrevert`` which will take in the git hash for the commit you want to +revert, look up the appropriate svn revision, and output a message where all +references to the git hash have been replaced with the svn revision. -To commit back changes via git-svn, use ``dcommit``: +To commit back changes via git-svn, use ``git svn dcommit``: .. code-block:: console @@ -752,8 +758,8 @@ The following options can be used to set or enable LLVM specific options: target names that you want available in llc. The target names use all lower case. The current set of targets is: - ``arm, cpp, hexagon, mblaze, mips, mipsel, msp430, powerpc, ptx, sparc, spu, - x86, x86_64, xcore``. + ``arm, cpp, hexagon, mips, mipsel, msp430, powerpc, ptx, sparc, spu, + systemz, x86, x86_64, xcore``. ``--enable-doxygen`` @@ -991,7 +997,7 @@ Optional Configuration Items ---------------------------- If you're running on a Linux system that supports the `binfmt_misc -<http://www.tat.physik.uni-tuebingen.de/~rguenth/linux/binfmt_misc.html>`_ +<http://en.wikipedia.org/wiki/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): @@ -1068,7 +1074,7 @@ different `tools`_. This directory holds the source code for the LLVM assembly language parser library. -``llvm/lib/BitCode/`` +``llvm/lib/Bitcode/`` This directory holds code for reading and write LLVM bitcode. diff --git a/docs/GettingStartedVS.rst b/docs/GettingStartedVS.rst index 4c80f2c..9847c83 100644 --- a/docs/GettingStartedVS.rst +++ b/docs/GettingStartedVS.rst @@ -45,13 +45,13 @@ and software you will need. Hardware -------- -Any system that can adequately run Visual Studio 2008 is fine. The LLVM +Any system that can adequately run Visual Studio 2010 is fine. The LLVM source tree and object files, libraries and executables will consume approximately 3GB. Software -------- -You will need Visual Studio 2008 or higher. Earlier versions of Visual +You will need Visual Studio 2010 or higher. Earlier versions of Visual Studio have bugs, are not completely compatible, or do not support the C++ standard well enough. @@ -137,15 +137,18 @@ Here's the short story for getting up and running quickly with LLVM: .. code-block:: bat - C:\..\llvm> llvm-lit test + C:\..\llvm> python ..\build\bin\llvm-lit --param build_config=Win32 --param build_mode=Debug --param llvm_site_config=../build/test/lit.site.cfg test - Note that quite a few of these test will fail. + This example assumes that Python is in your PATH variable, you + have built a Win32 Debug version of llvm with a standard out of + line build. You should not see any unexpected failures, but will + see many unsupported tests and expected failures. A specific test or test directory can be run with: .. code-block:: bat - C:\..\llvm> llvm-lit test/path/to/test + C:\..\llvm> python ..\build\bin\llvm-lit --param build_config=Win32 --param build_mode=Debug --param llvm_site_config=../build/test/lit.site.cfg test/path/to/test An Example Using the LLVM Tool Chain diff --git a/docs/HowToReleaseLLVM.rst b/docs/HowToReleaseLLVM.rst index 31877bd..bc3b093 100644 --- a/docs/HowToReleaseLLVM.rst +++ b/docs/HowToReleaseLLVM.rst @@ -14,6 +14,9 @@ including subprojects: e.g., ``clang`` and ``dragonegg`` --- to the public. It is the Release Manager's responsibility to ensure that a high quality build of LLVM is released. +If you're looking for the document on how to test the release candidates and +create the binary packages, please refer to the :doc:`ReleaseProcess` instead. + .. _timeline: Release Timeline diff --git a/docs/LLVMBuild.rst b/docs/LLVMBuild.rst index d9215dd..040b044 100644 --- a/docs/LLVMBuild.rst +++ b/docs/LLVMBuild.rst @@ -123,8 +123,8 @@ the file format is below: boolean_property_name = 1 (or 0) LLVMBuild files are expected to define a strict set of sections and -properties. An typical component description file for a library -component would look typically look like the following example: +properties. A typical component description file for a library +component would look like the following example: .. code-block:: ini diff --git a/docs/LangRef.rst b/docs/LangRef.rst index 03004f6..b69e2a3 100644 --- a/docs/LangRef.rst +++ b/docs/LangRef.rst @@ -127,7 +127,8 @@ lexical features of LLVM: #. Comments are delimited with a '``;``' and go until the end of line. #. Unnamed temporaries are created when the result of a computation is not assigned to a named value. -#. Unnamed temporaries are numbered sequentially +#. Unnamed temporaries are numbered sequentially (using a per-function + incrementing counter, starting with 0). It also shows a convention that we follow in this document. When demonstrating instructions, we will follow an instruction with a comment @@ -386,6 +387,8 @@ More calling conventions can be added/defined on an as-needed basis, to support Pascal conventions or any other well-known target-independent convention. +.. _visibilitystyles: + Visibility Styles ----------------- @@ -411,6 +414,8 @@ styles: defining module will bind to the local symbol. That is, the symbol cannot be overridden by another module. +.. _namedtypes: + Named Types ----------- @@ -563,7 +568,11 @@ A function definition contains a list of basic blocks, forming the CFG start with a label (giving the basic block a symbol table entry), contains a list of instructions, and ends with a :ref:`terminator <terminators>` instruction (such as a branch or function -return). +return). If explicit label is not provided, a block is assigned an +implicit numbered label, using a next value from the same counter as used +for unnamed temporaries (:ref:`see above<identifiers>`). For example, if a +function entry block does not have explicit label, it will be assigned +label "%0", then first unnamed temporary in that block will be "%1", etc. The first basic block in a function is special in two ways: it is immediately executed on entrance to the function, and it is not allowed @@ -591,6 +600,8 @@ Syntax:: [fn Attrs] [section "name"] [align N] [gc] { ... } +.. _langref_aliases: + Aliases ------- @@ -692,7 +703,7 @@ Currently, only the following parameter attributes are defined: the first parameter. This is not a valid attribute for return values. ``noalias`` - This indicates that pointer values `*based* <pointeraliasing>` on + This indicates that pointer values :ref:`based <pointeraliasing>` on the argument or return value do not alias pointer values which are not *based* on it, ignoring certain "irrelevant" dependencies. For a call to the parent function, dependencies between memory references @@ -719,12 +730,16 @@ Currently, only the following parameter attributes are defined: ``nest`` This indicates that the pointer parameter can be excised using the :ref:`trampoline intrinsics <int_trampoline>`. This is not a valid - attribute for return values. -``nobuiltin`` - This indicates that the callee function at a call site is not - recognized as a built-in function. LLVM will retain the original call - and not replace it with equivalent code based on the semantics of the - built-in function. + attribute for return values and can only be applied to one parameter. + +``returned`` + This indicates that the function always returns the argument as its return + value. This is an optimization hint to the code generator when generating + the caller, allowing tail call optimization and omission of register saves + and restores in some cases; it is not checked or enforced when generating + the callee. The parameter and the function return type must be valid + operands for the :ref:`bitcast instruction <i_bitcast>`. This is not a + valid attribute for return values and can only be applied to one parameter. .. _gc: @@ -764,10 +779,10 @@ inlined, has a stack alignment of 4, and which shouldn't use SSE instructions: .. code-block:: llvm ; Target-independent attributes: - #0 = attributes { alwaysinline alignstack=4 } + attributes #0 = { alwaysinline alignstack=4 } ; Target-dependent attributes: - #1 = attributes { "no-sse" } + attributes #1 = { "no-sse" } ; Function @f has attributes: alwaysinline, alignstack=4, and "no-sse". define void @f() #0 #1 { ... } @@ -802,10 +817,17 @@ example: This attribute indicates that the inliner should attempt to inline this function into callers whenever possible, ignoring any active inlining size threshold for this caller. -``nonlazybind`` - This attribute suppresses lazy symbol binding for the function. This - may make calls to the function faster, at the cost of extra program - startup time if the function is not called during program startup. +``builtin`` + This indicates that the callee function at a call site should be + recognized as a built-in function, even though the function's declaration + uses the ``nobuiltin`` attribute. This is only valid at call sites for + direct calls to functions which are declared with the ``nobuiltin`` + attribute. +``cold`` + This attribute indicates that this function is rarely called. When + computing edge weights, basic blocks post-dominated by a cold + function call are also considered to be cold; and, thus, given low + weight. ``inlinehint`` This attribute indicates that the source code contained a hint that inlining this function is desirable (such as the "inline" keyword in @@ -814,6 +836,12 @@ example: ``naked`` This attribute disables prologue / epilogue emission for the function. This can have very system-specific consequences. +``nobuiltin`` + This indicates that the callee function at a call site is not recognized as + a built-in function. LLVM will retain the original call and not replace it + with equivalent code based on the semantics of the built-in function, unless + the call site uses the ``builtin`` attribute. This is valid at call sites + and on function declarations and definitions. ``noduplicate`` This attribute indicates that calls to the function cannot be duplicated. A call to a ``noduplicate`` function may be moved @@ -831,6 +859,10 @@ example: This attribute indicates that the inliner should never inline this function in any situation. This attribute may not be used together with the ``alwaysinline`` attribute. +``nonlazybind`` + This attribute suppresses lazy symbol binding for the function. This + may make calls to the function faster, at the cost of extra program + startup time if the function is not called during program startup. ``noredzone`` This attribute indicates that the code generator should not use a red zone, even if the target-specific ABI normally permits it. @@ -847,17 +879,21 @@ example: passes make choices that keep the code size of this function low, and otherwise do optimizations specifically to reduce code size. ``readnone`` - This attribute indicates that the function computes its result (or - decides to unwind an exception) based strictly on its arguments, + On a function, this attribute indicates that the function computes its + result (or decides to unwind an exception) based strictly on its arguments, without dereferencing any pointer arguments or otherwise accessing any mutable state (e.g. memory, control registers, etc) visible to caller functions. It does not write through any pointer arguments (including ``byval`` arguments) and never changes any state visible to callers. This means that it cannot unwind exceptions by calling the ``C++`` exception throwing methods. + + On an argument, this attribute indicates that the function does not + dereference that pointer argument, even though it may read or write the + memory that the pointer points to if accessed through other pointers. ``readonly`` - This attribute indicates that the function does not write through - any pointer arguments (including ``byval`` arguments) or otherwise + On a function, this attribute indicates that the function does not write + through any pointer arguments (including ``byval`` arguments) or otherwise modify any state (e.g. memory, control registers, etc) visible to caller functions. It may dereference pointer arguments and read state that may be set in the caller. A readonly function always @@ -865,6 +901,10 @@ example: called with the same set of arguments and global state. It cannot unwind an exception by calling the ``C++`` exception throwing methods. + + On an argument, this attribute indicates that the function does not write + through this pointer argument, even though it may write to the memory that + the pointer points to. ``returns_twice`` This attribute indicates that this function can return twice. The C ``setjmp`` is an example of such a function. The compiler disables @@ -949,6 +989,8 @@ two digit hex code for the number. The inline asm code is simply printed to the machine code .s file when assembly code is generated. +.. _langref_datalayout: + Data Layout ----------- @@ -1019,7 +1061,9 @@ the specifications in the ``datalayout`` keyword. The default specifications are given in this list: - ``E`` - big endian -- ``p:64:64:64`` - 64-bit pointers with 64-bit alignment +- ``p:64:64:64`` - 64-bit pointers with 64-bit alignment. +- ``p[n]:64:64:64`` - Other address spaces are assumed to be the + same as the default address space. - ``S0`` - natural stack alignment is unspecified - ``i1:8:8`` - i1 is 8-bit (byte) aligned - ``i8:8:8`` - i8 is 8-bit (byte) aligned @@ -1338,6 +1382,8 @@ transformation. A strong type system makes it easier to read the generated code and enables novel analyses and transformations that are not feasible to perform on normal three address code representations. +.. _typeclassifications: + Type Classifications -------------------- @@ -1843,14 +1889,16 @@ double, and there are three forms of long double. The 80-bit format used by x86 is represented as ``0xK`` followed by 20 hexadecimal digits. The 128-bit format used by PowerPC (two adjacent doubles) is represented by ``0xM`` followed by 32 hexadecimal digits. The IEEE 128-bit format is -represented by ``0xL`` followed by 32 hexadecimal digits; no currently -supported target uses this format. Long doubles will only work if they -match the long double format on your target. The IEEE 16-bit format -(half precision) is represented by ``0xH`` followed by 4 hexadecimal -digits. All hexadecimal formats are big-endian (sign bit at the left). +represented by ``0xL`` followed by 32 hexadecimal digits. Long doubles +will only work if they match the long double format on your target. +The IEEE 16-bit format (half precision) is represented by ``0xH`` +followed by 4 hexadecimal digits. All hexadecimal formats are big-endian +(sign bit at the left). There are no constants of type x86mmx. +.. _complexconstants: + Complex Constants ----------------- @@ -2172,6 +2220,8 @@ instruction. Finally, some targets may provide defined semantics when using the value as the operand to an inline assembly, but that is target specific. +.. _constantexprs: + Constant Expressions -------------------- @@ -2276,6 +2326,8 @@ The following is the syntax for constant expressions: Other Values ============ +.. _inlineasmexprs: + Inline Assembler Expressions ---------------------------- @@ -2533,8 +2585,8 @@ Examples: It is sometimes useful to attach information to loop constructs. Currently, loop metadata is implemented as metadata attached to the branch instruction in the loop latch block. This type of metadata refer to a metadata node that is -guaranteed to be separate for each loop. The loop-level metadata is prefixed -with ``llvm.loop``. +guaranteed to be separate for each loop. The loop identifier metadata is +specified with the name ``llvm.loop``. The loop identifier metadata is implemented using a metadata that refers to itself to avoid merging it with any other identifier metadata, e.g., @@ -2548,32 +2600,17 @@ constructs: !0 = metadata !{ metadata !0 } !1 = metadata !{ metadata !1 } +The loop identifier metadata can be used to specify additional per-loop +metadata. Any operands after the first operand can be treated as user-defined +metadata. For example the ``llvm.vectorizer.unroll`` metadata is understood +by the loop vectorizer to indicate how many times to unroll the loop: -'``llvm.loop.parallel``' Metadata -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: llvm -This loop metadata can be used to communicate that a loop should be considered -a parallel loop. The semantics of parallel loops in this case is the one -with the strongest cross-iteration instruction ordering freedom: the -iterations in the loop can be considered completely independent of each -other (also known as embarrassingly parallel loops). - -This metadata can originate from a programming language with parallel loop -constructs. In such a case it is completely the programmer's responsibility -to ensure the instructions from the different iterations of the loop can be -executed in an arbitrary order, in parallel, or intertwined. No loop-carried -dependency checking at all must be expected from the compiler. - -In order to fulfill the LLVM requirement for metadata to be safely ignored, -it is important to ensure that a parallel loop is converted to -a sequential loop in case an optimization (agnostic of the parallel loop -semantics) converts the loop back to such. This happens when new memory -accesses that do not fulfill the requirement of free ordering across iterations -are added to the loop. Therefore, this metadata is required, but not -sufficient, to consider the loop at hand a parallel loop. For a loop -to be parallel, all its memory accessing instructions need to be -marked with the ``llvm.mem.parallel_loop_access`` metadata that refer -to the same loop identifier metadata that identify the loop at hand. + br i1 %exitcond, label %._crit_edge, label %.lr.ph, !llvm.loop !0 + ... + !0 = metadata !{ metadata !0, metadata !1 } + !1 = metadata !{ metadata !"llvm.vectorizer.unroll", i32 2 } '``llvm.mem``' ^^^^^^^^^^^^^^^ @@ -2585,29 +2622,28 @@ for optimizations are prefixed with ``llvm.mem``. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ For a loop to be parallel, in addition to using -the ``llvm.loop.parallel`` metadata to mark the loop latch branch instruction, +the ``llvm.loop`` metadata to mark the loop latch branch instruction, also all of the memory accessing instructions in the loop body need to be marked with the ``llvm.mem.parallel_loop_access`` metadata. If there is at least one memory accessing instruction not marked with the metadata, -the loop, despite it possibly using the ``llvm.loop.parallel`` metadata, -must be considered a sequential loop. This causes parallel loops to be +the loop must be considered a sequential loop. This causes parallel loops to be converted to sequential loops due to optimization passes that are unaware of the parallel semantics and that insert new memory instructions to the loop body. Example of a loop that is considered parallel due to its correct use of -both ``llvm.loop.parallel`` and ``llvm.mem.parallel_loop_access`` +both ``llvm.loop`` and ``llvm.mem.parallel_loop_access`` metadata types that refer to the same loop identifier metadata. .. code-block:: llvm for.body: - ... - %0 = load i32* %arrayidx, align 4, !llvm.mem.parallel_loop_access !0 - ... - store i32 %0, i32* %arrayidx4, align 4, !llvm.mem.parallel_loop_access !0 - ... - br i1 %exitcond, label %for.end, label %for.body, !llvm.loop.parallel !0 + ... + %0 = load i32* %arrayidx, align 4, !llvm.mem.parallel_loop_access !0 + ... + store i32 %0, i32* %arrayidx4, align 4, !llvm.mem.parallel_loop_access !0 + ... + br i1 %exitcond, label %for.end, label %for.body, !llvm.loop !0 for.end: ... @@ -2623,27 +2659,75 @@ the loop identifier metadata node directly: ... inner.for.body: - ... - %0 = load i32* %arrayidx, align 4, !llvm.mem.parallel_loop_access !0 - ... - store i32 %0, i32* %arrayidx4, align 4, !llvm.mem.parallel_loop_access !0 - ... - br i1 %exitcond, label %inner.for.end, label %inner.for.body, !llvm.loop.parallel !1 + ... + %0 = load i32* %arrayidx, align 4, !llvm.mem.parallel_loop_access !0 + ... + store i32 %0, i32* %arrayidx4, align 4, !llvm.mem.parallel_loop_access !0 + ... + br i1 %exitcond, label %inner.for.end, label %inner.for.body, !llvm.loop !1 inner.for.end: - ... - %0 = load i32* %arrayidx, align 4, !llvm.mem.parallel_loop_access !0 - ... - store i32 %0, i32* %arrayidx4, align 4, !llvm.mem.parallel_loop_access !0 - ... - br i1 %exitcond, label %outer.for.end, label %outer.for.body, !llvm.loop.parallel !2 + ... + %0 = load i32* %arrayidx, align 4, !llvm.mem.parallel_loop_access !0 + ... + store i32 %0, i32* %arrayidx4, align 4, !llvm.mem.parallel_loop_access !0 + ... + br i1 %exitcond, label %outer.for.end, label %outer.for.body, !llvm.loop !2 outer.for.end: ; preds = %for.body ... - !0 = metadata !{ metadata !1, metadata !2 } ; a list of parallel loop identifiers - !1 = metadata !{ metadata !1 } ; an identifier for the inner parallel loop - !2 = metadata !{ metadata !2 } ; an identifier for the outer parallel loop + !0 = metadata !{ metadata !1, metadata !2 } ; a list of loop identifiers + !1 = metadata !{ metadata !1 } ; an identifier for the inner loop + !2 = metadata !{ metadata !2 } ; an identifier for the outer loop + +'``llvm.vectorizer``' +^^^^^^^^^^^^^^^^^^^^^ + +Metadata prefixed with ``llvm.vectorizer`` is used to control per-loop +vectorization parameters such as vectorization factor and unroll factor. + +``llvm.vectorizer`` metadata should be used in conjunction with ``llvm.loop`` +loop identification metadata. + +'``llvm.vectorizer.unroll``' Metadata +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This metadata instructs the loop vectorizer to unroll the specified +loop exactly ``N`` times. + +The first operand is the string ``llvm.vectorizer.unroll`` and the second +operand is an integer specifying the unroll factor. For example: +.. code-block:: llvm + + !0 = metadata !{ metadata !"llvm.vectorizer.unroll", i32 4 } + +Note that setting ``llvm.vectorizer.unroll`` to 1 disables unrolling of the +loop. + +If ``llvm.vectorizer.unroll`` is set to 0 then the amount of unrolling will be +determined automatically. + +'``llvm.vectorizer.width``' Metadata +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This metadata sets the target width of the vectorizer to ``N``. Without +this metadata, the vectorizer will choose a width automatically. +Regardless of this metadata, the vectorizer will only vectorize loops if +it believes it is valid to do so. + +The first operand is the string ``llvm.vectorizer.width`` and the second +operand is an integer specifying the width. For example: + +.. code-block:: llvm + + !0 = metadata !{ metadata !"llvm.vectorizer.width", i32 4 } + +Note that setting ``llvm.vectorizer.width`` to 1 disables vectorization of the +loop. + +If ``llvm.vectorizer.width`` is set to 0 then the width will be determined +automatically. Module Flags Metadata ===================== @@ -2845,6 +2929,8 @@ Each individual option is required to be either a valid option for the target's linker, or an option that is reserved by the target specific assembly writer or object file emitter. No other aspect of these options is defined by the IR. +.. _intrinsicglobalvariables: + Intrinsic Global Variables ========================== @@ -2854,13 +2940,15 @@ All globals of this sort should have a section specified as "``llvm.metadata``". This section and all globals that start with "``llvm.``" are reserved for use by LLVM. +.. _gv_llvmused: + The '``llvm.used``' Global Variable ----------------------------------- -The ``@llvm.used`` global is an array with i8\* element type which has +The ``@llvm.used`` global is an array which has :ref:`appending linkage <linkage_appending>`. This array contains a list of -pointers to global variables and functions which may optionally have a -pointer cast formed of bitcast or getelementptr. For example, a legal +pointers to named global variables, functions and aliases which may optionally +have a pointer cast formed of bitcast or getelementptr. For example, a legal use of it is: .. code-block:: llvm @@ -2873,18 +2961,20 @@ use of it is: i8* bitcast (i32* @Y to i8*) ], section "llvm.metadata" -If a global variable appears in the ``@llvm.used`` list, then the -compiler, assembler, and linker are required to treat the symbol as if -there is a reference to the global that it cannot see. For example, if a -variable has internal linkage and no references other than that from the -``@llvm.used`` list, it cannot be deleted. This is commonly used to -represent references from inline asms and other things the compiler -cannot "see", and corresponds to "``attribute((used))``" in GNU C. +If a symbol appears in the ``@llvm.used`` list, then the compiler, assembler, +and linker are required to treat the symbol as if there is a reference to the +symbol that it cannot see (which is why they have to be named). For example, if +a variable has internal linkage and no references other than that from the +``@llvm.used`` list, it cannot be deleted. This is commonly used to represent +references from inline asms and other things the compiler cannot "see", and +corresponds to "``attribute((used))``" in GNU C. On some targets, the code generator must emit a directive to the assembler or object file to prevent the assembler and linker from molesting the symbol. +.. _gv_llvmcompilerused: + The '``llvm.compiler.used``' Global Variable -------------------------------------------- @@ -2897,6 +2987,8 @@ by ``@llvm.used``. This is a rare construct that should only be used in rare circumstances, and should not be exposed to source languages. +.. _gv_llvmglobalctors: + The '``llvm.global_ctors``' Global Variable ------------------------------------------- @@ -2911,6 +3003,8 @@ array will be called in ascending order of priority (i.e. lowest first) when the module is loaded. The order of functions with the same priority is not defined. +.. _llvmglobaldtors: + The '``llvm.global_dtors``' Global Variable ------------------------------------------- @@ -3997,7 +4091,7 @@ Example: <result> = lshr i32 4, 1 ; yields {i32}:result = 2 <result> = lshr i32 4, 2 ; yields {i32}:result = 1 <result> = lshr i8 4, 3 ; yields {i8}:result = 0 - <result> = lshr i8 -2, 1 ; yields {i8}:result = 0x7FFFFFFF + <result> = lshr i8 -2, 1 ; yields {i8}:result = 0x7F <result> = lshr i32 1, 32 ; undefined <result> = lshr <2 x i32> < i32 -2, i32 4>, < i32 1, i32 2> ; yields: result=<2 x i32> < i32 0x7FFFFFFF, i32 1> @@ -4534,7 +4628,7 @@ The '``load``' instruction is used to read from memory. Arguments: """""""""" -The argument to the '``load``' instruction specifies the memory address +The argument to the ``load`` instruction specifies the memory address from which to load. The pointer must point to a :ref:`first class <t_firstclass>` type. If the ``load`` is marked as ``volatile``, then the optimizer is not allowed to modify the number or order of @@ -4555,23 +4649,23 @@ any defined semantics for atomic loads. The optional constant ``align`` argument specifies the alignment of the operation (that is, the alignment of the memory address). A value of 0 -or an omitted ``align`` argument means that the operation has the abi +or an omitted ``align`` argument means that the operation has the ABI alignment for the target. It is the responsibility of the code emitter to ensure that the alignment information is correct. Overestimating the alignment results in undefined behavior. Underestimating the alignment may produce less efficient code. An alignment of 1 is always safe. The optional ``!nontemporal`` metadata must reference a single -metatadata name <index> corresponding to a metadata node with one +metadata name ``<index>`` corresponding to a metadata node with one ``i32`` entry of value 1. The existence of the ``!nontemporal`` -metatadata on the instruction tells the optimizer and code generator +metadata on the instruction tells the optimizer and code generator that this load is not expected to be reused in the cache. The code generator may select special instructions to save cache bandwidth, such as the ``MOVNT`` instruction on x86. The optional ``!invariant.load`` metadata must reference a single -metatadata name <index> corresponding to a metadata node with no -entries. The existence of the ``!invariant.load`` metatadata on the +metadata name ``<index>`` corresponding to a metadata node with no +entries. The existence of the ``!invariant.load`` metadata on the instruction tells the optimizer and code generator that this load address points to memory which does not change value during program execution. The optimizer may then move this load around, for example, by @@ -4618,10 +4712,10 @@ The '``store``' instruction is used to write to memory. Arguments: """""""""" -There are two arguments to the '``store``' instruction: a value to store -and an address at which to store it. The type of the '``<pointer>``' +There are two arguments to the ``store`` instruction: a value to store +and an address at which to store it. The type of the ``<pointer>`` operand must be a pointer to the :ref:`first class <t_firstclass>` type of -the '``<value>``' operand. If the ``store`` is marked as ``volatile``, +the ``<value>`` operand. If the ``store`` is marked as ``volatile``, then the optimizer is not allowed to modify the number or order of execution of this ``store`` with other :ref:`volatile operations <volatile>`. @@ -4638,18 +4732,18 @@ has undefined behavior if the alignment is not set to a value which is at least the size in bytes of the pointee. ``!nontemporal`` does not have any defined semantics for atomic stores. -The optional constant "align" argument specifies the alignment of the +The optional constant ``align`` argument specifies the alignment of the operation (that is, the alignment of the memory address). A value of 0 -or an omitted "align" argument means that the operation has the abi +or an omitted ``align`` argument means that the operation has the ABI alignment for the target. It is the responsibility of the code emitter to ensure that the alignment information is correct. Overestimating the -alignment results in an undefined behavior. Underestimating the +alignment results in undefined behavior. Underestimating the alignment may produce less efficient code. An alignment of 1 is always safe. -The optional !nontemporal metadata must reference a single metatadata -name <index> corresponding to a metadata node with one i32 entry of -value 1. The existence of the !nontemporal metatadata on the instruction +The optional ``!nontemporal`` metadata must reference a single metadata +name ``<index>`` corresponding to a metadata node with one ``i32`` entry of +value 1. The existence of the ``!nontemporal`` metadata on the instruction tells the optimizer and code generator that this load is not expected to be reused in the cache. The code generator may select special instructions to save cache bandwidth, such as the MOVNT instruction on @@ -4658,8 +4752,8 @@ x86. Semantics: """""""""" -The contents of memory are updated to contain '``<value>``' at the -location specified by the '``<pointer>``' operand. If '``<value>``' is +The contents of memory are updated to contain ``<value>`` at the +location specified by the ``<pointer>`` operand. If ``<value>`` is of scalar type then the number of bytes written does not exceed the minimum number of bytes needed to hold all bits of the type. For example, storing an ``i24`` writes at most three bytes. When writing a @@ -5521,24 +5615,24 @@ Arguments: The '``bitcast``' instruction takes a value to cast, which must be a non-aggregate first class value, and a type to cast it to, which must -also be a non-aggregate :ref:`first class <t_firstclass>` type. The bit -sizes of ``value`` and the destination type, ``ty2``, must be identical. -If the source type is a pointer, the destination type must also be a -pointer. This instruction supports bitwise conversion of vectors to -integers and to vectors of other types (as long as they have the same -size). +also be a non-aggregate :ref:`first class <t_firstclass>` type. The +bit sizes of ``value`` and the destination type, ``ty2``, must be +identical. If the source type is a pointer, the destination type must +also be a pointer of the same size. This instruction supports bitwise +conversion of vectors to integers and to vectors of other types (as +long as they have the same size). Semantics: """""""""" -The '``bitcast``' instruction converts ``value`` to type ``ty2``. It is -always a *no-op cast* because no bits change with this conversion. The -conversion is done as if the ``value`` had been stored to memory and -read back as type ``ty2``. Pointer (or vector of pointers) types may -only be converted to other pointer (or vector of pointers) types with -this instruction. To convert pointers to other types, use the -:ref:`inttoptr <i_inttoptr>` or :ref:`ptrtoint <i_ptrtoint>` instructions -first. +The '``bitcast``' instruction converts ``value`` to type ``ty2``. It +is always a *no-op cast* because no bits change with this +conversion. The conversion is done as if the ``value`` had been stored +to memory and read back as type ``ty2``. Pointer (or vector of +pointers) types may only be converted to other pointer (or vector of +pointers) types with this instruction if the pointer sizes are +equal. To convert pointers to other types, use the :ref:`inttoptr +<i_inttoptr>` or :ref:`ptrtoint <i_ptrtoint>` instructions first. Example: """""""" @@ -6647,6 +6741,9 @@ memory. Implementations are allowed to either return a application specific value or a system wide value. On backends without support, this is lowered to a constant 0. +Note that runtime support may be conditional on the privilege-level code is +running at and the host platform. + Standard C Library Intrinsics ----------------------------- @@ -8342,6 +8439,46 @@ strings. This can be useful for special purpose optimizations that want to look for these annotations. These have no other defined use; they are ignored by code generation and optimization. +'``llvm.ptr.annotation.*``' Intrinsic +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Syntax: +""""""" + +This is an overloaded intrinsic. You can use '``llvm.ptr.annotation``' on a +pointer to an integer of any width. *NOTE* you must specify an address space for +the pointer. The identifier for the default address space is the integer +'``0``'. + +:: + + declare i8* @llvm.ptr.annotation.p<address space>i8(i8* <val>, i8* <str>, i8* <str>, i32 <int>) + declare i16* @llvm.ptr.annotation.p<address space>i16(i16* <val>, i8* <str>, i8* <str>, i32 <int>) + declare i32* @llvm.ptr.annotation.p<address space>i32(i32* <val>, i8* <str>, i8* <str>, i32 <int>) + declare i64* @llvm.ptr.annotation.p<address space>i64(i64* <val>, i8* <str>, i8* <str>, i32 <int>) + declare i256* @llvm.ptr.annotation.p<address space>i256(i256* <val>, i8* <str>, i8* <str>, i32 <int>) + +Overview: +""""""""" + +The '``llvm.ptr.annotation``' intrinsic. + +Arguments: +"""""""""" + +The first argument is a pointer to an integer value of arbitrary bitwidth +(result of some expression), the second is a pointer to a global string, the +third is a pointer to a global string which is the source file name, and the +last argument is the line number. It returns the value of the first argument. + +Semantics: +"""""""""" + +This intrinsic allows annotation of a pointer to an integer with arbitrary +strings. This can be useful for special purpose optimizations that want to look +for these annotations. These have no other defined use; they are ignored by code +generation and optimization. + '``llvm.annotation.*``' Intrinsic ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/MakefileGuide.rst b/docs/MakefileGuide.rst index 3e90907..0bb4a3c 100644 --- a/docs/MakefileGuide.rst +++ b/docs/MakefileGuide.rst @@ -172,26 +172,6 @@ intend to be loaded into an tool via the ``-load`` option. `Pass documentation <writing-an-llvm-pass-makefile>`_ has an example of why you might want to do this. -Bitcode Modules -^^^^^^^^^^^^^^^ - -In some situations, it is desirable to build a single bitcode module from a -variety of sources, instead of an archive, shared library, or bitcode -library. Bitcode modules can be specified in addition to any of the other types -of libraries by defining the `MODULE_NAME`_ variable. For example: - -.. code-block:: makefile - - LIBRARYNAME = mylib - BYTECODE_LIBRARY = 1 - MODULE_NAME = mymod - -will build a module named ``mymod.bc`` from the sources in the directory. This -module will be an aggregation of all the bitcode modules derived from the -sources. The example will also build a bitcode archive containing a bitcode -module for each compiled source file. The difference is subtle, but important -depending on how the module or library is to be linked. - Loadable Modules ^^^^^^^^^^^^^^^^ @@ -486,9 +466,6 @@ system that tell it what to do for the current directory. files. These sources will be built before any other target processing to ensure they are present. -``BYTECODE_LIBRARY`` - If set to any value, causes a bitcode library (.bc) to be built. - ``CONFIG_FILES`` Specifies a set of configuration files to be installed. @@ -590,13 +567,6 @@ system that tell it what to do for the current directory. setting this variable without also setting ``SHARED_LIBRARY`` will have no effect. -.. _MODULE_NAME: - -``MODULE_NAME`` - Specifies the name of a bitcode module to be created. A bitcode module can - be specified in conjunction with other kinds of library builds or by - itself. It constructs from the sources a single linked bitcode file. - ``NO_INSTALL`` Specifies that the build products of the directory should not be installed but should be built even if the ``install`` target is given. This is handy @@ -739,12 +709,6 @@ The override variables are given below: ``LLVMAS`` (defaulted) Specifies the path to the ``llvm-as`` tool. -``LLVMCC`` - Specifies the path to the LLVM capable compiler. - -``LLVMCXX`` - Specifies the path to the LLVM C++ capable compiler. - ``LLVMGCC`` (defaulted) Specifies the path to the LLVM version of the GCC 'C' Compiler. @@ -888,8 +852,6 @@ internal. You should not use these variables under any circumstances. Archive AR.Flags BaseNameSources - BCCompile.C - BCCompile.CXX BCLinkLib C.Flags Compile.C @@ -936,7 +898,6 @@ internal. You should not use these variables under any circumstances. LLVMUsedLibs LocalTargets Module - ObjectsBC ObjectsLO ObjectsO ObjMakefiles diff --git a/docs/NVPTXUsage.rst b/docs/NVPTXUsage.rst new file mode 100644 index 0000000..5451619 --- /dev/null +++ b/docs/NVPTXUsage.rst @@ -0,0 +1,276 @@ +============================= +User Guide for NVPTX Back-end +============================= + +.. contents:: + :local: + :depth: 3 + + +Introduction +============ + +To support GPU programming, the NVPTX back-end supports a subset of LLVM IR +along with a defined set of conventions used to represent GPU programming +concepts. This document provides an overview of the general usage of the back- +end, including a description of the conventions used and the set of accepted +LLVM IR. + +.. note:: + + This document assumes a basic familiarity with CUDA and the PTX + assembly language. Information about the CUDA Driver API and the PTX assembly + language can be found in the `CUDA documentation + <http://docs.nvidia.com/cuda/index.html>`_. + + + +Conventions +=========== + +Marking Functions as Kernels +---------------------------- + +In PTX, there are two types of functions: *device functions*, which are only +callable by device code, and *kernel functions*, which are callable by host +code. By default, the back-end will emit device functions. Metadata is used to +declare a function as a kernel function. This metadata is attached to the +``nvvm.annotations`` named metadata object, and has the following format: + +.. code-block:: llvm + + !0 = metadata !{<function-ref>, metadata !"kernel", i32 1} + +The first parameter is a reference to the kernel function. The following +example shows a kernel function calling a device function in LLVM IR. The +function ``@my_kernel`` is callable from host code, but ``@my_fmad`` is not. + +.. code-block:: llvm + + define float @my_fmad(float %x, float %y, float %z) { + %mul = fmul float %x, %y + %add = fadd float %mul, %z + ret float %add + } + + define void @my_kernel(float* %ptr) { + %val = load float* %ptr + %ret = call float @my_fmad(float %val, float %val, float %val) + store float %ret, float* %ptr + ret void + } + + !nvvm.annotations = !{!1} + !1 = metadata !{void (float*)* @my_kernel, metadata !"kernel", i32 1} + +When compiled, the PTX kernel functions are callable by host-side code. + + +Address Spaces +-------------- + +The NVPTX back-end uses the following address space mapping: + + ============= ====================== + Address Space Memory Space + ============= ====================== + 0 Generic + 1 Global + 2 Internal Use + 3 Shared + 4 Constant + 5 Local + ============= ====================== + +Every global variable and pointer type is assigned to one of these address +spaces, with 0 being the default address space. Intrinsics are provided which +can be used to convert pointers between the generic and non-generic address +spaces. + +As an example, the following IR will define an array ``@g`` that resides in +global device memory. + +.. code-block:: llvm + + @g = internal addrspace(1) global [4 x i32] [ i32 0, i32 1, i32 2, i32 3 ] + +LLVM IR functions can read and write to this array, and host-side code can +copy data to it by name with the CUDA Driver API. + +Note that since address space 0 is the generic space, it is illegal to have +global variables in address space 0. Address space 0 is the default address +space in LLVM, so the ``addrspace(N)`` annotation is *required* for global +variables. + + +NVPTX Intrinsics +================ + +Address Space Conversion +------------------------ + +'``llvm.nvvm.ptr.*.to.gen``' Intrinsics +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Syntax: +""""""" + +These are overloaded intrinsics. You can use these on any pointer types. + +.. code-block:: llvm + + declare i8* @llvm.nvvm.ptr.global.to.gen.p0i8.p1i8(i8 addrspace(1)*) + declare i8* @llvm.nvvm.ptr.shared.to.gen.p0i8.p3i8(i8 addrspace(3)*) + declare i8* @llvm.nvvm.ptr.constant.to.gen.p0i8.p4i8(i8 addrspace(4)*) + declare i8* @llvm.nvvm.ptr.local.to.gen.p0i8.p5i8(i8 addrspace(5)*) + +Overview: +""""""""" + +The '``llvm.nvvm.ptr.*.to.gen``' intrinsics convert a pointer in a non-generic +address space to a generic address space pointer. + +Semantics: +"""""""""" + +These intrinsics modify the pointer value to be a valid generic address space +pointer. + + +'``llvm.nvvm.ptr.gen.to.*``' Intrinsics +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Syntax: +""""""" + +These are overloaded intrinsics. You can use these on any pointer types. + +.. code-block:: llvm + + declare i8* @llvm.nvvm.ptr.gen.to.global.p1i8.p0i8(i8 addrspace(1)*) + declare i8* @llvm.nvvm.ptr.gen.to.shared.p3i8.p0i8(i8 addrspace(3)*) + declare i8* @llvm.nvvm.ptr.gen.to.constant.p4i8.p0i8(i8 addrspace(4)*) + declare i8* @llvm.nvvm.ptr.gen.to.local.p5i8.p0i8(i8 addrspace(5)*) + +Overview: +""""""""" + +The '``llvm.nvvm.ptr.gen.to.*``' intrinsics convert a pointer in the generic +address space to a pointer in the target address space. Note that these +intrinsics are only useful if the address space of the target address space of +the pointer is known. It is not legal to use address space conversion +intrinsics to convert a pointer from one non-generic address space to another +non-generic address space. + +Semantics: +"""""""""" + +These intrinsics modify the pointer value to be a valid pointer in the target +non-generic address space. + + +Reading PTX Special Registers +----------------------------- + +'``llvm.nvvm.read.ptx.sreg.*``' +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Syntax: +""""""" + +.. code-block:: llvm + + declare i32 @llvm.nvvm.read.ptx.sreg.tid.x() + declare i32 @llvm.nvvm.read.ptx.sreg.tid.y() + declare i32 @llvm.nvvm.read.ptx.sreg.tid.z() + declare i32 @llvm.nvvm.read.ptx.sreg.ntid.x() + declare i32 @llvm.nvvm.read.ptx.sreg.ntid.y() + declare i32 @llvm.nvvm.read.ptx.sreg.ntid.z() + declare i32 @llvm.nvvm.read.ptx.sreg.ctaid.x() + declare i32 @llvm.nvvm.read.ptx.sreg.ctaid.y() + declare i32 @llvm.nvvm.read.ptx.sreg.ctaid.z() + declare i32 @llvm.nvvm.read.ptx.sreg.nctaid.x() + declare i32 @llvm.nvvm.read.ptx.sreg.nctaid.y() + declare i32 @llvm.nvvm.read.ptx.sreg.nctaid.z() + declare i32 @llvm.nvvm.read.ptx.sreg.warpsize() + +Overview: +""""""""" + +The '``@llvm.nvvm.read.ptx.sreg.*``' intrinsics provide access to the PTX +special registers, in particular the kernel launch bounds. These registers +map in the following way to CUDA builtins: + + ============ ===================================== + CUDA Builtin PTX Special Register Intrinsic + ============ ===================================== + ``threadId`` ``@llvm.nvvm.read.ptx.sreg.tid.*`` + ``blockIdx`` ``@llvm.nvvm.read.ptx.sreg.ctaid.*`` + ``blockDim`` ``@llvm.nvvm.read.ptx.sreg.ntid.*`` + ``gridDim`` ``@llvm.nvvm.read.ptx.sreg.nctaid.*`` + ============ ===================================== + + +Barriers +-------- + +'``llvm.nvvm.barrier0``' +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Syntax: +""""""" + +.. code-block:: llvm + + declare void @llvm.nvvm.barrier0() + +Overview: +""""""""" + +The '``@llvm.nvvm.barrier0()``' intrinsic emits a PTX ``bar.sync 0`` +instruction, equivalent to the ``__syncthreads()`` call in CUDA. + + +Other Intrinsics +---------------- + +For the full set of NVPTX intrinsics, please see the +``include/llvm/IR/IntrinsicsNVVM.td`` file in the LLVM source tree. + + +Executing PTX +============= + +The most common way to execute PTX assembly on a GPU device is to use the CUDA +Driver API. This API is a low-level interface to the GPU driver and allows for +JIT compilation of PTX code to native GPU machine code. + +Initializing the Driver API: + +.. code-block:: c++ + + CUdevice device; + CUcontext context; + + // Initialize the driver API + cuInit(0); + // Get a handle to the first compute device + cuDeviceGet(&device, 0); + // Create a compute device context + cuCtxCreate(&context, 0, device); + +JIT compiling a PTX string to a device binary: + +.. code-block:: c++ + + CUmodule module; + CUfunction funcion; + + // JIT compile a null-terminated PTX string + cuModuleLoadData(&module, (void*)PTXString); + + // Get a handle to the "myfunction" kernel function + cuModuleGetFunction(&function, module, "myfunction"); + +For full examples of executing PTX assembly, please see the `CUDA Samples +<https://developer.nvidia.com/cuda-downloads>`_ distribution. diff --git a/docs/Passes.rst b/docs/Passes.rst index 9cb8ba0..d30c3ca 100644 --- a/docs/Passes.rst +++ b/docs/Passes.rst @@ -490,7 +490,7 @@ string is available. ``-constprop``: Simple constant propagation ------------------------------------------- -This file implements constant propagation and merging. It looks for +This pass implements constant propagation and merging. It looks for instructions involving only constant operands and replaces them with a constant value instead of an instruction. For example: @@ -505,8 +505,8 @@ becomes i32 3 NOTE: this pass has a habit of making definitions be dead. It is a good idea -to to run a :ref:`Dead Instruction Elimination <passes-die>` pass sometime -after running this pass. +to run a :ref:`Dead Instruction Elimination <passes-die>` pass sometime after +running this pass. .. _passes-dce: @@ -1018,8 +1018,8 @@ possible, it transforms the individual ``alloca`` instructions into nice clean scalar SSA form. This combines a simple scalar replacement of aggregates algorithm with the -:ref:`mem2reg <passes-mem2reg>` algorithm because often interact, especially -for C++ programs. As such, iterating between ``scalarrepl``, then +:ref:`mem2reg <passes-mem2reg>` algorithm because they often interact, +especially for C++ programs. As such, iterating between ``scalarrepl``, then :ref:`mem2reg <passes-mem2reg>` until we run out of things to promote works well. @@ -1037,7 +1037,7 @@ as: * Proves conditional branches to be unconditional Note that this pass has a habit of making definitions be dead. It is a good -idea to to run a :ref:`DCE <passes-dce>` pass sometime after running this pass. +idea to run a :ref:`DCE <passes-dce>` pass sometime after running this pass. ``-simplify-libcalls``: Simplify well-known library calls --------------------------------------------------------- diff --git a/docs/Phabricator.rst b/docs/Phabricator.rst index efab10c..0c6990e 100644 --- a/docs/Phabricator.rst +++ b/docs/Phabricator.rst @@ -56,7 +56,7 @@ to upload your patch): To upload a new patch: * Click *Differential*. -* Click *Create Revision*. +* Click *Create Diff*. * Paste the text diff or upload the patch file. Note that TODO * Leave the drop down on *Create a new Revision...* and click *Continue*. diff --git a/docs/ProgrammersManual.rst b/docs/ProgrammersManual.rst index 4fc4597..2910a2a 100644 --- a/docs/ProgrammersManual.rst +++ b/docs/ProgrammersManual.rst @@ -626,6 +626,33 @@ SmallVectors are most useful when on the stack. SmallVector also provides a nice portable and efficient replacement for ``alloca``. +.. note:: + + Prefer to use ``SmallVectorImpl<T>`` as a parameter type. + + In APIs that don't care about the "small size" (most?), prefer to use + the ``SmallVectorImpl<T>`` class, which is basically just the "vector + header" (and methods) without the elements allocated after it. Note that + ``SmallVector<T, N>`` inherits from ``SmallVectorImpl<T>`` so the + conversion is implicit and costs nothing. E.g. + + .. code-block:: c++ + + // BAD: Clients cannot pass e.g. SmallVector<Foo, 4>. + hardcodedSmallSize(SmallVector<Foo, 2> &Out); + // GOOD: Clients can pass any SmallVector<Foo, N>. + allowsAnySmallSize(SmallVectorImpl<Foo> &Out); + + void someFunc() { + SmallVector<Foo, 8> Vec; + hardcodedSmallSize(Vec); // Error. + allowsAnySmallSize(Vec); // Works. + } + + Even though it has "``Impl``" in the name, this is so widely used that + it really isn't "private to the implementation" anymore. A name like + ``SmallVectorHeader`` would be more appropriate. + .. _dss_vector: <vector> @@ -989,7 +1016,9 @@ coupled with a good choice of :ref:`sequential container <ds_sequential>`. This combination provides the several nice properties: the result data is contiguous in memory (good for cache locality), has few allocations, is easy to address (iterators in the final vector are just indices or pointers), and can be -efficiently queried with a standard binary or radix search. +efficiently queried with a standard binary search (e.g. +``std::lower_bound``; if you want the whole range of elements comparing +equal, use ``std::equal_range``). .. _dss_smallset: @@ -2392,7 +2421,7 @@ place the ``vptr`` in the first word of the instances.) The Core LLVM Class Hierarchy Reference ======================================= -``#include "llvm/Type.h"`` +``#include "llvm/IR/Type.h"`` header source: `Type.h <http://llvm.org/doxygen/Type_8h-source.html>`_ @@ -2495,7 +2524,7 @@ Important Derived Types The ``Module`` class -------------------- -``#include "llvm/Module.h"`` +``#include "llvm/IR/Module.h"`` header source: `Module.h <http://llvm.org/doxygen/Module_8h-source.html>`_ @@ -2582,7 +2611,7 @@ Important Public Members of the ``Module`` class The ``Value`` class ------------------- -``#include "llvm/Value.h"`` +``#include "llvm/IR/Value.h"`` header source: `Value.h <http://llvm.org/doxygen/Value_8h-source.html>`_ @@ -2673,7 +2702,7 @@ Important Public Members of the ``Value`` class The ``User`` class ------------------ -``#include "llvm/User.h"`` +``#include "llvm/IR/User.h"`` header source: `User.h <http://llvm.org/doxygen/User_8h-source.html>`_ @@ -2719,7 +2748,7 @@ interface and through an iterator based interface. The ``Instruction`` class ------------------------- -``#include "llvm/Instruction.h"`` +``#include "llvm/IR/Instruction.h"`` header source: `Instruction.h <http://llvm.org/doxygen/Instruction_8h-source.html>`_ @@ -2867,7 +2896,7 @@ Important Subclasses of Constant The ``GlobalValue`` class ------------------------- -``#include "llvm/GlobalValue.h"`` +``#include "llvm/IR/GlobalValue.h"`` header source: `GlobalValue.h <http://llvm.org/doxygen/GlobalValue_8h-source.html>`_ @@ -2926,7 +2955,7 @@ Important Public Members of the ``GlobalValue`` class The ``Function`` class ---------------------- -``#include "llvm/Function.h"`` +``#include "llvm/IR/Function.h"`` header source: `Function.h <http://llvm.org/doxygen/Function_8h-source.html>`_ @@ -3034,7 +3063,7 @@ Important Public Members of the ``Function`` The ``GlobalVariable`` class ---------------------------- -``#include "llvm/GlobalVariable.h"`` +``#include "llvm/IR/GlobalVariable.h"`` header source: `GlobalVariable.h <http://llvm.org/doxygen/GlobalVariable_8h-source.html>`_ @@ -3092,7 +3121,7 @@ Important Public Members of the ``GlobalVariable`` class The ``BasicBlock`` class ------------------------ -``#include "llvm/BasicBlock.h"`` +``#include "llvm/IR/BasicBlock.h"`` header source: `BasicBlock.h <http://llvm.org/doxygen/BasicBlock_8h-source.html>`_ diff --git a/docs/ReleaseNotes.rst b/docs/ReleaseNotes.rst index 822b55f..7b143f6 100644 --- a/docs/ReleaseNotes.rst +++ b/docs/ReleaseNotes.rst @@ -1,13 +1,13 @@ ====================== -LLVM 3.3 Release Notes +LLVM 3.4 Release Notes ====================== .. contents:: :local: .. warning:: - These are in-progress notes for the upcoming LLVM 3.3 release. You may - prefer the `LLVM 3.2 Release Notes <http://llvm.org/releases/3.2/docs + These are in-progress notes for the upcoming LLVM 3.4 release. You may + prefer the `LLVM 3.3 Release Notes <http://llvm.org/releases/3.3/docs /ReleaseNotes.html>`_. @@ -15,7 +15,7 @@ Introduction ============ This document contains the release notes for the LLVM Compiler Infrastructure, -release 3.3. Here we describe the status of LLVM, including major improvements +release 3.4. Here we describe the status of LLVM, including major improvements from the previous release, improvements in various subprojects of LLVM, and some of the current users of the code. All LLVM releases may be downloaded from the `LLVM releases web site <http://llvm.org/releases/>`_. @@ -41,28 +41,34 @@ Non-comprehensive list of changes in this release functionality, or simply have a lot to talk about), see the `NOTE` below for adding a new subsection. -* The CellSPU port has been removed. It can still be found in older versions. +* The regression tests now fail if any command in a pipe fails. To disable it in + a directory, just add ``config.pipefail = False`` to its ``lit.local.cfg``. + See :doc:`Lit <CommandGuide/lit>` for the details. -* The IR-level extended linker APIs (for example, to link bitcode files out of - archives) have been removed. Any existing clients of these features should - move to using a linker with integrated LTO support. +* Support for exception handling has been removed from the old JIT. Use MCJIT + if you need EH support. -* LLVM and Clang's documentation has been migrated to the `Sphinx - <http://sphinx-doc.org/>`_ documentation generation system which uses - easy-to-write reStructuredText. See `llvm/docs/README.txt` for more - information. +* The R600 backend is not marked experimental anymore and is built by default. -* TargetTransformInfo (TTI) is a new interface that can be used by IR-level - passes to obtain target-specific information, such as the costs of - instructions. Only "Lowering" passes such as LSR and the vectorizer are - allowed to use the TTI infrastructure. +* APFloat::isNormal() was renamed to APFloat::isFiniteNonZero() and + APFloat::isIEEENormal() was renamed to APFloat::isNormal(). This ensures that + APFloat::isNormal() conforms to IEEE-754R-2008. -* We've improved the X86 and ARM cost model. +* The library call simplification pass has been removed. Its functionality + has been integrated into the instruction combiner and function attribute + marking passes. -* The Attributes classes have been completely rewritten and expanded. They now - support not only enumerated attributes and alignments, but "string" - attributes, which are useful for passing information to code generation. See - :doc:`HowToUseAttributes` for more details. +* Support for building using Visual Studio 2008 has been dropped. Use VS 2010 + or later instead. For more information, see the `Getting Started using Visual + Studio <GettingStartedVS.html>`_ page. + +* The Loop Vectorizer that was previously enabled for -O3 is now enabled for + -Os and -O2. + +* The new SLP Vectorizer is now enabled by default. + +* llvm-ar now uses the new Object library and produces archives and + symbol tables in the gnu format. * ... next change ... @@ -76,51 +82,13 @@ Non-comprehensive list of changes in this release Makes programs 10x faster by doing Special New Thing. -AArch64 target --------------- - -We've added support for AArch64, ARM's 64-bit architecture. Development is still -in fairly early stages, but we expect successful compilation when: - -- compiling standard compliant C99 and C++03 with Clang; -- using Linux as a target platform; -- where code + static data doesn't exceed 4GB in size (heap allocated data has - no limitation). - -Some additional functionality is also implemented, notably DWARF debugging, -GNU-style thread local storage and inline assembly. - -Hexagon Target --------------- - -- Removed support for legacy hexagonv2 and hexagonv3 processor - architectures which are no longer in use. Currently supported - architectures are hexagonv4 and hexagonv5. - -Loop Vectorizer ---------------- - -We've continued the work on the loop vectorizer. The loop vectorizer now -has the following features: - -- Loops with unknown trip count. -- Runtime checks of pointers -- Reductions, Inductions -- If Conversion -- Pointer induction variables -- Reverse iterators -- Vectorization of mixed types -- Vectorization of function calls -- Partial unrolling during vectorization - -R600 Backend ------------- -The R600 backend was added in this release, it supports AMD GPUs -(HD2XXX - HD7XXX). This backend is used in AMD's Open Source -graphics / compute drivers which are developed as part of the `Mesa3D -<http://www.mesa3d.org>`_ project. +External Open Source Projects Using LLVM 3.4 +============================================ +An exciting aspect of LLVM is that it is used as an enabling technology for +a lot of other language and tools projects. This section lists some of the +projects that have already been updated to work with LLVM 3.4. Additional Information diff --git a/docs/ReleaseProcess.rst b/docs/ReleaseProcess.rst new file mode 100644 index 0000000..c4bbc91 --- /dev/null +++ b/docs/ReleaseProcess.rst @@ -0,0 +1,210 @@ +============================= +How To Validate a New Release +============================= + +.. contents:: + :local: + :depth: 1 + +Introduction +============ + +This document contains information about testing the release candidates that will +ultimately be the next LLVM release. For more information on how to manage the +actual release, please refer to :doc:`HowToReleaseLLVM`. + +Overview of the Release Process +------------------------------- + +Once the release process starts, the Release Manager will ask for volunteers, +and it'll be the role of each volunteer to: + +* Test and benchmark the previous release + +* Test and benchmark each release candidate, comparing to the previous release and candidates + +* Identify, reduce and report every regression found during tests and benchmarks + +* Make sure the critical bugs get fixed and merged to the next release candidate + +Not all bugs or regressions are show-stoppers and it's a bit of a grey area what +should be fixed before the next candidate and what can wait until the next release. + +It'll depend on: + +* The severity of the bug, how many people it affects and if it's a regression or a + known bug. Known bugs are "unsupported features" and some bugs can be disabled if + they have been implemented recently. + +* The stage in the release. Less critical bugs should be considered to be fixed between + RC1 and RC2, but not so much at the end of it. + +* If it's a correctness or a performance regression. Performance regression tends to be + taken more lightly than correctness. + +.. _scripts: + +Scripts +======= + +The scripts are in the ``utils/release`` directory. + +test-release.sh +--------------- + +This script will check-out, configure and compile LLVM+Clang (+ most add-ons, like ``compiler-rt``, +``libcxx`` and ``clang-extra-tools``) in three stages, and will test the final stage. +It'll have installed the final binaries on the Phase3/Releasei(+Asserts) directory, and +that's the one you should use for the test-suite and other external tests. + +To run the script on a specific release candidate run:: + + ./test-release.sh \ + -release 3.3 \ + -rc 1 \ + -no-64bit \ + -test-asserts \ + -no-compare-files + +Each system will require different options. For instance, x86_64 will obviously not need +``-no-64bit`` while 32-bit systems will, or the script will fail. + +The important flags to get right are: + +* On the pre-release, you should change ``-rc 1`` to ``-final``. On RC2, change it to ``-rc 2`` and so on. + +* On non-release testing, you can use ``-final`` in conjunction with ``-no-checkout``, but you'll have to + create the ``final`` directory by hand and link the correct source dir to ``final/llvm.src``. + +* For release candidates, you need ``-test-asserts``, or it won't create a "Release+Asserts" directory, + which is needed for release testing and benchmarking. This will take twice as long. + +* On the final candidate you just need Release builds, and that's the binary directory you'll have to pack. + +This script builds three phases of Clang+LLVM twice each (Release and Release+Asserts), so use +screen or nohup to avoid headaches, since it'll take a long time. + +Use the ``--help`` option to see all the options and chose it according to your needs. + + +findRegressions-nightly.py +-------------------------- + +TODO + +.. _test-suite: + +Test Suite +========== + +.. contents:: + :local: + +Follow the `LNT Quick Start Guide <http://llvm.org/docs/lnt/quickstart.html>`__ link on how to set-up the test-suite + +The binary location you'll have to use for testing is inside the ``rcN/Phase3/Release+Asserts/llvmCore-REL-RC.install``. +Link that directory to an easier location and run the test-suite. + +An example on the run command line, assuming you created a link from the correct +install directory to ``~/devel/llvm/install``:: + + ./sandbox/bin/python sandbox/bin/lnt runtest \ + nt \ + -j4 \ + --sandbox sandbox \ + --test-suite ~/devel/llvm/test/test-suite \ + --cc ~/devel/llvm/install/bin/clang \ + --cxx ~/devel/llvm/install/bin/clang++ + +It should have no new regressions, compared to the previous release or release candidate. You don't need to fix +all the bugs in the test-suite, since they're not necessarily meant to pass on all architectures all the time. This is +due to the nature of the result checking, which relies on direct comparison, and most of the time, the failures are +related to bad output checking, rather than bad code generation. + +If the errors are in LLVM itself, please report every single regression found as blocker, and all the other bugs +as important, but not necessarily blocking the release to proceed. They can be set as "known failures" and to be +fix on a future date. + +.. _pre-release-process: + +Pre-Release Process +=================== + +.. contents:: + :local: + +When the release process is announced on the mailing list, you should prepare +for the testing, by applying the same testing you'll do on the release candidates, +on the previous release. + +You should: + +* Download the previous release sources from http://llvm.org/releases/download.html. + +* Run the test-release.sh script on ``final`` mode (change ``-rc 1`` to ``-final``). + +* Once all three stages are done, it'll test the final stage. + +* Using the ``Phase3/Release+Asserts/llvmCore-MAJ.MIN-final.install`` base, run the test-suite. + +If the final phase's ``make check-all`` failed, it's a good idea to also test the +intermediate stages by going on the obj directory and running ``make check-all`` to find +if there's at least one stage that passes (helps when reducing the error for bug report +purposes). + +.. _release-process: + +Release Process +=============== + +.. contents:: + :local: + +When the Release Manager sends you the release candidate, download all sources, +unzip on the same directory (there will be sym-links from the appropriate places +to them), and run the release test as above. + +You should: + +* Download the current candidate sources from where the release manager points you + (ex. http://llvm.org/pre-releases/3.3/rc1/). + +* Repeat the steps above with ``-rc 1``, ``-rc 2`` etc modes and run the test-suite + the same way. + +* Compare the results, report all errors on Bugzilla and publish the binary blob + where the release manager can grab it. + +Once the release manages announces that the latest candidate is the good one, you +have to pack the ``Release`` (no Asserts) install directory on ``Phase3`` and that +will be the official binary. + +* Rename (or link) ``clang+llvm-REL-ARCH-ENV`` to the .install directory + +* Tar that into the same name with ``.tar.gz`` extensioan from outside the directory + +* Make it available for the release manager to download + +.. _bug-reporting: + +Bug Reporting Process +===================== + +.. contents:: + :local: + +If you found regressions or failures when comparing a release candidate with the +previous release, follow the rules below: + +* Critical bugs on compilation should be fixed as soon as possible, possibly before + releasing the binary blobs. + +* Check-all tests should be fixed before the next release candidate, but can wait + until the test-suite run is finished. + +* Bugs in the test suite or unimportant check-all tests can be fixed in between + release candidates. + +* New features or recent big changes, when close to the release, should have done + in a way that it's easy to disable. If they misbehave, prefer disabling them than + releasing an unstable (but untested) binary package. diff --git a/docs/SourceLevelDebugging.rst b/docs/SourceLevelDebugging.rst index 16fa7f0..ad03871 100644 --- a/docs/SourceLevelDebugging.rst +++ b/docs/SourceLevelDebugging.rst @@ -169,9 +169,7 @@ provides a specification for well formed debug descriptors. Consumers of LLVM debug information expect the descriptors for program objects to start in a canonical format, but the descriptors can include additional -information appended at the end that is source-language specific. All LLVM -debugging information is versioned, allowing backwards compatibility in the -case that the core structures need to change in some way. Also, all debugging +information appended at the end that is source-language specific. All debugging information objects start with a tag to indicate what type of object it is. The source-language is allowed to define its own objects, by using unreserved tag numbers. We recommend using with tags in the range 0x1000 through 0x2000 @@ -192,10 +190,7 @@ the simple data types ``i32``, ``i1``, ``float``, ``double``, ``mdstring`` and ``i32`` containing a tag value identifying the content of the descriptor. The remaining fields are specific to the descriptor. The values of tags are loosely bound to the tag values of DWARF information entries. However, that -does not restrict the use of the information supplied to DWARF targets. To -facilitate versioning of debug information, the tag is augmented with the -current debug version (``LLVMDebugVersion = 8 << 16`` or 0x80000 or -524288.) +does not restrict the use of the information supplied to DWARF targets. The details of the various descriptors follow. @@ -205,13 +200,10 @@ Compile unit descriptors .. code-block:: llvm !0 = metadata !{ - i32, ;; Tag = 17 + LLVMDebugVersion (DW_TAG_compile_unit) - i32, ;; Unused field. + i32, ;; Tag = 17 (DW_TAG_compile_unit) + metadata, ;; Source directory (including trailing slash) & file pair i32, ;; DWARF language identifier (ex. DW_LANG_C89) - metadata, ;; Source file name - metadata, ;; Source file directory (includes trailing slash) metadata ;; Producer (ex. "4.0.1 LLVM (LLVM research group)") - i1, ;; True if this is a main compile unit. i1, ;; True if this is optimized. metadata, ;; Flags i32 ;; Runtime version @@ -219,18 +211,21 @@ Compile unit descriptors metadata ;; List of retained types metadata ;; List of subprograms metadata ;; List of global variables + metadata ;; List of imported entities + metadata ;; Split debug filename } These descriptors contain a source language ID for the file (we use the DWARF 3.0 ID numbers, such as ``DW_LANG_C89``, ``DW_LANG_C_plus_plus``, -``DW_LANG_Cobol74``, etc), three strings describing the filename, working -directory of the compiler, and an identifier string for the compiler that -produced it. +``DW_LANG_Cobol74``, etc), a reference to a metadata node containing a pair of +strings for the source file name and the working directory, as well as an +identifier string for the compiler that produced it. Compile unit descriptors provide the root context for objects declared in a specific compilation unit. File descriptors are defined using this context. These descriptors are collected by a named metadata ``!llvm.dbg.cu``. They -keep track of subprograms, global variables and type information. +keep track of subprograms, global variables, type information, and imported +entities (declarations and namespaces). .. _format_files: @@ -240,10 +235,8 @@ File descriptors .. code-block:: llvm !0 = metadata !{ - i32, ;; Tag = 41 + LLVMDebugVersion (DW_TAG_file_type) - metadata, ;; Source file name - metadata, ;; Source file directory (includes trailing slash) - metadata ;; Unused + i32, ;; Tag = 41 (DW_TAG_file_type) + metadata, ;; Source directory (including trailing slash) & file pair } These descriptors contain information for a file. Global variables and top @@ -261,7 +254,7 @@ Global variable descriptors .. code-block:: llvm !1 = metadata !{ - i32, ;; Tag = 52 + LLVMDebugVersion (DW_TAG_variable) + i32, ;; Tag = 52 (DW_TAG_variable) i32, ;; Unused field. metadata, ;; Reference to context descriptor metadata, ;; Name @@ -272,7 +265,8 @@ Global variable descriptors metadata, ;; Reference to type descriptor i1, ;; True if the global is local to compile unit (static) i1, ;; True if the global is defined in the compile unit (not extern) - {}* ;; Reference to the global variable + {}*, ;; Reference to the global variable + metadata, ;; The static member declaration, if any } These descriptors provide debug information about globals variables. They @@ -287,13 +281,12 @@ Subprogram descriptors .. code-block:: llvm !2 = metadata !{ - i32, ;; Tag = 46 + LLVMDebugVersion (DW_TAG_subprogram) - i32, ;; Unused field. + i32, ;; Tag = 46 (DW_TAG_subprogram) + metadata, ;; Source directory (including trailing slash) & file pair metadata, ;; Reference to context descriptor metadata, ;; Name metadata, ;; Display name (fully qualified C++ name) metadata, ;; MIPS linkage name (for C++) - metadata, ;; Reference to file where defined i32, ;; Line number where defined metadata, ;; Reference to type descriptor i1, ;; True if the global is local to compile unit (static) @@ -321,11 +314,11 @@ Block descriptors .. code-block:: llvm !3 = metadata !{ - i32, ;; Tag = 11 + LLVMDebugVersion (DW_TAG_lexical_block) + i32, ;; Tag = 11 (DW_TAG_lexical_block) + metadata,;; Source directory (including trailing slash) & file pair metadata,;; Reference to context descriptor i32, ;; Line number i32, ;; Column number - metadata,;; Reference to source file i32 ;; Unique ID to identify blocks from a template function } @@ -336,9 +329,9 @@ lexical blocks at same depth. .. code-block:: llvm !3 = metadata !{ - i32, ;; Tag = 11 + LLVMDebugVersion (DW_TAG_lexical_block) + i32, ;; Tag = 11 (DW_TAG_lexical_block) + metadata,;; Source directory (including trailing slash) & file pair metadata ;; Reference to the scope we're annotating with a file change - metadata,;; Reference to the file the scope is enclosed in. } This descriptor provides a wrapper around a lexical scope to handle file @@ -352,10 +345,10 @@ Basic type descriptors .. code-block:: llvm !4 = metadata !{ - i32, ;; Tag = 36 + LLVMDebugVersion (DW_TAG_base_type) + i32, ;; Tag = 36 (DW_TAG_base_type) + metadata,;; Source directory (including trailing slash) & file pair (may be null) metadata, ;; Reference to context metadata, ;; Name (may be "" for anonymous types) - metadata, ;; Reference to file where defined (may be NULL) i32, ;; Line number where defined (may be 0) i64, ;; Size in bits i64, ;; Alignment in bits @@ -396,9 +389,9 @@ Derived type descriptors !5 = metadata !{ i32, ;; Tag (see below) + metadata,;; Source directory (including trailing slash) & file pair (may be null) metadata, ;; Reference to context metadata, ;; Name (may be "" for anonymous types) - metadata, ;; Reference to file where defined (may be NULL) i32, ;; Line number where defined (may be 0) i64, ;; Size in bits i64, ;; Alignment in bits @@ -459,9 +452,9 @@ Composite type descriptors !6 = metadata !{ i32, ;; Tag (see below) + metadata,;; Source directory (including trailing slash) & file pair (may be null) metadata, ;; Reference to context metadata, ;; Name (may be "" for anonymous types) - metadata, ;; Reference to file where defined (may be NULL) i32, ;; Line number where defined (may be 0) i64, ;; Size in bits i64, ;; Alignment in bits @@ -470,6 +463,8 @@ Composite type descriptors metadata, ;; Reference to type derived from metadata, ;; Reference to array of member descriptors i32 ;; Runtime languages + metadata, ;; Base type containing the vtable pointer for this type + metadata ;; Template parameters } These descriptors are used to define types that are composed of 0 or more @@ -531,7 +526,7 @@ Subrange descriptors .. code-block:: llvm !42 = metadata !{ - i32, ;; Tag = 33 + LLVMDebugVersion (DW_TAG_subrange_type) + i32, ;; Tag = 33 (DW_TAG_subrange_type) i64, ;; Low value i64 ;; High value } @@ -550,7 +545,7 @@ Enumerator descriptors .. code-block:: llvm !6 = metadata !{ - i32, ;; Tag = 40 + LLVMDebugVersion (DW_TAG_enumerator) + i32, ;; Tag = 40 (DW_TAG_enumerator) metadata, ;; Name i64 ;; Value } @@ -654,59 +649,85 @@ Compiled to LLVM, this function would be represented like this: .. code-block:: llvm - define void @foo() nounwind ssp { + define void @_Z3foov() #0 { entry: - %X = alloca i32, align 4 ; <i32*> [#uses=4] - %Y = alloca i32, align 4 ; <i32*> [#uses=4] - %Z = alloca i32, align 4 ; <i32*> [#uses=3] - %0 = bitcast i32* %X to {}* ; <{}*> [#uses=1] - call void @llvm.dbg.declare(metadata !{i32 * %X}, metadata !0), !dbg !7 - store i32 21, i32* %X, !dbg !8 - %1 = bitcast i32* %Y to {}* ; <{}*> [#uses=1] - call void @llvm.dbg.declare(metadata !{i32 * %Y}, metadata !9), !dbg !10 - store i32 22, i32* %Y, !dbg !11 - %2 = bitcast i32* %Z to {}* ; <{}*> [#uses=1] - call void @llvm.dbg.declare(metadata !{i32 * %Z}, metadata !12), !dbg !14 - store i32 23, i32* %Z, !dbg !15 - %tmp = load i32* %X, !dbg !16 ; <i32> [#uses=1] - %tmp1 = load i32* %Y, !dbg !16 ; <i32> [#uses=1] - %add = add nsw i32 %tmp, %tmp1, !dbg !16 ; <i32> [#uses=1] - store i32 %add, i32* %Z, !dbg !16 - %tmp2 = load i32* %Y, !dbg !17 ; <i32> [#uses=1] - store i32 %tmp2, i32* %X, !dbg !17 - ret void, !dbg !18 + %X = alloca i32, align 4 ; [#uses=3 type=i32*] + %Y = alloca i32, align 4 ; [#uses=2 type=i32*] + %Z = alloca i32, align 4 ; [#uses=2 type=i32*] + call void @llvm.dbg.declare(metadata !{i32* %X}, metadata !8), !dbg !10 + ; [debug line = 2:7] [debug variable = X] + store i32 21, i32* %X, align 4, !dbg !11 ; [debug line = 2:13] + call void @llvm.dbg.declare(metadata !{i32* %Y}, metadata !12), !dbg !13 + ; [debug line = 3:7] [debug variable = Y] + store i32 22, i32* %Y, align 4, !dbg !14 ; [debug line = 3:13] + call void @llvm.dbg.declare(metadata !{i32* %Z}, metadata !15), !dbg !17 + ; [debug line = 5:9] [debug variable = Z] + store i32 23, i32* %Z, align 4, !dbg !18 ; [debug line = 5:15] + %0 = load i32* %X, align 4, !dbg !19 ; [#uses=1 type=i32] \ + [debug line = 6:5] + store i32 %0, i32* %Z, align 4, !dbg !19 ; [debug line = 6:5] + %1 = load i32* %Y, align 4, !dbg !20 ; [#uses=1 type=i32] \ + [debug line = 8:3] + store i32 %1, i32* %X, align 4, !dbg !20 ; [debug line = 8:3] + ret void, !dbg !21 ; [debug line = 9:1] } - declare void @llvm.dbg.declare(metadata, metadata) nounwind readnone - - !0 = metadata !{i32 459008, metadata !1, metadata !"X", - metadata !3, i32 2, metadata !6}; [ DW_TAG_auto_variable ] - !1 = metadata !{i32 458763, metadata !2}; [DW_TAG_lexical_block ] - !2 = metadata !{i32 458798, i32 0, metadata !3, metadata !"foo", metadata !"foo", - metadata !"foo", metadata !3, i32 1, metadata !4, - i1 false, i1 true}; [DW_TAG_subprogram ] - !3 = metadata !{i32 458769, i32 0, i32 12, metadata !"foo.c", - metadata !"/private/tmp", metadata !"clang 1.1", i1 true, - i1 false, metadata !"", i32 0}; [DW_TAG_compile_unit ] - !4 = metadata !{i32 458773, metadata !3, metadata !"", null, i32 0, i64 0, i64 0, - i64 0, i32 0, null, metadata !5, i32 0}; [DW_TAG_subroutine_type ] - !5 = metadata !{null} - !6 = metadata !{i32 458788, metadata !3, metadata !"int", metadata !3, i32 0, - i64 32, i64 32, i64 0, i32 0, i32 5}; [DW_TAG_base_type ] - !7 = metadata !{i32 2, i32 7, metadata !1, null} - !8 = metadata !{i32 2, i32 3, metadata !1, null} - !9 = metadata !{i32 459008, metadata !1, metadata !"Y", metadata !3, i32 3, - metadata !6}; [ DW_TAG_auto_variable ] - !10 = metadata !{i32 3, i32 7, metadata !1, null} - !11 = metadata !{i32 3, i32 3, metadata !1, null} - !12 = metadata !{i32 459008, metadata !13, metadata !"Z", metadata !3, i32 5, - metadata !6}; [ DW_TAG_auto_variable ] - !13 = metadata !{i32 458763, metadata !1}; [DW_TAG_lexical_block ] - !14 = metadata !{i32 5, i32 9, metadata !13, null} - !15 = metadata !{i32 5, i32 5, metadata !13, null} - !16 = metadata !{i32 6, i32 5, metadata !13, null} - !17 = metadata !{i32 8, i32 3, metadata !1, null} - !18 = metadata !{i32 9, i32 1, metadata !2, null} + ; [#uses=3] + ; Function Attrs: nounwind readnone + declare void @llvm.dbg.declare(metadata, metadata) #1 + + attributes #0 = { optsize zeroext "less-precise-fpmad"="false" + "no-frame-pointer-elim"="true" "no-frame-pointer-elim-non-leaf"="true" + "no-infs-fp-math"="false" "no-nans-fp-math"="false" "unsafe-fp-math"="false" + "use-soft-float"="false" } + attributes #1 = { nounwind readnone } + + !llvm.dbg.cu = !{!0} + + !0 = metadata !{i32 786449, metadata !1, i32 12, + metadata !"clang version 3.4 ", i1 false, metadata !"", i32 0, + metadata !2, metadata !2, metadata !3, metadata !2, + metadata !2, metadata !""} ; [ DW_TAG_compile_unit ] \ + [/private/tmp/foo.c] \ + [DW_LANG_C] + !1 = metadata !{metadata !"foo.c", metadata !"/private/tmp"} + !2 = metadata !{i32 0} + !3 = metadata !{metadata !4} + !4 = metadata !{i32 786478, metadata !1, metadata !5, metadata !"foo", + metadata !"foo", metadata !"_Z3foov", i32 1, metadata !6, + i1 false, i1 true, i32 0, i32 0, null, i32 256, i1 false, + void ()* @_Z3foov, null, null, metadata !2, i32 1} + ; [ DW_TAG_subprogram ] [line 1] [def] [foo] + !5 = metadata !{i32 786473, metadata !1} ; [ DW_TAG_file_type ] \ + [/private/tmp/foo.c] + !6 = metadata !{i32 786453, i32 0, i32 0, metadata !"", i32 0, i64 0, i64 0, + i64 0, i32 0, null, metadata !7, i32 0, i32 0} + ; [ DW_TAG_subroutine_type ] \ + [line 0, size 0, align 0, offset 0] [from ] + !7 = metadata !{null} + !8 = metadata !{i32 786688, metadata !4, metadata !"X", metadata !5, i32 2, \ + metadata !9, i32 0, i32 0} ; [ DW_TAG_auto_variable ] [X] \ + [line 2] + !9 = metadata !{i32 786468, null, null, metadata !"int", i32 0, i64 32, \ + i64 32, i64 0, i32 0, i32 5} ; [ DW_TAG_base_type ] [int] \ + [line 0, size 32, align 32, offset 0, enc DW_ATE_signed] + !10 = metadata !{i32 2, i32 7, metadata !4, null} + !11 = metadata !{i32 2, i32 13, metadata !4, null} + !12 = metadata !{i32 786688, metadata !4, metadata !"Y", metadata !5, i32 3, \ + metadata !9, i32 0, i32 0} ; [ DW_TAG_auto_variable ] [Y] \ + [line 3] + !13 = metadata !{i32 3, i32 7, metadata !4, null} + !14 = metadata !{i32 3, i32 13, metadata !4, null} + !15 = metadata !{i32 786688, metadata !16, metadata !"Z", metadata !5, i32 5, \ + metadata !9, i32 0, i32 0} ; [ DW_TAG_auto_variable ] [Z] \ + [line 5] + !16 = metadata !{i32 786443, metadata !1, metadata !4, i32 4, i32 3, i32 0} + ; [ DW_TAG_lexical_block ] [/private/tmp/foo.c] + !17 = metadata !{i32 5, i32 9, metadata !16, null} + !18 = metadata !{i32 5, i32 15, metadata !16, null} + !19 = metadata !{i32 6, i32 5, metadata !16, null} + !20 = metadata !{i32 8, i32 3, metadata !4, null} + !21 = metadata !{i32 9, i32 1, metadata !4, null} This example illustrates a few important details about LLVM debugging information. In particular, it shows how the ``llvm.dbg.declare`` intrinsic and @@ -716,25 +737,26 @@ variable definitions, and the code used to implement the function. .. code-block:: llvm - call void @llvm.dbg.declare(metadata, metadata !0), !dbg !7 + call void @llvm.dbg.declare(metadata !{i32* %X}, metadata !8), !dbg !10 + ; [debug line = 2:7] [debug variable = X] The first intrinsic ``%llvm.dbg.declare`` encodes debugging information for the -variable ``X``. The metadata ``!dbg !7`` attached to the intrinsic provides +variable ``X``. The metadata ``!dbg !10`` attached to the intrinsic provides scope information for the variable ``X``. .. code-block:: llvm - !7 = metadata !{i32 2, i32 7, metadata !1, null} - !1 = metadata !{i32 458763, metadata !2}; [DW_TAG_lexical_block ] - !2 = metadata !{i32 458798, i32 0, metadata !3, metadata !"foo", - metadata !"foo", metadata !"foo", metadata !3, i32 1, - metadata !4, i1 false, i1 true}; [DW_TAG_subprogram ] + !10 = metadata !{i32 2, i32 7, metadata !4, null} + !4 = metadata !{i32 786478, metadata !1, metadata !5, metadata !"foo", + metadata !"foo", metadata !"_Z3foov", i32 1, metadata !6, + i1 false, i1 true, i32 0, i32 0, null, i32 256, i1 false, + void ()* @_Z3foov, null, null, metadata !2, i32 1} + ; [ DW_TAG_subprogram ] [line 1] [def] [foo] -Here ``!7`` is metadata providing location information. It has four fields: +Here ``!10`` is metadata providing location information. It has four fields: line number, column number, scope, and original scope. The original scope represents inline location if this instruction is inlined inside a caller, and -is null otherwise. In this example, scope is encoded by ``!1``. ``!1`` -represents a lexical block inside the scope ``!2``, where ``!2`` is a +is null otherwise. In this example, scope is encoded by ``!4``, a :ref:`subprogram descriptor <format_subprograms>`. This way the location information attached to the intrinsics indicates that the variable ``X`` is declared at line number 2 at a function level scope in function ``foo``. @@ -743,20 +765,22 @@ Now lets take another example. .. code-block:: llvm - call void @llvm.dbg.declare(metadata, metadata !12), !dbg !14 + call void @llvm.dbg.declare(metadata !{i32* %Z}, metadata !15), !dbg !17 + ; [debug line = 5:9] [debug variable = Z] -The second intrinsic ``%llvm.dbg.declare`` encodes debugging information for -variable ``Z``. The metadata ``!dbg !14`` attached to the intrinsic provides +The third intrinsic ``%llvm.dbg.declare`` encodes debugging information for +variable ``Z``. The metadata ``!dbg !17`` attached to the intrinsic provides scope information for the variable ``Z``. .. code-block:: llvm - !13 = metadata !{i32 458763, metadata !1}; [DW_TAG_lexical_block ] - !14 = metadata !{i32 5, i32 9, metadata !13, null} + !16 = metadata !{i32 786443, metadata !1, metadata !4, i32 4, i32 3, i32 0} + ; [ DW_TAG_lexical_block ] [/private/tmp/foo.c] + !17 = metadata !{i32 5, i32 9, metadata !16, null} -Here ``!14`` indicates that ``Z`` is declared at line number 5 and -column number 9 inside of lexical scope ``!13``. The lexical scope itself -resides inside of lexical scope ``!1`` described above. +Here ``!15`` indicates that ``Z`` is declared at line number 5 and +column number 9 inside of lexical scope ``!16``. The lexical scope itself +resides inside of subprogram ``!4`` described above. The scope information attached with each instruction provides a straightforward way to find instructions covered by a scope. @@ -805,36 +829,44 @@ a C/C++ front-end would generate the following descriptors: ;; ;; Define the compile unit for the main source file "/Users/mine/sources/MySource.cpp". ;; - !2 = metadata !{ - i32 524305, ;; Tag - i32 0, ;; Unused - i32 4, ;; Language Id - metadata !"MySource.cpp", - metadata !"/Users/mine/sources", - metadata !"4.2.1 (Based on Apple Inc. build 5649) (LLVM build 00)", - i1 true, ;; Main Compile Unit - i1 false, ;; Optimized compile unit - metadata !"", ;; Compiler flags - i32 0} ;; Runtime version + !0 = metadata !{ + i32 786449, ;; Tag + metadata !1, ;; File/directory name + i32 4, ;; Language Id + metadata !"clang version 3.4 ", + i1 false, ;; Optimized compile unit + metadata !"", ;; Compiler flags + i32 0, ;; Runtime version + metadata !2, ;; Enumeration types + metadata !2, ;; Retained types + metadata !3, ;; Subprograms + metadata !2, ;; Global variables + metadata !2, ;; Imported entities (declarations and namespaces) + metadata !"" ;; Split debug filename + } ;; ;; Define the file for the file "/Users/mine/sources/MySource.cpp". ;; !1 = metadata !{ - i32 524329, ;; Tag metadata !"MySource.cpp", - metadata !"/Users/mine/sources", - metadata !2 ;; Compile unit + metadata !"/Users/mine/sources" + } + !5 = metadata !{ + i32 786473, ;; Tag + metadata !1 } ;; ;; Define the file for the file "/Users/mine/sources/Myheader.h" ;; - !3 = metadata !{ - i32 524329, ;; Tag - metadata !"Myheader.h" + !14 = metadata !{ + i32 786473, ;; Tag + metadata !15 + } + !15 = metadata !{ + metadata !"./MyHeader.h", metadata !"/Users/mine/sources", - metadata !2 ;; Compile unit } ... @@ -890,7 +922,9 @@ a C/C++ front-end would generate the following descriptors: metadata !1, ;; Enum Types metadata !1, ;; Retained Types metadata !1, ;; Subprograms - metadata !3 ;; Global Variables + metadata !3, ;; Global Variables + metadata !1, ;; Imported entities + "", ;; Split debug filename } ; [ DW_TAG_compile_unit ] ;; The Array of Global Variables @@ -898,14 +932,10 @@ a C/C++ front-end would generate the following descriptors: metadata !4 } - !4 = metadata !{ - metadata !5 - } - ;; ;; Define the global variable itself. ;; - !5 = metadata !{ + !4 = metadata !{ i32 786484, ;; Tag i32 0, ;; Unused null, ;; Unused @@ -917,17 +947,20 @@ a C/C++ front-end would generate the following descriptors: metadata !7, ;; Type i32 0, ;; IsLocalToUnit i32 1, ;; IsDefinition - i32* @MyGlobal ;; LLVM-IR Value + i32* @MyGlobal, ;; LLVM-IR Value + null ;; Static member declaration } ; [ DW_TAG_variable ] ;; ;; Define the file ;; - !6 = metadata !{ - i32 786473, ;; Tag + !5 = metadata !{ metadata !"foo.cpp", ;; File metadata !"/Volumes/Data/tmp", ;; Directory - null ;; Unused + } + !6 = metadata !{ + i32 786473, ;; Tag + metadata !5 ;; Unused } ; [ DW_TAG_file_type ] ;; @@ -936,8 +969,8 @@ a C/C++ front-end would generate the following descriptors: !7 = metadata !{ i32 786468, ;; Tag null, ;; Unused - metadata !"int", ;; Name null, ;; Unused + metadata !"int", ;; Name i32 0, ;; Line i64 32, ;; Size in Bits i64 32, ;; Align in Bits @@ -962,18 +995,15 @@ a C/C++ front-end would generate the following descriptors: .. code-block:: llvm ;; - ;; Define the anchor for subprograms. Note that the second field of the - ;; anchor is 46, which is the same as the tag for subprograms - ;; (46 = DW_TAG_subprogram.) + ;; Define the anchor for subprograms. ;; !6 = metadata !{ - i32 524334, ;; Tag - i32 0, ;; Unused + i32 786484, ;; Tag + metadata !1, ;; File metadata !1, ;; Context metadata !"main", ;; Name metadata !"main", ;; Display name metadata !"main", ;; Linkage name - metadata !1, ;; File i32 1, ;; Line number metadata !4, ;; Type i1 false, ;; Is local @@ -984,7 +1014,9 @@ a C/C++ front-end would generate the following descriptors: i32 0, ;; Flags i1 false, ;; True if this function is optimized Function *, ;; Pointer to llvm::Function - null ;; Function template parameters + null, ;; Function template parameters + null, ;; List of function variables (emitted when optimizing) + 1 ;; Line number of the opening '{' of the function } ;; ;; Define the subprogram itself. @@ -1004,10 +1036,10 @@ bool .. code-block:: llvm !2 = metadata !{ - i32 524324, ;; Tag - metadata !1, ;; Context + i32 786468, ;; Tag + null, ;; File + null, ;; Context metadata !"bool", ;; Name - metadata !1, ;; File i32 0, ;; Line number i64 8, ;; Size in Bits i64 8, ;; Align in Bits @@ -1022,10 +1054,10 @@ char .. code-block:: llvm !2 = metadata !{ - i32 524324, ;; Tag - metadata !1, ;; Context + i32 786468, ;; Tag + null, ;; File + null, ;; Context metadata !"char", ;; Name - metadata !1, ;; File i32 0, ;; Line number i64 8, ;; Size in Bits i64 8, ;; Align in Bits @@ -1040,10 +1072,10 @@ unsigned char .. code-block:: llvm !2 = metadata !{ - i32 524324, ;; Tag - metadata !1, ;; Context + i32 786468, ;; Tag + null, ;; File + null, ;; Context metadata !"unsigned char", - metadata !1, ;; File i32 0, ;; Line number i64 8, ;; Size in Bits i64 8, ;; Align in Bits @@ -1058,10 +1090,10 @@ short .. code-block:: llvm !2 = metadata !{ - i32 524324, ;; Tag - metadata !1, ;; Context + i32 786468, ;; Tag + null, ;; File + null, ;; Context metadata !"short int", - metadata !1, ;; File i32 0, ;; Line number i64 16, ;; Size in Bits i64 16, ;; Align in Bits @@ -1076,10 +1108,10 @@ unsigned short .. code-block:: llvm !2 = metadata !{ - i32 524324, ;; Tag - metadata !1, ;; Context + i32 786468, ;; Tag + null, ;; File + null, ;; Context metadata !"short unsigned int", - metadata !1, ;; File i32 0, ;; Line number i64 16, ;; Size in Bits i64 16, ;; Align in Bits @@ -1094,10 +1126,10 @@ int .. code-block:: llvm !2 = metadata !{ - i32 524324, ;; Tag - metadata !1, ;; Context + i32 786468, ;; Tag + null, ;; File + null, ;; Context metadata !"int", ;; Name - metadata !1, ;; File i32 0, ;; Line number i64 32, ;; Size in Bits i64 32, ;; Align in Bits @@ -1112,10 +1144,10 @@ unsigned int .. code-block:: llvm !2 = metadata !{ - i32 524324, ;; Tag - metadata !1, ;; Context + i32 786468, ;; Tag + null, ;; File + null, ;; Context metadata !"unsigned int", - metadata !1, ;; File i32 0, ;; Line number i64 32, ;; Size in Bits i64 32, ;; Align in Bits @@ -1130,10 +1162,10 @@ long long .. code-block:: llvm !2 = metadata !{ - i32 524324, ;; Tag - metadata !1, ;; Context + i32 786468, ;; Tag + null, ;; File + null, ;; Context metadata !"long long int", - metadata !1, ;; File i32 0, ;; Line number i64 64, ;; Size in Bits i64 64, ;; Align in Bits @@ -1148,10 +1180,10 @@ unsigned long long .. code-block:: llvm !2 = metadata !{ - i32 524324, ;; Tag - metadata !1, ;; Context + i32 786468, ;; Tag + null, ;; File + null, ;; Context metadata !"long long unsigned int", - metadata !1, ;; File i32 0, ;; Line number i64 64, ;; Size in Bits i64 64, ;; Align in Bits @@ -1166,10 +1198,10 @@ float .. code-block:: llvm !2 = metadata !{ - i32 524324, ;; Tag - metadata !1, ;; Context + i32 786468, ;; Tag + null, ;; File + null, ;; Context metadata !"float", - metadata !1, ;; File i32 0, ;; Line number i64 32, ;; Size in Bits i64 32, ;; Align in Bits @@ -1184,10 +1216,10 @@ double .. code-block:: llvm !2 = metadata !{ - i32 524324, ;; Tag - metadata !1, ;; Context + i32 786468, ;; Tag + null, ;; File + null, ;; Context metadata !"double",;; Name - metadata !1, ;; File i32 0, ;; Line number i64 64, ;; Size in Bits i64 64, ;; Align in Bits @@ -1213,10 +1245,10 @@ a C/C++ front-end would generate the following descriptors: ;; Define the typedef "IntPtr". ;; !2 = metadata !{ - i32 524310, ;; Tag + i32 786454, ;; Tag + metadata !3, ;; File metadata !1, ;; Context metadata !"IntPtr", ;; Name - metadata !3, ;; File i32 0, ;; Line number i64 0, ;; Size in bits i64 0, ;; Align in bits @@ -1228,10 +1260,10 @@ a C/C++ front-end would generate the following descriptors: ;; Define the pointer type. ;; !4 = metadata !{ - i32 524303, ;; Tag - metadata !1, ;; Context + i32 786447, ;; Tag + null, ;; File + null, ;; Context metadata !"", ;; Name - metadata !1, ;; File i32 0, ;; Line number i64 64, ;; Size in bits i64 64, ;; Align in bits @@ -1243,13 +1275,13 @@ a C/C++ front-end would generate the following descriptors: ;; Define the const type. ;; !5 = metadata !{ - i32 524326, ;; Tag - metadata !1, ;; Context + i32 786470, ;; Tag + null, ;; File + null, ;; Context metadata !"", ;; Name - metadata !1, ;; File i32 0, ;; Line number - i64 32, ;; Size in bits - i64 32, ;; Align in bits + i64 0, ;; Size in bits + i64 0, ;; Align in bits i64 0, ;; Offset in bits i32 0, ;; Flags metadata !6 ;; Derived From type @@ -1258,16 +1290,16 @@ a C/C++ front-end would generate the following descriptors: ;; Define the int type. ;; !6 = metadata !{ - i32 524324, ;; Tag - metadata !1, ;; Context + i32 786468, ;; Tag + null, ;; File + null, ;; Context metadata !"int", ;; Name - metadata !1, ;; File i32 0, ;; Line number i64 32, ;; Size in bits i64 32, ;; Align in bits i64 0, ;; Offset in bits i32 0, ;; Flags - 5 ;; Encoding + i32 5 ;; Encoding } C/C++ struct/union types @@ -1291,10 +1323,10 @@ a C/C++ front-end would generate the following descriptors: ;; Define basic type for unsigned int. ;; !5 = metadata !{ - i32 524324, ;; Tag - metadata !1, ;; Context + i32 786468, ;; Tag + null, ;; File + null, ;; Context metadata !"unsigned int", - metadata !1, ;; File i32 0, ;; Line number i64 32, ;; Size in Bits i64 32, ;; Align in Bits @@ -1306,10 +1338,10 @@ a C/C++ front-end would generate the following descriptors: ;; Define composite type for struct Color. ;; !2 = metadata !{ - i32 524307, ;; Tag - metadata !1, ;; Context - metadata !"Color", ;; Name + i32 786451, ;; Tag metadata !1, ;; Compile unit + null, ;; Context + metadata !"Color", ;; Name i32 1, ;; Line number i64 96, ;; Size in bits i64 32, ;; Align in bits @@ -1317,17 +1349,19 @@ a C/C++ front-end would generate the following descriptors: i32 0, ;; Flags null, ;; Derived From metadata !3, ;; Elements - i32 0 ;; Runtime Language + i32 0, ;; Runtime Language + null, ;; Base type containing the vtable pointer for this type + null ;; Template parameters } ;; ;; Define the Red field. ;; !4 = metadata !{ - i32 524301, ;; Tag + i32 786445, ;; Tag + metadata !1, ;; File metadata !1, ;; Context metadata !"Red", ;; Name - metadata !1, ;; File i32 2, ;; Line number i64 32, ;; Size in bits i64 32, ;; Align in bits @@ -1340,10 +1374,10 @@ a C/C++ front-end would generate the following descriptors: ;; Define the Green field. ;; !6 = metadata !{ - i32 524301, ;; Tag + i32 786445, ;; Tag + metadata !1, ;; File metadata !1, ;; Context metadata !"Green", ;; Name - metadata !1, ;; File i32 3, ;; Line number i64 32, ;; Size in bits i64 32, ;; Align in bits @@ -1356,10 +1390,10 @@ a C/C++ front-end would generate the following descriptors: ;; Define the Blue field. ;; !7 = metadata !{ - i32 524301, ;; Tag + i32 786445, ;; Tag + metadata !1, ;; File metadata !1, ;; Context metadata !"Blue", ;; Name - metadata !1, ;; File i32 4, ;; Line number i64 32, ;; Size in bits i64 32, ;; Align in bits @@ -1394,10 +1428,10 @@ a C/C++ front-end would generate the following descriptors: ;; Define composite type for enum Trees ;; !2 = metadata !{ - i32 524292, ;; Tag + i32 786436, ;; Tag + metadata !1, ;; File metadata !1, ;; Context metadata !"Trees", ;; Name - metadata !1, ;; File i32 1, ;; Line number i64 32, ;; Size in bits i64 32, ;; Align in bits @@ -1416,17 +1450,17 @@ a C/C++ front-end would generate the following descriptors: ;; ;; Define Spruce enumerator. ;; - !4 = metadata !{i32 524328, metadata !"Spruce", i64 100} + !4 = metadata !{i32 786472, metadata !"Spruce", i64 100} ;; ;; Define Oak enumerator. ;; - !5 = metadata !{i32 524328, metadata !"Oak", i64 200} + !5 = metadata !{i32 786472, metadata !"Oak", i64 200} ;; ;; Define Maple enumerator. ;; - !6 = metadata !{i32 524328, metadata !"Maple", i64 300} + !6 = metadata !{i32 786472, metadata !"Maple", i64 300} Debugging information format ============================ @@ -2080,23 +2114,23 @@ array to be: HeaderData.atoms[0].form = DW_FORM_data4; This defines the contents to be the DIE offset (eAtomTypeDIEOffset) that is - encoded as a 32 bit value (DW_FORM_data4). This allows a single name to have - multiple matching DIEs in a single file, which could come up with an inlined - function for instance. Future tables could include more information about the - DIE such as flags indicating if the DIE is a function, method, block, - or inlined. +encoded as a 32 bit value (DW_FORM_data4). This allows a single name to have +multiple matching DIEs in a single file, which could come up with an inlined +function for instance. Future tables could include more information about the +DIE such as flags indicating if the DIE is a function, method, block, +or inlined. The KeyType for the DWARF table is a 32 bit string table offset into the - ".debug_str" table. The ".debug_str" is the string table for the DWARF which - may already contain copies of all of the strings. This helps make sure, with - help from the compiler, that we reuse the strings between all of the DWARF - sections and keeps the hash table size down. Another benefit to having the - compiler generate all strings as DW_FORM_strp in the debug info, is that - DWARF parsing can be made much faster. +".debug_str" table. The ".debug_str" is the string table for the DWARF which +may already contain copies of all of the strings. This helps make sure, with +help from the compiler, that we reuse the strings between all of the DWARF +sections and keeps the hash table size down. Another benefit to having the +compiler generate all strings as DW_FORM_strp in the debug info, is that +DWARF parsing can be made much faster. After a lookup is made, we get an offset into the hash data. The hash data - needs to be able to deal with 32 bit hash collisions, so the chunk of data - at the offset in the hash data consists of a triple: +needs to be able to deal with 32 bit hash collisions, so the chunk of data +at the offset in the hash data consists of a triple: .. code-block:: c @@ -2105,7 +2139,7 @@ After a lookup is made, we get an offset into the hash data. The hash data HashData[hash_data_count] If "str_offset" is zero, then the bucket contents are done. 99.9% of the - hash data chunks contain a single item (no 32 bit hash collision): +hash data chunks contain a single item (no 32 bit hash collision): .. code-block:: none diff --git a/docs/TableGen/LangRef.rst b/docs/TableGen/LangRef.rst index c9e1efb..bd28a90 100644 --- a/docs/TableGen/LangRef.rst +++ b/docs/TableGen/LangRef.rst @@ -286,7 +286,7 @@ given values. .. productionlist:: SimpleValue: "(" `DagArg` `DagArgList` ")" DagArgList: `DagArg` ("," `DagArg`)* - DagArg: `Value` [":" `TokVarName`] + DagArg: `Value` [":" `TokVarName`] | `TokVarName` The initial :token:`DagArg` is called the "operator" of the dag. diff --git a/docs/TestingGuide.rst b/docs/TestingGuide.rst index 4d8c8ce..3cfbb21 100644 --- a/docs/TestingGuide.rst +++ b/docs/TestingGuide.rst @@ -224,16 +224,7 @@ Below is an example of legal RUN lines in a ``.ll`` file: ; RUN: diff %t1 %t2 As with a Unix shell, the RUN lines permit pipelines and I/O -redirection to be used. However, the usage is slightly different than -for Bash. In general, it's useful to read the code of other tests to figure out -what you can use in yours. The major differences are: - -- You can't do ``2>&1``. That will cause :program:`lit` to write to a file - named ``&1``. Usually this is done to get stderr to go through a pipe. You - can do that with ``|&`` so replace this idiom: - ``... 2>&1 | FileCheck`` with ``... |& FileCheck`` -- You can only redirect to a file, not to another descriptor and not - from a here document. +redirection to be used. There are some quoting rules that you must pay attention to when writing your RUN lines. In general nothing needs to be quoted. :program:`lit` won't @@ -243,7 +234,7 @@ everything enclosed as one value. In general, you should strive to keep your RUN lines as simple as possible, using them only to run tools that generate textual output you can then examine. -The recommended way to examine output to figure out if the test passes it using +The recommended way to examine output to figure out if the test passes is using the :doc:`FileCheck tool <CommandGuide/FileCheck>`. *[The usage of grep in RUN lines is deprecated - please do not send or commit patches that use it.]* @@ -284,6 +275,66 @@ This test will fail if placed into a ``download`` directory. To make your tests robust, always use ``opt ... < %s`` in the RUN line. :program:`opt` does not output a ``ModuleID`` when input comes from stdin. +Platform-Specific Tests +----------------------- + +Whenever adding tests that require the knowledge of a specific platform, +either related to code generated, specific output or back-end features, +you must make sure to isolate the features, so that buildbots that +run on different architectures (and don't even compile all back-ends), +don't fail. + +The first problem is to check for target-specific output, for example sizes +of structures, paths and architecture names, for example: + +* Tests containing Windows paths will fail on Linux and vice-versa. +* Tests that check for ``x86_64`` somewhere in the text will fail anywhere else. +* Tests where the debug information calculates the size of types and structures. + +Also, if the test rely on any behaviour that is coded in any back-end, it must +go in its own directory. So, for instance, code generator tests for ARM go +into ``test/CodeGen/ARM`` and so on. Those directories contain a special +``lit`` configuration file that ensure all tests in that directory will +only run if a specific back-end is compiled and available. + +For instance, on ``test/CodeGen/ARM``, the ``lit.local.cfg`` is: + +.. code-block:: python + + config.suffixes = ['.ll', '.c', '.cpp', '.test'] + targets = set(config.root.targets_to_build.split()) + if not 'ARM' in targets: + config.unsupported = True + +Other platform-specific tests are those that depend on a specific feature +of a specific sub-architecture, for example only to Intel chips that support ``AVX2``. + +For instance, ``test/CodeGen/X86/psubus.ll`` tests three sub-architecture +variants: + +.. code-block:: llvm + + ; RUN: llc -mcpu=core2 < %s | FileCheck %s -check-prefix=SSE2 + ; RUN: llc -mcpu=corei7-avx < %s | FileCheck %s -check-prefix=AVX1 + ; RUN: llc -mcpu=core-avx2 < %s | FileCheck %s -check-prefix=AVX2 + +And the checks are different: + +.. code-block:: llvm + + ; SSE2: @test1 + ; SSE2: psubusw LCPI0_0(%rip), %xmm0 + ; AVX1: @test1 + ; AVX1: vpsubusw LCPI0_0(%rip), %xmm0, %xmm0 + ; AVX2: @test1 + ; AVX2: vpsubusw LCPI0_0(%rip), %xmm0, %xmm0 + +So, if you're testing for a behaviour that you know is platform-specific or +depends on special features of sub-architectures, you must add the specific +triple, test with the specific FileCheck and put it into the specific +directory that will filter out all other architectures. + + Variables and substitutions --------------------------- diff --git a/docs/Vectorizers.rst b/docs/Vectorizers.rst index e2d3667..61ebca2 100644 --- a/docs/Vectorizers.rst +++ b/docs/Vectorizers.rst @@ -6,12 +6,14 @@ Auto-Vectorization in LLVM :local: LLVM has two vectorizers: The :ref:`Loop Vectorizer <loop-vectorizer>`, -which operates on Loops, and the :ref:`Basic Block Vectorizer -<bb-vectorizer>`, which optimizes straight-line code. These vectorizers +which operates on Loops, and the :ref:`SLP Vectorizer +<slp-vectorizer>`. These vectorizers focus on different optimization opportunities and use different techniques. -The BB vectorizer merges multiple scalars that are found in the code into -vectors while the Loop Vectorizer widens instructions in the original loop -to operate on multiple consecutive loop iterations. +The SLP vectorizer merges multiple scalars that are found in the code into +vectors while the Loop Vectorizer widens instructions in loops +to operate on multiple consecutive iterations. + +Both the Loop Vectorizer and the SLP Vectorizer are enabled by default. .. _loop-vectorizer: @@ -21,19 +23,12 @@ The Loop Vectorizer Usage ----- -LLVM's Loop Vectorizer is now available and will be useful for many people. -It is not enabled by default, but can be enabled through clang using the -command line flag: +The Loop Vectorizer is enabled by default, but it can be disabled +through clang using the command line flag: .. code-block:: console - $ clang -fvectorize -O3 file.c - -If the ``-fvectorize`` flag is used then the loop vectorizer will be enabled -when running with ``-O3``, ``-O2``. When ``-Os`` is used, the loop vectorizer -will only vectorize loops that do not require a major increase in code size. - -We plan to enable the Loop Vectorizer by default as part of the LLVM 3.3 release. + $ clang ... -fno-vectorize file.c Command line flags ^^^^^^^^^^^^^^^^^^ @@ -299,29 +294,18 @@ And Linpack-pc with the same configuration. Result is Mflops, higher is better. .. image:: linpack-pc.png -.. _bb-vectorizer: - -The Basic Block Vectorizer -========================== - -Usage ------- - -The Basic Block Vectorizer is not enabled by default, but it can be enabled -through clang using the command line flag: - -.. code-block:: console +.. _slp-vectorizer: - $ clang -fslp-vectorize file.c +The SLP Vectorizer +================== Details ------- -The goal of basic-block vectorization (a.k.a. superword-level parallelism) is -to combine similar independent instructions within simple control-flow regions -into vector instructions. Memory accesses, arithemetic operations, comparison -operations and some math functions can all be vectorized using this technique -(subject to the capabilities of the target architecture). +The goal of SLP vectorization (a.k.a. superword-level parallelism) is +to combine similar independent instructions +into vector instructions. Memory accesses, arithmetic operations, comparison +operations, PHI-nodes, can all be vectorized using this technique. For example, the following function performs very similar operations on its inputs (a1, b1) and (a2, b2). The basic-block vectorizer may combine these @@ -329,10 +313,28 @@ into vector operations. .. code-block:: c++ - int foo(int a1, int a2, int b1, int b2) { - int r1 = a1*(a1 + b1)/b1 + 50*b1/a1; - int r2 = a2*(a2 + b2)/b2 + 50*b2/a2; - return r1 + r2; + void foo(int a1, int a2, int b1, int b2, int *A) { + A[0] = a1*(a1 + b1)/b1 + 50*b1/a1; + A[1] = a2*(a2 + b2)/b2 + 50*b2/a2; } +The SLP-vectorizer processes the code bottom-up, across basic blocks, in search of scalars to combine. + +Usage +------ + +The SLP Vectorizer is enabled by default, but it can be disabled +through clang using the command line flag: + +.. code-block:: console + + $ clang -fno-slp-vectorize file.c + +LLVM has a second basic block vectorization phase +which is more compile-time intensive (The BB vectorizer). This optimization +can be enabled through clang using the command line flag: + +.. code-block:: console + + $ clang -fslp-vectorize-aggressive file.c diff --git a/docs/WritingAnLLVMBackend.rst b/docs/WritingAnLLVMBackend.rst index 6d6c2a1..73381b5 100644 --- a/docs/WritingAnLLVMBackend.rst +++ b/docs/WritingAnLLVMBackend.rst @@ -1,6 +1,6 @@ -================================ -Writing an LLVM Compiler Backend -================================ +======================= +Writing an LLVM Backend +======================= .. toctree:: :hidden: @@ -760,7 +760,7 @@ target description file (``IntRegs``). def LDrr : F3_1 <3, 0b000000, (outs IntRegs:$dst), (ins MEMrr:$addr), "ld [$addr], $dst", - [(set IntRegs:$dst, (load ADDRrr:$addr))]>; + [(set i32:$dst, (load ADDRrr:$addr))]>; The fourth parameter is the input source, which uses the address operand ``MEMrr`` that is defined earlier in ``SparcInstrInfo.td``: @@ -788,7 +788,7 @@ class is defined: def LDri : F3_2 <3, 0b000000, (outs IntRegs:$dst), (ins MEMri:$addr), "ld [$addr], $dst", - [(set IntRegs:$dst, (load ADDRri:$addr))]>; + [(set i32:$dst, (load ADDRri:$addr))]>; Writing these definitions for so many similar instructions can involve a lot of cut and paste. In ``.td`` files, the ``multiclass`` directive enables the @@ -803,11 +803,11 @@ pattern ``F3_12`` is defined to create 2 instruction classes each time def rr : F3_1 <2, Op3Val, (outs IntRegs:$dst), (ins IntRegs:$b, IntRegs:$c), !strconcat(OpcStr, " $b, $c, $dst"), - [(set IntRegs:$dst, (OpNode IntRegs:$b, IntRegs:$c))]>; + [(set i32:$dst, (OpNode i32:$b, i32:$c))]>; def ri : F3_2 <2, Op3Val, (outs IntRegs:$dst), (ins IntRegs:$b, i32imm:$c), !strconcat(OpcStr, " $b, $c, $dst"), - [(set IntRegs:$dst, (OpNode IntRegs:$b, simm13:$c))]>; + [(set i32:$dst, (OpNode i32:$b, simm13:$c))]>; } So when the ``defm`` directive is used for the ``XOR`` and ``ADD`` @@ -856,7 +856,7 @@ format instruction having three operands. def XNORrr : F3_1<2, 0b000111, (outs IntRegs:$dst), (ins IntRegs:$b, IntRegs:$c), "xnor $b, $c, $dst", - [(set IntRegs:$dst, (not (xor IntRegs:$b, IntRegs:$c)))]>; + [(set i32:$dst, (not (xor i32:$b, i32:$c)))]>; The instruction templates in ``SparcInstrFormats.td`` show the base class for ``F3_1`` is ``InstSP``. @@ -911,6 +911,47 @@ format instructions will bind the operands to the ``rd``, ``rs1``, and ``rs2`` fields. This results in the ``XNORrr`` instruction binding ``$dst``, ``$b``, and ``$c`` operands to the ``rd``, ``rs1``, and ``rs2`` fields respectively. +TableGen will also generate a function called getNamedOperandIdx() which +can be used to look up an operand's index in a MachineInstr based on its +TableGen name. Setting the UseNamedOperandTable bit in an instruction's +TableGen definition will add all of its operands to an enumeration in the +llvm::XXX:OpName namespace and also add an entry for it into the OperandMap +table, which can be queried using getNamedOperandIdx() + +.. code-block:: llvm + + int DstIndex = SP::getNamedOperandIdx(SP::XNORrr, SP::OpName::dst); // => 0 + int BIndex = SP::getNamedOperandIdx(SP::XNORrr, SP::OpName::b); // => 1 + int CIndex = SP::getNamedOperandIdx(SP::XNORrr, SP::OpName::c); // => 2 + int DIndex = SP::getNamedOperandIdx(SP::XNORrr, SP::OpName::d); // => -1 + + ... + +The entries in the OpName enum are taken verbatim from the TableGen definitions, +so operands with lowercase names will have lower case entries in the enum. + +To include the getNamedOperandIdx() function in your backend, you will need +to define a few preprocessor macros in XXXInstrInfo.cpp and XXXInstrInfo.h. +For example: + +XXXInstrInfo.cpp: + +.. code-block:: c++ + + #define GET_INSTRINFO_NAMED_OPS // For getNamedOperandIdx() function + #include "XXXGenInstrInfo.inc" + +XXXInstrInfo.h: + +.. code-block:: c++ + + #define GET_INSTRINFO_OPERAND_ENUM // For OpName enum + #include "XXXGenInstrInfo.inc" + + namespace XXX { + int16_t getNamedOperandIdx(uint16_t Opcode, uint16_t NamedIndex); + } // End namespace XXX + Instruction Relation Mapping ---------------------------- @@ -1124,7 +1165,7 @@ a pattern with the store DAG operator. .. code-block:: llvm def STrr : F3_1< 3, 0b000100, (outs), (ins MEMrr:$addr, IntRegs:$src), - "st $src, [$addr]", [(store IntRegs:$src, ADDRrr:$addr)]>; + "st $src, [$addr]", [(store i32:$src, ADDRrr:$addr)]>; ``ADDRrr`` is a memory mode that is also defined in ``SparcInstrInfo.td``: @@ -1185,7 +1226,7 @@ instruction. SDValue CPTmp0; SDValue CPTmp1; - // Pattern: (st:void IntRegs:i32:$src, + // Pattern: (st:void i32:i32:$src, // ADDRrr:i32:$addr)<<P:Predicate_store>> // Emits: (STrr:void ADDRrr:i32:$addr, IntRegs:i32:$src) // Pattern complexity = 13 cost = 1 size = 0 diff --git a/docs/WritingAnLLVMPass.rst b/docs/WritingAnLLVMPass.rst index b10d98f..1114fa0 100644 --- a/docs/WritingAnLLVMPass.rst +++ b/docs/WritingAnLLVMPass.rst @@ -96,7 +96,7 @@ Start out with: .. code-block:: c++ #include "llvm/Pass.h" - #include "llvm/Function.h" + #include "llvm/IR/Function.h" #include "llvm/Support/raw_ostream.h" Which are needed because we are writing a `Pass @@ -184,7 +184,7 @@ As a whole, the ``.cpp`` file looks like: .. code-block:: c++ #include "llvm/Pass.h" - #include "llvm/Function.h" + #include "llvm/IR/Function.h" #include "llvm/Support/raw_ostream.h" using namespace llvm; @@ -454,7 +454,7 @@ external functions. To be explicit, ``FunctionPass`` subclasses are not allowed to: -#. Modify a ``Function`` other than the one currently being processed. +#. Inspect or modify a ``Function`` other than the one currently being processed. #. Add or remove ``Function``\ s from the current ``Module``. #. Add or remove global variables from the current ``Module``. #. Maintain state across invocations of:ref:`runOnFunction diff --git a/docs/YamlIO.rst b/docs/YamlIO.rst index ac50292..a5cb637 100644 --- a/docs/YamlIO.rst +++ b/docs/YamlIO.rst @@ -109,7 +109,7 @@ ScalarEnumerationTraits on that type and define the enumeration() method: As with all YAML I/O template specializations, the ScalarEnumerationTraits is used for both reading and writing YAML. That is, the mapping between in-memory enum -values and the YAML string representation is only in place. +values and the YAML string representation is only in one place. This assures that the code for writing and parsing of YAML stays in sync. To specify a YAML mappings, you define a specialization on @@ -353,7 +353,7 @@ had the following bit flags defined: flagsRound = 8 }; - LLVM_YAML_UNIQUE_TYPE(MyFlags, uint32_t) + LLVM_YAML_STRONG_TYPEDEF(uint32_t, MyFlags) To support reading and writing of MyFlags, you specialize ScalarBitSetTraits<> on MyFlags and provide the bit values and their names. @@ -533,7 +533,7 @@ coordinates into polar when reading YAML. y(polar.distance * sin(polar.angle)) { } Polar denormalize(IO &) { - return Polar(sqrt(x*x+y*y, arctan(x,y)); + return Polar(sqrt(x*x+y*y), arctan(x,y)); } float x; diff --git a/docs/conf.py b/docs/conf.py index 0ac3b78..d71f46e 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -47,9 +47,9 @@ copyright = u'2003-2013, LLVM Project' # built documents. # # The short X.Y version. -version = '3.3' +version = '3.4' # The full version, including alpha/beta/rc tags. -release = '3.3' +release = '3.4' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. diff --git a/docs/index.rst b/docs/index.rst index 8f22ef2..be72195 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -22,7 +22,6 @@ Several introductory papers and presentations. :hidden: LangRef - GetElementPtr :doc:`LangRef` Defines the LLVM intermediate representation. @@ -48,10 +47,6 @@ Several introductory papers and presentations. .. __: http://llvm.org/pubs/2002-12-LattnerMSThesis.html -:doc:`GetElementPtr` - Answers to some very frequent questions about LLVM's most frequently - misunderstood instruction. - `Publications mentioning LLVM <http://llvm.org/pubs>`_ .. @@ -72,7 +67,6 @@ representation. CMake HowToBuildOnARM CommandGuide/index - DeveloperPolicy GettingStarted GettingStartedVS FAQ @@ -87,6 +81,7 @@ representation. ReleaseNotes Passes YamlIO + GetElementPtr :doc:`GettingStarted` Discusses how to get up and running quickly with the LLVM infrastructure. @@ -108,9 +103,6 @@ representation. Tutorials about using LLVM. Includes a tutorial about making a custom language with LLVM. -:doc:`DeveloperPolicy` - The LLVM project's policy towards developers and their contributions. - :doc:`LLVM Command Guide <CommandGuide/index>` A reference manual for the LLVM command line utilities ("man" pages for LLVM tools). @@ -149,25 +141,9 @@ representation. :doc:`YamlIO` A reference guide for using LLVM's YAML I/O library. -IRC -=== - -Users and developers of the LLVM project (including subprojects such as Clang) -can be found in #llvm on `irc.oftc.net <irc://irc.oftc.net/llvm>`_. - -This channel has several bots. - -* Buildbot reporters - - * llvmbb - Bot for the main LLVM buildbot master. - http://lab.llvm.org:8011/console - * bb-chapuni - An individually run buildbot master. http://bb.pgr.jp/console - * smooshlab - Apple's internal buildbot master. - -* robot - Bugzilla linker. %bug <number> - -* clang-bot - A `geordi <http://www.eelis.net/geordi/>`_ instance running - near-trunk clang instead of gcc. +:doc:`GetElementPtr` + Answers to some very frequent questions about LLVM's most frequently + misunderstood instruction. Programming Documentation ========================= @@ -184,6 +160,7 @@ For developers of applications which use LLVM as a library. ExtendingLLVM HowToSetUpLLVMStyleRTTI ProgrammersManual + Extensions :doc:`LLVM Language Reference Manual <LangRef>` Defines the LLVM intermediate representation and the assembly form of the @@ -196,6 +173,9 @@ For developers of applications which use LLVM as a library. Introduction to the general layout of the LLVM sourcebase, important classes and APIs, and some tips & tricks. +:doc:`Extensions` + LLVM-specific extensions to tools and formats LLVM seeks compatibility with. + :doc:`CommandLine` Provides information on using the command line parsing library. @@ -248,6 +228,7 @@ For API clients and LLVM developers. WritingAnLLVMPass TableGen/LangRef HowToUseAttributes + NVPTXUsage :doc:`WritingAnLLVMPass` Information on how to write LLVM transformations and analyses. @@ -316,6 +297,10 @@ For API clients and LLVM developers. :doc:`HowToUseAttributes` Answers some questions about the new Attributes infrastructure. +:doc:`NVPTXUsage` + This document describes using the NVPTX back-end to compile GPU kernels. + + Development Process Documentation ================================= @@ -324,12 +309,16 @@ Information about LLVM's development process. .. toctree:: :hidden: + DeveloperPolicy MakefileGuide Projects LLVMBuild HowToReleaseLLVM Packaging +:doc:`DeveloperPolicy` + The LLVM project's policy towards developers and their contributions. + :doc:`Projects` How-to guide and templates for new projects that *use* the LLVM infrastructure. The templates (directory organization, Makefiles, and test @@ -346,49 +335,81 @@ Information about LLVM's development process. :doc:`HowToReleaseLLVM` This is a guide to preparing LLVM releases. Most developers can ignore it. +:doc:`ReleaseProcess` + This is a validate a new release, during the release process. Most developers can ignore it. + :doc:`Packaging` Advice on packaging LLVM into a distribution. +Community +========= + +LLVM has a thriving community of friendly and helpful developers. +The two primary communication mechanisms in the LLVM community are mailing +lists and IRC. + Mailing Lists -============= +------------- If you can't find what you need in these docs, try consulting the mailing lists. -`LLVM Announcements List`__ - This is a low volume list that provides important announcements regarding - LLVM. It gets email about once a month. - - .. __: http://lists.cs.uiuc.edu/mailman/listinfo/llvm-announce - -`Developer's List`__ +`Developer's List (llvmdev)`__ This list is for people who want to be included in technical discussions of LLVM. People post to this list when they have questions about writing code for or using the LLVM tools. It is relatively low volume. .. __: http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev -`Bugs & Patches Archive`__ - This list gets emailed every time a bug is opened and closed, and when people - submit patches to be included in LLVM. It is higher volume than the LLVMdev - list. - - .. __: http://lists.cs.uiuc.edu/pipermail/llvmbugs/ - -`Commits Archive`__ +`Commits Archive (llvm-commits)`__ This list contains all commit messages that are made when LLVM developers - commit code changes to the repository. It is useful for those who want to - stay on the bleeding edge of LLVM development. This list is very high volume. + commit code changes to the repository. It also serves as a forum for + patch review (i.e. send patches here). It is useful for those who want to + stay on the bleeding edge of LLVM development. This list is very high + volume. .. __: http://lists.cs.uiuc.edu/pipermail/llvm-commits/ -`Test Results Archive`__ +`Bugs & Patches Archive (llvmbugs)`__ + This list gets emailed every time a bug is opened and closed. It is + higher volume than the LLVMdev list. + + .. __: http://lists.cs.uiuc.edu/pipermail/llvmbugs/ + +`Test Results Archive (llvm-testresults)`__ A message is automatically sent to this list by every active nightly tester when it completes. As such, this list gets email several times each day, making it a high volume list. .. __: http://lists.cs.uiuc.edu/pipermail/llvm-testresults/ +`LLVM Announcements List (llvm-announce)`__ + This is a low volume list that provides important announcements regarding + LLVM. It gets email about once a month. + + .. __: http://lists.cs.uiuc.edu/mailman/listinfo/llvm-announce + +IRC +--- + +Users and developers of the LLVM project (including subprojects such as Clang) +can be found in #llvm on `irc.oftc.net <irc://irc.oftc.net/llvm>`_. + +This channel has several bots. + +* Buildbot reporters + + * llvmbb - Bot for the main LLVM buildbot master. + http://lab.llvm.org:8011/console + * bb-chapuni - An individually run buildbot master. http://bb.pgr.jp/console + * smooshlab - Apple's internal buildbot master. + +* robot - Bugzilla linker. %bug <number> + +* clang-bot - A `geordi <http://www.eelis.net/geordi/>`_ instance running + near-trunk clang instead of gcc. + + Indices and tables ================== diff --git a/docs/tutorial/LangImpl1.rst b/docs/tutorial/LangImpl1.rst index aa619cf..a2c5eee 100644 --- a/docs/tutorial/LangImpl1.rst +++ b/docs/tutorial/LangImpl1.rst @@ -55,7 +55,7 @@ in the various pieces. The structure of the tutorial is: - Because a lot of people are interested in using LLVM as a JIT, we'll dive right into it and show you the 3 lines it takes to add JIT support. LLVM is also useful in many other ways, but this is one - simple and "sexy" way to shows off its power. :) + simple and "sexy" way to show off its power. :) - `Chapter #5 <LangImpl5.html>`_: Extending the Language: Control Flow - With the language up and running, we show how to extend it with control flow operations (if/then/else and a 'for' loop). This diff --git a/docs/tutorial/LangImpl2.rst b/docs/tutorial/LangImpl2.rst index 7262afa..06b18ff 100644 --- a/docs/tutorial/LangImpl2.rst +++ b/docs/tutorial/LangImpl2.rst @@ -691,406 +691,8 @@ libraries, of course.) To build this, just compile with: Here is the code: -.. code-block:: c++ - - #include <cstdio> - #include <cstdlib> - #include <string> - #include <map> - #include <vector> - - //===----------------------------------------------------------------------===// - // Lexer - //===----------------------------------------------------------------------===// - - // The lexer returns tokens [0-255] if it is an unknown character, otherwise one - // of these for known things. - enum Token { - tok_eof = -1, - - // commands - tok_def = -2, tok_extern = -3, - - // primary - tok_identifier = -4, tok_number = -5 - }; - - static std::string IdentifierStr; // Filled in if tok_identifier - static double NumVal; // Filled in if tok_number - - /// gettok - Return the next token from standard input. - static int gettok() { - static int LastChar = ' '; - - // Skip any whitespace. - while (isspace(LastChar)) - LastChar = getchar(); - - if (isalpha(LastChar)) { // identifier: [a-zA-Z][a-zA-Z0-9]* - IdentifierStr = LastChar; - while (isalnum((LastChar = getchar()))) - IdentifierStr += LastChar; - - if (IdentifierStr == "def") return tok_def; - if (IdentifierStr == "extern") return tok_extern; - return tok_identifier; - } - - if (isdigit(LastChar) || LastChar == '.') { // Number: [0-9.]+ - std::string NumStr; - do { - NumStr += LastChar; - LastChar = getchar(); - } while (isdigit(LastChar) || LastChar == '.'); - - NumVal = strtod(NumStr.c_str(), 0); - return tok_number; - } - - if (LastChar == '#') { - // Comment until end of line. - do LastChar = getchar(); - while (LastChar != EOF && LastChar != '\n' && LastChar != '\r'); - - if (LastChar != EOF) - return gettok(); - } - - // Check for end of file. Don't eat the EOF. - if (LastChar == EOF) - return tok_eof; - - // Otherwise, just return the character as its ascii value. - int ThisChar = LastChar; - LastChar = getchar(); - return ThisChar; - } - - //===----------------------------------------------------------------------===// - // Abstract Syntax Tree (aka Parse Tree) - //===----------------------------------------------------------------------===// - - /// ExprAST - Base class for all expression nodes. - class ExprAST { - public: - virtual ~ExprAST() {} - }; - - /// NumberExprAST - Expression class for numeric literals like "1.0". - class NumberExprAST : public ExprAST { - double Val; - public: - NumberExprAST(double val) : Val(val) {} - }; - - /// VariableExprAST - Expression class for referencing a variable, like "a". - class VariableExprAST : public ExprAST { - std::string Name; - public: - VariableExprAST(const std::string &name) : Name(name) {} - }; - - /// BinaryExprAST - Expression class for a binary operator. - class BinaryExprAST : public ExprAST { - char Op; - ExprAST *LHS, *RHS; - public: - BinaryExprAST(char op, ExprAST *lhs, ExprAST *rhs) - : Op(op), LHS(lhs), RHS(rhs) {} - }; - - /// CallExprAST - Expression class for function calls. - class CallExprAST : public ExprAST { - std::string Callee; - std::vector<ExprAST*> Args; - public: - CallExprAST(const std::string &callee, std::vector<ExprAST*> &args) - : Callee(callee), Args(args) {} - }; - - /// PrototypeAST - This class represents the "prototype" for a function, - /// which captures its name, and its argument names (thus implicitly the number - /// of arguments the function takes). - class PrototypeAST { - std::string Name; - std::vector<std::string> Args; - public: - PrototypeAST(const std::string &name, const std::vector<std::string> &args) - : Name(name), Args(args) {} - - }; - - /// FunctionAST - This class represents a function definition itself. - class FunctionAST { - PrototypeAST *Proto; - ExprAST *Body; - public: - FunctionAST(PrototypeAST *proto, ExprAST *body) - : Proto(proto), Body(body) {} - - }; - - //===----------------------------------------------------------------------===// - // Parser - //===----------------------------------------------------------------------===// - - /// CurTok/getNextToken - Provide a simple token buffer. CurTok is the current - /// token the parser is looking at. getNextToken reads another token from the - /// lexer and updates CurTok with its results. - static int CurTok; - static int getNextToken() { - return CurTok = gettok(); - } - - /// BinopPrecedence - This holds the precedence for each binary operator that is - /// defined. - static std::map<char, int> BinopPrecedence; - - /// GetTokPrecedence - Get the precedence of the pending binary operator token. - static int GetTokPrecedence() { - if (!isascii(CurTok)) - return -1; - - // Make sure it's a declared binop. - int TokPrec = BinopPrecedence[CurTok]; - if (TokPrec <= 0) return -1; - return TokPrec; - } - - /// Error* - These are little helper functions for error handling. - ExprAST *Error(const char *Str) { fprintf(stderr, "Error: %s\n", Str);return 0;} - PrototypeAST *ErrorP(const char *Str) { Error(Str); return 0; } - FunctionAST *ErrorF(const char *Str) { Error(Str); return 0; } - - static ExprAST *ParseExpression(); - - /// identifierexpr - /// ::= identifier - /// ::= identifier '(' expression* ')' - static ExprAST *ParseIdentifierExpr() { - std::string IdName = IdentifierStr; - - getNextToken(); // eat identifier. - - if (CurTok != '(') // Simple variable ref. - return new VariableExprAST(IdName); - - // Call. - getNextToken(); // eat ( - std::vector<ExprAST*> Args; - if (CurTok != ')') { - while (1) { - ExprAST *Arg = ParseExpression(); - if (!Arg) return 0; - Args.push_back(Arg); - - if (CurTok == ')') break; - - if (CurTok != ',') - return Error("Expected ')' or ',' in argument list"); - getNextToken(); - } - } - - // Eat the ')'. - getNextToken(); - - return new CallExprAST(IdName, Args); - } - - /// numberexpr ::= number - static ExprAST *ParseNumberExpr() { - ExprAST *Result = new NumberExprAST(NumVal); - getNextToken(); // consume the number - return Result; - } - - /// parenexpr ::= '(' expression ')' - static ExprAST *ParseParenExpr() { - getNextToken(); // eat (. - ExprAST *V = ParseExpression(); - if (!V) return 0; - - if (CurTok != ')') - return Error("expected ')'"); - getNextToken(); // eat ). - return V; - } - - /// primary - /// ::= identifierexpr - /// ::= numberexpr - /// ::= parenexpr - static ExprAST *ParsePrimary() { - switch (CurTok) { - default: return Error("unknown token when expecting an expression"); - case tok_identifier: return ParseIdentifierExpr(); - case tok_number: return ParseNumberExpr(); - case '(': return ParseParenExpr(); - } - } - - /// binoprhs - /// ::= ('+' primary)* - static ExprAST *ParseBinOpRHS(int ExprPrec, ExprAST *LHS) { - // If this is a binop, find its precedence. - while (1) { - int TokPrec = GetTokPrecedence(); - - // If this is a binop that binds at least as tightly as the current binop, - // consume it, otherwise we are done. - if (TokPrec < ExprPrec) - return LHS; - - // Okay, we know this is a binop. - int BinOp = CurTok; - getNextToken(); // eat binop - - // Parse the primary expression after the binary operator. - ExprAST *RHS = ParsePrimary(); - if (!RHS) return 0; - - // If BinOp binds less tightly with RHS than the operator after RHS, let - // the pending operator take RHS as its LHS. - int NextPrec = GetTokPrecedence(); - if (TokPrec < NextPrec) { - RHS = ParseBinOpRHS(TokPrec+1, RHS); - if (RHS == 0) return 0; - } - - // Merge LHS/RHS. - LHS = new BinaryExprAST(BinOp, LHS, RHS); - } - } - - /// expression - /// ::= primary binoprhs - /// - static ExprAST *ParseExpression() { - ExprAST *LHS = ParsePrimary(); - if (!LHS) return 0; - - return ParseBinOpRHS(0, LHS); - } - - /// prototype - /// ::= id '(' id* ')' - static PrototypeAST *ParsePrototype() { - if (CurTok != tok_identifier) - return ErrorP("Expected function name in prototype"); - - std::string FnName = IdentifierStr; - getNextToken(); - - if (CurTok != '(') - return ErrorP("Expected '(' in prototype"); - - std::vector<std::string> ArgNames; - while (getNextToken() == tok_identifier) - ArgNames.push_back(IdentifierStr); - if (CurTok != ')') - return ErrorP("Expected ')' in prototype"); - - // success. - getNextToken(); // eat ')'. - - return new PrototypeAST(FnName, ArgNames); - } - - /// definition ::= 'def' prototype expression - static FunctionAST *ParseDefinition() { - getNextToken(); // eat def. - PrototypeAST *Proto = ParsePrototype(); - if (Proto == 0) return 0; - - if (ExprAST *E = ParseExpression()) - return new FunctionAST(Proto, E); - return 0; - } - - /// toplevelexpr ::= expression - static FunctionAST *ParseTopLevelExpr() { - if (ExprAST *E = ParseExpression()) { - // Make an anonymous proto. - PrototypeAST *Proto = new PrototypeAST("", std::vector<std::string>()); - return new FunctionAST(Proto, E); - } - return 0; - } - - /// external ::= 'extern' prototype - static PrototypeAST *ParseExtern() { - getNextToken(); // eat extern. - return ParsePrototype(); - } - - //===----------------------------------------------------------------------===// - // Top-Level parsing - //===----------------------------------------------------------------------===// - - static void HandleDefinition() { - if (ParseDefinition()) { - fprintf(stderr, "Parsed a function definition.\n"); - } else { - // Skip token for error recovery. - getNextToken(); - } - } - - static void HandleExtern() { - if (ParseExtern()) { - fprintf(stderr, "Parsed an extern\n"); - } else { - // Skip token for error recovery. - getNextToken(); - } - } - - static void HandleTopLevelExpression() { - // Evaluate a top-level expression into an anonymous function. - if (ParseTopLevelExpr()) { - fprintf(stderr, "Parsed a top-level expr\n"); - } else { - // Skip token for error recovery. - getNextToken(); - } - } - - /// top ::= definition | external | expression | ';' - static void MainLoop() { - while (1) { - fprintf(stderr, "ready> "); - switch (CurTok) { - case tok_eof: return; - case ';': getNextToken(); break; // ignore top-level semicolons. - case tok_def: HandleDefinition(); break; - case tok_extern: HandleExtern(); break; - default: HandleTopLevelExpression(); break; - } - } - } - - //===----------------------------------------------------------------------===// - // Main driver code. - //===----------------------------------------------------------------------===// - - int main() { - // Install standard binary operators. - // 1 is lowest precedence. - BinopPrecedence['<'] = 10; - BinopPrecedence['+'] = 20; - BinopPrecedence['-'] = 20; - BinopPrecedence['*'] = 40; // highest. - - // Prime the first token. - fprintf(stderr, "ready> "); - getNextToken(); - - // Run the main "interpreter loop" now. - MainLoop(); - - return 0; - } +.. literalinclude:: ../../examples/Kaleidoscope/Chapter2/toy.cpp + :language: c++ `Next: Implementing Code Generation to LLVM IR <LangImpl3.html>`_ diff --git a/docs/tutorial/LangImpl3.rst b/docs/tutorial/LangImpl3.rst index 9d5f908..7174c09 100644 --- a/docs/tutorial/LangImpl3.rst +++ b/docs/tutorial/LangImpl3.rst @@ -587,574 +587,8 @@ our makefile/command line about which options to use: Here is the code: -.. code-block:: c++ - - // To build this: - // See example below. - - #include "llvm/DerivedTypes.h" - #include "llvm/IRBuilder.h" - #include "llvm/LLVMContext.h" - #include "llvm/Module.h" - #include "llvm/Analysis/Verifier.h" - #include <cstdio> - #include <string> - #include <map> - #include <vector> - using namespace llvm; - - //===----------------------------------------------------------------------===// - // Lexer - //===----------------------------------------------------------------------===// - - // The lexer returns tokens [0-255] if it is an unknown character, otherwise one - // of these for known things. - enum Token { - tok_eof = -1, - - // commands - tok_def = -2, tok_extern = -3, - - // primary - tok_identifier = -4, tok_number = -5 - }; - - static std::string IdentifierStr; // Filled in if tok_identifier - static double NumVal; // Filled in if tok_number - - /// gettok - Return the next token from standard input. - static int gettok() { - static int LastChar = ' '; - - // Skip any whitespace. - while (isspace(LastChar)) - LastChar = getchar(); - - if (isalpha(LastChar)) { // identifier: [a-zA-Z][a-zA-Z0-9]* - IdentifierStr = LastChar; - while (isalnum((LastChar = getchar()))) - IdentifierStr += LastChar; - - if (IdentifierStr == "def") return tok_def; - if (IdentifierStr == "extern") return tok_extern; - return tok_identifier; - } - - if (isdigit(LastChar) || LastChar == '.') { // Number: [0-9.]+ - std::string NumStr; - do { - NumStr += LastChar; - LastChar = getchar(); - } while (isdigit(LastChar) || LastChar == '.'); - - NumVal = strtod(NumStr.c_str(), 0); - return tok_number; - } - - if (LastChar == '#') { - // Comment until end of line. - do LastChar = getchar(); - while (LastChar != EOF && LastChar != '\n' && LastChar != '\r'); - - if (LastChar != EOF) - return gettok(); - } - - // Check for end of file. Don't eat the EOF. - if (LastChar == EOF) - return tok_eof; - - // Otherwise, just return the character as its ascii value. - int ThisChar = LastChar; - LastChar = getchar(); - return ThisChar; - } - - //===----------------------------------------------------------------------===// - // Abstract Syntax Tree (aka Parse Tree) - //===----------------------------------------------------------------------===// - - /// ExprAST - Base class for all expression nodes. - class ExprAST { - public: - virtual ~ExprAST() {} - virtual Value *Codegen() = 0; - }; - - /// NumberExprAST - Expression class for numeric literals like "1.0". - class NumberExprAST : public ExprAST { - double Val; - public: - NumberExprAST(double val) : Val(val) {} - virtual Value *Codegen(); - }; - - /// VariableExprAST - Expression class for referencing a variable, like "a". - class VariableExprAST : public ExprAST { - std::string Name; - public: - VariableExprAST(const std::string &name) : Name(name) {} - virtual Value *Codegen(); - }; - - /// BinaryExprAST - Expression class for a binary operator. - class BinaryExprAST : public ExprAST { - char Op; - ExprAST *LHS, *RHS; - public: - BinaryExprAST(char op, ExprAST *lhs, ExprAST *rhs) - : Op(op), LHS(lhs), RHS(rhs) {} - virtual Value *Codegen(); - }; - - /// CallExprAST - Expression class for function calls. - class CallExprAST : public ExprAST { - std::string Callee; - std::vector<ExprAST*> Args; - public: - CallExprAST(const std::string &callee, std::vector<ExprAST*> &args) - : Callee(callee), Args(args) {} - virtual Value *Codegen(); - }; - - /// PrototypeAST - This class represents the "prototype" for a function, - /// which captures its name, and its argument names (thus implicitly the number - /// of arguments the function takes). - class PrototypeAST { - std::string Name; - std::vector<std::string> Args; - public: - PrototypeAST(const std::string &name, const std::vector<std::string> &args) - : Name(name), Args(args) {} - - Function *Codegen(); - }; - - /// FunctionAST - This class represents a function definition itself. - class FunctionAST { - PrototypeAST *Proto; - ExprAST *Body; - public: - FunctionAST(PrototypeAST *proto, ExprAST *body) - : Proto(proto), Body(body) {} - - Function *Codegen(); - }; - - //===----------------------------------------------------------------------===// - // Parser - //===----------------------------------------------------------------------===// - - /// CurTok/getNextToken - Provide a simple token buffer. CurTok is the current - /// token the parser is looking at. getNextToken reads another token from the - /// lexer and updates CurTok with its results. - static int CurTok; - static int getNextToken() { - return CurTok = gettok(); - } - - /// BinopPrecedence - This holds the precedence for each binary operator that is - /// defined. - static std::map<char, int> BinopPrecedence; - - /// GetTokPrecedence - Get the precedence of the pending binary operator token. - static int GetTokPrecedence() { - if (!isascii(CurTok)) - return -1; - - // Make sure it's a declared binop. - int TokPrec = BinopPrecedence[CurTok]; - if (TokPrec <= 0) return -1; - return TokPrec; - } - - /// Error* - These are little helper functions for error handling. - ExprAST *Error(const char *Str) { fprintf(stderr, "Error: %s\n", Str);return 0;} - PrototypeAST *ErrorP(const char *Str) { Error(Str); return 0; } - FunctionAST *ErrorF(const char *Str) { Error(Str); return 0; } - - static ExprAST *ParseExpression(); - - /// identifierexpr - /// ::= identifier - /// ::= identifier '(' expression* ')' - static ExprAST *ParseIdentifierExpr() { - std::string IdName = IdentifierStr; - - getNextToken(); // eat identifier. - - if (CurTok != '(') // Simple variable ref. - return new VariableExprAST(IdName); - - // Call. - getNextToken(); // eat ( - std::vector<ExprAST*> Args; - if (CurTok != ')') { - while (1) { - ExprAST *Arg = ParseExpression(); - if (!Arg) return 0; - Args.push_back(Arg); - - if (CurTok == ')') break; - - if (CurTok != ',') - return Error("Expected ')' or ',' in argument list"); - getNextToken(); - } - } - - // Eat the ')'. - getNextToken(); - - return new CallExprAST(IdName, Args); - } - - /// numberexpr ::= number - static ExprAST *ParseNumberExpr() { - ExprAST *Result = new NumberExprAST(NumVal); - getNextToken(); // consume the number - return Result; - } - - /// parenexpr ::= '(' expression ')' - static ExprAST *ParseParenExpr() { - getNextToken(); // eat (. - ExprAST *V = ParseExpression(); - if (!V) return 0; - - if (CurTok != ')') - return Error("expected ')'"); - getNextToken(); // eat ). - return V; - } - - /// primary - /// ::= identifierexpr - /// ::= numberexpr - /// ::= parenexpr - static ExprAST *ParsePrimary() { - switch (CurTok) { - default: return Error("unknown token when expecting an expression"); - case tok_identifier: return ParseIdentifierExpr(); - case tok_number: return ParseNumberExpr(); - case '(': return ParseParenExpr(); - } - } - - /// binoprhs - /// ::= ('+' primary)* - static ExprAST *ParseBinOpRHS(int ExprPrec, ExprAST *LHS) { - // If this is a binop, find its precedence. - while (1) { - int TokPrec = GetTokPrecedence(); - - // If this is a binop that binds at least as tightly as the current binop, - // consume it, otherwise we are done. - if (TokPrec < ExprPrec) - return LHS; - - // Okay, we know this is a binop. - int BinOp = CurTok; - getNextToken(); // eat binop - - // Parse the primary expression after the binary operator. - ExprAST *RHS = ParsePrimary(); - if (!RHS) return 0; - - // If BinOp binds less tightly with RHS than the operator after RHS, let - // the pending operator take RHS as its LHS. - int NextPrec = GetTokPrecedence(); - if (TokPrec < NextPrec) { - RHS = ParseBinOpRHS(TokPrec+1, RHS); - if (RHS == 0) return 0; - } - - // Merge LHS/RHS. - LHS = new BinaryExprAST(BinOp, LHS, RHS); - } - } - - /// expression - /// ::= primary binoprhs - /// - static ExprAST *ParseExpression() { - ExprAST *LHS = ParsePrimary(); - if (!LHS) return 0; - - return ParseBinOpRHS(0, LHS); - } - - /// prototype - /// ::= id '(' id* ')' - static PrototypeAST *ParsePrototype() { - if (CurTok != tok_identifier) - return ErrorP("Expected function name in prototype"); - - std::string FnName = IdentifierStr; - getNextToken(); - - if (CurTok != '(') - return ErrorP("Expected '(' in prototype"); - - std::vector<std::string> ArgNames; - while (getNextToken() == tok_identifier) - ArgNames.push_back(IdentifierStr); - if (CurTok != ')') - return ErrorP("Expected ')' in prototype"); - - // success. - getNextToken(); // eat ')'. - - return new PrototypeAST(FnName, ArgNames); - } - - /// definition ::= 'def' prototype expression - static FunctionAST *ParseDefinition() { - getNextToken(); // eat def. - PrototypeAST *Proto = ParsePrototype(); - if (Proto == 0) return 0; - - if (ExprAST *E = ParseExpression()) - return new FunctionAST(Proto, E); - return 0; - } - - /// toplevelexpr ::= expression - static FunctionAST *ParseTopLevelExpr() { - if (ExprAST *E = ParseExpression()) { - // Make an anonymous proto. - PrototypeAST *Proto = new PrototypeAST("", std::vector<std::string>()); - return new FunctionAST(Proto, E); - } - return 0; - } - - /// external ::= 'extern' prototype - static PrototypeAST *ParseExtern() { - getNextToken(); // eat extern. - return ParsePrototype(); - } - - //===----------------------------------------------------------------------===// - // Code Generation - //===----------------------------------------------------------------------===// - - static Module *TheModule; - static IRBuilder<> Builder(getGlobalContext()); - static std::map<std::string, Value*> NamedValues; - - Value *ErrorV(const char *Str) { Error(Str); return 0; } - - Value *NumberExprAST::Codegen() { - return ConstantFP::get(getGlobalContext(), APFloat(Val)); - } - - Value *VariableExprAST::Codegen() { - // Look this variable up in the function. - Value *V = NamedValues[Name]; - return V ? V : ErrorV("Unknown variable name"); - } - - Value *BinaryExprAST::Codegen() { - Value *L = LHS->Codegen(); - Value *R = RHS->Codegen(); - if (L == 0 || R == 0) return 0; - - switch (Op) { - case '+': return Builder.CreateFAdd(L, R, "addtmp"); - case '-': return Builder.CreateFSub(L, R, "subtmp"); - case '*': return Builder.CreateFMul(L, R, "multmp"); - case '<': - L = Builder.CreateFCmpULT(L, R, "cmptmp"); - // Convert bool 0/1 to double 0.0 or 1.0 - return Builder.CreateUIToFP(L, Type::getDoubleTy(getGlobalContext()), - "booltmp"); - default: return ErrorV("invalid binary operator"); - } - } - - Value *CallExprAST::Codegen() { - // Look up the name in the global module table. - Function *CalleeF = TheModule->getFunction(Callee); - if (CalleeF == 0) - return ErrorV("Unknown function referenced"); - - // If argument mismatch error. - if (CalleeF->arg_size() != Args.size()) - return ErrorV("Incorrect # arguments passed"); - - std::vector<Value*> ArgsV; - for (unsigned i = 0, e = Args.size(); i != e; ++i) { - ArgsV.push_back(Args[i]->Codegen()); - if (ArgsV.back() == 0) return 0; - } - - return Builder.CreateCall(CalleeF, ArgsV, "calltmp"); - } - - Function *PrototypeAST::Codegen() { - // Make the function type: double(double,double) etc. - std::vector<Type*> Doubles(Args.size(), - Type::getDoubleTy(getGlobalContext())); - FunctionType *FT = FunctionType::get(Type::getDoubleTy(getGlobalContext()), - Doubles, false); - - Function *F = Function::Create(FT, Function::ExternalLinkage, Name, TheModule); - - // If F conflicted, there was already something named 'Name'. If it has a - // body, don't allow redefinition or reextern. - if (F->getName() != Name) { - // Delete the one we just made and get the existing one. - F->eraseFromParent(); - F = TheModule->getFunction(Name); - - // If F already has a body, reject this. - if (!F->empty()) { - ErrorF("redefinition of function"); - return 0; - } - - // If F took a different number of args, reject. - if (F->arg_size() != Args.size()) { - ErrorF("redefinition of function with different # args"); - return 0; - } - } - - // Set names for all arguments. - unsigned Idx = 0; - for (Function::arg_iterator AI = F->arg_begin(); Idx != Args.size(); - ++AI, ++Idx) { - AI->setName(Args[Idx]); - - // Add arguments to variable symbol table. - NamedValues[Args[Idx]] = AI; - } - - return F; - } - - Function *FunctionAST::Codegen() { - NamedValues.clear(); - - Function *TheFunction = Proto->Codegen(); - if (TheFunction == 0) - return 0; - - // Create a new basic block to start insertion into. - BasicBlock *BB = BasicBlock::Create(getGlobalContext(), "entry", TheFunction); - Builder.SetInsertPoint(BB); - - if (Value *RetVal = Body->Codegen()) { - // Finish off the function. - Builder.CreateRet(RetVal); - - // Validate the generated code, checking for consistency. - verifyFunction(*TheFunction); - - return TheFunction; - } - - // Error reading body, remove function. - TheFunction->eraseFromParent(); - return 0; - } - - //===----------------------------------------------------------------------===// - // Top-Level parsing and JIT Driver - //===----------------------------------------------------------------------===// - - static void HandleDefinition() { - if (FunctionAST *F = ParseDefinition()) { - if (Function *LF = F->Codegen()) { - fprintf(stderr, "Read function definition:"); - LF->dump(); - } - } else { - // Skip token for error recovery. - getNextToken(); - } - } - - static void HandleExtern() { - if (PrototypeAST *P = ParseExtern()) { - if (Function *F = P->Codegen()) { - fprintf(stderr, "Read extern: "); - F->dump(); - } - } else { - // Skip token for error recovery. - getNextToken(); - } - } - - static void HandleTopLevelExpression() { - // Evaluate a top-level expression into an anonymous function. - if (FunctionAST *F = ParseTopLevelExpr()) { - if (Function *LF = F->Codegen()) { - fprintf(stderr, "Read top-level expression:"); - LF->dump(); - } - } else { - // Skip token for error recovery. - getNextToken(); - } - } - - /// top ::= definition | external | expression | ';' - static void MainLoop() { - while (1) { - fprintf(stderr, "ready> "); - switch (CurTok) { - case tok_eof: return; - case ';': getNextToken(); break; // ignore top-level semicolons. - case tok_def: HandleDefinition(); break; - case tok_extern: HandleExtern(); break; - default: HandleTopLevelExpression(); break; - } - } - } - - //===----------------------------------------------------------------------===// - // "Library" functions that can be "extern'd" from user code. - //===----------------------------------------------------------------------===// - - /// putchard - putchar that takes a double and returns 0. - extern "C" - double putchard(double X) { - putchar((char)X); - return 0; - } - - //===----------------------------------------------------------------------===// - // Main driver code. - //===----------------------------------------------------------------------===// - - int main() { - LLVMContext &Context = getGlobalContext(); - - // Install standard binary operators. - // 1 is lowest precedence. - BinopPrecedence['<'] = 10; - BinopPrecedence['+'] = 20; - BinopPrecedence['-'] = 20; - BinopPrecedence['*'] = 40; // highest. - - // Prime the first token. - fprintf(stderr, "ready> "); - getNextToken(); - - // Make the module, which holds all the code. - TheModule = new Module("my cool jit", Context); - - // Run the main "interpreter loop" now. - MainLoop(); - - // Print out all of the generated code. - TheModule->dump(); - - return 0; - } +.. literalinclude:: ../../examples/Kaleidoscope/Chapter3/toy.cpp + :language: c++ `Next: Adding JIT and Optimizer Support <LangImpl4.html>`_ diff --git a/docs/tutorial/LangImpl4.rst b/docs/tutorial/LangImpl4.rst index 96c06d1..44e0cc1 100644 --- a/docs/tutorial/LangImpl4.rst +++ b/docs/tutorial/LangImpl4.rst @@ -438,624 +438,8 @@ properly at runtime. Here is the code: -.. code-block:: c++ - - #include "llvm/DerivedTypes.h" - #include "llvm/ExecutionEngine/ExecutionEngine.h" - #include "llvm/ExecutionEngine/JIT.h" - #include "llvm/IRBuilder.h" - #include "llvm/LLVMContext.h" - #include "llvm/Module.h" - #include "llvm/PassManager.h" - #include "llvm/Analysis/Verifier.h" - #include "llvm/Analysis/Passes.h" - #include "llvm/DataLayout.h" - #include "llvm/Transforms/Scalar.h" - #include "llvm/Support/TargetSelect.h" - #include <cstdio> - #include <string> - #include <map> - #include <vector> - using namespace llvm; - - //===----------------------------------------------------------------------===// - // Lexer - //===----------------------------------------------------------------------===// - - // The lexer returns tokens [0-255] if it is an unknown character, otherwise one - // of these for known things. - enum Token { - tok_eof = -1, - - // commands - tok_def = -2, tok_extern = -3, - - // primary - tok_identifier = -4, tok_number = -5 - }; - - static std::string IdentifierStr; // Filled in if tok_identifier - static double NumVal; // Filled in if tok_number - - /// gettok - Return the next token from standard input. - static int gettok() { - static int LastChar = ' '; - - // Skip any whitespace. - while (isspace(LastChar)) - LastChar = getchar(); - - if (isalpha(LastChar)) { // identifier: [a-zA-Z][a-zA-Z0-9]* - IdentifierStr = LastChar; - while (isalnum((LastChar = getchar()))) - IdentifierStr += LastChar; - - if (IdentifierStr == "def") return tok_def; - if (IdentifierStr == "extern") return tok_extern; - return tok_identifier; - } - - if (isdigit(LastChar) || LastChar == '.') { // Number: [0-9.]+ - std::string NumStr; - do { - NumStr += LastChar; - LastChar = getchar(); - } while (isdigit(LastChar) || LastChar == '.'); - - NumVal = strtod(NumStr.c_str(), 0); - return tok_number; - } - - if (LastChar == '#') { - // Comment until end of line. - do LastChar = getchar(); - while (LastChar != EOF && LastChar != '\n' && LastChar != '\r'); - - if (LastChar != EOF) - return gettok(); - } - - // Check for end of file. Don't eat the EOF. - if (LastChar == EOF) - return tok_eof; - - // Otherwise, just return the character as its ascii value. - int ThisChar = LastChar; - LastChar = getchar(); - return ThisChar; - } - - //===----------------------------------------------------------------------===// - // Abstract Syntax Tree (aka Parse Tree) - //===----------------------------------------------------------------------===// - - /// ExprAST - Base class for all expression nodes. - class ExprAST { - public: - virtual ~ExprAST() {} - virtual Value *Codegen() = 0; - }; - - /// NumberExprAST - Expression class for numeric literals like "1.0". - class NumberExprAST : public ExprAST { - double Val; - public: - NumberExprAST(double val) : Val(val) {} - virtual Value *Codegen(); - }; - - /// VariableExprAST - Expression class for referencing a variable, like "a". - class VariableExprAST : public ExprAST { - std::string Name; - public: - VariableExprAST(const std::string &name) : Name(name) {} - virtual Value *Codegen(); - }; - - /// BinaryExprAST - Expression class for a binary operator. - class BinaryExprAST : public ExprAST { - char Op; - ExprAST *LHS, *RHS; - public: - BinaryExprAST(char op, ExprAST *lhs, ExprAST *rhs) - : Op(op), LHS(lhs), RHS(rhs) {} - virtual Value *Codegen(); - }; - - /// CallExprAST - Expression class for function calls. - class CallExprAST : public ExprAST { - std::string Callee; - std::vector<ExprAST*> Args; - public: - CallExprAST(const std::string &callee, std::vector<ExprAST*> &args) - : Callee(callee), Args(args) {} - virtual Value *Codegen(); - }; - - /// PrototypeAST - This class represents the "prototype" for a function, - /// which captures its name, and its argument names (thus implicitly the number - /// of arguments the function takes). - class PrototypeAST { - std::string Name; - std::vector<std::string> Args; - public: - PrototypeAST(const std::string &name, const std::vector<std::string> &args) - : Name(name), Args(args) {} - - Function *Codegen(); - }; - - /// FunctionAST - This class represents a function definition itself. - class FunctionAST { - PrototypeAST *Proto; - ExprAST *Body; - public: - FunctionAST(PrototypeAST *proto, ExprAST *body) - : Proto(proto), Body(body) {} - - Function *Codegen(); - }; - - //===----------------------------------------------------------------------===// - // Parser - //===----------------------------------------------------------------------===// - - /// CurTok/getNextToken - Provide a simple token buffer. CurTok is the current - /// token the parser is looking at. getNextToken reads another token from the - /// lexer and updates CurTok with its results. - static int CurTok; - static int getNextToken() { - return CurTok = gettok(); - } - - /// BinopPrecedence - This holds the precedence for each binary operator that is - /// defined. - static std::map<char, int> BinopPrecedence; - - /// GetTokPrecedence - Get the precedence of the pending binary operator token. - static int GetTokPrecedence() { - if (!isascii(CurTok)) - return -1; - - // Make sure it's a declared binop. - int TokPrec = BinopPrecedence[CurTok]; - if (TokPrec <= 0) return -1; - return TokPrec; - } - - /// Error* - These are little helper functions for error handling. - ExprAST *Error(const char *Str) { fprintf(stderr, "Error: %s\n", Str);return 0;} - PrototypeAST *ErrorP(const char *Str) { Error(Str); return 0; } - FunctionAST *ErrorF(const char *Str) { Error(Str); return 0; } - - static ExprAST *ParseExpression(); - - /// identifierexpr - /// ::= identifier - /// ::= identifier '(' expression* ')' - static ExprAST *ParseIdentifierExpr() { - std::string IdName = IdentifierStr; - - getNextToken(); // eat identifier. - - if (CurTok != '(') // Simple variable ref. - return new VariableExprAST(IdName); - - // Call. - getNextToken(); // eat ( - std::vector<ExprAST*> Args; - if (CurTok != ')') { - while (1) { - ExprAST *Arg = ParseExpression(); - if (!Arg) return 0; - Args.push_back(Arg); - - if (CurTok == ')') break; - - if (CurTok != ',') - return Error("Expected ')' or ',' in argument list"); - getNextToken(); - } - } - - // Eat the ')'. - getNextToken(); - - return new CallExprAST(IdName, Args); - } - - /// numberexpr ::= number - static ExprAST *ParseNumberExpr() { - ExprAST *Result = new NumberExprAST(NumVal); - getNextToken(); // consume the number - return Result; - } - - /// parenexpr ::= '(' expression ')' - static ExprAST *ParseParenExpr() { - getNextToken(); // eat (. - ExprAST *V = ParseExpression(); - if (!V) return 0; - - if (CurTok != ')') - return Error("expected ')'"); - getNextToken(); // eat ). - return V; - } - - /// primary - /// ::= identifierexpr - /// ::= numberexpr - /// ::= parenexpr - static ExprAST *ParsePrimary() { - switch (CurTok) { - default: return Error("unknown token when expecting an expression"); - case tok_identifier: return ParseIdentifierExpr(); - case tok_number: return ParseNumberExpr(); - case '(': return ParseParenExpr(); - } - } - - /// binoprhs - /// ::= ('+' primary)* - static ExprAST *ParseBinOpRHS(int ExprPrec, ExprAST *LHS) { - // If this is a binop, find its precedence. - while (1) { - int TokPrec = GetTokPrecedence(); - - // If this is a binop that binds at least as tightly as the current binop, - // consume it, otherwise we are done. - if (TokPrec < ExprPrec) - return LHS; - - // Okay, we know this is a binop. - int BinOp = CurTok; - getNextToken(); // eat binop - - // Parse the primary expression after the binary operator. - ExprAST *RHS = ParsePrimary(); - if (!RHS) return 0; - - // If BinOp binds less tightly with RHS than the operator after RHS, let - // the pending operator take RHS as its LHS. - int NextPrec = GetTokPrecedence(); - if (TokPrec < NextPrec) { - RHS = ParseBinOpRHS(TokPrec+1, RHS); - if (RHS == 0) return 0; - } - - // Merge LHS/RHS. - LHS = new BinaryExprAST(BinOp, LHS, RHS); - } - } - - /// expression - /// ::= primary binoprhs - /// - static ExprAST *ParseExpression() { - ExprAST *LHS = ParsePrimary(); - if (!LHS) return 0; - - return ParseBinOpRHS(0, LHS); - } - - /// prototype - /// ::= id '(' id* ')' - static PrototypeAST *ParsePrototype() { - if (CurTok != tok_identifier) - return ErrorP("Expected function name in prototype"); - - std::string FnName = IdentifierStr; - getNextToken(); - - if (CurTok != '(') - return ErrorP("Expected '(' in prototype"); - - std::vector<std::string> ArgNames; - while (getNextToken() == tok_identifier) - ArgNames.push_back(IdentifierStr); - if (CurTok != ')') - return ErrorP("Expected ')' in prototype"); - - // success. - getNextToken(); // eat ')'. - - return new PrototypeAST(FnName, ArgNames); - } - - /// definition ::= 'def' prototype expression - static FunctionAST *ParseDefinition() { - getNextToken(); // eat def. - PrototypeAST *Proto = ParsePrototype(); - if (Proto == 0) return 0; - - if (ExprAST *E = ParseExpression()) - return new FunctionAST(Proto, E); - return 0; - } - - /// toplevelexpr ::= expression - static FunctionAST *ParseTopLevelExpr() { - if (ExprAST *E = ParseExpression()) { - // Make an anonymous proto. - PrototypeAST *Proto = new PrototypeAST("", std::vector<std::string>()); - return new FunctionAST(Proto, E); - } - return 0; - } - - /// external ::= 'extern' prototype - static PrototypeAST *ParseExtern() { - getNextToken(); // eat extern. - return ParsePrototype(); - } - - //===----------------------------------------------------------------------===// - // Code Generation - //===----------------------------------------------------------------------===// - - static Module *TheModule; - static IRBuilder<> Builder(getGlobalContext()); - static std::map<std::string, Value*> NamedValues; - static FunctionPassManager *TheFPM; - - Value *ErrorV(const char *Str) { Error(Str); return 0; } - - Value *NumberExprAST::Codegen() { - return ConstantFP::get(getGlobalContext(), APFloat(Val)); - } - - Value *VariableExprAST::Codegen() { - // Look this variable up in the function. - Value *V = NamedValues[Name]; - return V ? V : ErrorV("Unknown variable name"); - } - - Value *BinaryExprAST::Codegen() { - Value *L = LHS->Codegen(); - Value *R = RHS->Codegen(); - if (L == 0 || R == 0) return 0; - - switch (Op) { - case '+': return Builder.CreateFAdd(L, R, "addtmp"); - case '-': return Builder.CreateFSub(L, R, "subtmp"); - case '*': return Builder.CreateFMul(L, R, "multmp"); - case '<': - L = Builder.CreateFCmpULT(L, R, "cmptmp"); - // Convert bool 0/1 to double 0.0 or 1.0 - return Builder.CreateUIToFP(L, Type::getDoubleTy(getGlobalContext()), - "booltmp"); - default: return ErrorV("invalid binary operator"); - } - } - - Value *CallExprAST::Codegen() { - // Look up the name in the global module table. - Function *CalleeF = TheModule->getFunction(Callee); - if (CalleeF == 0) - return ErrorV("Unknown function referenced"); - - // If argument mismatch error. - if (CalleeF->arg_size() != Args.size()) - return ErrorV("Incorrect # arguments passed"); - - std::vector<Value*> ArgsV; - for (unsigned i = 0, e = Args.size(); i != e; ++i) { - ArgsV.push_back(Args[i]->Codegen()); - if (ArgsV.back() == 0) return 0; - } - - return Builder.CreateCall(CalleeF, ArgsV, "calltmp"); - } - - Function *PrototypeAST::Codegen() { - // Make the function type: double(double,double) etc. - std::vector<Type*> Doubles(Args.size(), - Type::getDoubleTy(getGlobalContext())); - FunctionType *FT = FunctionType::get(Type::getDoubleTy(getGlobalContext()), - Doubles, false); - - Function *F = Function::Create(FT, Function::ExternalLinkage, Name, TheModule); - - // If F conflicted, there was already something named 'Name'. If it has a - // body, don't allow redefinition or reextern. - if (F->getName() != Name) { - // Delete the one we just made and get the existing one. - F->eraseFromParent(); - F = TheModule->getFunction(Name); - - // If F already has a body, reject this. - if (!F->empty()) { - ErrorF("redefinition of function"); - return 0; - } - - // If F took a different number of args, reject. - if (F->arg_size() != Args.size()) { - ErrorF("redefinition of function with different # args"); - return 0; - } - } - - // Set names for all arguments. - unsigned Idx = 0; - for (Function::arg_iterator AI = F->arg_begin(); Idx != Args.size(); - ++AI, ++Idx) { - AI->setName(Args[Idx]); - - // Add arguments to variable symbol table. - NamedValues[Args[Idx]] = AI; - } - - return F; - } - - Function *FunctionAST::Codegen() { - NamedValues.clear(); - - Function *TheFunction = Proto->Codegen(); - if (TheFunction == 0) - return 0; - - // Create a new basic block to start insertion into. - BasicBlock *BB = BasicBlock::Create(getGlobalContext(), "entry", TheFunction); - Builder.SetInsertPoint(BB); - - if (Value *RetVal = Body->Codegen()) { - // Finish off the function. - Builder.CreateRet(RetVal); - - // Validate the generated code, checking for consistency. - verifyFunction(*TheFunction); - - // Optimize the function. - TheFPM->run(*TheFunction); - - return TheFunction; - } - - // Error reading body, remove function. - TheFunction->eraseFromParent(); - return 0; - } - - //===----------------------------------------------------------------------===// - // Top-Level parsing and JIT Driver - //===----------------------------------------------------------------------===// - - static ExecutionEngine *TheExecutionEngine; - - static void HandleDefinition() { - if (FunctionAST *F = ParseDefinition()) { - if (Function *LF = F->Codegen()) { - fprintf(stderr, "Read function definition:"); - LF->dump(); - } - } else { - // Skip token for error recovery. - getNextToken(); - } - } - - static void HandleExtern() { - if (PrototypeAST *P = ParseExtern()) { - if (Function *F = P->Codegen()) { - fprintf(stderr, "Read extern: "); - F->dump(); - } - } else { - // Skip token for error recovery. - getNextToken(); - } - } - - static void HandleTopLevelExpression() { - // Evaluate a top-level expression into an anonymous function. - if (FunctionAST *F = ParseTopLevelExpr()) { - if (Function *LF = F->Codegen()) { - fprintf(stderr, "Read top-level expression:"); - LF->dump(); - - // JIT the function, returning a function pointer. - void *FPtr = TheExecutionEngine->getPointerToFunction(LF); - - // Cast it to the right type (takes no arguments, returns a double) so we - // can call it as a native function. - double (*FP)() = (double (*)())(intptr_t)FPtr; - fprintf(stderr, "Evaluated to %f\n", FP()); - } - } else { - // Skip token for error recovery. - getNextToken(); - } - } - - /// top ::= definition | external | expression | ';' - static void MainLoop() { - while (1) { - fprintf(stderr, "ready> "); - switch (CurTok) { - case tok_eof: return; - case ';': getNextToken(); break; // ignore top-level semicolons. - case tok_def: HandleDefinition(); break; - case tok_extern: HandleExtern(); break; - default: HandleTopLevelExpression(); break; - } - } - } - - //===----------------------------------------------------------------------===// - // "Library" functions that can be "extern'd" from user code. - //===----------------------------------------------------------------------===// - - /// putchard - putchar that takes a double and returns 0. - extern "C" - double putchard(double X) { - putchar((char)X); - return 0; - } - - //===----------------------------------------------------------------------===// - // Main driver code. - //===----------------------------------------------------------------------===// - - int main() { - InitializeNativeTarget(); - LLVMContext &Context = getGlobalContext(); - - // Install standard binary operators. - // 1 is lowest precedence. - BinopPrecedence['<'] = 10; - BinopPrecedence['+'] = 20; - BinopPrecedence['-'] = 20; - BinopPrecedence['*'] = 40; // highest. - - // Prime the first token. - fprintf(stderr, "ready> "); - getNextToken(); - - // Make the module, which holds all the code. - TheModule = new Module("my cool jit", Context); - - // Create the JIT. This takes ownership of the module. - std::string ErrStr; - TheExecutionEngine = EngineBuilder(TheModule).setErrorStr(&ErrStr).create(); - if (!TheExecutionEngine) { - fprintf(stderr, "Could not create ExecutionEngine: %s\n", ErrStr.c_str()); - exit(1); - } - - FunctionPassManager OurFPM(TheModule); - - // Set up the optimizer pipeline. Start with registering info about how the - // target lays out data structures. - OurFPM.add(new DataLayout(*TheExecutionEngine->getDataLayout())); - // Provide basic AliasAnalysis support for GVN. - OurFPM.add(createBasicAliasAnalysisPass()); - // Do simple "peephole" optimizations and bit-twiddling optzns. - OurFPM.add(createInstructionCombiningPass()); - // Reassociate expressions. - OurFPM.add(createReassociatePass()); - // Eliminate Common SubExpressions. - OurFPM.add(createGVNPass()); - // Simplify the control flow graph (deleting unreachable blocks, etc). - OurFPM.add(createCFGSimplificationPass()); - - OurFPM.doInitialization(); - - // Set the global so the code gen can use this. - TheFPM = &OurFPM; - - // Run the main "interpreter loop" now. - MainLoop(); - - TheFPM = 0; - - // Print out all of the generated code. - TheModule->dump(); - - return 0; - } +.. literalinclude:: ../../examples/Kaleidoscope/Chapter4/toy.cpp + :language: c++ `Next: Extending the language: control flow <LangImpl5.html>`_ diff --git a/docs/tutorial/LangImpl5.rst b/docs/tutorial/LangImpl5.rst index 80d5f37..ed5b652 100644 --- a/docs/tutorial/LangImpl5.rst +++ b/docs/tutorial/LangImpl5.rst @@ -742,866 +742,8 @@ the if/then/else and for expressions.. To build this example, use: Here is the code: -.. code-block:: c++ - - #include "llvm/DerivedTypes.h" - #include "llvm/ExecutionEngine/ExecutionEngine.h" - #include "llvm/ExecutionEngine/JIT.h" - #include "llvm/IRBuilder.h" - #include "llvm/LLVMContext.h" - #include "llvm/Module.h" - #include "llvm/PassManager.h" - #include "llvm/Analysis/Verifier.h" - #include "llvm/Analysis/Passes.h" - #include "llvm/DataLayout.h" - #include "llvm/Transforms/Scalar.h" - #include "llvm/Support/TargetSelect.h" - #include <cstdio> - #include <string> - #include <map> - #include <vector> - using namespace llvm; - - //===----------------------------------------------------------------------===// - // Lexer - //===----------------------------------------------------------------------===// - - // The lexer returns tokens [0-255] if it is an unknown character, otherwise one - // of these for known things. - enum Token { - tok_eof = -1, - - // commands - tok_def = -2, tok_extern = -3, - - // primary - tok_identifier = -4, tok_number = -5, - - // control - tok_if = -6, tok_then = -7, tok_else = -8, - tok_for = -9, tok_in = -10 - }; - - static std::string IdentifierStr; // Filled in if tok_identifier - static double NumVal; // Filled in if tok_number - - /// gettok - Return the next token from standard input. - static int gettok() { - static int LastChar = ' '; - - // Skip any whitespace. - while (isspace(LastChar)) - LastChar = getchar(); - - if (isalpha(LastChar)) { // identifier: [a-zA-Z][a-zA-Z0-9]* - IdentifierStr = LastChar; - while (isalnum((LastChar = getchar()))) - IdentifierStr += LastChar; - - if (IdentifierStr == "def") return tok_def; - if (IdentifierStr == "extern") return tok_extern; - if (IdentifierStr == "if") return tok_if; - if (IdentifierStr == "then") return tok_then; - if (IdentifierStr == "else") return tok_else; - if (IdentifierStr == "for") return tok_for; - if (IdentifierStr == "in") return tok_in; - return tok_identifier; - } - - if (isdigit(LastChar) || LastChar == '.') { // Number: [0-9.]+ - std::string NumStr; - do { - NumStr += LastChar; - LastChar = getchar(); - } while (isdigit(LastChar) || LastChar == '.'); - - NumVal = strtod(NumStr.c_str(), 0); - return tok_number; - } - - if (LastChar == '#') { - // Comment until end of line. - do LastChar = getchar(); - while (LastChar != EOF && LastChar != '\n' && LastChar != '\r'); - - if (LastChar != EOF) - return gettok(); - } - - // Check for end of file. Don't eat the EOF. - if (LastChar == EOF) - return tok_eof; - - // Otherwise, just return the character as its ascii value. - int ThisChar = LastChar; - LastChar = getchar(); - return ThisChar; - } - - //===----------------------------------------------------------------------===// - // Abstract Syntax Tree (aka Parse Tree) - //===----------------------------------------------------------------------===// - - /// ExprAST - Base class for all expression nodes. - class ExprAST { - public: - virtual ~ExprAST() {} - virtual Value *Codegen() = 0; - }; - - /// NumberExprAST - Expression class for numeric literals like "1.0". - class NumberExprAST : public ExprAST { - double Val; - public: - NumberExprAST(double val) : Val(val) {} - virtual Value *Codegen(); - }; - - /// VariableExprAST - Expression class for referencing a variable, like "a". - class VariableExprAST : public ExprAST { - std::string Name; - public: - VariableExprAST(const std::string &name) : Name(name) {} - virtual Value *Codegen(); - }; - - /// BinaryExprAST - Expression class for a binary operator. - class BinaryExprAST : public ExprAST { - char Op; - ExprAST *LHS, *RHS; - public: - BinaryExprAST(char op, ExprAST *lhs, ExprAST *rhs) - : Op(op), LHS(lhs), RHS(rhs) {} - virtual Value *Codegen(); - }; - - /// CallExprAST - Expression class for function calls. - class CallExprAST : public ExprAST { - std::string Callee; - std::vector<ExprAST*> Args; - public: - CallExprAST(const std::string &callee, std::vector<ExprAST*> &args) - : Callee(callee), Args(args) {} - virtual Value *Codegen(); - }; - - /// IfExprAST - Expression class for if/then/else. - class IfExprAST : public ExprAST { - ExprAST *Cond, *Then, *Else; - public: - IfExprAST(ExprAST *cond, ExprAST *then, ExprAST *_else) - : Cond(cond), Then(then), Else(_else) {} - virtual Value *Codegen(); - }; - - /// ForExprAST - Expression class for for/in. - class ForExprAST : public ExprAST { - std::string VarName; - ExprAST *Start, *End, *Step, *Body; - public: - ForExprAST(const std::string &varname, ExprAST *start, ExprAST *end, - ExprAST *step, ExprAST *body) - : VarName(varname), Start(start), End(end), Step(step), Body(body) {} - virtual Value *Codegen(); - }; - - /// PrototypeAST - This class represents the "prototype" for a function, - /// which captures its name, and its argument names (thus implicitly the number - /// of arguments the function takes). - class PrototypeAST { - std::string Name; - std::vector<std::string> Args; - public: - PrototypeAST(const std::string &name, const std::vector<std::string> &args) - : Name(name), Args(args) {} - - Function *Codegen(); - }; - - /// FunctionAST - This class represents a function definition itself. - class FunctionAST { - PrototypeAST *Proto; - ExprAST *Body; - public: - FunctionAST(PrototypeAST *proto, ExprAST *body) - : Proto(proto), Body(body) {} - - Function *Codegen(); - }; - - //===----------------------------------------------------------------------===// - // Parser - //===----------------------------------------------------------------------===// - - /// CurTok/getNextToken - Provide a simple token buffer. CurTok is the current - /// token the parser is looking at. getNextToken reads another token from the - /// lexer and updates CurTok with its results. - static int CurTok; - static int getNextToken() { - return CurTok = gettok(); - } - - /// BinopPrecedence - This holds the precedence for each binary operator that is - /// defined. - static std::map<char, int> BinopPrecedence; - - /// GetTokPrecedence - Get the precedence of the pending binary operator token. - static int GetTokPrecedence() { - if (!isascii(CurTok)) - return -1; - - // Make sure it's a declared binop. - int TokPrec = BinopPrecedence[CurTok]; - if (TokPrec <= 0) return -1; - return TokPrec; - } - - /// Error* - These are little helper functions for error handling. - ExprAST *Error(const char *Str) { fprintf(stderr, "Error: %s\n", Str);return 0;} - PrototypeAST *ErrorP(const char *Str) { Error(Str); return 0; } - FunctionAST *ErrorF(const char *Str) { Error(Str); return 0; } - - static ExprAST *ParseExpression(); - - /// identifierexpr - /// ::= identifier - /// ::= identifier '(' expression* ')' - static ExprAST *ParseIdentifierExpr() { - std::string IdName = IdentifierStr; - - getNextToken(); // eat identifier. - - if (CurTok != '(') // Simple variable ref. - return new VariableExprAST(IdName); - - // Call. - getNextToken(); // eat ( - std::vector<ExprAST*> Args; - if (CurTok != ')') { - while (1) { - ExprAST *Arg = ParseExpression(); - if (!Arg) return 0; - Args.push_back(Arg); - - if (CurTok == ')') break; - - if (CurTok != ',') - return Error("Expected ')' or ',' in argument list"); - getNextToken(); - } - } - - // Eat the ')'. - getNextToken(); - - return new CallExprAST(IdName, Args); - } - - /// numberexpr ::= number - static ExprAST *ParseNumberExpr() { - ExprAST *Result = new NumberExprAST(NumVal); - getNextToken(); // consume the number - return Result; - } - - /// parenexpr ::= '(' expression ')' - static ExprAST *ParseParenExpr() { - getNextToken(); // eat (. - ExprAST *V = ParseExpression(); - if (!V) return 0; - - if (CurTok != ')') - return Error("expected ')'"); - getNextToken(); // eat ). - return V; - } - - /// ifexpr ::= 'if' expression 'then' expression 'else' expression - static ExprAST *ParseIfExpr() { - getNextToken(); // eat the if. - - // condition. - ExprAST *Cond = ParseExpression(); - if (!Cond) return 0; - - if (CurTok != tok_then) - return Error("expected then"); - getNextToken(); // eat the then - - ExprAST *Then = ParseExpression(); - if (Then == 0) return 0; - - if (CurTok != tok_else) - return Error("expected else"); - - getNextToken(); - - ExprAST *Else = ParseExpression(); - if (!Else) return 0; - - return new IfExprAST(Cond, Then, Else); - } - - /// forexpr ::= 'for' identifier '=' expr ',' expr (',' expr)? 'in' expression - static ExprAST *ParseForExpr() { - getNextToken(); // eat the for. - - if (CurTok != tok_identifier) - return Error("expected identifier after for"); - - std::string IdName = IdentifierStr; - getNextToken(); // eat identifier. - - if (CurTok != '=') - return Error("expected '=' after for"); - getNextToken(); // eat '='. - - - ExprAST *Start = ParseExpression(); - if (Start == 0) return 0; - if (CurTok != ',') - return Error("expected ',' after for start value"); - getNextToken(); - - ExprAST *End = ParseExpression(); - if (End == 0) return 0; - - // The step value is optional. - ExprAST *Step = 0; - if (CurTok == ',') { - getNextToken(); - Step = ParseExpression(); - if (Step == 0) return 0; - } - - if (CurTok != tok_in) - return Error("expected 'in' after for"); - getNextToken(); // eat 'in'. - - ExprAST *Body = ParseExpression(); - if (Body == 0) return 0; - - return new ForExprAST(IdName, Start, End, Step, Body); - } - - /// primary - /// ::= identifierexpr - /// ::= numberexpr - /// ::= parenexpr - /// ::= ifexpr - /// ::= forexpr - static ExprAST *ParsePrimary() { - switch (CurTok) { - default: return Error("unknown token when expecting an expression"); - case tok_identifier: return ParseIdentifierExpr(); - case tok_number: return ParseNumberExpr(); - case '(': return ParseParenExpr(); - case tok_if: return ParseIfExpr(); - case tok_for: return ParseForExpr(); - } - } - - /// binoprhs - /// ::= ('+' primary)* - static ExprAST *ParseBinOpRHS(int ExprPrec, ExprAST *LHS) { - // If this is a binop, find its precedence. - while (1) { - int TokPrec = GetTokPrecedence(); - - // If this is a binop that binds at least as tightly as the current binop, - // consume it, otherwise we are done. - if (TokPrec < ExprPrec) - return LHS; - - // Okay, we know this is a binop. - int BinOp = CurTok; - getNextToken(); // eat binop - - // Parse the primary expression after the binary operator. - ExprAST *RHS = ParsePrimary(); - if (!RHS) return 0; - - // If BinOp binds less tightly with RHS than the operator after RHS, let - // the pending operator take RHS as its LHS. - int NextPrec = GetTokPrecedence(); - if (TokPrec < NextPrec) { - RHS = ParseBinOpRHS(TokPrec+1, RHS); - if (RHS == 0) return 0; - } - - // Merge LHS/RHS. - LHS = new BinaryExprAST(BinOp, LHS, RHS); - } - } - - /// expression - /// ::= primary binoprhs - /// - static ExprAST *ParseExpression() { - ExprAST *LHS = ParsePrimary(); - if (!LHS) return 0; - - return ParseBinOpRHS(0, LHS); - } - - /// prototype - /// ::= id '(' id* ')' - static PrototypeAST *ParsePrototype() { - if (CurTok != tok_identifier) - return ErrorP("Expected function name in prototype"); - - std::string FnName = IdentifierStr; - getNextToken(); - - if (CurTok != '(') - return ErrorP("Expected '(' in prototype"); - - std::vector<std::string> ArgNames; - while (getNextToken() == tok_identifier) - ArgNames.push_back(IdentifierStr); - if (CurTok != ')') - return ErrorP("Expected ')' in prototype"); - - // success. - getNextToken(); // eat ')'. - - return new PrototypeAST(FnName, ArgNames); - } - - /// definition ::= 'def' prototype expression - static FunctionAST *ParseDefinition() { - getNextToken(); // eat def. - PrototypeAST *Proto = ParsePrototype(); - if (Proto == 0) return 0; - - if (ExprAST *E = ParseExpression()) - return new FunctionAST(Proto, E); - return 0; - } - - /// toplevelexpr ::= expression - static FunctionAST *ParseTopLevelExpr() { - if (ExprAST *E = ParseExpression()) { - // Make an anonymous proto. - PrototypeAST *Proto = new PrototypeAST("", std::vector<std::string>()); - return new FunctionAST(Proto, E); - } - return 0; - } - - /// external ::= 'extern' prototype - static PrototypeAST *ParseExtern() { - getNextToken(); // eat extern. - return ParsePrototype(); - } - - //===----------------------------------------------------------------------===// - // Code Generation - //===----------------------------------------------------------------------===// - - static Module *TheModule; - static IRBuilder<> Builder(getGlobalContext()); - static std::map<std::string, Value*> NamedValues; - static FunctionPassManager *TheFPM; - - Value *ErrorV(const char *Str) { Error(Str); return 0; } - - Value *NumberExprAST::Codegen() { - return ConstantFP::get(getGlobalContext(), APFloat(Val)); - } - - Value *VariableExprAST::Codegen() { - // Look this variable up in the function. - Value *V = NamedValues[Name]; - return V ? V : ErrorV("Unknown variable name"); - } - - Value *BinaryExprAST::Codegen() { - Value *L = LHS->Codegen(); - Value *R = RHS->Codegen(); - if (L == 0 || R == 0) return 0; - - switch (Op) { - case '+': return Builder.CreateFAdd(L, R, "addtmp"); - case '-': return Builder.CreateFSub(L, R, "subtmp"); - case '*': return Builder.CreateFMul(L, R, "multmp"); - case '<': - L = Builder.CreateFCmpULT(L, R, "cmptmp"); - // Convert bool 0/1 to double 0.0 or 1.0 - return Builder.CreateUIToFP(L, Type::getDoubleTy(getGlobalContext()), - "booltmp"); - default: return ErrorV("invalid binary operator"); - } - } - - Value *CallExprAST::Codegen() { - // Look up the name in the global module table. - Function *CalleeF = TheModule->getFunction(Callee); - if (CalleeF == 0) - return ErrorV("Unknown function referenced"); - - // If argument mismatch error. - if (CalleeF->arg_size() != Args.size()) - return ErrorV("Incorrect # arguments passed"); - - std::vector<Value*> ArgsV; - for (unsigned i = 0, e = Args.size(); i != e; ++i) { - ArgsV.push_back(Args[i]->Codegen()); - if (ArgsV.back() == 0) return 0; - } - - return Builder.CreateCall(CalleeF, ArgsV, "calltmp"); - } - - Value *IfExprAST::Codegen() { - Value *CondV = Cond->Codegen(); - if (CondV == 0) return 0; - - // Convert condition to a bool by comparing equal to 0.0. - CondV = Builder.CreateFCmpONE(CondV, - ConstantFP::get(getGlobalContext(), APFloat(0.0)), - "ifcond"); - - Function *TheFunction = Builder.GetInsertBlock()->getParent(); - - // Create blocks for the then and else cases. Insert the 'then' block at the - // end of the function. - BasicBlock *ThenBB = BasicBlock::Create(getGlobalContext(), "then", TheFunction); - BasicBlock *ElseBB = BasicBlock::Create(getGlobalContext(), "else"); - BasicBlock *MergeBB = BasicBlock::Create(getGlobalContext(), "ifcont"); - - Builder.CreateCondBr(CondV, ThenBB, ElseBB); - - // Emit then value. - Builder.SetInsertPoint(ThenBB); - - Value *ThenV = Then->Codegen(); - if (ThenV == 0) return 0; - - Builder.CreateBr(MergeBB); - // Codegen of 'Then' can change the current block, update ThenBB for the PHI. - ThenBB = Builder.GetInsertBlock(); - - // Emit else block. - TheFunction->getBasicBlockList().push_back(ElseBB); - Builder.SetInsertPoint(ElseBB); - - Value *ElseV = Else->Codegen(); - if (ElseV == 0) return 0; - - Builder.CreateBr(MergeBB); - // Codegen of 'Else' can change the current block, update ElseBB for the PHI. - ElseBB = Builder.GetInsertBlock(); - - // Emit merge block. - TheFunction->getBasicBlockList().push_back(MergeBB); - Builder.SetInsertPoint(MergeBB); - PHINode *PN = Builder.CreatePHI(Type::getDoubleTy(getGlobalContext()), 2, - "iftmp"); - - PN->addIncoming(ThenV, ThenBB); - PN->addIncoming(ElseV, ElseBB); - return PN; - } - - Value *ForExprAST::Codegen() { - // Output this as: - // ... - // start = startexpr - // goto loop - // loop: - // variable = phi [start, loopheader], [nextvariable, loopend] - // ... - // bodyexpr - // ... - // loopend: - // step = stepexpr - // nextvariable = variable + step - // endcond = endexpr - // br endcond, loop, endloop - // outloop: - - // Emit the start code first, without 'variable' in scope. - Value *StartVal = Start->Codegen(); - if (StartVal == 0) return 0; - - // Make the new basic block for the loop header, inserting after current - // block. - Function *TheFunction = Builder.GetInsertBlock()->getParent(); - BasicBlock *PreheaderBB = Builder.GetInsertBlock(); - BasicBlock *LoopBB = BasicBlock::Create(getGlobalContext(), "loop", TheFunction); - - // Insert an explicit fall through from the current block to the LoopBB. - Builder.CreateBr(LoopBB); - - // Start insertion in LoopBB. - Builder.SetInsertPoint(LoopBB); - - // Start the PHI node with an entry for Start. - PHINode *Variable = Builder.CreatePHI(Type::getDoubleTy(getGlobalContext()), 2, VarName.c_str()); - Variable->addIncoming(StartVal, PreheaderBB); - - // Within the loop, the variable is defined equal to the PHI node. If it - // shadows an existing variable, we have to restore it, so save it now. - Value *OldVal = NamedValues[VarName]; - NamedValues[VarName] = Variable; - - // Emit the body of the loop. This, like any other expr, can change the - // current BB. Note that we ignore the value computed by the body, but don't - // allow an error. - if (Body->Codegen() == 0) - return 0; - - // Emit the step value. - Value *StepVal; - if (Step) { - StepVal = Step->Codegen(); - if (StepVal == 0) return 0; - } else { - // If not specified, use 1.0. - StepVal = ConstantFP::get(getGlobalContext(), APFloat(1.0)); - } - - Value *NextVar = Builder.CreateFAdd(Variable, StepVal, "nextvar"); - - // Compute the end condition. - Value *EndCond = End->Codegen(); - if (EndCond == 0) return EndCond; - - // Convert condition to a bool by comparing equal to 0.0. - EndCond = Builder.CreateFCmpONE(EndCond, - ConstantFP::get(getGlobalContext(), APFloat(0.0)), - "loopcond"); - - // Create the "after loop" block and insert it. - BasicBlock *LoopEndBB = Builder.GetInsertBlock(); - BasicBlock *AfterBB = BasicBlock::Create(getGlobalContext(), "afterloop", TheFunction); - - // Insert the conditional branch into the end of LoopEndBB. - Builder.CreateCondBr(EndCond, LoopBB, AfterBB); - - // Any new code will be inserted in AfterBB. - Builder.SetInsertPoint(AfterBB); - - // Add a new entry to the PHI node for the backedge. - Variable->addIncoming(NextVar, LoopEndBB); - - // Restore the unshadowed variable. - if (OldVal) - NamedValues[VarName] = OldVal; - else - NamedValues.erase(VarName); - - - // for expr always returns 0.0. - return Constant::getNullValue(Type::getDoubleTy(getGlobalContext())); - } - - Function *PrototypeAST::Codegen() { - // Make the function type: double(double,double) etc. - std::vector<Type*> Doubles(Args.size(), - Type::getDoubleTy(getGlobalContext())); - FunctionType *FT = FunctionType::get(Type::getDoubleTy(getGlobalContext()), - Doubles, false); - - Function *F = Function::Create(FT, Function::ExternalLinkage, Name, TheModule); - - // If F conflicted, there was already something named 'Name'. If it has a - // body, don't allow redefinition or reextern. - if (F->getName() != Name) { - // Delete the one we just made and get the existing one. - F->eraseFromParent(); - F = TheModule->getFunction(Name); - - // If F already has a body, reject this. - if (!F->empty()) { - ErrorF("redefinition of function"); - return 0; - } - - // If F took a different number of args, reject. - if (F->arg_size() != Args.size()) { - ErrorF("redefinition of function with different # args"); - return 0; - } - } - - // Set names for all arguments. - unsigned Idx = 0; - for (Function::arg_iterator AI = F->arg_begin(); Idx != Args.size(); - ++AI, ++Idx) { - AI->setName(Args[Idx]); - - // Add arguments to variable symbol table. - NamedValues[Args[Idx]] = AI; - } - - return F; - } - - Function *FunctionAST::Codegen() { - NamedValues.clear(); - - Function *TheFunction = Proto->Codegen(); - if (TheFunction == 0) - return 0; - - // Create a new basic block to start insertion into. - BasicBlock *BB = BasicBlock::Create(getGlobalContext(), "entry", TheFunction); - Builder.SetInsertPoint(BB); - - if (Value *RetVal = Body->Codegen()) { - // Finish off the function. - Builder.CreateRet(RetVal); - - // Validate the generated code, checking for consistency. - verifyFunction(*TheFunction); - - // Optimize the function. - TheFPM->run(*TheFunction); - - return TheFunction; - } - - // Error reading body, remove function. - TheFunction->eraseFromParent(); - return 0; - } - - //===----------------------------------------------------------------------===// - // Top-Level parsing and JIT Driver - //===----------------------------------------------------------------------===// - - static ExecutionEngine *TheExecutionEngine; - - static void HandleDefinition() { - if (FunctionAST *F = ParseDefinition()) { - if (Function *LF = F->Codegen()) { - fprintf(stderr, "Read function definition:"); - LF->dump(); - } - } else { - // Skip token for error recovery. - getNextToken(); - } - } - - static void HandleExtern() { - if (PrototypeAST *P = ParseExtern()) { - if (Function *F = P->Codegen()) { - fprintf(stderr, "Read extern: "); - F->dump(); - } - } else { - // Skip token for error recovery. - getNextToken(); - } - } - - static void HandleTopLevelExpression() { - // Evaluate a top-level expression into an anonymous function. - if (FunctionAST *F = ParseTopLevelExpr()) { - if (Function *LF = F->Codegen()) { - // JIT the function, returning a function pointer. - void *FPtr = TheExecutionEngine->getPointerToFunction(LF); - - // Cast it to the right type (takes no arguments, returns a double) so we - // can call it as a native function. - double (*FP)() = (double (*)())(intptr_t)FPtr; - fprintf(stderr, "Evaluated to %f\n", FP()); - } - } else { - // Skip token for error recovery. - getNextToken(); - } - } - - /// top ::= definition | external | expression | ';' - static void MainLoop() { - while (1) { - fprintf(stderr, "ready> "); - switch (CurTok) { - case tok_eof: return; - case ';': getNextToken(); break; // ignore top-level semicolons. - case tok_def: HandleDefinition(); break; - case tok_extern: HandleExtern(); break; - default: HandleTopLevelExpression(); break; - } - } - } - - //===----------------------------------------------------------------------===// - // "Library" functions that can be "extern'd" from user code. - //===----------------------------------------------------------------------===// - - /// putchard - putchar that takes a double and returns 0. - extern "C" - double putchard(double X) { - putchar((char)X); - return 0; - } - - //===----------------------------------------------------------------------===// - // Main driver code. - //===----------------------------------------------------------------------===// - - int main() { - InitializeNativeTarget(); - LLVMContext &Context = getGlobalContext(); - - // Install standard binary operators. - // 1 is lowest precedence. - BinopPrecedence['<'] = 10; - BinopPrecedence['+'] = 20; - BinopPrecedence['-'] = 20; - BinopPrecedence['*'] = 40; // highest. - - // Prime the first token. - fprintf(stderr, "ready> "); - getNextToken(); - - // Make the module, which holds all the code. - TheModule = new Module("my cool jit", Context); - - // Create the JIT. This takes ownership of the module. - std::string ErrStr; - TheExecutionEngine = EngineBuilder(TheModule).setErrorStr(&ErrStr).create(); - if (!TheExecutionEngine) { - fprintf(stderr, "Could not create ExecutionEngine: %s\n", ErrStr.c_str()); - exit(1); - } - - FunctionPassManager OurFPM(TheModule); - - // Set up the optimizer pipeline. Start with registering info about how the - // target lays out data structures. - OurFPM.add(new DataLayout(*TheExecutionEngine->getDataLayout())); - // Provide basic AliasAnalysis support for GVN. - OurFPM.add(createBasicAliasAnalysisPass()); - // Do simple "peephole" optimizations and bit-twiddling optzns. - OurFPM.add(createInstructionCombiningPass()); - // Reassociate expressions. - OurFPM.add(createReassociatePass()); - // Eliminate Common SubExpressions. - OurFPM.add(createGVNPass()); - // Simplify the control flow graph (deleting unreachable blocks, etc). - OurFPM.add(createCFGSimplificationPass()); - - OurFPM.doInitialization(); - - // Set the global so the code gen can use this. - TheFPM = &OurFPM; - - // Run the main "interpreter loop" now. - MainLoop(); - - TheFPM = 0; - - // Print out all of the generated code. - TheModule->dump(); - - return 0; - } +.. literalinclude:: ../../examples/Kaleidoscope/Chapter5/toy.cpp + :language: c++ `Next: Extending the language: user-defined operators <LangImpl6.html>`_ diff --git a/docs/tutorial/LangImpl6.rst b/docs/tutorial/LangImpl6.rst index a5a60bf..42839fb 100644 --- a/docs/tutorial/LangImpl6.rst +++ b/docs/tutorial/LangImpl6.rst @@ -742,984 +742,8 @@ will cause problems on Windows. Here is the code: -.. code-block:: c++ - - #include "llvm/DerivedTypes.h" - #include "llvm/ExecutionEngine/ExecutionEngine.h" - #include "llvm/ExecutionEngine/JIT.h" - #include "llvm/IRBuilder.h" - #include "llvm/LLVMContext.h" - #include "llvm/Module.h" - #include "llvm/PassManager.h" - #include "llvm/Analysis/Verifier.h" - #include "llvm/Analysis/Passes.h" - #include "llvm/DataLayout.h" - #include "llvm/Transforms/Scalar.h" - #include "llvm/Support/TargetSelect.h" - #include <cstdio> - #include <string> - #include <map> - #include <vector> - using namespace llvm; - - //===----------------------------------------------------------------------===// - // Lexer - //===----------------------------------------------------------------------===// - - // The lexer returns tokens [0-255] if it is an unknown character, otherwise one - // of these for known things. - enum Token { - tok_eof = -1, - - // commands - tok_def = -2, tok_extern = -3, - - // primary - tok_identifier = -4, tok_number = -5, - - // control - tok_if = -6, tok_then = -7, tok_else = -8, - tok_for = -9, tok_in = -10, - - // operators - tok_binary = -11, tok_unary = -12 - }; - - static std::string IdentifierStr; // Filled in if tok_identifier - static double NumVal; // Filled in if tok_number - - /// gettok - Return the next token from standard input. - static int gettok() { - static int LastChar = ' '; - - // Skip any whitespace. - while (isspace(LastChar)) - LastChar = getchar(); - - if (isalpha(LastChar)) { // identifier: [a-zA-Z][a-zA-Z0-9]* - IdentifierStr = LastChar; - while (isalnum((LastChar = getchar()))) - IdentifierStr += LastChar; - - if (IdentifierStr == "def") return tok_def; - if (IdentifierStr == "extern") return tok_extern; - if (IdentifierStr == "if") return tok_if; - if (IdentifierStr == "then") return tok_then; - if (IdentifierStr == "else") return tok_else; - if (IdentifierStr == "for") return tok_for; - if (IdentifierStr == "in") return tok_in; - if (IdentifierStr == "binary") return tok_binary; - if (IdentifierStr == "unary") return tok_unary; - return tok_identifier; - } - - if (isdigit(LastChar) || LastChar == '.') { // Number: [0-9.]+ - std::string NumStr; - do { - NumStr += LastChar; - LastChar = getchar(); - } while (isdigit(LastChar) || LastChar == '.'); - - NumVal = strtod(NumStr.c_str(), 0); - return tok_number; - } - - if (LastChar == '#') { - // Comment until end of line. - do LastChar = getchar(); - while (LastChar != EOF && LastChar != '\n' && LastChar != '\r'); - - if (LastChar != EOF) - return gettok(); - } - - // Check for end of file. Don't eat the EOF. - if (LastChar == EOF) - return tok_eof; - - // Otherwise, just return the character as its ascii value. - int ThisChar = LastChar; - LastChar = getchar(); - return ThisChar; - } - - //===----------------------------------------------------------------------===// - // Abstract Syntax Tree (aka Parse Tree) - //===----------------------------------------------------------------------===// - - /// ExprAST - Base class for all expression nodes. - class ExprAST { - public: - virtual ~ExprAST() {} - virtual Value *Codegen() = 0; - }; - - /// NumberExprAST - Expression class for numeric literals like "1.0". - class NumberExprAST : public ExprAST { - double Val; - public: - NumberExprAST(double val) : Val(val) {} - virtual Value *Codegen(); - }; - - /// VariableExprAST - Expression class for referencing a variable, like "a". - class VariableExprAST : public ExprAST { - std::string Name; - public: - VariableExprAST(const std::string &name) : Name(name) {} - virtual Value *Codegen(); - }; - - /// UnaryExprAST - Expression class for a unary operator. - class UnaryExprAST : public ExprAST { - char Opcode; - ExprAST *Operand; - public: - UnaryExprAST(char opcode, ExprAST *operand) - : Opcode(opcode), Operand(operand) {} - virtual Value *Codegen(); - }; - - /// BinaryExprAST - Expression class for a binary operator. - class BinaryExprAST : public ExprAST { - char Op; - ExprAST *LHS, *RHS; - public: - BinaryExprAST(char op, ExprAST *lhs, ExprAST *rhs) - : Op(op), LHS(lhs), RHS(rhs) {} - virtual Value *Codegen(); - }; - - /// CallExprAST - Expression class for function calls. - class CallExprAST : public ExprAST { - std::string Callee; - std::vector<ExprAST*> Args; - public: - CallExprAST(const std::string &callee, std::vector<ExprAST*> &args) - : Callee(callee), Args(args) {} - virtual Value *Codegen(); - }; - - /// IfExprAST - Expression class for if/then/else. - class IfExprAST : public ExprAST { - ExprAST *Cond, *Then, *Else; - public: - IfExprAST(ExprAST *cond, ExprAST *then, ExprAST *_else) - : Cond(cond), Then(then), Else(_else) {} - virtual Value *Codegen(); - }; - - /// ForExprAST - Expression class for for/in. - class ForExprAST : public ExprAST { - std::string VarName; - ExprAST *Start, *End, *Step, *Body; - public: - ForExprAST(const std::string &varname, ExprAST *start, ExprAST *end, - ExprAST *step, ExprAST *body) - : VarName(varname), Start(start), End(end), Step(step), Body(body) {} - virtual Value *Codegen(); - }; - - /// PrototypeAST - This class represents the "prototype" for a function, - /// which captures its name, and its argument names (thus implicitly the number - /// of arguments the function takes), as well as if it is an operator. - class PrototypeAST { - std::string Name; - std::vector<std::string> Args; - bool isOperator; - unsigned Precedence; // Precedence if a binary op. - public: - PrototypeAST(const std::string &name, const std::vector<std::string> &args, - bool isoperator = false, unsigned prec = 0) - : Name(name), Args(args), isOperator(isoperator), Precedence(prec) {} - - bool isUnaryOp() const { return isOperator && Args.size() == 1; } - bool isBinaryOp() const { return isOperator && Args.size() == 2; } - - char getOperatorName() const { - assert(isUnaryOp() || isBinaryOp()); - return Name[Name.size()-1]; - } - - unsigned getBinaryPrecedence() const { return Precedence; } - - Function *Codegen(); - }; - - /// FunctionAST - This class represents a function definition itself. - class FunctionAST { - PrototypeAST *Proto; - ExprAST *Body; - public: - FunctionAST(PrototypeAST *proto, ExprAST *body) - : Proto(proto), Body(body) {} - - Function *Codegen(); - }; - - //===----------------------------------------------------------------------===// - // Parser - //===----------------------------------------------------------------------===// - - /// CurTok/getNextToken - Provide a simple token buffer. CurTok is the current - /// token the parser is looking at. getNextToken reads another token from the - /// lexer and updates CurTok with its results. - static int CurTok; - static int getNextToken() { - return CurTok = gettok(); - } - - /// BinopPrecedence - This holds the precedence for each binary operator that is - /// defined. - static std::map<char, int> BinopPrecedence; - - /// GetTokPrecedence - Get the precedence of the pending binary operator token. - static int GetTokPrecedence() { - if (!isascii(CurTok)) - return -1; - - // Make sure it's a declared binop. - int TokPrec = BinopPrecedence[CurTok]; - if (TokPrec <= 0) return -1; - return TokPrec; - } - - /// Error* - These are little helper functions for error handling. - ExprAST *Error(const char *Str) { fprintf(stderr, "Error: %s\n", Str);return 0;} - PrototypeAST *ErrorP(const char *Str) { Error(Str); return 0; } - FunctionAST *ErrorF(const char *Str) { Error(Str); return 0; } - - static ExprAST *ParseExpression(); - - /// identifierexpr - /// ::= identifier - /// ::= identifier '(' expression* ')' - static ExprAST *ParseIdentifierExpr() { - std::string IdName = IdentifierStr; - - getNextToken(); // eat identifier. - - if (CurTok != '(') // Simple variable ref. - return new VariableExprAST(IdName); - - // Call. - getNextToken(); // eat ( - std::vector<ExprAST*> Args; - if (CurTok != ')') { - while (1) { - ExprAST *Arg = ParseExpression(); - if (!Arg) return 0; - Args.push_back(Arg); - - if (CurTok == ')') break; - - if (CurTok != ',') - return Error("Expected ')' or ',' in argument list"); - getNextToken(); - } - } - - // Eat the ')'. - getNextToken(); - - return new CallExprAST(IdName, Args); - } - - /// numberexpr ::= number - static ExprAST *ParseNumberExpr() { - ExprAST *Result = new NumberExprAST(NumVal); - getNextToken(); // consume the number - return Result; - } - - /// parenexpr ::= '(' expression ')' - static ExprAST *ParseParenExpr() { - getNextToken(); // eat (. - ExprAST *V = ParseExpression(); - if (!V) return 0; - - if (CurTok != ')') - return Error("expected ')'"); - getNextToken(); // eat ). - return V; - } - - /// ifexpr ::= 'if' expression 'then' expression 'else' expression - static ExprAST *ParseIfExpr() { - getNextToken(); // eat the if. - - // condition. - ExprAST *Cond = ParseExpression(); - if (!Cond) return 0; - - if (CurTok != tok_then) - return Error("expected then"); - getNextToken(); // eat the then - - ExprAST *Then = ParseExpression(); - if (Then == 0) return 0; - - if (CurTok != tok_else) - return Error("expected else"); - - getNextToken(); - - ExprAST *Else = ParseExpression(); - if (!Else) return 0; - - return new IfExprAST(Cond, Then, Else); - } - - /// forexpr ::= 'for' identifier '=' expr ',' expr (',' expr)? 'in' expression - static ExprAST *ParseForExpr() { - getNextToken(); // eat the for. - - if (CurTok != tok_identifier) - return Error("expected identifier after for"); - - std::string IdName = IdentifierStr; - getNextToken(); // eat identifier. - - if (CurTok != '=') - return Error("expected '=' after for"); - getNextToken(); // eat '='. - - - ExprAST *Start = ParseExpression(); - if (Start == 0) return 0; - if (CurTok != ',') - return Error("expected ',' after for start value"); - getNextToken(); - - ExprAST *End = ParseExpression(); - if (End == 0) return 0; - - // The step value is optional. - ExprAST *Step = 0; - if (CurTok == ',') { - getNextToken(); - Step = ParseExpression(); - if (Step == 0) return 0; - } - - if (CurTok != tok_in) - return Error("expected 'in' after for"); - getNextToken(); // eat 'in'. - - ExprAST *Body = ParseExpression(); - if (Body == 0) return 0; - - return new ForExprAST(IdName, Start, End, Step, Body); - } - - /// primary - /// ::= identifierexpr - /// ::= numberexpr - /// ::= parenexpr - /// ::= ifexpr - /// ::= forexpr - static ExprAST *ParsePrimary() { - switch (CurTok) { - default: return Error("unknown token when expecting an expression"); - case tok_identifier: return ParseIdentifierExpr(); - case tok_number: return ParseNumberExpr(); - case '(': return ParseParenExpr(); - case tok_if: return ParseIfExpr(); - case tok_for: return ParseForExpr(); - } - } - - /// unary - /// ::= primary - /// ::= '!' unary - static ExprAST *ParseUnary() { - // If the current token is not an operator, it must be a primary expr. - if (!isascii(CurTok) || CurTok == '(' || CurTok == ',') - return ParsePrimary(); - - // If this is a unary operator, read it. - int Opc = CurTok; - getNextToken(); - if (ExprAST *Operand = ParseUnary()) - return new UnaryExprAST(Opc, Operand); - return 0; - } - - /// binoprhs - /// ::= ('+' unary)* - static ExprAST *ParseBinOpRHS(int ExprPrec, ExprAST *LHS) { - // If this is a binop, find its precedence. - while (1) { - int TokPrec = GetTokPrecedence(); - - // If this is a binop that binds at least as tightly as the current binop, - // consume it, otherwise we are done. - if (TokPrec < ExprPrec) - return LHS; - - // Okay, we know this is a binop. - int BinOp = CurTok; - getNextToken(); // eat binop - - // Parse the unary expression after the binary operator. - ExprAST *RHS = ParseUnary(); - if (!RHS) return 0; - - // If BinOp binds less tightly with RHS than the operator after RHS, let - // the pending operator take RHS as its LHS. - int NextPrec = GetTokPrecedence(); - if (TokPrec < NextPrec) { - RHS = ParseBinOpRHS(TokPrec+1, RHS); - if (RHS == 0) return 0; - } - - // Merge LHS/RHS. - LHS = new BinaryExprAST(BinOp, LHS, RHS); - } - } - - /// expression - /// ::= unary binoprhs - /// - static ExprAST *ParseExpression() { - ExprAST *LHS = ParseUnary(); - if (!LHS) return 0; - - return ParseBinOpRHS(0, LHS); - } - - /// prototype - /// ::= id '(' id* ')' - /// ::= binary LETTER number? (id, id) - /// ::= unary LETTER (id) - static PrototypeAST *ParsePrototype() { - std::string FnName; - - unsigned Kind = 0; // 0 = identifier, 1 = unary, 2 = binary. - unsigned BinaryPrecedence = 30; - - switch (CurTok) { - default: - return ErrorP("Expected function name in prototype"); - case tok_identifier: - FnName = IdentifierStr; - Kind = 0; - getNextToken(); - break; - case tok_unary: - getNextToken(); - if (!isascii(CurTok)) - return ErrorP("Expected unary operator"); - FnName = "unary"; - FnName += (char)CurTok; - Kind = 1; - getNextToken(); - break; - case tok_binary: - getNextToken(); - if (!isascii(CurTok)) - return ErrorP("Expected binary operator"); - FnName = "binary"; - FnName += (char)CurTok; - Kind = 2; - getNextToken(); - - // Read the precedence if present. - if (CurTok == tok_number) { - if (NumVal < 1 || NumVal > 100) - return ErrorP("Invalid precedecnce: must be 1..100"); - BinaryPrecedence = (unsigned)NumVal; - getNextToken(); - } - break; - } - - if (CurTok != '(') - return ErrorP("Expected '(' in prototype"); - - std::vector<std::string> ArgNames; - while (getNextToken() == tok_identifier) - ArgNames.push_back(IdentifierStr); - if (CurTok != ')') - return ErrorP("Expected ')' in prototype"); - - // success. - getNextToken(); // eat ')'. - - // Verify right number of names for operator. - if (Kind && ArgNames.size() != Kind) - return ErrorP("Invalid number of operands for operator"); - - return new PrototypeAST(FnName, ArgNames, Kind != 0, BinaryPrecedence); - } - - /// definition ::= 'def' prototype expression - static FunctionAST *ParseDefinition() { - getNextToken(); // eat def. - PrototypeAST *Proto = ParsePrototype(); - if (Proto == 0) return 0; - - if (ExprAST *E = ParseExpression()) - return new FunctionAST(Proto, E); - return 0; - } - - /// toplevelexpr ::= expression - static FunctionAST *ParseTopLevelExpr() { - if (ExprAST *E = ParseExpression()) { - // Make an anonymous proto. - PrototypeAST *Proto = new PrototypeAST("", std::vector<std::string>()); - return new FunctionAST(Proto, E); - } - return 0; - } - - /// external ::= 'extern' prototype - static PrototypeAST *ParseExtern() { - getNextToken(); // eat extern. - return ParsePrototype(); - } - - //===----------------------------------------------------------------------===// - // Code Generation - //===----------------------------------------------------------------------===// - - static Module *TheModule; - static IRBuilder<> Builder(getGlobalContext()); - static std::map<std::string, Value*> NamedValues; - static FunctionPassManager *TheFPM; - - Value *ErrorV(const char *Str) { Error(Str); return 0; } - - Value *NumberExprAST::Codegen() { - return ConstantFP::get(getGlobalContext(), APFloat(Val)); - } - - Value *VariableExprAST::Codegen() { - // Look this variable up in the function. - Value *V = NamedValues[Name]; - return V ? V : ErrorV("Unknown variable name"); - } - - Value *UnaryExprAST::Codegen() { - Value *OperandV = Operand->Codegen(); - if (OperandV == 0) return 0; - - Function *F = TheModule->getFunction(std::string("unary")+Opcode); - if (F == 0) - return ErrorV("Unknown unary operator"); - - return Builder.CreateCall(F, OperandV, "unop"); - } - - Value *BinaryExprAST::Codegen() { - Value *L = LHS->Codegen(); - Value *R = RHS->Codegen(); - if (L == 0 || R == 0) return 0; - - switch (Op) { - case '+': return Builder.CreateFAdd(L, R, "addtmp"); - case '-': return Builder.CreateFSub(L, R, "subtmp"); - case '*': return Builder.CreateFMul(L, R, "multmp"); - case '<': - L = Builder.CreateFCmpULT(L, R, "cmptmp"); - // Convert bool 0/1 to double 0.0 or 1.0 - return Builder.CreateUIToFP(L, Type::getDoubleTy(getGlobalContext()), - "booltmp"); - default: break; - } - - // If it wasn't a builtin binary operator, it must be a user defined one. Emit - // a call to it. - Function *F = TheModule->getFunction(std::string("binary")+Op); - assert(F && "binary operator not found!"); - - Value *Ops[2] = { L, R }; - return Builder.CreateCall(F, Ops, "binop"); - } - - Value *CallExprAST::Codegen() { - // Look up the name in the global module table. - Function *CalleeF = TheModule->getFunction(Callee); - if (CalleeF == 0) - return ErrorV("Unknown function referenced"); - - // If argument mismatch error. - if (CalleeF->arg_size() != Args.size()) - return ErrorV("Incorrect # arguments passed"); - - std::vector<Value*> ArgsV; - for (unsigned i = 0, e = Args.size(); i != e; ++i) { - ArgsV.push_back(Args[i]->Codegen()); - if (ArgsV.back() == 0) return 0; - } - - return Builder.CreateCall(CalleeF, ArgsV, "calltmp"); - } - - Value *IfExprAST::Codegen() { - Value *CondV = Cond->Codegen(); - if (CondV == 0) return 0; - - // Convert condition to a bool by comparing equal to 0.0. - CondV = Builder.CreateFCmpONE(CondV, - ConstantFP::get(getGlobalContext(), APFloat(0.0)), - "ifcond"); - - Function *TheFunction = Builder.GetInsertBlock()->getParent(); - - // Create blocks for the then and else cases. Insert the 'then' block at the - // end of the function. - BasicBlock *ThenBB = BasicBlock::Create(getGlobalContext(), "then", TheFunction); - BasicBlock *ElseBB = BasicBlock::Create(getGlobalContext(), "else"); - BasicBlock *MergeBB = BasicBlock::Create(getGlobalContext(), "ifcont"); - - Builder.CreateCondBr(CondV, ThenBB, ElseBB); - - // Emit then value. - Builder.SetInsertPoint(ThenBB); - - Value *ThenV = Then->Codegen(); - if (ThenV == 0) return 0; - - Builder.CreateBr(MergeBB); - // Codegen of 'Then' can change the current block, update ThenBB for the PHI. - ThenBB = Builder.GetInsertBlock(); - - // Emit else block. - TheFunction->getBasicBlockList().push_back(ElseBB); - Builder.SetInsertPoint(ElseBB); - - Value *ElseV = Else->Codegen(); - if (ElseV == 0) return 0; - - Builder.CreateBr(MergeBB); - // Codegen of 'Else' can change the current block, update ElseBB for the PHI. - ElseBB = Builder.GetInsertBlock(); - - // Emit merge block. - TheFunction->getBasicBlockList().push_back(MergeBB); - Builder.SetInsertPoint(MergeBB); - PHINode *PN = Builder.CreatePHI(Type::getDoubleTy(getGlobalContext()), 2, - "iftmp"); - - PN->addIncoming(ThenV, ThenBB); - PN->addIncoming(ElseV, ElseBB); - return PN; - } - - Value *ForExprAST::Codegen() { - // Output this as: - // ... - // start = startexpr - // goto loop - // loop: - // variable = phi [start, loopheader], [nextvariable, loopend] - // ... - // bodyexpr - // ... - // loopend: - // step = stepexpr - // nextvariable = variable + step - // endcond = endexpr - // br endcond, loop, endloop - // outloop: - - // Emit the start code first, without 'variable' in scope. - Value *StartVal = Start->Codegen(); - if (StartVal == 0) return 0; - - // Make the new basic block for the loop header, inserting after current - // block. - Function *TheFunction = Builder.GetInsertBlock()->getParent(); - BasicBlock *PreheaderBB = Builder.GetInsertBlock(); - BasicBlock *LoopBB = BasicBlock::Create(getGlobalContext(), "loop", TheFunction); - - // Insert an explicit fall through from the current block to the LoopBB. - Builder.CreateBr(LoopBB); - - // Start insertion in LoopBB. - Builder.SetInsertPoint(LoopBB); - - // Start the PHI node with an entry for Start. - PHINode *Variable = Builder.CreatePHI(Type::getDoubleTy(getGlobalContext()), 2, VarName.c_str()); - Variable->addIncoming(StartVal, PreheaderBB); - - // Within the loop, the variable is defined equal to the PHI node. If it - // shadows an existing variable, we have to restore it, so save it now. - Value *OldVal = NamedValues[VarName]; - NamedValues[VarName] = Variable; - - // Emit the body of the loop. This, like any other expr, can change the - // current BB. Note that we ignore the value computed by the body, but don't - // allow an error. - if (Body->Codegen() == 0) - return 0; - - // Emit the step value. - Value *StepVal; - if (Step) { - StepVal = Step->Codegen(); - if (StepVal == 0) return 0; - } else { - // If not specified, use 1.0. - StepVal = ConstantFP::get(getGlobalContext(), APFloat(1.0)); - } - - Value *NextVar = Builder.CreateFAdd(Variable, StepVal, "nextvar"); - - // Compute the end condition. - Value *EndCond = End->Codegen(); - if (EndCond == 0) return EndCond; - - // Convert condition to a bool by comparing equal to 0.0. - EndCond = Builder.CreateFCmpONE(EndCond, - ConstantFP::get(getGlobalContext(), APFloat(0.0)), - "loopcond"); - - // Create the "after loop" block and insert it. - BasicBlock *LoopEndBB = Builder.GetInsertBlock(); - BasicBlock *AfterBB = BasicBlock::Create(getGlobalContext(), "afterloop", TheFunction); - - // Insert the conditional branch into the end of LoopEndBB. - Builder.CreateCondBr(EndCond, LoopBB, AfterBB); - - // Any new code will be inserted in AfterBB. - Builder.SetInsertPoint(AfterBB); - - // Add a new entry to the PHI node for the backedge. - Variable->addIncoming(NextVar, LoopEndBB); - - // Restore the unshadowed variable. - if (OldVal) - NamedValues[VarName] = OldVal; - else - NamedValues.erase(VarName); - - - // for expr always returns 0.0. - return Constant::getNullValue(Type::getDoubleTy(getGlobalContext())); - } - - Function *PrototypeAST::Codegen() { - // Make the function type: double(double,double) etc. - std::vector<Type*> Doubles(Args.size(), - Type::getDoubleTy(getGlobalContext())); - FunctionType *FT = FunctionType::get(Type::getDoubleTy(getGlobalContext()), - Doubles, false); - - Function *F = Function::Create(FT, Function::ExternalLinkage, Name, TheModule); - - // If F conflicted, there was already something named 'Name'. If it has a - // body, don't allow redefinition or reextern. - if (F->getName() != Name) { - // Delete the one we just made and get the existing one. - F->eraseFromParent(); - F = TheModule->getFunction(Name); - - // If F already has a body, reject this. - if (!F->empty()) { - ErrorF("redefinition of function"); - return 0; - } - - // If F took a different number of args, reject. - if (F->arg_size() != Args.size()) { - ErrorF("redefinition of function with different # args"); - return 0; - } - } - - // Set names for all arguments. - unsigned Idx = 0; - for (Function::arg_iterator AI = F->arg_begin(); Idx != Args.size(); - ++AI, ++Idx) { - AI->setName(Args[Idx]); - - // Add arguments to variable symbol table. - NamedValues[Args[Idx]] = AI; - } - - return F; - } - - Function *FunctionAST::Codegen() { - NamedValues.clear(); - - Function *TheFunction = Proto->Codegen(); - if (TheFunction == 0) - return 0; - - // If this is an operator, install it. - if (Proto->isBinaryOp()) - BinopPrecedence[Proto->getOperatorName()] = Proto->getBinaryPrecedence(); - - // Create a new basic block to start insertion into. - BasicBlock *BB = BasicBlock::Create(getGlobalContext(), "entry", TheFunction); - Builder.SetInsertPoint(BB); - - if (Value *RetVal = Body->Codegen()) { - // Finish off the function. - Builder.CreateRet(RetVal); - - // Validate the generated code, checking for consistency. - verifyFunction(*TheFunction); - - // Optimize the function. - TheFPM->run(*TheFunction); - - return TheFunction; - } - - // Error reading body, remove function. - TheFunction->eraseFromParent(); - - if (Proto->isBinaryOp()) - BinopPrecedence.erase(Proto->getOperatorName()); - return 0; - } - - //===----------------------------------------------------------------------===// - // Top-Level parsing and JIT Driver - //===----------------------------------------------------------------------===// - - static ExecutionEngine *TheExecutionEngine; - - static void HandleDefinition() { - if (FunctionAST *F = ParseDefinition()) { - if (Function *LF = F->Codegen()) { - fprintf(stderr, "Read function definition:"); - LF->dump(); - } - } else { - // Skip token for error recovery. - getNextToken(); - } - } - - static void HandleExtern() { - if (PrototypeAST *P = ParseExtern()) { - if (Function *F = P->Codegen()) { - fprintf(stderr, "Read extern: "); - F->dump(); - } - } else { - // Skip token for error recovery. - getNextToken(); - } - } - - static void HandleTopLevelExpression() { - // Evaluate a top-level expression into an anonymous function. - if (FunctionAST *F = ParseTopLevelExpr()) { - if (Function *LF = F->Codegen()) { - // JIT the function, returning a function pointer. - void *FPtr = TheExecutionEngine->getPointerToFunction(LF); - - // Cast it to the right type (takes no arguments, returns a double) so we - // can call it as a native function. - double (*FP)() = (double (*)())(intptr_t)FPtr; - fprintf(stderr, "Evaluated to %f\n", FP()); - } - } else { - // Skip token for error recovery. - getNextToken(); - } - } - - /// top ::= definition | external | expression | ';' - static void MainLoop() { - while (1) { - fprintf(stderr, "ready> "); - switch (CurTok) { - case tok_eof: return; - case ';': getNextToken(); break; // ignore top-level semicolons. - case tok_def: HandleDefinition(); break; - case tok_extern: HandleExtern(); break; - default: HandleTopLevelExpression(); break; - } - } - } - - //===----------------------------------------------------------------------===// - // "Library" functions that can be "extern'd" from user code. - //===----------------------------------------------------------------------===// - - /// putchard - putchar that takes a double and returns 0. - extern "C" - double putchard(double X) { - putchar((char)X); - return 0; - } - - /// printd - printf that takes a double prints it as "%f\n", returning 0. - extern "C" - double printd(double X) { - printf("%f\n", X); - return 0; - } - - //===----------------------------------------------------------------------===// - // Main driver code. - //===----------------------------------------------------------------------===// - - int main() { - InitializeNativeTarget(); - LLVMContext &Context = getGlobalContext(); - - // Install standard binary operators. - // 1 is lowest precedence. - BinopPrecedence['<'] = 10; - BinopPrecedence['+'] = 20; - BinopPrecedence['-'] = 20; - BinopPrecedence['*'] = 40; // highest. - - // Prime the first token. - fprintf(stderr, "ready> "); - getNextToken(); - - // Make the module, which holds all the code. - TheModule = new Module("my cool jit", Context); - - // Create the JIT. This takes ownership of the module. - std::string ErrStr; - TheExecutionEngine = EngineBuilder(TheModule).setErrorStr(&ErrStr).create(); - if (!TheExecutionEngine) { - fprintf(stderr, "Could not create ExecutionEngine: %s\n", ErrStr.c_str()); - exit(1); - } - - FunctionPassManager OurFPM(TheModule); - - // Set up the optimizer pipeline. Start with registering info about how the - // target lays out data structures. - OurFPM.add(new DataLayout(*TheExecutionEngine->getDataLayout())); - // Provide basic AliasAnalysis support for GVN. - OurFPM.add(createBasicAliasAnalysisPass()); - // Do simple "peephole" optimizations and bit-twiddling optzns. - OurFPM.add(createInstructionCombiningPass()); - // Reassociate expressions. - OurFPM.add(createReassociatePass()); - // Eliminate Common SubExpressions. - OurFPM.add(createGVNPass()); - // Simplify the control flow graph (deleting unreachable blocks, etc). - OurFPM.add(createCFGSimplificationPass()); - - OurFPM.doInitialization(); - - // Set the global so the code gen can use this. - TheFPM = &OurFPM; - - // Run the main "interpreter loop" now. - MainLoop(); - - TheFPM = 0; - - // Print out all of the generated code. - TheModule->dump(); - - return 0; - } +.. literalinclude:: ../../examples/Kaleidoscope/Chapter6/toy.cpp + :language: c++ `Next: Extending the language: mutable variables / SSA construction <LangImpl7.html>`_ diff --git a/docs/tutorial/LangImpl7.rst b/docs/tutorial/LangImpl7.rst index 6dde2fe..a2e47b5 100644 --- a/docs/tutorial/LangImpl7.rst +++ b/docs/tutorial/LangImpl7.rst @@ -853,1151 +853,8 @@ mutable variables and var/in support. To build this example, use: Here is the code: -.. code-block:: c++ - - #include "llvm/DerivedTypes.h" - #include "llvm/ExecutionEngine/ExecutionEngine.h" - #include "llvm/ExecutionEngine/JIT.h" - #include "llvm/IRBuilder.h" - #include "llvm/LLVMContext.h" - #include "llvm/Module.h" - #include "llvm/PassManager.h" - #include "llvm/Analysis/Verifier.h" - #include "llvm/Analysis/Passes.h" - #include "llvm/DataLayout.h" - #include "llvm/Transforms/Scalar.h" - #include "llvm/Support/TargetSelect.h" - #include <cstdio> - #include <string> - #include <map> - #include <vector> - using namespace llvm; - - //===----------------------------------------------------------------------===// - // Lexer - //===----------------------------------------------------------------------===// - - // The lexer returns tokens [0-255] if it is an unknown character, otherwise one - // of these for known things. - enum Token { - tok_eof = -1, - - // commands - tok_def = -2, tok_extern = -3, - - // primary - tok_identifier = -4, tok_number = -5, - - // control - tok_if = -6, tok_then = -7, tok_else = -8, - tok_for = -9, tok_in = -10, - - // operators - tok_binary = -11, tok_unary = -12, - - // var definition - tok_var = -13 - }; - - static std::string IdentifierStr; // Filled in if tok_identifier - static double NumVal; // Filled in if tok_number - - /// gettok - Return the next token from standard input. - static int gettok() { - static int LastChar = ' '; - - // Skip any whitespace. - while (isspace(LastChar)) - LastChar = getchar(); - - if (isalpha(LastChar)) { // identifier: [a-zA-Z][a-zA-Z0-9]* - IdentifierStr = LastChar; - while (isalnum((LastChar = getchar()))) - IdentifierStr += LastChar; - - if (IdentifierStr == "def") return tok_def; - if (IdentifierStr == "extern") return tok_extern; - if (IdentifierStr == "if") return tok_if; - if (IdentifierStr == "then") return tok_then; - if (IdentifierStr == "else") return tok_else; - if (IdentifierStr == "for") return tok_for; - if (IdentifierStr == "in") return tok_in; - if (IdentifierStr == "binary") return tok_binary; - if (IdentifierStr == "unary") return tok_unary; - if (IdentifierStr == "var") return tok_var; - return tok_identifier; - } - - if (isdigit(LastChar) || LastChar == '.') { // Number: [0-9.]+ - std::string NumStr; - do { - NumStr += LastChar; - LastChar = getchar(); - } while (isdigit(LastChar) || LastChar == '.'); - - NumVal = strtod(NumStr.c_str(), 0); - return tok_number; - } - - if (LastChar == '#') { - // Comment until end of line. - do LastChar = getchar(); - while (LastChar != EOF && LastChar != '\n' && LastChar != '\r'); - - if (LastChar != EOF) - return gettok(); - } - - // Check for end of file. Don't eat the EOF. - if (LastChar == EOF) - return tok_eof; - - // Otherwise, just return the character as its ascii value. - int ThisChar = LastChar; - LastChar = getchar(); - return ThisChar; - } - - //===----------------------------------------------------------------------===// - // Abstract Syntax Tree (aka Parse Tree) - //===----------------------------------------------------------------------===// - - /// ExprAST - Base class for all expression nodes. - class ExprAST { - public: - virtual ~ExprAST() {} - virtual Value *Codegen() = 0; - }; - - /// NumberExprAST - Expression class for numeric literals like "1.0". - class NumberExprAST : public ExprAST { - double Val; - public: - NumberExprAST(double val) : Val(val) {} - virtual Value *Codegen(); - }; - - /// VariableExprAST - Expression class for referencing a variable, like "a". - class VariableExprAST : public ExprAST { - std::string Name; - public: - VariableExprAST(const std::string &name) : Name(name) {} - const std::string &getName() const { return Name; } - virtual Value *Codegen(); - }; - - /// UnaryExprAST - Expression class for a unary operator. - class UnaryExprAST : public ExprAST { - char Opcode; - ExprAST *Operand; - public: - UnaryExprAST(char opcode, ExprAST *operand) - : Opcode(opcode), Operand(operand) {} - virtual Value *Codegen(); - }; - - /// BinaryExprAST - Expression class for a binary operator. - class BinaryExprAST : public ExprAST { - char Op; - ExprAST *LHS, *RHS; - public: - BinaryExprAST(char op, ExprAST *lhs, ExprAST *rhs) - : Op(op), LHS(lhs), RHS(rhs) {} - virtual Value *Codegen(); - }; - - /// CallExprAST - Expression class for function calls. - class CallExprAST : public ExprAST { - std::string Callee; - std::vector<ExprAST*> Args; - public: - CallExprAST(const std::string &callee, std::vector<ExprAST*> &args) - : Callee(callee), Args(args) {} - virtual Value *Codegen(); - }; - - /// IfExprAST - Expression class for if/then/else. - class IfExprAST : public ExprAST { - ExprAST *Cond, *Then, *Else; - public: - IfExprAST(ExprAST *cond, ExprAST *then, ExprAST *_else) - : Cond(cond), Then(then), Else(_else) {} - virtual Value *Codegen(); - }; - - /// ForExprAST - Expression class for for/in. - class ForExprAST : public ExprAST { - std::string VarName; - ExprAST *Start, *End, *Step, *Body; - public: - ForExprAST(const std::string &varname, ExprAST *start, ExprAST *end, - ExprAST *step, ExprAST *body) - : VarName(varname), Start(start), End(end), Step(step), Body(body) {} - virtual Value *Codegen(); - }; - - /// VarExprAST - Expression class for var/in - class VarExprAST : public ExprAST { - std::vector<std::pair<std::string, ExprAST*> > VarNames; - ExprAST *Body; - public: - VarExprAST(const std::vector<std::pair<std::string, ExprAST*> > &varnames, - ExprAST *body) - : VarNames(varnames), Body(body) {} - - virtual Value *Codegen(); - }; - - /// PrototypeAST - This class represents the "prototype" for a function, - /// which captures its name, and its argument names (thus implicitly the number - /// of arguments the function takes), as well as if it is an operator. - class PrototypeAST { - std::string Name; - std::vector<std::string> Args; - bool isOperator; - unsigned Precedence; // Precedence if a binary op. - public: - PrototypeAST(const std::string &name, const std::vector<std::string> &args, - bool isoperator = false, unsigned prec = 0) - : Name(name), Args(args), isOperator(isoperator), Precedence(prec) {} - - bool isUnaryOp() const { return isOperator && Args.size() == 1; } - bool isBinaryOp() const { return isOperator && Args.size() == 2; } - - char getOperatorName() const { - assert(isUnaryOp() || isBinaryOp()); - return Name[Name.size()-1]; - } - - unsigned getBinaryPrecedence() const { return Precedence; } - - Function *Codegen(); - - void CreateArgumentAllocas(Function *F); - }; - - /// FunctionAST - This class represents a function definition itself. - class FunctionAST { - PrototypeAST *Proto; - ExprAST *Body; - public: - FunctionAST(PrototypeAST *proto, ExprAST *body) - : Proto(proto), Body(body) {} - - Function *Codegen(); - }; - - //===----------------------------------------------------------------------===// - // Parser - //===----------------------------------------------------------------------===// - - /// CurTok/getNextToken - Provide a simple token buffer. CurTok is the current - /// token the parser is looking at. getNextToken reads another token from the - /// lexer and updates CurTok with its results. - static int CurTok; - static int getNextToken() { - return CurTok = gettok(); - } - - /// BinopPrecedence - This holds the precedence for each binary operator that is - /// defined. - static std::map<char, int> BinopPrecedence; - - /// GetTokPrecedence - Get the precedence of the pending binary operator token. - static int GetTokPrecedence() { - if (!isascii(CurTok)) - return -1; - - // Make sure it's a declared binop. - int TokPrec = BinopPrecedence[CurTok]; - if (TokPrec <= 0) return -1; - return TokPrec; - } - - /// Error* - These are little helper functions for error handling. - ExprAST *Error(const char *Str) { fprintf(stderr, "Error: %s\n", Str);return 0;} - PrototypeAST *ErrorP(const char *Str) { Error(Str); return 0; } - FunctionAST *ErrorF(const char *Str) { Error(Str); return 0; } - - static ExprAST *ParseExpression(); - - /// identifierexpr - /// ::= identifier - /// ::= identifier '(' expression* ')' - static ExprAST *ParseIdentifierExpr() { - std::string IdName = IdentifierStr; - - getNextToken(); // eat identifier. - - if (CurTok != '(') // Simple variable ref. - return new VariableExprAST(IdName); - - // Call. - getNextToken(); // eat ( - std::vector<ExprAST*> Args; - if (CurTok != ')') { - while (1) { - ExprAST *Arg = ParseExpression(); - if (!Arg) return 0; - Args.push_back(Arg); - - if (CurTok == ')') break; - - if (CurTok != ',') - return Error("Expected ')' or ',' in argument list"); - getNextToken(); - } - } - - // Eat the ')'. - getNextToken(); - - return new CallExprAST(IdName, Args); - } - - /// numberexpr ::= number - static ExprAST *ParseNumberExpr() { - ExprAST *Result = new NumberExprAST(NumVal); - getNextToken(); // consume the number - return Result; - } - - /// parenexpr ::= '(' expression ')' - static ExprAST *ParseParenExpr() { - getNextToken(); // eat (. - ExprAST *V = ParseExpression(); - if (!V) return 0; - - if (CurTok != ')') - return Error("expected ')'"); - getNextToken(); // eat ). - return V; - } - - /// ifexpr ::= 'if' expression 'then' expression 'else' expression - static ExprAST *ParseIfExpr() { - getNextToken(); // eat the if. - - // condition. - ExprAST *Cond = ParseExpression(); - if (!Cond) return 0; - - if (CurTok != tok_then) - return Error("expected then"); - getNextToken(); // eat the then - - ExprAST *Then = ParseExpression(); - if (Then == 0) return 0; - - if (CurTok != tok_else) - return Error("expected else"); - - getNextToken(); - - ExprAST *Else = ParseExpression(); - if (!Else) return 0; - - return new IfExprAST(Cond, Then, Else); - } - - /// forexpr ::= 'for' identifier '=' expr ',' expr (',' expr)? 'in' expression - static ExprAST *ParseForExpr() { - getNextToken(); // eat the for. - - if (CurTok != tok_identifier) - return Error("expected identifier after for"); - - std::string IdName = IdentifierStr; - getNextToken(); // eat identifier. - - if (CurTok != '=') - return Error("expected '=' after for"); - getNextToken(); // eat '='. - - - ExprAST *Start = ParseExpression(); - if (Start == 0) return 0; - if (CurTok != ',') - return Error("expected ',' after for start value"); - getNextToken(); - - ExprAST *End = ParseExpression(); - if (End == 0) return 0; - - // The step value is optional. - ExprAST *Step = 0; - if (CurTok == ',') { - getNextToken(); - Step = ParseExpression(); - if (Step == 0) return 0; - } - - if (CurTok != tok_in) - return Error("expected 'in' after for"); - getNextToken(); // eat 'in'. - - ExprAST *Body = ParseExpression(); - if (Body == 0) return 0; - - return new ForExprAST(IdName, Start, End, Step, Body); - } - - /// varexpr ::= 'var' identifier ('=' expression)? - // (',' identifier ('=' expression)?)* 'in' expression - static ExprAST *ParseVarExpr() { - getNextToken(); // eat the var. - - std::vector<std::pair<std::string, ExprAST*> > VarNames; - - // At least one variable name is required. - if (CurTok != tok_identifier) - return Error("expected identifier after var"); - - while (1) { - std::string Name = IdentifierStr; - getNextToken(); // eat identifier. - - // Read the optional initializer. - ExprAST *Init = 0; - if (CurTok == '=') { - getNextToken(); // eat the '='. - - Init = ParseExpression(); - if (Init == 0) return 0; - } - - VarNames.push_back(std::make_pair(Name, Init)); - - // End of var list, exit loop. - if (CurTok != ',') break; - getNextToken(); // eat the ','. - - if (CurTok != tok_identifier) - return Error("expected identifier list after var"); - } - - // At this point, we have to have 'in'. - if (CurTok != tok_in) - return Error("expected 'in' keyword after 'var'"); - getNextToken(); // eat 'in'. - - ExprAST *Body = ParseExpression(); - if (Body == 0) return 0; - - return new VarExprAST(VarNames, Body); - } - - /// primary - /// ::= identifierexpr - /// ::= numberexpr - /// ::= parenexpr - /// ::= ifexpr - /// ::= forexpr - /// ::= varexpr - static ExprAST *ParsePrimary() { - switch (CurTok) { - default: return Error("unknown token when expecting an expression"); - case tok_identifier: return ParseIdentifierExpr(); - case tok_number: return ParseNumberExpr(); - case '(': return ParseParenExpr(); - case tok_if: return ParseIfExpr(); - case tok_for: return ParseForExpr(); - case tok_var: return ParseVarExpr(); - } - } - - /// unary - /// ::= primary - /// ::= '!' unary - static ExprAST *ParseUnary() { - // If the current token is not an operator, it must be a primary expr. - if (!isascii(CurTok) || CurTok == '(' || CurTok == ',') - return ParsePrimary(); - - // If this is a unary operator, read it. - int Opc = CurTok; - getNextToken(); - if (ExprAST *Operand = ParseUnary()) - return new UnaryExprAST(Opc, Operand); - return 0; - } - - /// binoprhs - /// ::= ('+' unary)* - static ExprAST *ParseBinOpRHS(int ExprPrec, ExprAST *LHS) { - // If this is a binop, find its precedence. - while (1) { - int TokPrec = GetTokPrecedence(); - - // If this is a binop that binds at least as tightly as the current binop, - // consume it, otherwise we are done. - if (TokPrec < ExprPrec) - return LHS; - - // Okay, we know this is a binop. - int BinOp = CurTok; - getNextToken(); // eat binop - - // Parse the unary expression after the binary operator. - ExprAST *RHS = ParseUnary(); - if (!RHS) return 0; - - // If BinOp binds less tightly with RHS than the operator after RHS, let - // the pending operator take RHS as its LHS. - int NextPrec = GetTokPrecedence(); - if (TokPrec < NextPrec) { - RHS = ParseBinOpRHS(TokPrec+1, RHS); - if (RHS == 0) return 0; - } - - // Merge LHS/RHS. - LHS = new BinaryExprAST(BinOp, LHS, RHS); - } - } - - /// expression - /// ::= unary binoprhs - /// - static ExprAST *ParseExpression() { - ExprAST *LHS = ParseUnary(); - if (!LHS) return 0; - - return ParseBinOpRHS(0, LHS); - } - - /// prototype - /// ::= id '(' id* ')' - /// ::= binary LETTER number? (id, id) - /// ::= unary LETTER (id) - static PrototypeAST *ParsePrototype() { - std::string FnName; - - unsigned Kind = 0; // 0 = identifier, 1 = unary, 2 = binary. - unsigned BinaryPrecedence = 30; - - switch (CurTok) { - default: - return ErrorP("Expected function name in prototype"); - case tok_identifier: - FnName = IdentifierStr; - Kind = 0; - getNextToken(); - break; - case tok_unary: - getNextToken(); - if (!isascii(CurTok)) - return ErrorP("Expected unary operator"); - FnName = "unary"; - FnName += (char)CurTok; - Kind = 1; - getNextToken(); - break; - case tok_binary: - getNextToken(); - if (!isascii(CurTok)) - return ErrorP("Expected binary operator"); - FnName = "binary"; - FnName += (char)CurTok; - Kind = 2; - getNextToken(); - - // Read the precedence if present. - if (CurTok == tok_number) { - if (NumVal < 1 || NumVal > 100) - return ErrorP("Invalid precedecnce: must be 1..100"); - BinaryPrecedence = (unsigned)NumVal; - getNextToken(); - } - break; - } - - if (CurTok != '(') - return ErrorP("Expected '(' in prototype"); - - std::vector<std::string> ArgNames; - while (getNextToken() == tok_identifier) - ArgNames.push_back(IdentifierStr); - if (CurTok != ')') - return ErrorP("Expected ')' in prototype"); - - // success. - getNextToken(); // eat ')'. - - // Verify right number of names for operator. - if (Kind && ArgNames.size() != Kind) - return ErrorP("Invalid number of operands for operator"); - - return new PrototypeAST(FnName, ArgNames, Kind != 0, BinaryPrecedence); - } - - /// definition ::= 'def' prototype expression - static FunctionAST *ParseDefinition() { - getNextToken(); // eat def. - PrototypeAST *Proto = ParsePrototype(); - if (Proto == 0) return 0; - - if (ExprAST *E = ParseExpression()) - return new FunctionAST(Proto, E); - return 0; - } - - /// toplevelexpr ::= expression - static FunctionAST *ParseTopLevelExpr() { - if (ExprAST *E = ParseExpression()) { - // Make an anonymous proto. - PrototypeAST *Proto = new PrototypeAST("", std::vector<std::string>()); - return new FunctionAST(Proto, E); - } - return 0; - } - - /// external ::= 'extern' prototype - static PrototypeAST *ParseExtern() { - getNextToken(); // eat extern. - return ParsePrototype(); - } - - //===----------------------------------------------------------------------===// - // Code Generation - //===----------------------------------------------------------------------===// - - static Module *TheModule; - static IRBuilder<> Builder(getGlobalContext()); - static std::map<std::string, AllocaInst*> NamedValues; - static FunctionPassManager *TheFPM; - - Value *ErrorV(const char *Str) { Error(Str); return 0; } - - /// CreateEntryBlockAlloca - Create an alloca instruction in the entry block of - /// the function. This is used for mutable variables etc. - static AllocaInst *CreateEntryBlockAlloca(Function *TheFunction, - const std::string &VarName) { - IRBuilder<> TmpB(&TheFunction->getEntryBlock(), - TheFunction->getEntryBlock().begin()); - return TmpB.CreateAlloca(Type::getDoubleTy(getGlobalContext()), 0, - VarName.c_str()); - } - - Value *NumberExprAST::Codegen() { - return ConstantFP::get(getGlobalContext(), APFloat(Val)); - } - - Value *VariableExprAST::Codegen() { - // Look this variable up in the function. - Value *V = NamedValues[Name]; - if (V == 0) return ErrorV("Unknown variable name"); - - // Load the value. - return Builder.CreateLoad(V, Name.c_str()); - } - - Value *UnaryExprAST::Codegen() { - Value *OperandV = Operand->Codegen(); - if (OperandV == 0) return 0; - - Function *F = TheModule->getFunction(std::string("unary")+Opcode); - if (F == 0) - return ErrorV("Unknown unary operator"); - - return Builder.CreateCall(F, OperandV, "unop"); - } - - Value *BinaryExprAST::Codegen() { - // Special case '=' because we don't want to emit the LHS as an expression. - if (Op == '=') { - // Assignment requires the LHS to be an identifier. - VariableExprAST *LHSE = dynamic_cast<VariableExprAST*>(LHS); - if (!LHSE) - return ErrorV("destination of '=' must be a variable"); - // Codegen the RHS. - Value *Val = RHS->Codegen(); - if (Val == 0) return 0; - - // Look up the name. - Value *Variable = NamedValues[LHSE->getName()]; - if (Variable == 0) return ErrorV("Unknown variable name"); - - Builder.CreateStore(Val, Variable); - return Val; - } - - Value *L = LHS->Codegen(); - Value *R = RHS->Codegen(); - if (L == 0 || R == 0) return 0; - - switch (Op) { - case '+': return Builder.CreateFAdd(L, R, "addtmp"); - case '-': return Builder.CreateFSub(L, R, "subtmp"); - case '*': return Builder.CreateFMul(L, R, "multmp"); - case '<': - L = Builder.CreateFCmpULT(L, R, "cmptmp"); - // Convert bool 0/1 to double 0.0 or 1.0 - return Builder.CreateUIToFP(L, Type::getDoubleTy(getGlobalContext()), - "booltmp"); - default: break; - } - - // If it wasn't a builtin binary operator, it must be a user defined one. Emit - // a call to it. - Function *F = TheModule->getFunction(std::string("binary")+Op); - assert(F && "binary operator not found!"); - - Value *Ops[2] = { L, R }; - return Builder.CreateCall(F, Ops, "binop"); - } - - Value *CallExprAST::Codegen() { - // Look up the name in the global module table. - Function *CalleeF = TheModule->getFunction(Callee); - if (CalleeF == 0) - return ErrorV("Unknown function referenced"); - - // If argument mismatch error. - if (CalleeF->arg_size() != Args.size()) - return ErrorV("Incorrect # arguments passed"); - - std::vector<Value*> ArgsV; - for (unsigned i = 0, e = Args.size(); i != e; ++i) { - ArgsV.push_back(Args[i]->Codegen()); - if (ArgsV.back() == 0) return 0; - } - - return Builder.CreateCall(CalleeF, ArgsV, "calltmp"); - } - - Value *IfExprAST::Codegen() { - Value *CondV = Cond->Codegen(); - if (CondV == 0) return 0; - - // Convert condition to a bool by comparing equal to 0.0. - CondV = Builder.CreateFCmpONE(CondV, - ConstantFP::get(getGlobalContext(), APFloat(0.0)), - "ifcond"); - - Function *TheFunction = Builder.GetInsertBlock()->getParent(); - - // Create blocks for the then and else cases. Insert the 'then' block at the - // end of the function. - BasicBlock *ThenBB = BasicBlock::Create(getGlobalContext(), "then", TheFunction); - BasicBlock *ElseBB = BasicBlock::Create(getGlobalContext(), "else"); - BasicBlock *MergeBB = BasicBlock::Create(getGlobalContext(), "ifcont"); - - Builder.CreateCondBr(CondV, ThenBB, ElseBB); - - // Emit then value. - Builder.SetInsertPoint(ThenBB); - - Value *ThenV = Then->Codegen(); - if (ThenV == 0) return 0; - - Builder.CreateBr(MergeBB); - // Codegen of 'Then' can change the current block, update ThenBB for the PHI. - ThenBB = Builder.GetInsertBlock(); - - // Emit else block. - TheFunction->getBasicBlockList().push_back(ElseBB); - Builder.SetInsertPoint(ElseBB); - - Value *ElseV = Else->Codegen(); - if (ElseV == 0) return 0; - - Builder.CreateBr(MergeBB); - // Codegen of 'Else' can change the current block, update ElseBB for the PHI. - ElseBB = Builder.GetInsertBlock(); - - // Emit merge block. - TheFunction->getBasicBlockList().push_back(MergeBB); - Builder.SetInsertPoint(MergeBB); - PHINode *PN = Builder.CreatePHI(Type::getDoubleTy(getGlobalContext()), 2, - "iftmp"); - - PN->addIncoming(ThenV, ThenBB); - PN->addIncoming(ElseV, ElseBB); - return PN; - } - - Value *ForExprAST::Codegen() { - // Output this as: - // var = alloca double - // ... - // start = startexpr - // store start -> var - // goto loop - // loop: - // ... - // bodyexpr - // ... - // loopend: - // step = stepexpr - // endcond = endexpr - // - // curvar = load var - // nextvar = curvar + step - // store nextvar -> var - // br endcond, loop, endloop - // outloop: - - Function *TheFunction = Builder.GetInsertBlock()->getParent(); - - // Create an alloca for the variable in the entry block. - AllocaInst *Alloca = CreateEntryBlockAlloca(TheFunction, VarName); - - // Emit the start code first, without 'variable' in scope. - Value *StartVal = Start->Codegen(); - if (StartVal == 0) return 0; - - // Store the value into the alloca. - Builder.CreateStore(StartVal, Alloca); - - // Make the new basic block for the loop header, inserting after current - // block. - BasicBlock *LoopBB = BasicBlock::Create(getGlobalContext(), "loop", TheFunction); - - // Insert an explicit fall through from the current block to the LoopBB. - Builder.CreateBr(LoopBB); - - // Start insertion in LoopBB. - Builder.SetInsertPoint(LoopBB); - - // Within the loop, the variable is defined equal to the PHI node. If it - // shadows an existing variable, we have to restore it, so save it now. - AllocaInst *OldVal = NamedValues[VarName]; - NamedValues[VarName] = Alloca; - - // Emit the body of the loop. This, like any other expr, can change the - // current BB. Note that we ignore the value computed by the body, but don't - // allow an error. - if (Body->Codegen() == 0) - return 0; - - // Emit the step value. - Value *StepVal; - if (Step) { - StepVal = Step->Codegen(); - if (StepVal == 0) return 0; - } else { - // If not specified, use 1.0. - StepVal = ConstantFP::get(getGlobalContext(), APFloat(1.0)); - } - - // Compute the end condition. - Value *EndCond = End->Codegen(); - if (EndCond == 0) return EndCond; - - // Reload, increment, and restore the alloca. This handles the case where - // the body of the loop mutates the variable. - Value *CurVar = Builder.CreateLoad(Alloca, VarName.c_str()); - Value *NextVar = Builder.CreateFAdd(CurVar, StepVal, "nextvar"); - Builder.CreateStore(NextVar, Alloca); - - // Convert condition to a bool by comparing equal to 0.0. - EndCond = Builder.CreateFCmpONE(EndCond, - ConstantFP::get(getGlobalContext(), APFloat(0.0)), - "loopcond"); - - // Create the "after loop" block and insert it. - BasicBlock *AfterBB = BasicBlock::Create(getGlobalContext(), "afterloop", TheFunction); - - // Insert the conditional branch into the end of LoopEndBB. - Builder.CreateCondBr(EndCond, LoopBB, AfterBB); - - // Any new code will be inserted in AfterBB. - Builder.SetInsertPoint(AfterBB); - - // Restore the unshadowed variable. - if (OldVal) - NamedValues[VarName] = OldVal; - else - NamedValues.erase(VarName); - - - // for expr always returns 0.0. - return Constant::getNullValue(Type::getDoubleTy(getGlobalContext())); - } - - Value *VarExprAST::Codegen() { - std::vector<AllocaInst *> OldBindings; - - Function *TheFunction = Builder.GetInsertBlock()->getParent(); - - // Register all variables and emit their initializer. - for (unsigned i = 0, e = VarNames.size(); i != e; ++i) { - const std::string &VarName = VarNames[i].first; - ExprAST *Init = VarNames[i].second; - - // Emit the initializer before adding the variable to scope, this prevents - // the initializer from referencing the variable itself, and permits stuff - // like this: - // var a = 1 in - // var a = a in ... # refers to outer 'a'. - Value *InitVal; - if (Init) { - InitVal = Init->Codegen(); - if (InitVal == 0) return 0; - } else { // If not specified, use 0.0. - InitVal = ConstantFP::get(getGlobalContext(), APFloat(0.0)); - } - - AllocaInst *Alloca = CreateEntryBlockAlloca(TheFunction, VarName); - Builder.CreateStore(InitVal, Alloca); - - // Remember the old variable binding so that we can restore the binding when - // we unrecurse. - OldBindings.push_back(NamedValues[VarName]); - - // Remember this binding. - NamedValues[VarName] = Alloca; - } - - // Codegen the body, now that all vars are in scope. - Value *BodyVal = Body->Codegen(); - if (BodyVal == 0) return 0; - - // Pop all our variables from scope. - for (unsigned i = 0, e = VarNames.size(); i != e; ++i) - NamedValues[VarNames[i].first] = OldBindings[i]; - - // Return the body computation. - return BodyVal; - } - - Function *PrototypeAST::Codegen() { - // Make the function type: double(double,double) etc. - std::vector<Type*> Doubles(Args.size(), - Type::getDoubleTy(getGlobalContext())); - FunctionType *FT = FunctionType::get(Type::getDoubleTy(getGlobalContext()), - Doubles, false); - - Function *F = Function::Create(FT, Function::ExternalLinkage, Name, TheModule); - - // If F conflicted, there was already something named 'Name'. If it has a - // body, don't allow redefinition or reextern. - if (F->getName() != Name) { - // Delete the one we just made and get the existing one. - F->eraseFromParent(); - F = TheModule->getFunction(Name); - - // If F already has a body, reject this. - if (!F->empty()) { - ErrorF("redefinition of function"); - return 0; - } - - // If F took a different number of args, reject. - if (F->arg_size() != Args.size()) { - ErrorF("redefinition of function with different # args"); - return 0; - } - } - - // Set names for all arguments. - unsigned Idx = 0; - for (Function::arg_iterator AI = F->arg_begin(); Idx != Args.size(); - ++AI, ++Idx) - AI->setName(Args[Idx]); - - return F; - } - - /// CreateArgumentAllocas - Create an alloca for each argument and register the - /// argument in the symbol table so that references to it will succeed. - void PrototypeAST::CreateArgumentAllocas(Function *F) { - Function::arg_iterator AI = F->arg_begin(); - for (unsigned Idx = 0, e = Args.size(); Idx != e; ++Idx, ++AI) { - // Create an alloca for this variable. - AllocaInst *Alloca = CreateEntryBlockAlloca(F, Args[Idx]); - - // Store the initial value into the alloca. - Builder.CreateStore(AI, Alloca); - - // Add arguments to variable symbol table. - NamedValues[Args[Idx]] = Alloca; - } - } - - Function *FunctionAST::Codegen() { - NamedValues.clear(); - - Function *TheFunction = Proto->Codegen(); - if (TheFunction == 0) - return 0; - - // If this is an operator, install it. - if (Proto->isBinaryOp()) - BinopPrecedence[Proto->getOperatorName()] = Proto->getBinaryPrecedence(); - - // Create a new basic block to start insertion into. - BasicBlock *BB = BasicBlock::Create(getGlobalContext(), "entry", TheFunction); - Builder.SetInsertPoint(BB); - - // Add all arguments to the symbol table and create their allocas. - Proto->CreateArgumentAllocas(TheFunction); - - if (Value *RetVal = Body->Codegen()) { - // Finish off the function. - Builder.CreateRet(RetVal); - - // Validate the generated code, checking for consistency. - verifyFunction(*TheFunction); - - // Optimize the function. - TheFPM->run(*TheFunction); - - return TheFunction; - } - - // Error reading body, remove function. - TheFunction->eraseFromParent(); - - if (Proto->isBinaryOp()) - BinopPrecedence.erase(Proto->getOperatorName()); - return 0; - } - - //===----------------------------------------------------------------------===// - // Top-Level parsing and JIT Driver - //===----------------------------------------------------------------------===// - - static ExecutionEngine *TheExecutionEngine; - - static void HandleDefinition() { - if (FunctionAST *F = ParseDefinition()) { - if (Function *LF = F->Codegen()) { - fprintf(stderr, "Read function definition:"); - LF->dump(); - } - } else { - // Skip token for error recovery. - getNextToken(); - } - } - - static void HandleExtern() { - if (PrototypeAST *P = ParseExtern()) { - if (Function *F = P->Codegen()) { - fprintf(stderr, "Read extern: "); - F->dump(); - } - } else { - // Skip token for error recovery. - getNextToken(); - } - } - - static void HandleTopLevelExpression() { - // Evaluate a top-level expression into an anonymous function. - if (FunctionAST *F = ParseTopLevelExpr()) { - if (Function *LF = F->Codegen()) { - // JIT the function, returning a function pointer. - void *FPtr = TheExecutionEngine->getPointerToFunction(LF); - - // Cast it to the right type (takes no arguments, returns a double) so we - // can call it as a native function. - double (*FP)() = (double (*)())(intptr_t)FPtr; - fprintf(stderr, "Evaluated to %f\n", FP()); - } - } else { - // Skip token for error recovery. - getNextToken(); - } - } - - /// top ::= definition | external | expression | ';' - static void MainLoop() { - while (1) { - fprintf(stderr, "ready> "); - switch (CurTok) { - case tok_eof: return; - case ';': getNextToken(); break; // ignore top-level semicolons. - case tok_def: HandleDefinition(); break; - case tok_extern: HandleExtern(); break; - default: HandleTopLevelExpression(); break; - } - } - } - - //===----------------------------------------------------------------------===// - // "Library" functions that can be "extern'd" from user code. - //===----------------------------------------------------------------------===// - - /// putchard - putchar that takes a double and returns 0. - extern "C" - double putchard(double X) { - putchar((char)X); - return 0; - } - - /// printd - printf that takes a double prints it as "%f\n", returning 0. - extern "C" - double printd(double X) { - printf("%f\n", X); - return 0; - } - - //===----------------------------------------------------------------------===// - // Main driver code. - //===----------------------------------------------------------------------===// - - int main() { - InitializeNativeTarget(); - LLVMContext &Context = getGlobalContext(); - - // Install standard binary operators. - // 1 is lowest precedence. - BinopPrecedence['='] = 2; - BinopPrecedence['<'] = 10; - BinopPrecedence['+'] = 20; - BinopPrecedence['-'] = 20; - BinopPrecedence['*'] = 40; // highest. - - // Prime the first token. - fprintf(stderr, "ready> "); - getNextToken(); - - // Make the module, which holds all the code. - TheModule = new Module("my cool jit", Context); - - // Create the JIT. This takes ownership of the module. - std::string ErrStr; - TheExecutionEngine = EngineBuilder(TheModule).setErrorStr(&ErrStr).create(); - if (!TheExecutionEngine) { - fprintf(stderr, "Could not create ExecutionEngine: %s\n", ErrStr.c_str()); - exit(1); - } - - FunctionPassManager OurFPM(TheModule); - - // Set up the optimizer pipeline. Start with registering info about how the - // target lays out data structures. - OurFPM.add(new DataLayout(*TheExecutionEngine->getDataLayout())); - // Provide basic AliasAnalysis support for GVN. - OurFPM.add(createBasicAliasAnalysisPass()); - // Promote allocas to registers. - OurFPM.add(createPromoteMemoryToRegisterPass()); - // Do simple "peephole" optimizations and bit-twiddling optzns. - OurFPM.add(createInstructionCombiningPass()); - // Reassociate expressions. - OurFPM.add(createReassociatePass()); - // Eliminate Common SubExpressions. - OurFPM.add(createGVNPass()); - // Simplify the control flow graph (deleting unreachable blocks, etc). - OurFPM.add(createCFGSimplificationPass()); - - OurFPM.doInitialization(); - - // Set the global so the code gen can use this. - TheFPM = &OurFPM; - - // Run the main "interpreter loop" now. - MainLoop(); - - TheFPM = 0; - - // Print out all of the generated code. - TheModule->dump(); - - return 0; - } +.. literalinclude:: ../../examples/Kaleidoscope/Chapter7/toy.cpp + :language: c++ `Next: Conclusion and other useful LLVM tidbits <LangImpl8.html>`_ diff --git a/docs/tutorial/index.rst b/docs/tutorial/index.rst index 69a9aee..dde53ba 100644 --- a/docs/tutorial/index.rst +++ b/docs/tutorial/index.rst @@ -34,7 +34,7 @@ External Tutorials A simple guide for how to implement an LLVM integrated assembler for an architecture. -.. _`Howto: Implementing LLVM Integrated Assembler`: http://www.embecosm.com/download/ean10.html +.. _`Howto: Implementing LLVM Integrated Assembler`: http://www.embecosm.com/appnotes/ean10/ean10-howto-llvmas-1.0.html Advanced Topics =============== |