diff options
Diffstat (limited to 'docs')
63 files changed, 1153 insertions, 1327 deletions
diff --git a/docs/AliasAnalysis.rst b/docs/AliasAnalysis.rst index 54b4a4a..712d57d 100644 --- a/docs/AliasAnalysis.rst +++ b/docs/AliasAnalysis.rst @@ -1,5 +1,3 @@ -.. _alias_analysis: - ================================== LLVM Alias Analysis Infrastructure ================================== diff --git a/docs/Atomics.rst b/docs/Atomics.rst index 1bca53e..705d73f 100644 --- a/docs/Atomics.rst +++ b/docs/Atomics.rst @@ -1,5 +1,3 @@ -.. _atomics: - ============================================== LLVM Atomic Instructions and Concurrency Guide ============================================== diff --git a/docs/BitCodeFormat.rst b/docs/BitCodeFormat.rst index 333e79b..c83b6c1 100644 --- a/docs/BitCodeFormat.rst +++ b/docs/BitCodeFormat.rst @@ -1,5 +1,3 @@ -.. _bitcode_format: - .. role:: raw-html(raw) :format: html diff --git a/docs/BranchWeightMetadata.rst b/docs/BranchWeightMetadata.rst index 2667ce3..71ecd34 100644 --- a/docs/BranchWeightMetadata.rst +++ b/docs/BranchWeightMetadata.rst @@ -1,5 +1,3 @@ -.. _branch_weight: - =========================== LLVM Branch Weight Metadata =========================== diff --git a/docs/Bugpoint.rst b/docs/Bugpoint.rst index 047129f..1a5fc8c 100644 --- a/docs/Bugpoint.rst +++ b/docs/Bugpoint.rst @@ -1,5 +1,3 @@ -.. _bugpoint: - ==================================== LLVM bugpoint tool: design and usage ==================================== diff --git a/docs/CMake.rst b/docs/CMake.rst index f895788..6eab04b 100644 --- a/docs/CMake.rst +++ b/docs/CMake.rst @@ -1,5 +1,3 @@ -.. _building-with-cmake: - ======================== Building LLVM with CMake ======================== diff --git a/docs/CodeGenerator.rst b/docs/CodeGenerator.rst index ce23667..b5d4180 100644 --- a/docs/CodeGenerator.rst +++ b/docs/CodeGenerator.rst @@ -1,5 +1,3 @@ -.. _code_generator: - ========================================== The LLVM Target-Independent Code Generator ========================================== @@ -17,6 +15,8 @@ The LLVM Target-Independent Code Generator .partial { background-color: #F88017 } .yes { background-color: #0F0; } .yes:before { content: "Y" } + .na { background-color: #6666FF; } + .na:before { content: "N/A" } </style> .. contents:: @@ -285,12 +285,10 @@ The ``TargetInstrInfo`` class ----------------------------- The ``TargetInstrInfo`` class is used to describe the machine instructions -supported by the target. It is essentially an array of ``TargetInstrDescriptor`` -objects, each of which describes one instruction the target -supports. Descriptors define things like the mnemonic for the opcode, the number -of operands, the list of implicit register uses and defs, whether the -instruction has certain target-independent properties (accesses memory, is -commutable, etc), and holds any target-specific flags. +supported by the target. Descriptions define things like the mnemonic for +the opcode, the number of operands, the list of implicit register uses and defs, +whether the instruction has certain target-independent properties (accesses +memory, is commutable, etc), and holds any target-specific flags. The ``TargetFrameInfo`` class ----------------------------- @@ -1748,12 +1746,14 @@ the key: :raw-html:`<table border="1" cellspacing="0">` :raw-html:`<tr>` :raw-html:`<th>Unknown</th>` +:raw-html:`<th>Not Applicable</th>` :raw-html:`<th>No support</th>` :raw-html:`<th>Partial Support</th>` :raw-html:`<th>Complete Support</th>` :raw-html:`</tr>` :raw-html:`<tr>` :raw-html:`<td class="unknown"></td>` +:raw-html:`<td class="na"></td>` :raw-html:`<td class="no"></td>` :raw-html:`<td class="partial"></td>` :raw-html:`<td class="yes"></td>` @@ -1773,7 +1773,7 @@ Here is the table: :raw-html:`<th>MBlaze</th>` :raw-html:`<th>MSP430</th>` :raw-html:`<th>Mips</th>` -:raw-html:`<th>PTX</th>` +:raw-html:`<th>NVPTX</th>` :raw-html:`<th>PowerPC</th>` :raw-html:`<th>Sparc</th>` :raw-html:`<th>X86</th>` @@ -1787,7 +1787,7 @@ Here is the table: :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="no"></td> <!-- PTX -->` +: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> <!-- X86 -->` @@ -1801,7 +1801,7 @@ Here is the table: :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> <!-- PTX -->` +: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> <!-- X86 -->` @@ -1815,7 +1815,7 @@ Here is the table: :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> <!-- PTX -->` +: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> <!-- X86 -->` @@ -1829,7 +1829,7 @@ Here is the table: :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="unknown"></td> <!-- PTX -->` +: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> <!-- X86 -->` @@ -1843,7 +1843,7 @@ Here is the table: :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="unknown"></td> <!-- PTX -->` +: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> <!-- X86 -->` @@ -1857,7 +1857,7 @@ Here is the table: :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> <!-- PTX -->` +: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> <!-- X86 -->` @@ -1871,7 +1871,7 @@ Here is the table: :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="unknown"></td> <!-- PTX -->` +: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="yes"></td> <!-- X86 -->` @@ -1885,7 +1885,7 @@ Here is the table: :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> <!-- PTX -->` +: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="partial"><a href="#feat_segstacks_x86">*</a></td> <!-- X86 -->` @@ -2367,17 +2367,17 @@ Dynamic Allocation TODO - More to come. -The PTX backend ---------------- +The NVPTX backend +----------------- -The PTX code generator lives in the lib/Target/PTX directory. It is currently a -work-in-progress, but already supports most of the code generation functionality -needed to generate correct PTX kernels for CUDA devices. +The NVPTX code generator under lib/Target/NVPTX is an open-source version of +the NVIDIA NVPTX code generator for LLVM. It is contributed by NVIDIA and is +a port of the code generator used in the CUDA compiler (nvcc). It targets the +PTX 3.0/3.1 ISA and can target any compute capability greater than or equal to +2.0 (Fermi). -The code generator can target PTX 2.0+, and shader model 1.0+. The PTX ISA -Reference Manual is used as the primary source of ISA information, though an -effort is made to make the output of the code generator match the output of the -NVidia nvcc compiler, whenever possible. +This target is of production quality and should be completely compatible with +the official NVIDIA toolchain. Code Generator Options: @@ -2387,39 +2387,28 @@ Code Generator Options: :raw-html:`<th>Description</th>` :raw-html:`</tr>` :raw-html:`<tr>` -:raw-html:`<td>``double``</td>` -:raw-html:`<td align="left">If enabled, the map_f64_to_f32 directive is disabled in the PTX output, allowing native double-precision arithmetic</td>` +:raw-html:`<td>sm_20</td>` +:raw-html:`<td align="left">Set shader model/compute capability to 2.0</td>` +:raw-html:`</tr>` +:raw-html:`<tr>` +:raw-html:`<td>sm_21</td>` +:raw-html:`<td align="left">Set shader model/compute capability to 2.1</td>` +:raw-html:`</tr>` +:raw-html:`<tr>` +:raw-html:`<td>sm_30</td>` +:raw-html:`<td align="left">Set shader model/compute capability to 3.0</td>` +:raw-html:`</tr>` +:raw-html:`<tr>` +:raw-html:`<td>sm_35</td>` +:raw-html:`<td align="left">Set shader model/compute capability to 3.5</td>` :raw-html:`</tr>` :raw-html:`<tr>` -:raw-html:`<td>``no-fma``</td>` -:raw-html:`<td align="left">Disable generation of Fused-Multiply Add instructions, which may be beneficial for some devices</td>` +:raw-html:`<td>ptx30</td>` +:raw-html:`<td align="left">Target PTX 3.0</td>` :raw-html:`</tr>` :raw-html:`<tr>` -:raw-html:`<td>``smxy / computexy``</td>` -:raw-html:`<td align="left">Set shader model/compute capability to x.y, e.g. sm20 or compute13</td>` +:raw-html:`<td>ptx31</td>` +:raw-html:`<td align="left">Target PTX 3.1</td>` :raw-html:`</tr>` :raw-html:`</table>` -Working: - -* Arithmetic instruction selection (including combo FMA) - -* Bitwise instruction selection - -* Control-flow instruction selection - -* Function calls (only on SM 2.0+ and no return arguments) - -* Addresses spaces (0 = global, 1 = constant, 2 = local, 4 = shared) - -* Thread synchronization (bar.sync) - -* Special register reads ([N]TID, [N]CTAID, PMx, CLOCK, etc.) - -In Progress: - -* Robust call instruction selection - -* Stack frame allocation - -* Device-specific instruction scheduling optimizations diff --git a/docs/CodingStandards.rst b/docs/CodingStandards.rst index 8003c12..4d66ad7 100644 --- a/docs/CodingStandards.rst +++ b/docs/CodingStandards.rst @@ -1,5 +1,3 @@ -.. _coding_standards: - ===================== LLVM Coding Standards ===================== @@ -1090,6 +1088,34 @@ flushes the output stream. In other words, these are equivalent: Most of the time, you probably have no reason to flush the output stream, so it's better to use a literal ``'\n'``. +Don't use ``inline`` when defining a function in a class definition +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A member function defined in a class definition is implicitly inline, so don't +put the ``inline`` keyword in this case. + +Don't: + +.. code-block:: c++ + + class Foo { + public: + inline void bar() { + // ... + } + }; + +Do: + +.. code-block:: c++ + + class Foo { + public: + void bar() { + // ... + } + }; + Microscopic Details ------------------- @@ -1304,7 +1330,7 @@ namespace just because it was declared there. See Also ======== -A lot of these comments and recommendations have been culled for other sources. +A lot of these comments and recommendations have been culled from other sources. Two particularly important books for our work are: #. `Effective C++ diff --git a/docs/CommandGuide/FileCheck.rst b/docs/CommandGuide/FileCheck.rst index 256970b..fce63ba 100644 --- a/docs/CommandGuide/FileCheck.rst +++ b/docs/CommandGuide/FileCheck.rst @@ -43,7 +43,8 @@ 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. + The :option:`--strict-whitespace` argument disables this behavior. End-of-line + sequences are canonicalized to UNIX-style '\n' in all modes. .. option:: -version diff --git a/docs/CommandGuide/index.rst b/docs/CommandGuide/index.rst index 73a4835..9bfa964 100644 --- a/docs/CommandGuide/index.rst +++ b/docs/CommandGuide/index.rst @@ -1,5 +1,3 @@ -.. _commands: - LLVM Command Guide ------------------ diff --git a/docs/CommandGuide/lit.rst b/docs/CommandGuide/lit.rst index 1dcaff1..40c7646 100644 --- a/docs/CommandGuide/lit.rst +++ b/docs/CommandGuide/lit.rst @@ -151,10 +151,6 @@ ADDITIONAL OPTIONS List the discovered test suites as part of the standard output. -.. option:: --no-tcl-as-sh - - Run Tcl scripts internally (instead of converting to shell scripts). - .. option:: --repeat=N Run each test ``N`` times. Currently this is primarily useful for timing @@ -298,14 +294,13 @@ executed, two important global variables are predefined: tests in the suite. **suffixes** For **lit** test formats which scan directories for tests, this - variable is a list of suffixes to identify test files. Used by: *ShTest*, - *TclTest*. + variable is a list of suffixes to identify test files. Used by: *ShTest*. **substitutions** For **lit** test formats which substitute variables into a test - script, the list of substitutions to perform. Used by: *ShTest*, *TclTest*. + script, the list of substitutions to perform. Used by: *ShTest*. **unsupported** Mark an unsupported directory, all tests within it will be - reported as unsupported. Used by: *ShTest*, *TclTest*. + reported as unsupported. Used by: *ShTest*. **parent** The parent configuration, this is the config object for the directory containing the test suite, or None. diff --git a/docs/CommandLine.rst b/docs/CommandLine.rst index 302f5a4..073958b 100644 --- a/docs/CommandLine.rst +++ b/docs/CommandLine.rst @@ -1,5 +1,3 @@ -.. _commandline: - ============================== CommandLine 2.0 Library Manual ============================== @@ -68,9 +66,7 @@ CommandLine library to have the following features: This document will hopefully let you jump in and start using CommandLine in your utility quickly and painlessly. Additionally it should be a simple reference -manual to figure out how stuff works. If it is failing in some area (or you -want an extension to the library), nag the author, `Chris -Lattner <mailto:sabre@nondot.org>`_. +manual to figure out how stuff works. Quick Start Guide ================= diff --git a/docs/CompilerWriterInfo.rst b/docs/CompilerWriterInfo.rst index f214919..bc0b996 100644 --- a/docs/CompilerWriterInfo.rst +++ b/docs/CompilerWriterInfo.rst @@ -1,5 +1,3 @@ -.. _compiler_writer_info: - ======================================================== Architecture & Platform Information for Compiler Writers ======================================================== @@ -24,6 +22,11 @@ ARM * `ABI <http://www.arm.com/products/DevTools/ABI.html>`_ +AArch64 +------- + +* `ARMv8 Instruction Set Overview <http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.genc010197a/index.html>`_ + Itanium (ia64) -------------- @@ -40,19 +43,15 @@ PowerPC IBM - Official manuals and docs ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -* `PowerPC Architecture Book <http://www-106.ibm.com/developerworks/eserver/articles/archguide.html>`_ - - * Book I: `PowerPC User Instruction Set Architecture <http://www-106.ibm.com/developerworks/eserver/pdfs/archpub1.pdf>`_ - - * Book II: `PowerPC Virtual Environment Architecture <http://www-106.ibm.com/developerworks/eserver/pdfs/archpub2.pdf>`_ +* `Power Instruction Set Architecture, Versions 2.03 through 2.06 (authentication required, free sign-up) <https://www.power.org/technology-introduction/standards-specifications>`_ - * Book III: `PowerPC Operating Environment Architecture <http://www-106.ibm.com/developerworks/eserver/pdfs/archpub3.pdf>`_ +* `PowerPC Compiler Writer's Guide <http://www.ibm.com/chips/techlib/techlib.nsf/techdocs/852569B20050FF7785256996007558C6>`_ -* `PowerPC Compiler Writer's Guide <http://www-3.ibm.com/chips/techlib/techlib.nsf/techdocs/852569B20050FF7785256996007558C6>`_ +* `Intro to PowerPC Architecture <http://www.ibm.com/developerworks/linux/library/l-powarch/>`_ -* `PowerPC Processor Manuals <http://www-3.ibm.com/chips/techlib/techlib.nsf/products/PowerPC>`_ +* `PowerPC Processor Manuals (embedded) <http://www.ibm.com/chips/techlib/techlib.nsf/products/PowerPC>`_ -* `Intro to PowerPC Architecture <http://www-106.ibm.com/developerworks/linux/library/l-powarch/>`_ +* `Various IBM specifications and white papers <https://www.power.org/documentation/?document_company=105&document_category=all&publish_year=all&grid_order=DESC&grid_sort=title>`_ * `IBM AIX/5L for POWER Assembly Reference <http://publibn.boulder.ibm.com/doc_link/en_US/a_doc_lib/aixassem/alangref/alangreftfrm.htm>`_ @@ -101,6 +100,8 @@ 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>`_ OS X ---- diff --git a/docs/DebuggingJITedCode.rst b/docs/DebuggingJITedCode.rst index eeb2f77..d6101d5 100644 --- a/docs/DebuggingJITedCode.rst +++ b/docs/DebuggingJITedCode.rst @@ -1,11 +1,7 @@ -.. _debugging-jited-code: - ============================== Debugging JIT-ed Code With GDB ============================== -.. sectionauthor:: Reid Kleckner and Eli Bendersky - Background ========== diff --git a/docs/DeveloperPolicy.rst b/docs/DeveloperPolicy.rst index 925e769..43bdc85 100644 --- a/docs/DeveloperPolicy.rst +++ b/docs/DeveloperPolicy.rst @@ -1,5 +1,3 @@ -.. _developer_policy: - ===================== LLVM Developer Policy ===================== diff --git a/docs/ExceptionHandling.rst b/docs/ExceptionHandling.rst index 190f182..0a86607 100644 --- a/docs/ExceptionHandling.rst +++ b/docs/ExceptionHandling.rst @@ -1,5 +1,3 @@ -.. _exception_handling: - ========================== Exception Handling in LLVM ========================== @@ -34,13 +32,13 @@ execution of an application. A more complete description of the Itanium ABI exception handling runtime support of can be found at `Itanium C++ ABI: Exception Handling -<http://www.codesourcery.com/cxx-abi/abi-eh.html>`_. A description of the +<http://mentorembedded.github.com/cxx-abi/abi-eh.html>`_. A description of the exception frame format can be found at `Exception Frames -<http://refspecs.freestandards.org/LSB_3.0.0/LSB-Core-generic/LSB-Core-generic/ehframechpt.html>`_, +<http://refspecs.linuxfoundation.org/LSB_3.0.0/LSB-Core-generic/LSB-Core-generic/ehframechpt.html>`_, with details of the DWARF 4 specification at `DWARF 4 Standard <http://dwarfstd.org/Dwarf4Std.php>`_. A description for the C++ exception table formats can be found at `Exception Handling Tables -<http://www.codesourcery.com/cxx-abi/exceptions.pdf>`_. +<http://mentorembedded.github.com/cxx-abi/exceptions.pdf>`_. Setjmp/Longjmp Exception Handling --------------------------------- @@ -151,10 +149,10 @@ type info index are passed in as arguments. The landing pad saves the exception structure reference and then proceeds to select the catch block that corresponds to the type info of the exception object. -The LLVM `landingpad instruction <LangRef.html#i_landingpad>`_ is used to convey -information about the landing pad to the back end. For C++, the ``landingpad`` -instruction returns a pointer and integer pair corresponding to the pointer to -the *exception structure* and the *selector value* respectively. +The LLVM :ref:`i_landingpad` is used to convey information about the landing +pad to the back end. For C++, the ``landingpad`` instruction returns a pointer +and integer pair corresponding to the pointer to the *exception structure* and +the *selector value* respectively. The ``landingpad`` instruction takes a reference to the personality function to be used for this ``try``/``catch`` sequence. The remainder of the instruction is @@ -203,10 +201,9 @@ A cleanup is extra code which needs to be run as part of unwinding a scope. C++ destructors are a typical example, but other languages and language extensions provide a variety of different kinds of cleanups. In general, a landing pad may need to run arbitrary amounts of cleanup code before actually entering a catch -block. To indicate the presence of cleanups, a `landingpad -instruction <LangRef.html#i_landingpad>`_ should have a *cleanup* -clause. Otherwise, the unwinder will not stop at the landing pad if there are no -catches or filters that require it to. +block. To indicate the presence of cleanups, a :ref:`i_landingpad` should have +a *cleanup* clause. Otherwise, the unwinder will not stop at the landing pad if +there are no catches or filters that require it to. .. note:: @@ -226,9 +223,9 @@ Throw Filters C++ allows the specification of which exception types may be thrown from a function. To represent this, a top level landing pad may exist to filter out -invalid types. To express this in LLVM code the `landingpad -instruction <LangRef.html#i_landingpad>`_ will have a filter clause. The clause -consists of an array of type infos. ``landingpad`` will return a negative value +invalid types. To express this in LLVM code the :ref:`i_landingpad` will have a +filter clause. The clause consists of an array of type infos. +``landingpad`` will return a negative value if the exception does not match any of the type infos. If no match is found then a call to ``__cxa_call_unexpected`` should be made, otherwise ``_Unwind_Resume``. Each of these functions requires a reference to the @@ -269,8 +266,8 @@ handling information at various points in generated code. .. _llvm.eh.typeid.for: -llvm.eh.typeid.for ------------------- +``llvm.eh.typeid.for`` +---------------------- .. code-block:: llvm @@ -283,8 +280,8 @@ function. This value can be used to compare against the result of .. _llvm.eh.sjlj.setjmp: -llvm.eh.sjlj.setjmp -------------------- +``llvm.eh.sjlj.setjmp`` +----------------------- .. code-block:: llvm @@ -305,8 +302,8 @@ available for use in a target-specific manner. .. _llvm.eh.sjlj.longjmp: -llvm.eh.sjlj.longjmp --------------------- +``llvm.eh.sjlj.longjmp`` +------------------------ .. code-block:: llvm @@ -318,8 +315,8 @@ a buffer populated by `llvm.eh.sjlj.setjmp`_. The frame pointer and stack pointer are restored from the buffer, then control is transferred to the destination address. -llvm.eh.sjlj.lsda ------------------ +``llvm.eh.sjlj.lsda`` +--------------------- .. code-block:: llvm @@ -330,8 +327,8 @@ the address of the Language Specific Data Area (LSDA) for the current function. The SJLJ front-end code stores this address in the exception handling function context for use by the runtime. -llvm.eh.sjlj.callsite ---------------------- +``llvm.eh.sjlj.callsite`` +------------------------- .. code-block:: llvm diff --git a/docs/ExtendingLLVM.rst b/docs/ExtendingLLVM.rst index 6df08ee..3d8e9ee 100644 --- a/docs/ExtendingLLVM.rst +++ b/docs/ExtendingLLVM.rst @@ -1,5 +1,3 @@ -.. _extending_llvm: - ============================================================ Extending LLVM: Adding instructions, intrinsics, types, etc. ============================================================ diff --git a/docs/FAQ.rst b/docs/FAQ.rst index b4c6261..e4ab2c1 100644 --- a/docs/FAQ.rst +++ b/docs/FAQ.rst @@ -1,5 +1,3 @@ -.. _faq: - ================================ Frequently Asked Questions (FAQ) ================================ diff --git a/docs/GarbageCollection.rst b/docs/GarbageCollection.rst index 7765bd7..5c3a1af 100644 --- a/docs/GarbageCollection.rst +++ b/docs/GarbageCollection.rst @@ -5,9 +5,6 @@ Accurate Garbage Collection with LLVM .. contents:: :local: -.. sectionauthor:: Chris Lattner <sabre@nondot.org> and - Gordon Henriksen - Introduction ============ diff --git a/docs/GetElementPtr.rst b/docs/GetElementPtr.rst index 3b57d78..306a2a8 100644 --- a/docs/GetElementPtr.rst +++ b/docs/GetElementPtr.rst @@ -1,5 +1,3 @@ -.. _gep: - ======================================= The Often Misunderstood GEP Instruction ======================================= diff --git a/docs/GettingStarted.rst b/docs/GettingStarted.rst index 5009d1c..539c75e 100644 --- a/docs/GettingStarted.rst +++ b/docs/GettingStarted.rst @@ -1,5 +1,3 @@ -.. _getting_started: - ==================================== Getting Started with the LLVM System ==================================== @@ -126,6 +124,8 @@ LLVM is known to work on the following platforms: +-----------------+----------------------+-------------------------+ |Linux | amd64 | GCC | +-----------------+----------------------+-------------------------+ +|Linux | ARM\ :sup:`13` | GCC | ++-----------------+----------------------+-------------------------+ |Solaris | V9 (Ultrasparc) | GCC | +-----------------+----------------------+-------------------------+ |FreeBSD | x86\ :sup:`1` | GCC | @@ -161,8 +161,6 @@ LLVM has partial support for the following platforms: .. note:: - Code generation supported for Pentium processors and up - #. Code generation supported for Pentium processors and up #. Code generation supported for 32-bit ABI only #. No native code generation @@ -182,9 +180,9 @@ LLVM has partial support for the following platforms: Windows-specifics that will cause the build to fail. #. To use LLVM modules on Win32-based system, you may configure LLVM with ``--enable-shared``. - #. To compile SPU backend, you need to add ``LDFLAGS=-Wl,--stack,16777216`` to configure. + #. MCJIT not working well pre-v7, old JIT engine not supported any more. Note that you will need about 1-3 GB of space for a full LLVM build in Debug mode, depending on the system (it is so large because of all the debugging @@ -219,11 +217,7 @@ uses the package and provides other details. +--------------------------------------------------------------+-----------------+---------------------------------------------+ | `SVN <http://subversion.tigris.org/project_packages.html>`_ | >=1.3 | Subversion access to LLVM\ :sup:`2` | +--------------------------------------------------------------+-----------------+---------------------------------------------+ -| `DejaGnu <http://savannah.gnu.org/projects/dejagnu>`_ | 1.4.2 | Automated test suite\ :sup:`3` | -+--------------------------------------------------------------+-----------------+---------------------------------------------+ -| `tcl <http://www.tcl.tk/software/tcltk/>`_ | 8.3, 8.4 | Automated test suite\ :sup:`3` | -+--------------------------------------------------------------+-----------------+---------------------------------------------+ -| `expect <http://expect.nist.gov/>`_ | 5.38.0 | Automated test suite\ :sup:`3` | +| `python <http://www.python.org/>`_ | >=2.4 | Automated test suite\ :sup:`3` | +--------------------------------------------------------------+-----------------+---------------------------------------------+ | `perl <http://www.perl.com/download.csp>`_ | >=5.6.0 | Utilities | +--------------------------------------------------------------+-----------------+---------------------------------------------+ @@ -368,6 +362,9 @@ optimizations are turned on. The symptom is an infinite loop in ``-O0``. A test failure in ``test/Assembler/alignstack.ll`` is one symptom of the problem. +**GCC 4.6.3 on ARM**: Miscompiles ``llvm-readobj`` at ``-O3``. A test failure +in ``test/Object/readobj-shared-object.test`` is one symptom of the problem. + **GNU ld 2.16.X**. Some 2.16.X versions of the ld linker will produce very long warning messages complaining that some "``.gnu.linkonce.t.*``" symbol was defined in a discarded section. You can safely ignore these messages as they are @@ -467,6 +464,8 @@ The files are as follows, with *x.y* marking the version number: Binary release of the llvm-gcc-4.2 front end for a specific platform. +.. _checkout: + Checkout LLVM from Subversion ----------------------------- @@ -643,6 +642,34 @@ 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 + + if [ ! -z $STASH ]; then + git stash pop >/dev/null + fi + +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. + To commit back changes via git-svn, use ``dcommit``: .. code-block:: console diff --git a/docs/GettingStartedVS.rst b/docs/GettingStartedVS.rst index 35f97f0..4c80f2c 100644 --- a/docs/GettingStartedVS.rst +++ b/docs/GettingStartedVS.rst @@ -1,5 +1,3 @@ -.. _winvs: - ================================================================== Getting Started with the LLVM System using Microsoft Visual Studio ================================================================== diff --git a/docs/GoldPlugin.rst b/docs/GoldPlugin.rst index 300aea9..17bbeb8 100644 --- a/docs/GoldPlugin.rst +++ b/docs/GoldPlugin.rst @@ -1,11 +1,7 @@ -.. _gold-plugin: - ==================== The LLVM gold plugin ==================== -.. sectionauthor:: Nick Lewycky - Introduction ============ diff --git a/docs/HowToAddABuilder.rst b/docs/HowToAddABuilder.rst index b0cd290..893f12d 100644 --- a/docs/HowToAddABuilder.rst +++ b/docs/HowToAddABuilder.rst @@ -1,11 +1,7 @@ -.. _how_to_add_a_builder: - =================================================================== How To Add Your Build Configuration To LLVM Buildbot Infrastructure =================================================================== -.. sectionauthor:: Galina Kistanova <gkistanova@gmail.com> - Introduction ============ diff --git a/docs/HowToBuildOnARM.rst b/docs/HowToBuildOnARM.rst index d786a7d..32ae39b 100644 --- a/docs/HowToBuildOnARM.rst +++ b/docs/HowToBuildOnARM.rst @@ -1,11 +1,7 @@ -.. _how_to_build_on_arm: - =================================================================== How To Build On ARM =================================================================== -.. sectionauthor:: Wei-Ren Chen (陳韋任) <chenwj@iis.sinica.edu.tw> - Introduction ============ @@ -40,8 +36,8 @@ on the ARMv6 and ARMv7 architectures and may be inapplicable to older chips. .. code-block:: bash - ./configure --build=armv7l-unknown-linux-gnueabihf - --host=armv7l-unknown-linux-gnueabihf - --target=armv7l-unknown-linux-gnueabihf --with-cpu=cortex-a9 - --with-float=hard --with-abi=aapcs-vfp --with-fpu=neon - --enable-targets=arm --disable-optimized --enable-assertions + ./configure --build=armv7l-unknown-linux-gnueabihf \ + --host=armv7l-unknown-linux-gnueabihf \ + --target=armv7l-unknown-linux-gnueabihf --with-cpu=cortex-a9 \ + --with-float=hard --with-abi=aapcs-vfp --with-fpu=neon \ + --enable-targets=arm --enable-optimized --enable-assertions diff --git a/docs/HowToReleaseLLVM.rst b/docs/HowToReleaseLLVM.rst index eb6c838..31877bd 100644 --- a/docs/HowToReleaseLLVM.rst +++ b/docs/HowToReleaseLLVM.rst @@ -6,11 +6,6 @@ How To Release LLVM To The Public :local: :depth: 1 -.. sectionauthor:: Tanya Lattner <tonic@nondot.org>, - Reid Spencer <rspencer@x10sys.com>, - John Criswell <criswell@cs.uiuc.edu> and - Bill Wendling <wendling@apple.com> - Introduction ============ @@ -201,7 +196,7 @@ Build LLVM Build ``Debug``, ``Release+Asserts``, and ``Release`` versions of ``llvm`` on all supported platforms. Directions to build ``llvm`` -are :ref:`here <getting_started>`. +are :doc:`here <GettingStarted>`. Build Clang Binary Distribution ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -268,7 +263,7 @@ no regressions when using either ``clang`` or ``dragonegg`` with the Qualify Clang ^^^^^^^^^^^^^ -``Clang`` is qualified when front-end specific tests in the ``llvm`` dejagnu +``Clang`` is qualified when front-end specific tests in the ``llvm`` regression test suite all pass, clang's own test suite passes cleanly, and there are no regressions in the ``test-suite``. @@ -278,26 +273,26 @@ Specific Target Qualification Details +--------------+-------------+----------------+-----------------------------+ | Architecture | OS | clang baseline | tests | +==============+=============+================+=============================+ -| x86-32 | Linux | last release | llvm dejagnu, | -| | | | clang tests, | +| x86-32 | Linux | last release | llvm regression tests, | +| | | | clang regression tests, | | | | | test-suite (including spec) | +--------------+-------------+----------------+-----------------------------+ -| x86-32 | FreeBSD | last release | llvm dejagnu, | -| | | | clang tests, | +| x86-32 | FreeBSD | last release | llvm regression tests, | +| | | | clang regression tests, | | | | | test-suite | +--------------+-------------+----------------+-----------------------------+ | x86-32 | mingw | none | QT | +--------------+-------------+----------------+-----------------------------+ -| x86-64 | Mac OS 10.X | last release | llvm dejagnu, | -| | | | clang tests, | +| x86-64 | Mac OS 10.X | last release | llvm regression tests, | +| | | | clang regression tests, | | | | | test-suite (including spec) | +--------------+-------------+----------------+-----------------------------+ -| x86-64 | Linux | last release | llvm dejagnu, | -| | | | clang tests, | +| x86-64 | Linux | last release | llvm regression tests, | +| | | | clang regression tests, | | | | | test-suite (including spec) | +--------------+-------------+----------------+-----------------------------+ -| x86-64 | FreeBSD | last release | llvm dejagnu, | -| | | | clang tests, | +| x86-64 | FreeBSD | last release | llvm regression tests, | +| | | | clang regression tests, | | | | | test-suite | +--------------+-------------+----------------+-----------------------------+ diff --git a/docs/HowToSetUpLLVMStyleRTTI.rst b/docs/HowToSetUpLLVMStyleRTTI.rst index aa1ad84..b906b25 100644 --- a/docs/HowToSetUpLLVMStyleRTTI.rst +++ b/docs/HowToSetUpLLVMStyleRTTI.rst @@ -1,11 +1,7 @@ -.. _how-to-set-up-llvm-style-rtti: - ====================================================== How to set up LLVM-style RTTI for your class hierarchy ====================================================== -.. sectionauthor:: Sean Silva <silvas@purdue.edu> - .. contents:: Background diff --git a/docs/HowToSubmitABug.rst b/docs/HowToSubmitABug.rst index ff2d649..45be282 100644 --- a/docs/HowToSubmitABug.rst +++ b/docs/HowToSubmitABug.rst @@ -1,11 +1,7 @@ -.. _how-to-submit-a-bug-report: - ================================ How to submit an LLVM bug report ================================ -.. sectionauthor:: Chris Lattner <sabre@nondot.org> and Misha Brukman <http://misha.brukman.net> - Introduction - Got bugs? ======================== diff --git a/docs/HowToUseAttributes.rst b/docs/HowToUseAttributes.rst new file mode 100644 index 0000000..66c44c0 --- /dev/null +++ b/docs/HowToUseAttributes.rst @@ -0,0 +1,81 @@ +===================== +How To Use Attributes +===================== + +.. contents:: + :local: + +Introduction +============ + +Attributes in LLVM have changed in some fundamental ways. It was necessary to +do this to support expanding the attributes to encompass more than a handful of +attributes --- e.g. command line options. The old way of handling attributes +consisted of representing them as a bit mask of values. This bit mask was +stored in a "list" structure that was reference counted. The advantage of this +was that attributes could be manipulated with 'or's and 'and's. The +disadvantage of this was that there was limited room for expansion, and +virtually no support for attribute-value pairs other than alignment. + +In the new scheme, an ``Attribute`` object represents a single attribute that's +uniqued. You use the ``Attribute::get`` methods to create a new ``Attribute`` +object. An attribute can be a single "enum" value (the enum being the +``Attribute::AttrKind`` enum), a string representing a target-dependent +attribute, or an attribute-value pair. Some examples: + +* Target-independent: ``noinline``, ``zext`` +* Target-dependent: ``"no-sse"``, ``"thumb2"`` +* Attribute-value pair: ``"cpu" = "cortex-a8"``, ``align = 4`` + +Note: for an attribute value pair, we expect a target-dependent attribute to +have a string for the value. + +``Attribute`` +============= +An ``Attribute`` object is designed to be passed around by value. + +Because attributes are no longer represented as a bit mask, you will need to +convert any code which does treat them as a bit mask to use the new query +methods on the Attribute class. + +``AttributeSet`` +================ + +The ``AttributeSet`` class replaces the old ``AttributeList`` class. The +``AttributeSet`` stores a collection of Attribute objects for each kind of +object that may have an attribute associated with it: the function as a +whole, the return type, or the function's parameters. A function's attributes +are at index ``AttributeSet::FunctionIndex``; the return type's attributes are +at index ``AttributeSet::ReturnIndex``; and the function's parameters' +attributes are at indices 1, ..., n (where 'n' is the number of parameters). +Most methods on the ``AttributeSet`` class take an index parameter. + +An ``AttributeSet`` is also a uniqued and immutable object. You create an +``AttributeSet`` through the ``AttributeSet::get`` methods. You can add and +remove attributes, which result in the creation of a new ``AttributeSet``. + +An ``AttributeSet`` object is designed to be passed around by value. + +Note: It is advised that you do *not* use the ``AttributeSet`` "introspection" +methods (e.g. ``Raw``, ``getRawPointer``, etc.). These methods break +encapsulation, and may be removed in a future release (i.e. LLVM 4.0). + +``AttrBuilder`` +=============== + +Lastly, we have a "builder" class to help create the ``AttributeSet`` object +without having to create several different intermediate uniqued +``AttributeSet`` objects. The ``AttrBuilder`` class allows you to add and +remove attributes at will. The attributes won't be uniqued until you call the +appropriate ``AttributeSet::get`` method. + +An ``AttrBuilder`` object is *not* designed to be passed around by value. It +should be passed by reference. + +Note: It is advised that you do *not* use the ``AttrBuilder::addRawValue()`` +method or the ``AttrBuilder(uint64_t Val)`` constructor. These are for +backwards compatibility and may be removed in a future release (i.e. LLVM 4.0). + +And that's basically it! A lot of functionality is hidden behind these classes, +but the interfaces are pretty straight forward. + diff --git a/docs/HowToUseInstrMappings.rst b/docs/HowToUseInstrMappings.rst index bf9278e..8a3e7c8 100644 --- a/docs/HowToUseInstrMappings.rst +++ b/docs/HowToUseInstrMappings.rst @@ -1,11 +1,7 @@ -.. _how_to_use_instruction_mappings: - =============================== How To Use Instruction Mappings =============================== -.. sectionauthor:: Jyotsna Verma <jverma@codeaurora.org> - .. contents:: :local: diff --git a/docs/LangRef.rst b/docs/LangRef.rst index 3c49ed0..c08cee1 100644 --- a/docs/LangRef.rst +++ b/docs/LangRef.rst @@ -111,7 +111,7 @@ After strength reduction: .. code-block:: llvm - %result = shl i32 %X, i8 3 + %result = shl i32 %X, 3 And the hard way: @@ -148,20 +148,20 @@ symbol table entries. Here is an example of the "hello world" module: .. code-block:: llvm - ; Declare the string constant as a global constant. - @.str = private unnamed_addr constant [13 x i8] c"hello world\0A\00" + ; Declare the string constant as a global constant. + @.str = private unnamed_addr constant [13 x i8] c"hello world\0A\00" - ; External declaration of the puts function - declare i32 @puts(i8* nocapture) nounwind + ; External declaration of the puts function + declare i32 @puts(i8* nocapture) nounwind ; Definition of main function - define i32 @main() { ; i32()* - ; Convert [13 x i8]* to i8 *... + define i32 @main() { ; i32()* + ; Convert [13 x i8]* to i8 *... %cast210 = getelementptr [13 x i8]* @.str, i64 0, i64 0 - ; Call puts function to write out the string to stdout. + ; Call puts function to write out the string to stdout. call i32 @puts(i8* %cast210) - ret i32 0 + ret i32 0 } ; Named metadata @@ -262,7 +262,7 @@ linkage: Some languages allow differing globals to be merged, such as two functions with different semantics. Other languages, such as ``C++``, ensure that only equivalent globals are ever merged (the - "one definition rule" — "ODR"). Such languages can use the + "one definition rule" --- "ODR"). Such languages can use the ``linkonce_odr`` and ``weak_odr`` linkage types to indicate that the global will only be merged with equivalent globals. These linkage types are otherwise the same as their non-``odr`` versions. @@ -465,11 +465,11 @@ more information on under which circumstances the different models may be used. The target may choose a different TLS model if the specified model is not supported, or if a better choice of model can be made. -A variable may be defined as a global "constant," which indicates that +A variable may be defined as a global ``constant``, which indicates that the contents of the variable will **never** be modified (enabling better optimization, allowing the global data to be placed in the read-only section of an executable, etc). Note that variables that need runtime -initialization cannot be marked "constant" as there is a store to the +initialization cannot be marked ``constant`` as there is a store to the variable. LLVM explicitly allows *declarations* of global variables to be marked @@ -501,6 +501,14 @@ is zero. The address space qualifier must precede any other attributes. LLVM allows an explicit section to be specified for globals. If the target supports it, it will emit globals to the section specified. +By default, global initializers are optimized by assuming that global +variables defined within the module are not modified from their +initial values before the start of the global initializer. This is +true even for variables potentially accessible from outside the +module, including those with external linkage or appearing in +``@llvm.used``. This assumption may be suppressed by marking the +variable with ``externally_initialized``. + An explicit alignment may be specified for a global, which must be a power of 2. If not present, or if the alignment is set to zero, the alignment of the global is set by the target to whatever it feels @@ -679,7 +687,7 @@ Currently, only the following parameter attributes are defined: This indicates that the pointer parameter specifies the address of a structure that is the return value of the function in the source program. This pointer must be guaranteed by the caller to be valid: - loads and stores to the structure may be assumed by the callee to + loads and stores to the structure may be assumed by the callee not to trap and to be properly aligned. This may only be applied to the first parameter. This is not a valid attribute for return values. @@ -712,6 +720,11 @@ Currently, only the following parameter attributes are defined: 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. .. _gc: @@ -729,6 +742,36 @@ The compiler declares the supported values of *name*. Specifying a collector which will cause the compiler to alter its output in order to support the named garbage collection algorithm. +.. _attrgrp: + +Attribute Groups +---------------- + +Attribute groups are groups of attributes that are referenced by objects within +the IR. They are important for keeping ``.ll`` files readable, because a lot of +functions will use the same set of attributes. In the degenerative case of a +``.ll`` file that corresponds to a single ``.c`` file, the single attribute +group will capture the important command line flags used to build that file. + +An attribute group is a module-level object. To use an attribute group, an +object references the attribute group's ID (e.g. ``#37``). An object may refer +to more than one attribute group. In that situation, the attributes from the +different groups are merged. + +Here is an example of attribute groups for a function that should always be +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 } + + ; Target-dependent attributes: + #1 = attributes { "no-sse" } + + ; Function @f has attributes: alwaysinline, alignstack=4, and "no-sse". + define void @f() #0 #1 { ... } + .. _fnattrs: Function Attributes @@ -750,9 +793,6 @@ example: define void @f() alwaysinline optsize { ... } define void @f() optsize { ... } -``address_safety`` - This attribute indicates that the address safety analysis is enabled - for this function. ``alignstack(<n>)`` This attribute indicates that, when emitting the prologue and epilogue, the backend should forcibly align the stack pointer. @@ -774,6 +814,17 @@ example: ``naked`` This attribute disables prologue / epilogue emission for the function. This can have very system-specific consequences. +``noduplicate`` + This attribute indicates that calls to the function cannot be + duplicated. A call to a ``noduplicate`` function may be moved + within its parent function, but may not be duplicated within + its parent function. + + A function containing a ``noduplicate`` call may still + be an inlining candidate, provided that the call is not + duplicated by inlining. That implies that the function has + internal linkage and only has one call site, so the original + call is dead after inlining. ``noimplicitfloat`` This attributes disables implicit floating point instructions. ``noinline`` @@ -819,13 +870,27 @@ example: ``setjmp`` is an example of such a function. The compiler disables some optimizations (like tail calls) in the caller of these functions. +``sanitize_address`` + This attribute indicates that AddressSanitizer checks + (dynamic address safety analysis) are enabled for this function. +``sanitize_memory`` + This attribute indicates that MemorySanitizer checks (dynamic detection + of accesses to uninitialized memory) are enabled for this function. +``sanitize_thread`` + This attribute indicates that ThreadSanitizer checks + (dynamic thread safety analysis) are enabled for this function. ``ssp`` This attribute indicates that the function should emit a stack - smashing protector. It is in the form of a "canary"—a random value + smashing protector. It is in the form of a "canary" --- a random value placed on the stack before the local variables that's checked upon return from the function to see if it has been overwritten. A heuristic is used to determine if a function needs stack protectors - or not. + or not. The heuristic used will enable protectors for functions with: + + - Character arrays larger than ``ssp-buffer-size`` (default 8). + - Aggregates containing character arrays larger than ``ssp-buffer-size``. + - Calls to alloca() with variable sizes or constant sizes greater than + ``ssp-buffer-size``. If a function that has an ``ssp`` attribute is inlined into a function that doesn't have an ``ssp`` attribute, then the resulting @@ -837,25 +902,30 @@ example: If a function that has an ``sspreq`` attribute is inlined into a function that doesn't have an ``sspreq`` attribute or which has an - ``ssp`` attribute, then the resulting function will have an - ``sspreq`` attribute. + ``ssp`` or ``sspstrong`` attribute, then the resulting function will have + an ``sspreq`` attribute. +``sspstrong`` + This attribute indicates that the function should emit a stack smashing + protector. This attribute causes a strong heuristic to be used when + determining if a function needs stack protectors. The strong heuristic + will enable protectors for functions with: + + - Arrays of any size and type + - Aggregates containing an array of any size and type. + - Calls to alloca(). + - Local variables that have had their address taken. + + This overrides the ``ssp`` function attribute. + + If a function that has an ``sspstrong`` attribute is inlined into a + function that doesn't have an ``sspstrong`` attribute, then the + resulting function will have an ``sspstrong`` attribute. ``uwtable`` This attribute indicates that the ABI being targeted requires that an unwind table entry be produce for this function even if we can show that no exceptions passes by it. This is normally the case for the ELF x86-64 abi, but it can be disabled for some compilation units. -``noduplicate`` - This attribute indicates that calls to the function cannot be - duplicated. A call to a ``noduplicate`` function may be moved - within its parent function, but may not be duplicated within - its parent function. - - A function containing a ``noduplicate`` call may still - be an inlining candidate, provided that the call is not - duplicated by inlining. That implies that the function has - internal linkage and only has one call site, so the original - call is dead after inlining. .. _moduleasm: @@ -950,22 +1020,20 @@ specifications are given in this list: - ``E`` - big endian - ``p:64:64:64`` - 64-bit pointers with 64-bit alignment -- ``p1:32:32:32`` - 32-bit pointers with 32-bit alignment for address - space 1 -- ``p2:16:32:32`` - 16-bit pointers with 32-bit alignment for address - space 2 +- ``S0`` - natural stack alignment is unspecified - ``i1:8:8`` - i1 is 8-bit (byte) aligned - ``i8:8:8`` - i8 is 8-bit (byte) aligned - ``i16:16:16`` - i16 is 16-bit aligned - ``i32:32:32`` - i32 is 32-bit aligned - ``i64:32:64`` - i64 has ABI alignment of 32-bits but preferred alignment of 64-bits +- ``f16:16:16`` - half is 16-bit aligned - ``f32:32:32`` - float is 32-bit aligned - ``f64:64:64`` - double is 64-bit aligned +- ``f128:128:128`` - quad is 128-bit aligned - ``v64:64:64`` - 64-bit vector is 64-bit aligned - ``v128:128:128`` - 128-bit vector is 128-bit aligned -- ``a0:0:1`` - aggregates are 8-bit aligned -- ``s0:64:64`` - stack objects are 64-bit aligned +- ``a0:0:64`` - aggregates are 64-bit aligned When LLVM is determining the alignment for a given type, it uses the following rules: @@ -1061,6 +1129,21 @@ volatile operations. The optimizers *may* change the order of volatile operations relative to non-volatile operations. This is not Java's "volatile" and has no cross-thread synchronization behavior. +IR-level volatile loads and stores cannot safely be optimized into +llvm.memcpy or llvm.memmove intrinsics even when those intrinsics are +flagged volatile. Likewise, the backend should never split or merge +target-legal volatile load/store instructions. + +.. admonition:: Rationale + + Platforms may rely on volatile loads and stores of natively supported + data width to be executed as single instruction. For example, in C + this holds for an l-value of volatile primitive type with native + hardware support, but not necessarily for aggregate types. The + frontend upholds these expectations, which are intentionally + unspecified in the IR. The rules above ensure that IR transformation + do not violate the frontend's contract with the language. + .. _memmodel: Memory Model for Concurrent Operations @@ -1554,7 +1637,7 @@ Examples: +---------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | ``i32 (i32)`` | function taking an ``i32``, returning an ``i32`` | +---------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``float (i16, i32 *) *`` | :ref:`Pointer <t_pointer>` to a function that takes an ``i16`` and a :ref:`pointer <t_pointer>` to ``i32``, returning ``float``. | +| ``float (i16, i32 *) *`` | :ref:`Pointer <t_pointer>` to a function that takes an ``i16`` and a :ref:`pointer <t_pointer>` to ``i32``, returning ``float``. | +---------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | ``i32 (i8*, ...)`` | A vararg function that takes at least one :ref:`pointer <t_pointer>` to ``i8`` (char in C), which returns an integer. This is the signature for ``printf`` in LLVM. | +---------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -1605,7 +1688,7 @@ Examples: +------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | ``{ i32, i32, i32 }`` | A triple of three ``i32`` values | +------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``{ float, i32 (i32) * }`` | A pair, where the first element is a ``float`` and the second element is a :ref:`pointer <t_pointer>` to a :ref:`function <t_function>` that takes an ``i32``, returning an ``i32``. | +| ``{ float, i32 (i32) * }`` | A pair, where the first element is a ``float`` and the second element is a :ref:`pointer <t_pointer>` to a :ref:`function <t_function>` that takes an ``i32``, returning an ``i32``. | +------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | ``<{ i8, i32 }>`` | A packed struct known to be 5 bytes in size. | +------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -1754,7 +1837,7 @@ and disassembly do not cause any bits to change in the constants. When using the hexadecimal form, constants of types half, float, and double are represented using the 16-digit form shown above (which matches the IEEE754 representation for double); half and float values -must, however, be exactly representable as IEE754 half and single +must, however, be exactly representable as IEEE 754 half and single precision, respectively. Hexadecimal format is always used for long double, and there are three forms of long double. The 80-bit format used by x86 is represented as ``0xK`` followed by 20 hexadecimal digits. The @@ -2079,7 +2162,7 @@ Taking the address of the entry block is illegal. This value only has defined behavior when used as an operand to the ':ref:`indirectbr <i_indirectbr>`' instruction, or for comparisons against null. Pointer equality tests between labels addresses results in -undefined behavior — though, again, comparison against null is ok, and +undefined behavior --- though, again, comparison against null is ok, and no label is equal to the null pointer. This may be passed around as an opaque pointer sized value as long as the bits are not inspected. This allows ``ptrtoint`` and arithmetic to be performed on these values so @@ -2444,14 +2527,132 @@ Examples: !2 = metadata !{ i8 0, i8 2, i8 3, i8 6 } !3 = metadata !{ i8 -2, i8 0, i8 3, i8 6 } +'``llvm.loop``' +^^^^^^^^^^^^^^^ + +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``. + +The loop identifier metadata is implemented using a metadata that refers to +itself to avoid merging it with any other identifier metadata, e.g., +during module linkage or function inlining. That is, each loop should refer +to their own identification metadata even if they reside in separate functions. +The following example contains loop identifier metadata for two separate loop +constructs: + +.. code-block:: llvm + + !0 = metadata !{ metadata !0 } + !1 = metadata !{ metadata !1 } + + +'``llvm.loop.parallel``' Metadata +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +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. + +'``llvm.mem``' +^^^^^^^^^^^^^^^ + +Metadata types used to annotate memory accesses with information helpful +for optimizations are prefixed with ``llvm.mem``. + +'``llvm.mem.parallel_loop_access``' Metadata +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +For a loop to be parallel, in addition to using +the ``llvm.loop.parallel`` 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 +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`` +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 + + for.end: + ... + !0 = metadata !{ metadata !0 } + +It is also possible to have nested parallel loops. In that case the +memory accesses refer to a list of loop identifier metadata nodes instead of +the loop identifier metadata node directly: + +.. code-block:: llvm + + outer.for.body: + ... + + 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 + + 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 + + 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 + + Module Flags Metadata ===================== Information about the module as a whole is difficult to convey to LLVM's subsystems. The LLVM IR isn't sufficient to transmit this information. The ``llvm.module.flags`` named metadata exists in order to facilitate -this. These flags are in the form of key / value pairs — much like a -dictionary — making it easy for any subsystem who cares about a flag to +this. These flags are in the form of key / value pairs --- much like a +dictionary --- making it easy for any subsystem who cares about a flag to look it up. The ``llvm.module.flags`` metadata contains a list of metadata triplets. @@ -2462,14 +2663,16 @@ Each triplet has the following form: (or more) metadata with the same ID. The supported behaviors are described below. - The second element is a metadata string that is a unique ID for the - metadata. How each ID is interpreted is documented below. + metadata. Each module may only have one flag entry for each unique ID (not + including entries with the **Require** behavior). - The third element is the value of the flag. When two (or more) modules are merged together, the resulting -``llvm.module.flags`` metadata is the union of the modules' -``llvm.module.flags`` metadata. The only exception being a flag with the -*Override* behavior, which may override another flag's value (see -below). +``llvm.module.flags`` metadata is the union of the modules' flags. That is, for +each unique metadata ID string, there will be exactly one entry in the merged +modules ``llvm.module.flags`` metadata table, and the value for that entry will +be determined by the merge behavior flag, as described below. The only exception +is that entries with the *Require* behavior are always preserved. The following behaviors are supported: @@ -2482,25 +2685,43 @@ The following behaviors are supported: * - 1 - **Error** - Emits an error if two values disagree. It is an error to have an - ID with both an Error and a Warning behavior. + Emits an error if two values disagree, otherwise the resulting value + is that of the operands. * - 2 - **Warning** - Emits a warning if two values disagree. + Emits a warning if two values disagree. The result value will be the + operand for the flag from the first module being linked. * - 3 - **Require** - Emits an error when the specified value is not present or doesn't - have the specified value. It is an error for two (or more) - ``llvm.module.flags`` with the same ID to have the Require behavior - but different values. There may be multiple Require flags per ID. + Adds a requirement that another module flag be present and have a + specified value after linking is performed. The value must be a + metadata pair, where the first element of the pair is the ID of the + module flag to be restricted, and the second element of the pair is + the value the module flag should be restricted to. This behavior can + be used to restrict the allowable results (via triggering of an + error) of linking IDs with the **Override** behavior. * - 4 - **Override** - Uses the specified value if the two values disagree. It is an - error for two (or more) ``llvm.module.flags`` with the same ID - to have the Override behavior but different values. + Uses the specified value, regardless of the behavior or value of the + other module. If both modules specify **Override**, but the values + differ, an error will be emitted. + + * - 5 + - **Append** + Appends the two values, which are required to be metadata nodes. + + * - 6 + - **AppendUnique** + Appends the two values, which are required to be metadata + nodes. However, duplicate entries in the second list are dropped + during the append operation. + +It is an error for a particular unique flag ID to have multiple behaviors, +except in the case of **Require** (which adds restrictions on another metadata +value) or **Override**. An example of module flags: @@ -2522,7 +2743,7 @@ An example of module flags: - Metadata ``!1`` has the ID ``!"bar"`` and the value '37'. The behavior if two or more ``!"bar"`` flags are seen is to use the value - '37' if their values are not equal. + '37'. - Metadata ``!2`` has the ID ``!"qux"`` and the value '42'. The behavior if two or more ``!"qux"`` flags are seen is to emit a @@ -2534,10 +2755,9 @@ An example of module flags: metadata !{ metadata !"foo", i32 1 } - The behavior is to emit an error if the ``llvm.module.flags`` does - not contain a flag with the ID ``!"foo"`` that has the value '1'. If - two or more ``!"qux"`` flags exist, then they must have the same - value or an error will be issued. + The behavior is to emit an error if the ``llvm.module.flags`` does not + contain a flag with the ID ``!"foo"`` that has the value '1' after linking is + performed. Objective-C Garbage Collection Module Flags Metadata ---------------------------------------------------- @@ -2559,26 +2779,26 @@ following key-value pairs: * - Key - Value - * - ``Objective-C Version`` - - **[Required]** — The Objective-C ABI version. Valid values are 1 and 2. + * - ``Objective-C Version`` + - **[Required]** --- The Objective-C ABI version. Valid values are 1 and 2. - * - ``Objective-C Image Info Version`` - - **[Required]** — The version of the image info section. Currently + * - ``Objective-C Image Info Version`` + - **[Required]** --- The version of the image info section. Currently always 0. - * - ``Objective-C Image Info Section`` - - **[Required]** — The section to place the metadata. Valid values are + * - ``Objective-C Image Info Section`` + - **[Required]** --- The section to place the metadata. Valid values are ``"__OBJC, __image_info, regular"`` for Objective-C ABI version 1, and ``"__DATA,__objc_imageinfo, regular, no_dead_strip"`` for Objective-C ABI version 2. - * - ``Objective-C Garbage Collection`` - - **[Required]** — Specifies whether garbage collection is supported or + * - ``Objective-C Garbage Collection`` + - **[Required]** --- Specifies whether garbage collection is supported or not. Valid values are 0, for no garbage collection, and 2, for garbage collection supported. - * - ``Objective-C GC Only`` - - **[Optional]** — Specifies that only garbage collection is supported. + * - ``Objective-C GC Only`` + - **[Optional]** --- Specifies that only garbage collection is supported. If present, its value must be 6. This flag requires that the ``Objective-C Garbage Collection`` flag have the value 2. @@ -2591,6 +2811,40 @@ Some important flag interactions: - A module with ``Objective-C Garbage Collection`` set to 0 cannot be merged with a module with ``Objective-C GC Only`` set to 6. +Automatic Linker Flags Module Flags Metadata +-------------------------------------------- + +Some targets support embedding flags to the linker inside individual object +files. Typically this is used in conjunction with language extensions which +allow source files to explicitly declare the libraries they depend on, and have +these automatically be transmitted to the linker via object files. + +These flags are encoded in the IR using metadata in the module flags section, +using the ``Linker Options`` key. The merge behavior for this flag is required +to be ``AppendUnique``, and the value for the key is expected to be a metadata +node which should be a list of other metadata nodes, each of which should be a +list of metadata strings defining linker options. + +For example, the following metadata section specifies two separate sets of +linker options, presumably to link against ``libz`` and the ``Cocoa`` +framework:: + + !0 = metadata !{ i32 6, metadata !"Linker Options", + metadata !{ + metadata !{ metadata !"-lz" }, + metadata !{ metadata !"-framework", metadata !"Cocoa" } } } + !llvm.module.flags = !{ !0 } + +The metadata encoding as lists of lists of options, as opposed to a collapsed +list of options, is chosen so that the IR encoding can use multiple option +strings to specify e.g., a single library, while still having that specifier be +preserved as an atomic element that can be recognized by a target specific +assembly writer or object file emitter. + +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. + Intrinsic Global Variables ========================== @@ -5777,7 +6031,7 @@ Overview: The '``landingpad``' instruction is used by `LLVM's exception handling system <ExceptionHandling.html#overview>`_ to specify that a basic block -is a landing pad — one where the exception lands, and corresponds to the +is a landing pad --- one where the exception lands, and corresponds to the code found in the ``catch`` portion of a ``try``/``catch`` sequence. It defines values supplied by the personality function (``pers_fn``) upon re-entry to the function. The ``resultval`` has the type ``resultty``. @@ -5789,7 +6043,7 @@ This instruction takes a ``pers_fn`` value. This is the personality function associated with the unwinding mechanism. The optional ``cleanup`` flag indicates that the landing pad block is a cleanup. -A ``clause`` begins with the clause type — ``catch`` or ``filter`` — and +A ``clause`` begins with the clause type --- ``catch`` or ``filter`` --- and contains the global variable representing the "type" that may be caught or filtered respectively. Unlike the ``catch`` clause, the ``filter`` clause takes an array constant as its argument. Use @@ -7388,7 +7642,7 @@ Semantics: """""""""" The '``llvm.sadd.with.overflow``' family of intrinsic functions perform -a signed addition of the two variables. They return a structure — the +a signed addition of the two variables. They return a structure --- the first element of which is the signed summation, and the second element of which is a bit specifying if the signed summation resulted in an overflow. @@ -7438,7 +7692,7 @@ Semantics: """""""""" The '``llvm.uadd.with.overflow``' family of intrinsic functions perform -an unsigned addition of the two arguments. They return a structure — the +an unsigned addition of the two arguments. They return a structure --- the first element of which is the sum, and the second element of which is a bit specifying if the unsigned summation resulted in a carry. @@ -7487,7 +7741,7 @@ Semantics: """""""""" The '``llvm.ssub.with.overflow``' family of intrinsic functions perform -a signed subtraction of the two arguments. They return a structure — the +a signed subtraction of the two arguments. They return a structure --- the first element of which is the subtraction, and the second element of which is a bit specifying if the signed subtraction resulted in an overflow. @@ -7537,7 +7791,7 @@ Semantics: """""""""" The '``llvm.usub.with.overflow``' family of intrinsic functions perform -an unsigned subtraction of the two arguments. They return a structure — +an unsigned subtraction of the two arguments. They return a structure --- the first element of which is the subtraction, and the second element of which is a bit specifying if the unsigned subtraction resulted in an overflow. @@ -7587,7 +7841,7 @@ Semantics: """""""""" The '``llvm.smul.with.overflow``' family of intrinsic functions perform -a signed multiplication of the two arguments. They return a structure — +a signed multiplication of the two arguments. They return a structure --- the first element of which is the multiplication, and the second element of which is a bit specifying if the signed multiplication resulted in an overflow. @@ -7637,8 +7891,8 @@ Semantics: """""""""" The '``llvm.umul.with.overflow``' family of intrinsic functions perform -an unsigned multiplication of the two arguments. They return a structure -— the first element of which is the multiplication, and the second +an unsigned multiplication of the two arguments. They return a structure --- +the first element of which is the multiplication, and the second element of which is a bit specifying if the unsigned multiplication resulted in an overflow. @@ -7670,8 +7924,10 @@ Overview: """"""""" The '``llvm.fmuladd.*``' intrinsic functions represent multiply-add -expressions that can be fused if the code generator determines that the -fused expression would be legal and efficient. +expressions that can be fused if the code generator determines that (a) the +target instruction set has support for a fused operation, and (b) that the +fused operation is more efficient than the equivalent, separate pair of mul +and add instructions. Arguments: """""""""" diff --git a/docs/Lexicon.rst b/docs/Lexicon.rst index cbe1585..11f1341 100644 --- a/docs/Lexicon.rst +++ b/docs/Lexicon.rst @@ -1,5 +1,3 @@ -.. _lexicon: - ================ The LLVM Lexicon ================ @@ -17,6 +15,21 @@ A **ADCE** Aggressive Dead Code Elimination +**AST** + Abstract Syntax Tree. + + Due to Clang's influence (mostly the fact that parsing and semantic + analysis are so intertwined for C and especially C++), the typical + working definition of AST in the LLVM community is roughly "the + compiler's first complete symbolic (as opposed to textual) + representation of an input program". + As such, an "AST" might be a more general graph instead of a "tree" + (consider the symbolic representation for the type of a typical "linked + list node"). This working definition is closer to what some authors + call an "annotated abstract syntax tree". + + Consult your favorite compiler book or search engine for more details. + B - diff --git a/docs/LinkTimeOptimization.rst b/docs/LinkTimeOptimization.rst index 822196c..c15abd3 100644 --- a/docs/LinkTimeOptimization.rst +++ b/docs/LinkTimeOptimization.rst @@ -1,5 +1,3 @@ -.. _lto: - ====================================================== LLVM Link Time Optimization: Design and Implementation ====================================================== diff --git a/docs/MakefileGuide.rst b/docs/MakefileGuide.rst index 4988fe6..3e90907 100644 --- a/docs/MakefileGuide.rst +++ b/docs/MakefileGuide.rst @@ -1,5 +1,3 @@ -.. _makefile_guide: - =================== LLVM Makefile Guide =================== @@ -348,9 +346,9 @@ details. This target should be implemented by the ``Makefile`` in the project's ``test`` directory. It is invoked by the ``check`` target elsewhere. Each project is free to define the actions of ``check-local`` as appropriate for that -project. The LLVM project itself uses dejagnu to run a suite of feature and -regression tests. Other projects may choose to use dejagnu or any other testing -mechanism. +project. The LLVM project itself uses the :doc:`Lit <CommandGuide/lit>` testing +tool to run a suite of feature and regression tests. Other projects may choose +to use :program:`lit` or any other testing mechanism. ``clean`` --------- @@ -701,6 +699,9 @@ The override variables are given below: ``CFLAGS`` Additional flags to be passed to the 'C' compiler. +``CPPFLAGS`` + Additional flags passed to the C/C++ preprocessor. + ``CXX`` Specifies the path to the C++ compiler. diff --git a/docs/MarkedUpDisassembly.rst b/docs/MarkedUpDisassembly.rst index e1282e1..cc4dbc8 100644 --- a/docs/MarkedUpDisassembly.rst +++ b/docs/MarkedUpDisassembly.rst @@ -1,5 +1,3 @@ -.. _marked_up_disassembly: - ======================================= LLVM's Optional Rich Disassembly Output ======================================= diff --git a/docs/Packaging.rst b/docs/Packaging.rst index 6e74158..7c2dc95 100644 --- a/docs/Packaging.rst +++ b/docs/Packaging.rst @@ -1,5 +1,3 @@ -.. _packaging: - ======================== Advice on Packaging LLVM ======================== diff --git a/docs/Phabricator.rst b/docs/Phabricator.rst index b454497..efab10c 100644 --- a/docs/Phabricator.rst +++ b/docs/Phabricator.rst @@ -88,6 +88,12 @@ diffs between different versions of the patch as it was reviewed in the *Revision Update History*. Most features are self descriptive - explore, and if you have a question, drop by on #llvm in IRC to get help. +Note that as e-mail is the system of reference for code reviews, and some +people prefer it over a web interface, we do not generate automated mail +when a review changes state, for example by clicking "Accept Revision" in +the web interface. Thus, please type LGTM into the comment box to accept +a change from Phabricator. + Status ------ diff --git a/docs/ProgrammersManual.rst b/docs/ProgrammersManual.rst index 2b272de..4fc4597 100644 --- a/docs/ProgrammersManual.rst +++ b/docs/ProgrammersManual.rst @@ -6,14 +6,7 @@ LLVM Programmer's Manual :local: .. warning:: - This is a work in progress. - -.. sectionauthor:: Chris Lattner <sabre@nondot.org>, - Dinakar Dhurjati <dhurjati@cs.uiuc.edu>, - Gabor Greif <ggreif@gmail.com>, - Joel Stanley <jstanley@cs.uiuc.edu>, - Reid Spencer <rspencer@x10sys.com> and - Owen Anderson <owen@apple.com> + This is always a work in progress. .. _introduction: @@ -84,8 +77,8 @@ Here are some useful links: (even better, get the book) <http://www.mindview.net/Books/TICPP/ThinkingInCPP2e.html>`_. -You are also encouraged to take a look at the :ref:`LLVM Coding Standards -<coding_standards>` guide which focuses on how to write maintainable code more +You are also encouraged to take a look at the :doc:`LLVM Coding Standards +<CodingStandards>` guide which focuses on how to write maintainable code more than where to put your curly braces. .. _resources: @@ -185,8 +178,8 @@ rarely have to include this file directly). These five templates can be used with any classes, whether they have a v-table or not. If you want to add support for these templates, see the document -:ref:`How to set up LLVM-style RTTI for your class hierarchy -<how-to-set-up-llvm-style-rtti>` +:doc:`How to set up LLVM-style RTTI for your class hierarchy +<HowToSetUpLLVMStyleRTTI>` .. _string_apis: @@ -1059,6 +1052,22 @@ SparseSet is useful for algorithms that need very fast clear/find/insert/erase and fast iteration over small sets. It is not intended for building composite data structures. +.. _dss_sparsemultiset: + +llvm/ADT/SparseMultiSet.h +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +SparseMultiSet adds multiset behavior to SparseSet, while retaining SparseSet's +desirable attributes. Like SparseSet, it typically uses a lot of memory, but +provides operations that are almost as fast as a vector. Typical keys are +physical registers, virtual registers, or numbered basic blocks. + +SparseMultiSet is useful for algorithms that need very fast +clear/find/insert/erase of the entire collection, and iteration over sets of +elements sharing a key. It is often a more efficient choice than using composite +data structures (e.g. vector-of-vectors, map-of-vectors). It is not intended for +building composite data structures. + .. _dss_FoldingSet: llvm/ADT/FoldingSet.h @@ -2256,13 +2265,13 @@ accomplished by the following scheme: A bit-encoding in the 2 LSBits (least significant bits) of the ``Use::Prev`` allows to find the start of the ``User`` object: -* ``00`` –> binary digit 0 +* ``00`` --- binary digit 0 -* ``01`` –> binary digit 1 +* ``01`` --- binary digit 1 -* ``10`` –> stop and calculate (``s``) +* ``10`` --- stop and calculate (``s``) -* ``11`` –> full stop (``S``) +* ``11`` --- full stop (``S``) Given a ``Use*``, all we have to do is to walk till we get a stop and we either have a ``User`` immediately behind or we have to walk to the next stop picking diff --git a/docs/Projects.rst b/docs/Projects.rst index c5d03d3..3246e3f 100644 --- a/docs/Projects.rst +++ b/docs/Projects.rst @@ -1,5 +1,3 @@ -.. _projects: - ======================== Creating an LLVM Project ======================== @@ -153,12 +151,10 @@ Underneath your top level directory, you should have the following directories: Currently, the LLVM build system provides basic support for tests. The LLVM system provides the following: -* LLVM provides a ``tcl`` procedure that is used by ``Dejagnu`` to run tests. - It can be found in ``llvm/lib/llvm-dg.exp``. This test procedure uses ``RUN`` +* LLVM contains regression tests in ``llvm/test``. These tests are run by the + :doc:`Lit <CommandGuide/lit>` testing tool. This test procedure uses ``RUN`` lines in the actual test case to determine how to run the test. See the - :doc:`TestingGuide` for more details. You can easily write Makefile - support similar to the Makefiles in ``llvm/test`` to use ``Dejagnu`` to - run your project's tests. + :doc:`TestingGuide` for more details. * LLVM contains an optional package called ``llvm-test``, which provides benchmarks and programs that are known to compile with the Clang front diff --git a/docs/ReleaseNotes.rst b/docs/ReleaseNotes.rst index 2de4ebb..9383c5b 100644 --- a/docs/ReleaseNotes.rst +++ b/docs/ReleaseNotes.rst @@ -1,27 +1,21 @@ -.. raw:: html - - <style> .red {color:red} </style> - -.. role:: red - ====================== -LLVM 3.2 Release Notes +LLVM 3.3 Release Notes ====================== .. contents:: :local: -Written by the `LLVM Team <http://llvm.org/>`_ +.. 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 + /ReleaseNotes.html>`_. -:red:`These are in-progress notes for the upcoming LLVM 3.2 release. You may -prefer the` `LLVM 3.1 Release Notes <http://llvm.org/releases/3.1/docs -/ReleaseNotes.html>`_. Introduction ============ This document contains the release notes for the LLVM Compiler Infrastructure, -release 3.2. Here we describe the status of LLVM, including major improvements +release 3.3. 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/>`_. @@ -37,504 +31,90 @@ LLVM web page, this document applies to the *next* release, not the current one. To see the release notes for a specific release, please see the `releases page <http://llvm.org/releases/>`_. -Sub-project Status Update -========================= - -The LLVM 3.2 distribution currently consists of code from the core LLVM -repository, which roughly includes the LLVM optimizers, code generators and -supporting tools, and the Clang repository. In addition to this code, the LLVM -Project includes other sub-projects that are in development. Here we include -updates on these subprojects. - -Clang: C/C++/Objective-C Frontend Toolkit ------------------------------------------ - -`Clang <http://clang.llvm.org/>`_ is an LLVM front end for the C, C++, and -Objective-C languages. Clang aims to provide a better user experience through -expressive diagnostics, a high level of conformance to language standards, fast -compilation, and low memory use. Like LLVM, Clang provides a modular, -library-based architecture that makes it suitable for creating or integrating -with other development tools. Clang is considered a production-quality -compiler for C, Objective-C, C++ and Objective-C++ on x86 (32- and 64-bit), and -for Darwin/ARM targets. - -In the LLVM 3.2 time-frame, the Clang team has made many improvements. -Highlights include: - -#. More powerful warnings, especially `-Wuninitialized` -#. Template type diffing in diagnostic messages -#. Higher quality and more efficient debug info generation - -For more details about the changes to Clang since the 3.1 release, see the -`Clang release notes. <http://clang.llvm.org/docs/ReleaseNotes.html>`_ - -If Clang rejects your code but another compiler accepts it, please take a look -at the `language compatibility <http://clang.llvm.org/compatibility.html>`_ -guide to make sure this is not intentional or a known issue. - -DragonEgg: GCC front-ends, LLVM back-end ----------------------------------------- - -`DragonEgg <http://dragonegg.llvm.org/>`_ is a `gcc plugin -<http://gcc.gnu.org/wiki/plugins>`_ that replaces GCC's optimizers and code -generators with LLVM's. It works with gcc-4.5 and gcc-4.6 (and partially with -gcc-4.7), can target the x86-32/x86-64 and ARM processor families, and has been -successfully used on the Darwin, FreeBSD, KFreeBSD, Linux and OpenBSD -platforms. It fully supports Ada, C, C++ and Fortran. It has partial support -for Go, Java, Obj-C and Obj-C++. - -The 3.2 release has the following notable changes: - -#. Able to load LLVM plugins such as Polly. -#. Supports thread-local storage models. -#. Passes knowledge of variable lifetimes to the LLVM optimizers. -#. No longer requires GCC to be built with LTO support. - -compiler-rt: Compiler Runtime Library -------------------------------------- - -The new LLVM `compiler-rt project <http://compiler-rt.llvm.org/>`_ is a simple -library that provides an implementation of the low-level target-specific hooks -required by code generation and other runtime components. For example, when -compiling for a 32-bit target, converting a double to a 64-bit unsigned integer -is compiled into a runtime call to the ``__fixunsdfdi`` function. The -``compiler-rt`` library provides highly optimized implementations of this and -other low-level routines (some are 3x faster than the equivalent libgcc -routines). - -The 3.2 release has the following notable changes: - -#. ... - -LLDB: Low Level Debugger ------------------------- - -`LLDB <http://lldb.llvm.org>`_ is a ground-up implementation of a command line -debugger, as well as a debugger API that can be used from other applications. -LLDB makes use of the Clang parser to provide high-fidelity expression parsing -(particularly for C++) and uses the LLVM JIT for target support. - -The 3.2 release has the following notable changes: - -#. ... - -libc++: C++ Standard Library ----------------------------- +Non-comprehensive list of changes in this release +================================================= -Like compiler_rt, libc++ is now :ref:`dual licensed -<copyright-license-patents>` under the MIT and UIUC license, allowing it to be -used more permissively. +.. NOTE + For small 1-3 sentence descriptions, just add an entry at the end of + this list. If your description won't fit comfortably in one bullet + point (e.g. maybe you would like to give an example of the + functionality, or simply have a lot to talk about), see the `NOTE` below + for adding a new subsection. -Within the LLVM 3.2 time-frame there were the following highlights: +* The CellSPU port has been removed. It can still be found in older versions. -#. ... +* 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. -VMKit ------ +* 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 `VMKit project <http://vmkit.llvm.org/>`_ is an implementation of a Java -Virtual Machine (Java VM or JVM) that uses LLVM for static and just-in-time -compilation. +* 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. -The 3.2 release has the following notable changes: +* We've improved the X86 and ARM cost model. -#. ... +* 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. -Polly: Polyhedral Optimizer ---------------------------- +* ... next change ... -`Polly <http://polly.llvm.org/>`_ is an *experimental* optimizer for data -locality and parallelism. It provides high-level loop optimizations and -automatic parallelisation. +.. NOTE + If you would like to document a larger change, then you can add a + subsection about it right here. You can copy the following boilerplate + and un-indent it (the indentation causes it to be inside this comment). -Within the LLVM 3.2 time-frame there were the following highlights: + Special New Feature + ------------------- -#. isl, the integer set library used by Polly, was relicensed to the MIT license -#. isl based code generation -#. MIT licensed replacement for CLooG (LGPLv2) -#. Fine grained option handling (separation of core and border computations, - control overhead vs. code size) -#. Support for FORTRAN and dragonegg -#. OpenMP code generation fixes + Makes programs 10x faster by doing Special New Thing. -External Open Source Projects Using LLVM 3.2 -============================================ +AArch64 target +-------------- -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.2. +We've added support for AArch64, ARM's 64-bit architecture. Development is still +in fairly early stages, but we expect successful compilation when: -Crack ------ +- 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). -`Crack <http://code.google.com/p/crack-language/>`_ aims to provide the ease of -development of a scripting language with the performance of a compiled -language. The language derives concepts from C++, Java and Python, -incorporating object-oriented programming, operator overloading and strong -typing. +Some additional functionality is also implemented, notably DWARF debugging, +GNU-style thread local storage and inline assembly. -FAUST ------ - -`FAUST <http://faust.grame.fr/>`_ is a compiled language for real-time audio -signal processing. The name FAUST stands for Functional AUdio STream. Its -programming model combines two approaches: functional programming and block -diagram composition. In addition with the C, C++, Java, JavaScript output -formats, the Faust compiler can generate LLVM bitcode, and works with LLVM -2.7-3.1. - -Glasgow Haskell Compiler (GHC) ------------------------------- - -`GHC <http://www.haskell.org/ghc/>`_ is an open source compiler and programming -suite for Haskell, a lazy functional programming language. It includes an -optimizing static compiler generating good code for a variety of platforms, -together with an interactive system for convenient, quick development. - -GHC 7.0 and onwards include an LLVM code generator, supporting LLVM 2.8 and -later. - -Julia ------ - -`Julia <https://github.com/JuliaLang/julia>`_ is a high-level, high-performance -dynamic language for technical computing. It provides a sophisticated -compiler, distributed parallel execution, numerical accuracy, and an extensive -mathematical function library. The compiler uses type inference to generate -fast code without any type declarations, and uses LLVM's optimization passes -and JIT compiler. The `Julia Language <http://julialang.org/>`_ is designed -around multiple dispatch, giving programs a large degree of flexibility. It is -ready for use on many kinds of problems. - -LLVM D Compiler +Loop Vectorizer --------------- -`LLVM D Compiler <https://github.com/ldc-developers/ldc>`_ (LDC) is a compiler -for the D programming Language. It is based on the DMD frontend and uses LLVM -as backend. - -Open Shading Language ---------------------- - -`Open Shading Language (OSL) -<https://github.com/imageworks/OpenShadingLanguage/>`_ is a small but rich -language for programmable shading in advanced global illumination renderers and -other applications, ideal for describing materials, lights, displacement, and -pattern generation. It uses LLVM to JIT complex shader networks to x86 code at -runtime. - -OSL was developed by Sony Pictures Imageworks for use in its in-house renderer -used for feature film animation and visual effects, and is distributed as open -source software with the "New BSD" license. - -Portable OpenCL (pocl) ----------------------- - -In addition to producing an easily portable open source OpenCL implementation, -another major goal of `pocl <http://pocl.sourceforge.net/>`_ is improving -performance portability of OpenCL programs with compiler optimizations, -reducing the need for target-dependent manual optimizations. An important part -of pocl is a set of LLVM passes used to statically parallelize multiple -work-items with the kernel compiler, even in the presence of work-group -barriers. This enables static parallelization of the fine-grained static -concurrency in the work groups in multiple ways (SIMD, VLIW, superscalar, ...). - -Pure ----- - -`Pure <http://pure-lang.googlecode.com/>`_ is an algebraic/functional -programming language based on term rewriting. Programs are collections of -equations which are used to evaluate expressions in a symbolic fashion. The -interpreter uses LLVM as a backend to JIT-compile Pure programs to fast native -code. Pure offers dynamic typing, eager and lazy evaluation, lexical closures, -a hygienic macro system (also based on term rewriting), built-in list and -matrix support (including list and matrix comprehensions) and an easy-to-use -interface to C and other programming languages (including the ability to load -LLVM bitcode modules, and inline C, C++, Fortran and Faust code in Pure -programs if the corresponding LLVM-enabled compilers are installed). - -Pure version 0.54 has been tested and is known to work with LLVM 3.1 (and -continues to work with older LLVM releases >= 2.5). - -TTA-based Co-design Environment (TCE) -------------------------------------- - -`TCE <http://tce.cs.tut.fi/>`_ is a toolset for designing application-specific -processors (ASP) based on the Transport triggered architecture (TTA). The -toolset provides a complete co-design flow from C/C++ programs down to -synthesizable VHDL/Verilog and parallel program binaries. Processor -customization points include the register files, function units, supported -operations, and the interconnection network. - -TCE uses Clang and LLVM for C/C++ language support, target independent -optimizations and also for parts of code generation. It generates new -LLVM-based code generators "on the fly" for the designed TTA processors and -loads them in to the compiler backend as runtime libraries to avoid per-target -recompilation of larger parts of the compiler chain. - -Installation Instructions -========================= - -See :doc:`GettingStarted`. - -What's New in LLVM 3.2? -======================= - -This release includes a huge number of bug fixes, performance tweaks and minor -improvements. Some of the major improvements and new features are listed in -this section. - -Major New Features ------------------- - -.. - - Features that need text if they're finished for 3.2: - ARM EHABI - combiner-aa? - strong phi elim - loop dependence analysis - CorrelatedValuePropagation - Integrated assembler on by default for arm/thumb? - - Near dead: - Analysis/RegionInfo.h + Dom Frontiers - SparseBitVector: used in LiveVar. - llvm/lib/Archive - replace with lib object? - - -LLVM 3.2 includes several major changes and big features: - -#. New NVPTX back-end (replacing existing PTX back-end) based on NVIDIA sources -#. ... - -LLVM IR and Core Improvements ------------------------------ - -LLVM IR has several new features for better support of new targets and that -expose new optimization opportunities: - -#. Thread local variables may have a specified TLS model. See the :ref:`Language - Reference Manual <globalvars>`. -#. ... - -Optimizer Improvements ----------------------- - -In addition to many minor performance tweaks and bug fixes, this release -includes a few major enhancements and additions to the optimizers: - -Loop Vectorizer - We've added a loop vectorizer and we are now able to -vectorize small loops. The loop vectorizer is disabled by default and can be -enabled using the ``-mllvm -vectorize-loops`` flag. The SIMD vector width can -be specified using the flag ``-mllvm -force-vector-width=4``. The default -value is ``0`` which means auto-select. - -We can now vectorize this function: - -.. code-block:: c++ - - unsigned sum_arrays(int *A, int *B, int start, int end) { - unsigned sum = 0; - for (int i = start; i < end; ++i) - sum += A[i] + B[i] + i; - return sum; - } - -We vectorize under the following loops: - -#. The inner most loops must have a single basic block. -#. The number of iterations are known before the loop starts to execute. -#. The loop counter needs to be incremented by one. -#. The loop trip count **can** be a variable. -#. Loops do **not** need to start at zero. -#. The induction variable can be used inside the loop. -#. Loop reductions are supported. -#. Arrays with affine access pattern do **not** need to be marked as - '``noalias``' and are checked at runtime. -#. ... - -SROA - We've re-written SROA to be significantly more powerful and generate -code which is much more friendly to the rest of the optimization pipeline. -Previously this pass had scaling problems that required it to only operate on -relatively small aggregates, and at times it would mistakenly replace a large -aggregate with a single very large integer in order to make it a scalar SSA -value. The result was a large number of i1024 and i2048 values representing any -small stack buffer. These in turn slowed down many subsequent optimization -paths. - -The new SROA pass uses a different algorithm that allows it to only promote to -scalars the pieces of the aggregate actively in use. Because of this it doesn't -require any thresholds. It also always deduces the scalar values from the uses -of the aggregate rather than the specific LLVM type of the aggregate. These -features combine to both optimize more code with the pass but to improve the -compile time of many functions dramatically. - -#. Branch weight metadata is preseved through more of the optimizer. -#. ... - -MC Level Improvements ---------------------- - -The LLVM Machine Code (aka MC) subsystem was created to solve a number of -problems in the realm of assembly, disassembly, object file format handling, -and a number of other related areas that CPU instruction-set level tools work -in. For more information, please see the `Intro to the LLVM MC Project Blog -Post <http://blog.llvm.org/2010/04/intro-to-llvm-mc-project.html>`_. - -#. ... - -.. _codegen: - -Target Independent Code Generator Improvements ----------------------------------------------- - -We have put a significant amount of work into the code generator -infrastructure, which allows us to implement more aggressive algorithms and -make it run faster: - -#. ... - -Stack Coloring - We have implemented a new optimization pass to merge stack -objects which are used in disjoin areas of the code. This optimization reduces -the required stack space significantly, in cases where it is clear to the -optimizer that the stack slot is not shared. We use the lifetime markers to -tell the codegen that a certain alloca is used within a region. - -We now merge consecutive loads and stores. - -X86-32 and X86-64 Target Improvements -------------------------------------- - -New features and major changes in the X86 target include: - -#. ... - -.. _ARM: - -ARM Target Improvements ------------------------ - -New features of the ARM target include: - -#. ... - -.. _armintegratedassembler: - -MIPS Target Improvements ------------------------- - -New features and major changes in the MIPS target include: - -#. ... - -PowerPC Target Improvements ---------------------------- - -Many fixes and changes across LLVM (and Clang) for better compliance with the -64-bit PowerPC ELF Application Binary Interface, interoperability with GCC, and -overall 64-bit PowerPC support. Some highlights include: - -#. MCJIT support added. -#. PPC64 relocation support and (small code model) TOC handling added. -#. Parameter passing and return value fixes (alignment issues, padding, varargs - support, proper register usage, odd-sized structure support, float support, - extension of return values for i32 return values). -#. Fixes in spill and reload code for vector registers. -#. C++ exception handling enabled. -#. Changes to remediate double-rounding compatibility issues with respect to - GCC behavior. -#. Refactoring to disentangle ``ppc64-elf-linux`` ABI from Darwin ppc64 ABI - support. -#. Assorted new test cases and test case fixes (endian and word size issues). -#. Fixes for big-endian codegen bugs, instruction encodings, and instruction - constraints. -#. Implemented ``-integrated-as`` support. -#. Additional support for Altivec compare operations. -#. IBM long double support. - -There have also been code generation improvements for both 32- and 64-bit code. -Instruction scheduling support for the Freescale e500mc and e5500 cores has -been added. - -PTX/NVPTX Target Improvements ------------------------------ - -The PTX back-end has been replaced by the NVPTX back-end, which is based on the -LLVM back-end used by NVIDIA in their CUDA (nvcc) and OpenCL compiler. Some -highlights include: - -#. Compatibility with PTX 3.1 and SM 3.5. -#. Support for NVVM intrinsics as defined in the NVIDIA Compiler SDK. -#. Full compatibility with old PTX back-end, with much greater coverage of LLVM - SIR. - -Please submit any back-end bugs to the LLVM Bugzilla site. - -Other Target Specific Improvements ----------------------------------- - -#. ... - -Major Changes and Removed Features ----------------------------------- - -If you're already an LLVM user or developer with out-of-tree changes based on -LLVM 3.2, this section lists some "gotchas" that you may run into upgrading -from the previous release. - -#. The CellSPU port has been removed. It can still be found in older versions. -#. ... - -Internal API Changes --------------------- - -In addition, many APIs have changed in this release. Some of the major LLVM -API changes are: - -We've added a new interface for allowing IR-level passes to access -target-specific information. A new IR-level pass, called -``TargetTransformInfo`` provides a number of low-level interfaces. LSR and -LowerInvoke already use the new interface. - -The ``TargetData`` structure has been renamed to ``DataLayout`` and moved to -``VMCore`` to remove a dependency on ``Target``. - -#. ... - -Tools Changes -------------- - -In addition, some tools have changed in this release. Some of the changes are: - -#. ... - -Python Bindings ---------------- - -Officially supported Python bindings have been added! Feature support is far -from complete. The current bindings support interfaces to: - -#. ... +We've continued the work on the loop vectorizer. The loop vectorizer now +has the following features: -Known Problems -============== +- 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 -LLVM is generally a production quality compiler, and is used by a broad range -of applications and shipping in many products. That said, not every subsystem -is as mature as the aggregate, particularly the more obscure1 targets. If you -run into a problem, please check the `LLVM bug database -<http://llvm.org/bugs/>`_ and submit a bug if there isn't already one or ask on -the `LLVMdev list <http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev>`_. +R600 Backend +------------ -Known problem areas include: +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. -#. The MSP430 and XCore backends are experimental. -#. The integrated assembler, disassembler, and JIT is not supported by several - targets. If an integrated assembler is not supported, then a system - assembler is required. For more details, see the - :ref:`target-feature-matrix`. Additional Information ====================== diff --git a/docs/SegmentedStacks.rst b/docs/SegmentedStacks.rst index f97d62a..e44ce423 100644 --- a/docs/SegmentedStacks.rst +++ b/docs/SegmentedStacks.rst @@ -1,5 +1,3 @@ -.. _segmented_stacks: - ======================== Segmented Stacks in LLVM ======================== diff --git a/docs/SourceLevelDebugging.rst b/docs/SourceLevelDebugging.rst index 781824c..78ce4e0 100644 --- a/docs/SourceLevelDebugging.rst +++ b/docs/SourceLevelDebugging.rst @@ -2,8 +2,6 @@ Source Level Debugging with LLVM ================================ -.. sectionauthor:: Chris Lattner <sabre@nondot.org> and Jim Laskey <jlaskey@mac.com> - .. contents:: :local: @@ -300,7 +298,6 @@ Subprogram 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) - i32, ;; Line number where the scope of the subprogram begins i32, ;; Virtuality, e.g. dwarf::DW_VIRTUALITY__virtual i32, ;; Index into a virtual function metadata, ;; indicates which base type contains the vtable pointer for the @@ -310,7 +307,8 @@ Subprogram descriptors Function * , ;; Pointer to LLVM function metadata, ;; Lists function template parameters metadata, ;; Function declaration descriptor - metadata ;; List of function variables + metadata, ;; List of function variables + i32 ;; Line number where the scope of the subprogram begins } These descriptors provide debug information about functions, methods and diff --git a/docs/SphinxQuickstartTemplate.rst b/docs/SphinxQuickstartTemplate.rst index b0002ba..8f6d71e 100644 --- a/docs/SphinxQuickstartTemplate.rst +++ b/docs/SphinxQuickstartTemplate.rst @@ -2,8 +2,6 @@ Sphinx Quickstart Template ========================== -.. sectionauthor:: Sean Silva <silvas@purdue.edu> - Introduction and Quickstart =========================== @@ -65,7 +63,7 @@ Your text can be *emphasized*, **bold**, or ``monospace``. Use blank lines to separate paragraphs. -Headings (like ``Example Section`` just above) give your document +Headings (like ``Example Section`` just above) give your document its structure. Use the same kind of adornments (e.g. ``======`` vs. ``------``) as are used in this document. The adornment must be the same length as the text above it. For Vim users, variations of ``yypVr=`` might be handy. @@ -86,7 +84,7 @@ Lists can be made like this: #. This is a second list element. - #. They nest too. + #. Use indentation to create nested lists. You can also use unordered lists. @@ -104,7 +102,7 @@ You can make blocks of code like this: .. code-block:: c++ int main() { - return 0 + return 0; } For a shell session, use a ``console`` code block (some existing docs use diff --git a/docs/SystemLibrary.rst b/docs/SystemLibrary.rst index 88404f4..0d0f4fa 100644 --- a/docs/SystemLibrary.rst +++ b/docs/SystemLibrary.rst @@ -2,8 +2,6 @@ System Library ============== -.. sectionauthor:: Reid Spencer <rspencer@x10sys.com> - Abstract ======== diff --git a/docs/TableGen/LangRef.rst b/docs/TableGen/LangRef.rst index 34098a0..c9e1efb 100644 --- a/docs/TableGen/LangRef.rst +++ b/docs/TableGen/LangRef.rst @@ -74,6 +74,11 @@ TableGen also has two string-like literals: TokString: '"' <non-'"' characters and C-like escapes> '"' TokCodeFragment: "[{" <shortest text not containing "}]"> "}]" +.. note:: + The current implementation accepts the following C-like escapes:: + + \\ \' \" \t \n + TableGen also has the following keywords:: bit bits class code dag @@ -81,11 +86,13 @@ TableGen also has the following keywords:: int let list multiclass string TableGen also has "bang operators" which have a -wide variety of meanings:: +wide variety of meanings: - !eq !if !head !tail !con - !shl !sra !srl - !cast !empty !subst !foreach !strconcat +.. productionlist:: + BangOperator: one of + :!eq !if !head !tail !con + :!add !shl !sra !srl + :!cast !empty !subst !foreach !strconcat Syntax ====== @@ -291,14 +298,14 @@ Bodies .. productionlist:: ObjectBody: `BaseClassList` `Body` - BaseClassList: [`BaseClassListNE`] + BaseClassList: [":" `BaseClassListNE`] BaseClassListNE: `SubClassRef` ("," `SubClassRef`)* - SubClassRef: (`ClassID` | `DefmID`) ["<" `ValueList` ">"] + SubClassRef: (`ClassID` | `MultiClassID`) ["<" `ValueList` ">"] DefmID: `TokIdentifier` -The version with the :token:`DefmID` is only valid in the +The version with the :token:`MultiClassID` is only valid in the :token:`BaseClassList` of a ``defm``. -The :token:`DefmID` should be the name of a ``multiclass``. +The :token:`MultiClassID` should be the name of a ``multiclass``. .. put this somewhere else @@ -336,7 +343,7 @@ a ``foreach``. -------- .. productionlist:: - Defm: "defm" `TokIdentifier` ":" `BaseClassList` ";" + Defm: "defm" `TokIdentifier` ":" `BaseClassListNE` ";" Note that in the :token:`BaseClassList`, all of the ``multiclass``'s must precede any ``class``'s that appear. @@ -370,6 +377,7 @@ applied at the end of parsing the base classes of a record. .. productionlist:: MultiClass: "multiclass" `TokIdentifier` [`TemplateArgList`] - : [":" `BaseMultiClassList`] "{" `MultiClassDef`+ "}" + : [":" `BaseMultiClassList`] "{" `MultiClassObject`+ "}" BaseMultiClassList: `MultiClassID` ("," `MultiClassID`)* MultiClassID: `TokIdentifier` + MultiClassObject: `Def` | `Defm` | `Let` | `Foreach` diff --git a/docs/TableGenFundamentals.rst b/docs/TableGenFundamentals.rst index 73bcd66..4fe4bb9 100644 --- a/docs/TableGenFundamentals.rst +++ b/docs/TableGenFundamentals.rst @@ -1,5 +1,3 @@ -.. _tablegen: - ===================== TableGen Fundamentals ===================== @@ -793,6 +791,10 @@ Expressions used by code generator to describe instructions and isel patterns: TableGen backends ================= +Until we get a step-by-step HowTo for writing TableGen backends, you can at +least grab the boilerplate (build system, new files, etc.) from Clang's +r173931. + TODO: How they work, how to write one. This section should not contain details about any particular backend, except maybe ``-print-enums`` as an example. This should highlight the APIs in ``TableGen/Record.h``. diff --git a/docs/TestSuiteMakefileGuide.rst b/docs/TestSuiteMakefileGuide.rst index b10379e..e2852a0 100644 --- a/docs/TestSuiteMakefileGuide.rst +++ b/docs/TestSuiteMakefileGuide.rst @@ -2,9 +2,6 @@ LLVM test-suite Makefile Guide ============================== -Written by John T. Criswell, Daniel Dunbar, Reid Spencer, and Tanya -Lattner - .. contents:: :local: diff --git a/docs/TestingGuide.rst b/docs/TestingGuide.rst index f26d1bf..4d8c8ce 100644 --- a/docs/TestingGuide.rst +++ b/docs/TestingGuide.rst @@ -2,9 +2,6 @@ LLVM Testing Infrastructure Guide ================================= -Written by John T. Criswell, Daniel Dunbar, Reid Spencer, and Tanya -Lattner - .. contents:: :local: @@ -234,33 +231,21 @@ 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 | grep`` with ``... |& grep`` + ``... 2>&1 | FileCheck`` with ``... |& FileCheck`` - You can only redirect to a file, not to another descriptor and not from a here document. 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 strip off any quote characters so they will get passed to the invoked program. -For example: - -.. code-block:: bash - - ... | grep 'find this string' - -This will fail because the ``'`` characters are passed to ``grep``. This would -make ``grep`` to look for ``'find`` in the files ``this`` and -``string'``. To avoid this use curly braces to tell :program:`lit` that it -should treat everything enclosed as one value. So our example would become: - -.. code-block:: bash - - ... | grep {find this string} +To avoid this use curly braces to tell :program:`lit` that it should treat +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 the output you can then examine. The -recommended way to examine output to figure out if the test passes it using the -:doc:`FileCheck tool <CommandGuide/FileCheck>`. The usage of ``grep`` in RUN -lines is discouraged. +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 :doc:`FileCheck tool <CommandGuide/FileCheck>`. *[The usage of grep in RUN +lines is deprecated - please do not send or commit patches that use it.]* Fragile tests ------------- @@ -299,24 +284,6 @@ 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. -The FileCheck utility ---------------------- - -A powerful feature of the RUN lines is that it allows any arbitrary -commands to be executed as part of the test harness. While standard -(portable) unix tools like ``grep`` work fine on run lines, as you see -above, there are a lot of caveats due to interaction with shell syntax, -and we want to make sure the run lines are portable to a wide range of -systems. Another major problem is that ``grep`` is not very good at checking -to verify that the output of a tools contains a series of different -output in a specific order. The :program:`FileCheck` tool was designed to -help with these problems. - -:program:`FileCheck` is designed to read a file to check from standard input, -and the set of things to verify from a file specified as a command line -argument. :program:`FileCheck` is described in :doc:`the FileCheck man page -<CommandGuide/FileCheck>`. - Variables and substitutions --------------------------- diff --git a/docs/Vectorizers.rst b/docs/Vectorizers.rst index 0748634..0894b1e 100644 --- a/docs/Vectorizers.rst +++ b/docs/Vectorizers.rst @@ -206,6 +206,25 @@ vectorization is profitable. A[i] += 4 * B[i]; } +Global Structures Alias Analysis +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Access to global structures can also be vectorized, with alias analysis being +used to make sure accesses don't alias. Run-time checks can also be added on +pointer access to structure members. + +Many variations are supported, but some that rely on undefined behaviour being +ignored (as other compilers do) are still being left un-vectorized. + +.. code-block:: c++ + + struct { int A[100], K, B[100]; } Foo; + + int foo() { + for (int i = 0; i < 100; ++i) + Foo.A[i] = Foo.B[i] + 100; + } + Vectorization of function calls ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/WritingAnLLVMBackend.rst b/docs/WritingAnLLVMBackend.rst index 868ca20..6d6c2a1 100644 --- a/docs/WritingAnLLVMBackend.rst +++ b/docs/WritingAnLLVMBackend.rst @@ -7,8 +7,6 @@ Writing an LLVM Compiler Backend HowToUseInstrMappings -.. sectionauthor:: Mason Woo <http://www.woo.com> and Misha Brukman <http://misha.brukman.net> - .. contents:: :local: diff --git a/docs/WritingAnLLVMPass.rst b/docs/WritingAnLLVMPass.rst index db47fef..b10d98f 100644 --- a/docs/WritingAnLLVMPass.rst +++ b/docs/WritingAnLLVMPass.rst @@ -5,9 +5,6 @@ Writing an LLVM Pass .. contents:: :local: -Written by `Chris Lattner <mailto:sabre@nondot.org>`_ and -`Jim Laskey <mailto:jlaskey@mac.com>`_ - Introduction --- What is a pass? ================================ diff --git a/docs/YamlIO.rst b/docs/YamlIO.rst index b009b67..ac50292 100644 --- a/docs/YamlIO.rst +++ b/docs/YamlIO.rst @@ -1,5 +1,3 @@ -.. _yamlio: - ===================== YAML I/O ===================== @@ -87,13 +85,13 @@ locations, making it hard for a human to write such YAML correctly. In relational database theory there is a design step called normalization in which you reorganize fields and tables. The same considerations need to go into the design of your YAML encoding. But, you may not want to change -your exisiting native data structures. Therefore, when writing out YAML +your existing native data structures. Therefore, when writing out YAML there may be a normalization step, and when reading YAML there would be a corresponding denormalization step. YAML I/O uses a non-invasive, traits based design. YAML I/O defines some abstract base templates. You specialize those templates on your data types. -For instance, if you have an eumerated type FooBar you could specialize +For instance, if you have an enumerated type FooBar you could specialize ScalarEnumerationTraits on that type and define the enumeration() method: .. code-block:: c++ @@ -115,17 +113,17 @@ values and the YAML string representation is only in 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 -llvm::yaml::MapppingTraits. +llvm::yaml::MappingTraits. If your native data structure happens to be a struct that is already normalized, then the specialization is simple. For example: .. code-block:: c++ - using llvm::yaml::MapppingTraits; + using llvm::yaml::MappingTraits; using llvm::yaml::IO; template <> - struct MapppingTraits<Person> { + struct MappingTraits<Person> { static void mapping(IO &io, Person &info) { io.mapRequired("name", info.name); io.mapOptional("hat-size", info.hatSize); @@ -133,7 +131,7 @@ then the specialization is simple. For example: }; -A YAML sequence is automatically infered if you data type has begin()/end() +A YAML sequence is automatically inferred if you data type has begin()/end() iterators and a push_back() method. Therefore any of the STL containers (such as std::vector<>) will automatically translate to YAML sequences. @@ -245,7 +243,7 @@ The following types have built-in support in YAML I/O: * uint16_t * uint8_t -That is, you can use those types in fields of MapppingTraits or as element type +That is, you can use those types in fields of MappingTraits or as element type in sequence. When reading, YAML I/O will validate that the string found is convertible to that type and error out if not. @@ -313,7 +311,7 @@ as a field type: .. code-block:: c++ using llvm::yaml::ScalarEnumerationTraits; - using llvm::yaml::MapppingTraits; + using llvm::yaml::MappingTraits; using llvm::yaml::IO; template <> @@ -326,7 +324,7 @@ as a field type: }; template <> - struct MapppingTraits<Info> { + struct MappingTraits<Info> { static void mapping(IO &io, Info &info) { io.mapRequired("cpu", info.cpu); io.mapOptional("flags", info.flags, 0); @@ -363,7 +361,7 @@ on MyFlags and provide the bit values and their names. .. code-block:: c++ using llvm::yaml::ScalarBitSetTraits; - using llvm::yaml::MapppingTraits; + using llvm::yaml::MappingTraits; using llvm::yaml::IO; template <> @@ -382,7 +380,7 @@ on MyFlags and provide the bit values and their names. }; template <> - struct MapppingTraits<Info> { + struct MappingTraits<Info> { static void mapping(IO &io, Info& info) { io.mapRequired("name", info.name); io.mapRequired("flags", info.flags); @@ -436,18 +434,18 @@ Mappings ======== To be translated to or from a YAML mapping for your type T you must specialize -llvm::yaml::MapppingTraits on T and implement the "void mapping(IO &io, T&)" +llvm::yaml::MappingTraits on T and implement the "void mapping(IO &io, T&)" method. If your native data structures use pointers to a class everywhere, you can specialize on the class pointer. Examples: .. code-block:: c++ - using llvm::yaml::MapppingTraits; + using llvm::yaml::MappingTraits; using llvm::yaml::IO; // Example of struct Foo which is used by value template <> - struct MapppingTraits<Foo> { + struct MappingTraits<Foo> { static void mapping(IO &io, Foo &foo) { io.mapOptional("size", foo.size); ... @@ -456,7 +454,7 @@ you can specialize on the class pointer. Examples: // Example of struct Bar which is natively always a pointer template <> - struct MapppingTraits<Bar*> { + struct MappingTraits<Bar*> { static void mapping(IO &io, Bar *&bar) { io.mapOptional("size", bar->size); ... @@ -474,11 +472,11 @@ bind the struct's fields to YAML key names. For example: .. code-block:: c++ - using llvm::yaml::MapppingTraits; + using llvm::yaml::MappingTraits; using llvm::yaml::IO; template <> - struct MapppingTraits<Person> { + struct MappingTraits<Person> { static void mapping(IO &io, Person &info) { io.mapRequired("name", info.name); io.mapOptional("hat-size", info.hatSize); @@ -513,17 +511,17 @@ is, you want the yaml to look like: x: 10.3 y: -4.7 -You can support this by defining a MapppingTraits that normalizes the polar +You can support this by defining a MappingTraits that normalizes the polar coordinates to x,y coordinates when writing YAML and denormalizes x,y -coordindates into polar when reading YAML. +coordinates into polar when reading YAML. .. code-block:: c++ - using llvm::yaml::MapppingTraits; + using llvm::yaml::MappingTraits; using llvm::yaml::IO; template <> - struct MapppingTraits<Polar> { + struct MappingTraits<Polar> { class NormalizedPolar { public: @@ -568,7 +566,7 @@ could be returned by the denormalize() method, except that the temporary normalized instance is stack allocated. In these cases, the utility template MappingNormalizationHeap<> can be used instead. It just like MappingNormalization<> except that it heap allocates the normalized object -when reading YAML. It never destroyes the normalized object. The denormalize() +when reading YAML. It never destroys the normalized object. The denormalize() method can this return "this". @@ -614,7 +612,7 @@ This works for both reading and writing. For example: .. code-block:: c++ - using llvm::yaml::MapppingTraits; + using llvm::yaml::MappingTraits; using llvm::yaml::IO; struct Info { @@ -623,7 +621,7 @@ This works for both reading and writing. For example: }; template <> - struct MapppingTraits<Info> { + struct MappingTraits<Info> { static void mapping(IO &io, Info &info) { io.mapRequired("cpu", info.cpu); // flags must come after cpu for this to work when reading yaml @@ -640,8 +638,8 @@ Sequence To be translated to or from a YAML sequence for your type T you must specialize llvm::yaml::SequenceTraits on T and implement two methods: -“size_t size(IO &io, T&)” and “T::value_type& element(IO &io, T&, size_t indx)”. -For example: +``size_t size(IO &io, T&)`` and +``T::value_type& element(IO &io, T&, size_t indx)``. For example: .. code-block:: c++ @@ -678,13 +676,13 @@ add "static const bool flow = true;". For instance: }; With the above, if you used MyList as the data type in your native data -strucutures, then then when converted to YAML, a flow sequence of integers +structures, then then when converted to YAML, a flow sequence of integers will be used (e.g. [ 10, -3, 4 ]). Utility Macros -------------- -Since a common source of sequences is std::vector<>, YAML I/O provids macros: +Since a common source of sequences is std::vector<>, YAML I/O provides macros: LLVM_YAML_IS_SEQUENCE_VECTOR() and LLVM_YAML_IS_FLOW_SEQUENCE_VECTOR() which can be used to easily specify SequenceTraits<> on a std::vector type. YAML I/O does not partial specialize SequenceTraits on std::vector<> because that diff --git a/docs/design_and_overview.rst b/docs/design_and_overview.rst deleted file mode 100644 index 4b1d627..0000000 --- a/docs/design_and_overview.rst +++ /dev/null @@ -1,37 +0,0 @@ -.. _design_and_overview: - -LLVM Design & Overview -====================== - -.. toctree:: - :hidden: - - LangRef - GetElementPtr - -* :doc:`LangRef` - - Defines the LLVM intermediate representation. - -* `Introduction to the LLVM Compiler <http://llvm.org/pubs/2008-10-04-ACAT-LLVM-Intro.html>`_ - - Presentation providing a users introduction to LLVM. - -* `Intro to LLVM <http://www.aosabook.org/en/llvm.html>`_ - - Book chapter providing a compiler hacker's introduction to LLVM. - -* `LLVM: A Compilation Framework for Lifelong Program Analysis & Transformation - <http://llvm.org/pubs/2004-01-30-CGO-LLVM.html>`_ - - Design overview. - -* `LLVM: An Infrastructure for Multi-Stage Optimization - <http://llvm.org/pubs/2002-12-LattnerMSThesis.html>`_ - - More details (quite old now). - -* :ref:`gep` - - Answers to some very frequent questions about LLVM's most frequently - misunderstood instruction. diff --git a/docs/development_process.rst b/docs/development_process.rst deleted file mode 100644 index ecd4c6a..0000000 --- a/docs/development_process.rst +++ /dev/null @@ -1,32 +0,0 @@ -.. _development_process: - -Development Process Documentation -================================= - -.. toctree:: - :hidden: - - MakefileGuide - Projects - LLVMBuild - HowToReleaseLLVM - -* :ref:`projects` - - How-to guide and templates for new projects that *use* the LLVM - infrastructure. The templates (directory organization, Makefiles, and test - tree) allow the project code to be located outside (or inside) the ``llvm/`` - tree, while using LLVM header files and libraries. - -* :doc:`LLVMBuild` - - Describes the LLVMBuild organization and files used by LLVM to specify - component descriptions. - -* :ref:`makefile_guide` - - Describes how the LLVM makefiles work and how to use them. - -* :doc:`HowToReleaseLLVM` - - This is a guide to preparing LLVM releases. Most developers can ignore it. diff --git a/docs/gcc-loops.png b/docs/gcc-loops.png Binary files differindex 6606bfd..8923a31 100644 --- a/docs/gcc-loops.png +++ b/docs/gcc-loops.png diff --git a/docs/index.rst b/docs/index.rst index d406b52..8f22ef2 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,5 +1,3 @@ -.. _contents: - Overview ======== @@ -15,54 +13,382 @@ research projects. Similarly, documentation is broken down into several high-level groupings targeted at different audiences: -* **Design & Overview** +LLVM Design & Overview +====================== + +Several introductory papers and presentations. + +.. toctree:: + :hidden: + + LangRef + GetElementPtr + +:doc:`LangRef` + Defines the LLVM intermediate representation. + +`Introduction to the LLVM Compiler`__ + Presentation providing a users introduction to LLVM. + + .. __: http://llvm.org/pubs/2008-10-04-ACAT-LLVM-Intro.html + +`Intro to LLVM`__ + Book chapter providing a compiler hacker's introduction to LLVM. + + .. __: http://www.aosabook.org/en/llvm.html + + +`LLVM: A Compilation Framework for Lifelong Program Analysis & Transformation`__ + Design overview. + + .. __: http://llvm.org/pubs/2004-01-30-CGO-LLVM.html + +`LLVM: An Infrastructure for Multi-Stage Optimization`__ + More details (quite old now). + + .. __: 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>`_ + .. + +User Guides +=========== + +For those new to the LLVM system. + +NOTE: If you are a user who is only interested in using LLVM-based +compilers, you should look into `Clang <http://clang.llvm.org>`_ or +`DragonEgg <http://dragonegg.llvm.org>`_ instead. The documentation here is +intended for users who have a need to work with the intermediate LLVM +representation. + +.. toctree:: + :hidden: + + CMake + HowToBuildOnARM + CommandGuide/index + DeveloperPolicy + GettingStarted + GettingStartedVS + FAQ + Lexicon + HowToAddABuilder + yaml2obj + HowToSubmitABug + SphinxQuickstartTemplate + Phabricator + TestingGuide + tutorial/index + ReleaseNotes + Passes + YamlIO + +:doc:`GettingStarted` + Discusses how to get up and running quickly with the LLVM infrastructure. + Everything from unpacking and compilation of the distribution to execution + of some tools. + +:doc:`CMake` + An addendum to the main Getting Started guide for those using the `CMake + build system <http://www.cmake.org>`_. + +:doc:`HowToBuildOnARM` + Notes on building and testing LLVM/Clang on ARM. + +:doc:`GettingStartedVS` + An addendum to the main Getting Started guide for those using Visual Studio + on Windows. + +:doc:`tutorial/index` + 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). + +:doc:`Passes` + A list of optimizations and analyses implemented in LLVM. + +:doc:`FAQ` + A list of common questions and problems and their solutions. + +:doc:`Release notes for the current release <ReleaseNotes>` + This describes new features, known bugs, and other limitations. + +:doc:`HowToSubmitABug` + Instructions for properly submitting information about any bugs you run into + in the LLVM system. + +:doc:`SphinxQuickstartTemplate` + A template + tutorial for writing new Sphinx documentation. It is meant + to be read in source form. + +:doc:`LLVM Testing Infrastructure Guide <TestingGuide>` + A reference manual for using the LLVM testing infrastructure. + +`How to build the C, C++, ObjC, and ObjC++ front end`__ + Instructions for building the clang front-end from source. + + .. __: http://clang.llvm.org/get_started.html + +:doc:`Lexicon` + Definition of acronyms, terms and concepts used in LLVM. + +:doc:`HowToAddABuilder` + Instructions for adding new builder to LLVM buildbot master. + +: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> - Several introductory papers and presentations are available at - :ref:`design_and_overview`. +* clang-bot - A `geordi <http://www.eelis.net/geordi/>`_ instance running + near-trunk clang instead of gcc. -* **Publications** +Programming Documentation +========================= - The list of `publications <http://llvm.org/pubs>`_ based on LLVM. +For developers of applications which use LLVM as a library. -* **User Guides** +.. toctree:: + :hidden: + + Atomics + CodingStandards + CommandLine + CompilerWriterInfo + ExtendingLLVM + HowToSetUpLLVMStyleRTTI + ProgrammersManual + +:doc:`LLVM Language Reference Manual <LangRef>` + Defines the LLVM intermediate representation and the assembly form of the + different nodes. - Those new to the LLVM system should first visit the :ref:`userguides`. +:doc:`Atomics` + Information about LLVM's concurrency model. - NOTE: If you are a user who is only interested in using LLVM-based - compilers, you should look into `Clang <http://clang.llvm.org>`_ or - `DragonEgg <http://dragonegg.llvm.org>`_ instead. The documentation here is - intended for users who have a need to work with the intermediate LLVM - representation. +:doc:`ProgrammersManual` + Introduction to the general layout of the LLVM sourcebase, important classes + and APIs, and some tips & tricks. -* **API Clients** +:doc:`CommandLine` + Provides information on using the command line parsing library. - Developers of applications which use LLVM as a library should visit the - :ref:`programming`. +:doc:`CodingStandards` + Details the LLVM coding standards and provides useful information on writing + efficient C++ code. -* **Subsystems** +:doc:`HowToSetUpLLVMStyleRTTI` + How to make ``isa<>``, ``dyn_cast<>``, etc. available for clients of your + class hierarchy. - API clients and LLVM developers may be interested in the - :ref:`subsystems` documentation. +:doc:`ExtendingLLVM` + Look here to see how to add instructions and intrinsics to LLVM. -* **Development Process** +`Doxygen generated documentation <http://llvm.org/doxygen/>`_ + (`classes <http://llvm.org/doxygen/inherits.html>`_) + (`tarball <http://llvm.org/doxygen/doxygen.tar.gz>`_) - Additional documentation on the LLVM project can be found at - :ref:`development_process`. +`ViewVC Repository Browser <http://llvm.org/viewvc/>`_ + .. -* **Mailing Lists** +:doc:`CompilerWriterInfo` + A list of helpful links for compiler writers. - For more information, consider consulting the LLVM :ref:`mailing_lists`. +Subsystem Documentation +======================= + +For API clients and LLVM developers. .. toctree:: - :maxdepth: 2 - - design_and_overview - userguides - programming - subsystems - development_process - mailing_lists - + :hidden: + + AliasAnalysis + BitCodeFormat + BranchWeightMetadata + Bugpoint + CodeGenerator + ExceptionHandling + LinkTimeOptimization + SegmentedStacks + TableGenFundamentals + DebuggingJITedCode + GoldPlugin + MarkedUpDisassembly + SystemLibrary + SourceLevelDebugging + Vectorizers + WritingAnLLVMBackend + GarbageCollection + WritingAnLLVMPass + TableGen/LangRef + HowToUseAttributes + +:doc:`WritingAnLLVMPass` + Information on how to write LLVM transformations and analyses. + +:doc:`WritingAnLLVMBackend` + Information on how to write LLVM backends for machine targets. + +:doc:`CodeGenerator` + The design and implementation of the LLVM code generator. Useful if you are + working on retargetting LLVM to a new architecture, designing a new codegen + pass, or enhancing existing components. + +:doc:`TableGenFundamentals` + Describes the TableGen tool, which is used heavily by the LLVM code + generator. + +:doc:`AliasAnalysis` + Information on how to write a new alias analysis implementation or how to + use existing analyses. + +:doc:`GarbageCollection` + The interfaces source-language compilers should use for compiling GC'd + programs. + +:doc:`Source Level Debugging with LLVM <SourceLevelDebugging>` + This document describes the design and philosophy behind the LLVM + source-level debugger. + +:doc:`Vectorizers` + This document describes the current status of vectorization in LLVM. + +:doc:`ExceptionHandling` + This document describes the design and implementation of exception handling + in LLVM. + +:doc:`Bugpoint` + Automatic bug finder and test-case reducer description and usage + information. + +:doc:`BitCodeFormat` + This describes the file format and encoding used for LLVM "bc" files. + +:doc:`System Library <SystemLibrary>` + This document describes the LLVM System Library (``lib/System``) and + how to keep LLVM source code portable + +:doc:`LinkTimeOptimization` + This document describes the interface between LLVM intermodular optimizer + and the linker and its design + +:doc:`GoldPlugin` + How to build your programs with link-time optimization on Linux. + +:doc:`DebuggingJITedCode` + How to debug JITed code with GDB. + +:doc:`BranchWeightMetadata` + Provides information about Branch Prediction Information. + +:doc:`SegmentedStacks` + This document describes segmented stacks and how they are used in LLVM. + +:doc:`MarkedUpDisassembly` + This document describes the optional rich disassembly output syntax. + +:doc:`HowToUseAttributes` + Answers some questions about the new Attributes infrastructure. + +Development Process Documentation +================================= + +Information about LLVM's development process. + +.. toctree:: + :hidden: + + MakefileGuide + Projects + LLVMBuild + HowToReleaseLLVM + Packaging + +:doc:`Projects` + How-to guide and templates for new projects that *use* the LLVM + infrastructure. The templates (directory organization, Makefiles, and test + tree) allow the project code to be located outside (or inside) the ``llvm/`` + tree, while using LLVM header files and libraries. + +:doc:`LLVMBuild` + Describes the LLVMBuild organization and files used by LLVM to specify + component descriptions. + +:doc:`MakefileGuide` + Describes how the LLVM makefiles work and how to use them. + +:doc:`HowToReleaseLLVM` + This is a guide to preparing LLVM releases. Most developers can ignore it. + +:doc:`Packaging` + Advice on packaging LLVM into a distribution. + +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`__ + 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`__ + 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. + + .. __: http://lists.cs.uiuc.edu/pipermail/llvm-commits/ + +`Test Results Archive`__ + A message is automatically sent to this list by every active nightly tester + when it completes. As such, this list gets email several times each day, + making it a high volume list. + + .. __: http://lists.cs.uiuc.edu/pipermail/llvm-testresults/ + Indices and tables ================== diff --git a/docs/linpack-pc.png b/docs/linpack-pc.png Binary files differindex 4294892..bbbee7d 100644 --- a/docs/linpack-pc.png +++ b/docs/linpack-pc.png diff --git a/docs/mailing_lists.rst b/docs/mailing_lists.rst deleted file mode 100644 index 106f1da..0000000 --- a/docs/mailing_lists.rst +++ /dev/null @@ -1,35 +0,0 @@ -.. _mailing_lists: - -Mailing Lists -============= - - * `LLVM Announcements List - <http://lists.cs.uiuc.edu/mailman/listinfo/llvm-announce>`_ - - This is a low volume list that provides important announcements regarding - LLVM. It gets email about once a month. - - * `Developer's List <http://lists.cs.uiuc.edu/mailman/listinfo/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. - - * `Bugs & Patches Archive <http://lists.cs.uiuc.edu/pipermail/llvmbugs/>`_ - - 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. - - * `Commits Archive <http://lists.cs.uiuc.edu/pipermail/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. - - * `Test Results Archive - <http://lists.cs.uiuc.edu/pipermail/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. diff --git a/docs/programming.rst b/docs/programming.rst deleted file mode 100644 index 3fea6ed..0000000 --- a/docs/programming.rst +++ /dev/null @@ -1,58 +0,0 @@ -.. _programming: - -Programming Documentation -========================= - -.. toctree:: - :hidden: - - Atomics - CodingStandards - CommandLine - CompilerWriterInfo - ExtendingLLVM - HowToSetUpLLVMStyleRTTI - ProgrammersManual - -* `LLVM Language Reference Manual <LangRef.html>`_ - - Defines the LLVM intermediate representation and the assembly form of the - different nodes. - -* :ref:`atomics` - - Information about LLVM's concurrency model. - -* :doc:`ProgrammersManual` - - Introduction to the general layout of the LLVM sourcebase, important classes - and APIs, and some tips & tricks. - -* :ref:`commandline` - - Provides information on using the command line parsing library. - -* :ref:`coding_standards` - - Details the LLVM coding standards and provides useful information on writing - efficient C++ code. - -* :doc:`HowToSetUpLLVMStyleRTTI` - - How to make ``isa<>``, ``dyn_cast<>``, etc. available for clients of your - class hierarchy. - -* :ref:`extending_llvm` - - Look here to see how to add instructions and intrinsics to LLVM. - -* `Doxygen generated documentation <http://llvm.org/doxygen/>`_ - - (`classes <http://llvm.org/doxygen/inherits.html>`_) - (`tarball <http://llvm.org/doxygen/doxygen.tar.gz>`_) - -* `ViewVC Repository Browser <http://llvm.org/viewvc/>`_ - -* :ref:`compiler_writer_info` - - A list of helpful links for compiler writers. diff --git a/docs/subsystems.rst b/docs/subsystems.rst deleted file mode 100644 index 505c573..0000000 --- a/docs/subsystems.rst +++ /dev/null @@ -1,110 +0,0 @@ -.. _subsystems: - -Subsystem Documentation -======================= - -.. toctree:: - :hidden: - - AliasAnalysis - BitCodeFormat - BranchWeightMetadata - Bugpoint - CodeGenerator - ExceptionHandling - LinkTimeOptimization - SegmentedStacks - TableGenFundamentals - DebuggingJITedCode - GoldPlugin - MarkedUpDisassembly - SystemLibrary - SourceLevelDebugging - Vectorizers - WritingAnLLVMBackend - GarbageCollection - WritingAnLLVMPass - TableGen/LangRef - -* :doc:`WritingAnLLVMPass` - - Information on how to write LLVM transformations and analyses. - -* :doc:`WritingAnLLVMBackend` - - Information on how to write LLVM backends for machine targets. - -* :ref:`code_generator` - - The design and implementation of the LLVM code generator. Useful if you are - working on retargetting LLVM to a new architecture, designing a new codegen - pass, or enhancing existing components. - -* :ref:`tablegen` - - Describes the TableGen tool, which is used heavily by the LLVM code - generator. - -* :ref:`alias_analysis` - - Information on how to write a new alias analysis implementation or how to - use existing analyses. - -* :doc:`GarbageCollection` - - The interfaces source-language compilers should use for compiling GC'd - programs. - -* :doc:`Source Level Debugging with LLVM <SourceLevelDebugging>` - - This document describes the design and philosophy behind the LLVM - source-level debugger. - -* :doc:`Vectorizers` - - This document describes the current status of vectorization in LLVM. - -* :ref:`exception_handling` - - This document describes the design and implementation of exception handling - in LLVM. - -* :ref:`bugpoint` - - Automatic bug finder and test-case reducer description and usage - information. - -* :ref:`bitcode_format` - - This describes the file format and encoding used for LLVM "bc" files. - -* :doc:`System Library <SystemLibrary>` - - This document describes the LLVM System Library (``lib/System``) and - how to keep LLVM source code portable - -* :ref:`lto` - - This document describes the interface between LLVM intermodular optimizer - and the linker and its design - -* :ref:`gold-plugin` - - How to build your programs with link-time optimization on Linux. - -* :ref:`debugging-jited-code` - - How to debug JITed code with GDB. - -* :ref:`branch_weight` - - Provides information about Branch Prediction Information. - -* :ref:`segmented_stacks` - - This document describes segmented stacks and how they are used in LLVM. - -* :ref:`marked_up_disassembly` - - This document describes the optional rich disassembly output syntax. - diff --git a/docs/tutorial/index.rst b/docs/tutorial/index.rst index a7e2c4f..69a9aee 100644 --- a/docs/tutorial/index.rst +++ b/docs/tutorial/index.rst @@ -25,7 +25,7 @@ Kaleidoscope: Implementing a Language with LLVM in Objective Caml External Tutorials ================== -`Write An LLVM Backend Tutorial For Cpu0 <http://jonathan2251.github.com/lbd/>`_ +`Tutorial: Creating an LLVM Backend for the Cpu0 Architecture <http://jonathan2251.github.com/lbd/>`_ A step-by-step tutorial for developing an LLVM backend. Under active development at `<https://github.com/Jonathan2251/lbd>`_ (please contribute!). diff --git a/docs/userguides.rst b/docs/userguides.rst deleted file mode 100644 index 7e4e3b7..0000000 --- a/docs/userguides.rst +++ /dev/null @@ -1,112 +0,0 @@ -.. _userguides: - -User Guides -=========== - -.. toctree:: - :hidden: - - CMake - HowToBuildOnARM - CommandGuide/index - DeveloperPolicy - GettingStarted - GettingStartedVS - FAQ - Lexicon - Packaging - HowToAddABuilder - yaml2obj - HowToSubmitABug - SphinxQuickstartTemplate - Phabricator - TestingGuide - tutorial/index - ReleaseNotes - Passes - YamlIO - -* :ref:`getting_started` - - Discusses how to get up and running quickly with the LLVM infrastructure. - Everything from unpacking and compilation of the distribution to execution - of some tools. - -* :ref:`building-with-cmake` - - An addendum to the main Getting Started guide for those using the `CMake - build system <http://www.cmake.org>`_. - -* :ref:`how_to_build_on_arm` - - Notes on building and testing LLVM/Clang on ARM. - -* :doc:`GettingStartedVS` - - An addendum to the main Getting Started guide for those using Visual Studio - on Windows. - -* :doc:`tutorial/index` - - A walk through the process of using LLVM for a custom language, and the - facilities LLVM offers in tutorial form. - -* :ref:`developer_policy` - - The LLVM project's policy towards developers and their contributions. - -* :ref:`LLVM Command Guide <commands>` - - A reference manual for the LLVM command line utilities ("man" pages for LLVM - tools). - -* :doc:`Passes` - - A list of optimizations and analyses implemented in LLVM. - -* :ref:`faq` - - A list of common questions and problems and their solutions. - -* :doc:`Release notes for the current release <ReleaseNotes>` - - This describes new features, known bugs, and other limitations. - -* :ref:`how-to-submit-a-bug-report` - - Instructions for properly submitting information about any bugs you run into - in the LLVM system. -* :doc:`SphinxQuickstartTemplate` - - A template + tutorial for writing new Sphinx documentation. It is meant - to be read in source form. - -* :doc:`LLVM Testing Infrastructure Guide <TestingGuide>` - - A reference manual for using the LLVM testing infrastructure. - -* `How to build the C, C++, ObjC, and ObjC++ front end <http://clang.llvm.org/get_started.html>`_ - - Instructions for building the clang front-end from source. - -* :ref:`packaging` - - Advice on packaging LLVM into a distribution. - -* :ref:`lexicon` - - Definition of acronyms, terms and concepts used in LLVM. - -* :ref:`how_to_add_a_builder` - - Instructions for adding new builder to LLVM buildbot master. - -* :ref:`yamlio` - - A reference guide for using LLVM's YAML I/O library. - -* **IRC** -- You can probably find help on the unofficial LLVM IRC. - - We often are on irc.oftc.net in the #llvm channel. If you are using the - mozilla browser, and have chatzilla installed, you can `join #llvm on - irc.oftc.net <irc://irc.oftc.net/llvm>`_. diff --git a/docs/yaml2obj.rst b/docs/yaml2obj.rst index d051e7e..b269806 100644 --- a/docs/yaml2obj.rst +++ b/docs/yaml2obj.rst @@ -1,5 +1,3 @@ -.. _yaml2obj: - yaml2obj ======== |
