[www-releases] r368037 - Add 8.0.1 LLVM docs

Tom Stellard via llvm-commits llvm-commits at lists.llvm.org
Tue Aug 6 06:51:06 PDT 2019


Added: www-releases/trunk/8.0.1/docs/_sources/CodeGenerator.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.1/docs/_sources/CodeGenerator.rst.txt?rev=368037&view=auto
==============================================================================
--- www-releases/trunk/8.0.1/docs/_sources/CodeGenerator.rst.txt (added)
+++ www-releases/trunk/8.0.1/docs/_sources/CodeGenerator.rst.txt Tue Aug  6 06:51:02 2019
@@ -0,0 +1,2658 @@
+==========================================
+The LLVM Target-Independent Code Generator
+==========================================
+
+.. role:: raw-html(raw)
+   :format: html
+
+.. raw:: html
+
+  <style>
+    .unknown { background-color: #C0C0C0; text-align: center; }
+    .unknown:before { content: "?" }
+    .no { background-color: #C11B17 }
+    .no:before { content: "N" }
+    .partial { background-color: #F88017 }
+    .yes { background-color: #0F0; }
+    .yes:before { content: "Y" }
+    .na { background-color: #6666FF; }
+    .na:before { content: "N/A" }
+  </style>
+
+.. contents::
+   :local:
+
+.. warning::
+  This is a work in progress.
+
+Introduction
+============
+
+The LLVM target-independent code generator is a framework that provides a suite
+of reusable components for translating the LLVM internal representation to the
+machine code for a specified target---either in assembly form (suitable for a
+static compiler) or in binary machine code format (usable for a JIT
+compiler). The LLVM target-independent code generator consists of six main
+components:
+
+1. `Abstract target description`_ interfaces which capture important properties
+   about various aspects of the machine, independently of how they will be used.
+   These interfaces are defined in ``include/llvm/Target/``.
+
+2. Classes used to represent the `code being generated`_ for a target.  These
+   classes are intended to be abstract enough to represent the machine code for
+   *any* target machine.  These classes are defined in
+   ``include/llvm/CodeGen/``. At this level, concepts like "constant pool
+   entries" and "jump tables" are explicitly exposed.
+
+3. Classes and algorithms used to represent code at the object file level, the
+   `MC Layer`_.  These classes represent assembly level constructs like labels,
+   sections, and instructions.  At this level, concepts like "constant pool
+   entries" and "jump tables" don't exist.
+
+4. `Target-independent algorithms`_ used to implement various phases of native
+   code generation (register allocation, scheduling, stack frame representation,
+   etc).  This code lives in ``lib/CodeGen/``.
+
+5. `Implementations of the abstract target description interfaces`_ for
+   particular targets.  These machine descriptions make use of the components
+   provided by LLVM, and can optionally provide custom target-specific passes,
+   to build complete code generators for a specific target.  Target descriptions
+   live in ``lib/Target/``.
+
+6. The target-independent JIT components.  The LLVM JIT is completely target
+   independent (it uses the ``TargetJITInfo`` structure to interface for
+   target-specific issues.  The code for the target-independent JIT lives in
+   ``lib/ExecutionEngine/JIT``.
+
+Depending on which part of the code generator you are interested in working on,
+different pieces of this will be useful to you.  In any case, you should be
+familiar with the `target description`_ and `machine code representation`_
+classes.  If you want to add a backend for a new target, you will need to
+`implement the target description`_ classes for your new target and understand
+the :doc:`LLVM code representation <LangRef>`.  If you are interested in
+implementing a new `code generation algorithm`_, it should only depend on the
+target-description and machine code representation classes, ensuring that it is
+portable.
+
+Required components in the code generator
+-----------------------------------------
+
+The two pieces of the LLVM code generator are the high-level interface to the
+code generator and the set of reusable components that can be used to build
+target-specific backends.  The two most important interfaces (:raw-html:`<tt>`
+`TargetMachine`_ :raw-html:`</tt>` and :raw-html:`<tt>` `DataLayout`_
+:raw-html:`</tt>`) are the only ones that are required to be defined for a
+backend to fit into the LLVM system, but the others must be defined if the
+reusable code generator components are going to be used.
+
+This design has two important implications.  The first is that LLVM can support
+completely non-traditional code generation targets.  For example, the C backend
+does not require register allocation, instruction selection, or any of the other
+standard components provided by the system.  As such, it only implements these
+two interfaces, and does its own thing. Note that C backend was removed from the
+trunk since LLVM 3.1 release. Another example of a code generator like this is a
+(purely hypothetical) backend that converts LLVM to the GCC RTL form and uses
+GCC to emit machine code for a target.
+
+This design also implies that it is possible to design and implement radically
+different code generators in the LLVM system that do not make use of any of the
+built-in components.  Doing so is not recommended at all, but could be required
+for radically different targets that do not fit into the LLVM machine
+description model: FPGAs for example.
+
+.. _high-level design of the code generator:
+
+The high-level design of the code generator
+-------------------------------------------
+
+The LLVM target-independent code generator is designed to support efficient and
+quality code generation for standard register-based microprocessors.  Code
+generation in this model is divided into the following stages:
+
+1. `Instruction Selection`_ --- This phase determines an efficient way to
+   express the input LLVM code in the target instruction set.  This stage
+   produces the initial code for the program in the target instruction set, then
+   makes use of virtual registers in SSA form and physical registers that
+   represent any required register assignments due to target constraints or
+   calling conventions.  This step turns the LLVM code into a DAG of target
+   instructions.
+
+2. `Scheduling and Formation`_ --- This phase takes the DAG of target
+   instructions produced by the instruction selection phase, determines an
+   ordering of the instructions, then emits the instructions as :raw-html:`<tt>`
+   `MachineInstr`_\s :raw-html:`</tt>` with that ordering.  Note that we
+   describe this in the `instruction selection section`_ because it operates on
+   a `SelectionDAG`_.
+
+3. `SSA-based Machine Code Optimizations`_ --- This optional stage consists of a
+   series of machine-code optimizations that operate on the SSA-form produced by
+   the instruction selector.  Optimizations like modulo-scheduling or peephole
+   optimization work here.
+
+4. `Register Allocation`_ --- The target code is transformed from an infinite
+   virtual register file in SSA form to the concrete register file used by the
+   target.  This phase introduces spill code and eliminates all virtual register
+   references from the program.
+
+5. `Prolog/Epilog Code Insertion`_ --- Once the machine code has been generated
+   for the function and the amount of stack space required is known (used for
+   LLVM alloca's and spill slots), the prolog and epilog code for the function
+   can be inserted and "abstract stack location references" can be eliminated.
+   This stage is responsible for implementing optimizations like frame-pointer
+   elimination and stack packing.
+
+6. `Late Machine Code Optimizations`_ --- Optimizations that operate on "final"
+   machine code can go here, such as spill code scheduling and peephole
+   optimizations.
+
+7. `Code Emission`_ --- The final stage actually puts out the code for the
+   current function, either in the target assembler format or in machine
+   code.
+
+The code generator is based on the assumption that the instruction selector will
+use an optimal pattern matching selector to create high-quality sequences of
+native instructions.  Alternative code generator designs based on pattern
+expansion and aggressive iterative peephole optimization are much slower.  This
+design permits efficient compilation (important for JIT environments) and
+aggressive optimization (used when generating code offline) by allowing
+components of varying levels of sophistication to be used for any step of
+compilation.
+
+In addition to these stages, target implementations can insert arbitrary
+target-specific passes into the flow.  For example, the X86 target uses a
+special pass to handle the 80x87 floating point stack architecture.  Other
+targets with unusual requirements can be supported with custom passes as needed.
+
+Using TableGen for target description
+-------------------------------------
+
+The target description classes require a detailed description of the target
+architecture.  These target descriptions often have a large amount of common
+information (e.g., an ``add`` instruction is almost identical to a ``sub``
+instruction).  In order to allow the maximum amount of commonality to be
+factored out, the LLVM code generator uses the
+:doc:`TableGen/index` tool to describe big chunks of the
+target machine, which allows the use of domain-specific and target-specific
+abstractions to reduce the amount of repetition.
+
+As LLVM continues to be developed and refined, we plan to move more and more of
+the target description to the ``.td`` form.  Doing so gives us a number of
+advantages.  The most important is that it makes it easier to port LLVM because
+it reduces the amount of C++ code that has to be written, and the surface area
+of the code generator that needs to be understood before someone can get
+something working.  Second, it makes it easier to change things. In particular,
+if tables and other things are all emitted by ``tblgen``, we only need a change
+in one place (``tblgen``) to update all of the targets to a new interface.
+
+.. _Abstract target description:
+.. _target description:
+
+Target description classes
+==========================
+
+The LLVM target description classes (located in the ``include/llvm/Target``
+directory) provide an abstract description of the target machine independent of
+any particular client.  These classes are designed to capture the *abstract*
+properties of the target (such as the instructions and registers it has), and do
+not incorporate any particular pieces of code generation algorithms.
+
+All of the target description classes (except the :raw-html:`<tt>` `DataLayout`_
+:raw-html:`</tt>` class) are designed to be subclassed by the concrete target
+implementation, and have virtual methods implemented.  To get to these
+implementations, the :raw-html:`<tt>` `TargetMachine`_ :raw-html:`</tt>` class
+provides accessors that should be implemented by the target.
+
+.. _TargetMachine:
+
+The ``TargetMachine`` class
+---------------------------
+
+The ``TargetMachine`` class provides virtual methods that are used to access the
+target-specific implementations of the various target description classes via
+the ``get*Info`` methods (``getInstrInfo``, ``getRegisterInfo``,
+``getFrameInfo``, etc.).  This class is designed to be specialized by a concrete
+target implementation (e.g., ``X86TargetMachine``) which implements the various
+virtual methods.  The only required target description class is the
+:raw-html:`<tt>` `DataLayout`_ :raw-html:`</tt>` class, but if the code
+generator components are to be used, the other interfaces should be implemented
+as well.
+
+.. _DataLayout:
+
+The ``DataLayout`` class
+------------------------
+
+The ``DataLayout`` class is the only required target description class, and it
+is the only class that is not extensible (you cannot derive a new class from
+it).  ``DataLayout`` specifies information about how the target lays out memory
+for structures, the alignment requirements for various data types, the size of
+pointers in the target, and whether the target is little-endian or
+big-endian.
+
+.. _TargetLowering:
+
+The ``TargetLowering`` class
+----------------------------
+
+The ``TargetLowering`` class is used by SelectionDAG based instruction selectors
+primarily to describe how LLVM code should be lowered to SelectionDAG
+operations.  Among other things, this class indicates:
+
+* an initial register class to use for various ``ValueType``\s,
+
+* which operations are natively supported by the target machine,
+
+* the return type of ``setcc`` operations,
+
+* the type to use for shift amounts, and
+
+* various high-level characteristics, like whether it is profitable to turn
+  division by a constant into a multiplication sequence.
+
+.. _TargetRegisterInfo:
+
+The ``TargetRegisterInfo`` class
+--------------------------------
+
+The ``TargetRegisterInfo`` class is used to describe the register file of the
+target and any interactions between the registers.
+
+Registers are represented in the code generator by unsigned integers.  Physical
+registers (those that actually exist in the target description) are unique
+small numbers, and virtual registers are generally large.  Note that
+register ``#0`` is reserved as a flag value.
+
+Each register in the processor description has an associated
+``TargetRegisterDesc`` entry, which provides a textual name for the register
+(used for assembly output and debugging dumps) and a set of aliases (used to
+indicate whether one register overlaps with another).
+
+In addition to the per-register description, the ``TargetRegisterInfo`` class
+exposes a set of processor specific register classes (instances of the
+``TargetRegisterClass`` class).  Each register class contains sets of registers
+that have the same properties (for example, they are all 32-bit integer
+registers).  Each SSA virtual register created by the instruction selector has
+an associated register class.  When the register allocator runs, it replaces
+virtual registers with a physical register in the set.
+
+The target-specific implementations of these classes is auto-generated from a
+:doc:`TableGen/index` description of the register file.
+
+.. _TargetInstrInfo:
+
+The ``TargetInstrInfo`` class
+-----------------------------
+
+The ``TargetInstrInfo`` class is used to describe the machine instructions
+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 ``TargetFrameLowering`` class
+---------------------------------
+
+The ``TargetFrameLowering`` class is used to provide information about the stack
+frame layout of the target. It holds the direction of stack growth, the known
+stack alignment on entry to each function, and the offset to the local area.
+The offset to the local area is the offset from the stack pointer on function
+entry to the first location where function data (local variables, spill
+locations) can be stored.
+
+The ``TargetSubtarget`` class
+-----------------------------
+
+The ``TargetSubtarget`` class is used to provide information about the specific
+chip set being targeted.  A sub-target informs code generation of which
+instructions are supported, instruction latencies and instruction execution
+itinerary; i.e., which processing units are used, in what order, and for how
+long.
+
+The ``TargetJITInfo`` class
+---------------------------
+
+The ``TargetJITInfo`` class exposes an abstract interface used by the
+Just-In-Time code generator to perform target-specific activities, such as
+emitting stubs.  If a ``TargetMachine`` supports JIT code generation, it should
+provide one of these objects through the ``getJITInfo`` method.
+
+.. _code being generated:
+.. _machine code representation:
+
+Machine code description classes
+================================
+
+At the high-level, LLVM code is translated to a machine specific representation
+formed out of :raw-html:`<tt>` `MachineFunction`_ :raw-html:`</tt>`,
+:raw-html:`<tt>` `MachineBasicBlock`_ :raw-html:`</tt>`, and :raw-html:`<tt>`
+`MachineInstr`_ :raw-html:`</tt>` instances (defined in
+``include/llvm/CodeGen``).  This representation is completely target agnostic,
+representing instructions in their most abstract form: an opcode and a series of
+operands.  This representation is designed to support both an SSA representation
+for machine code, as well as a register allocated, non-SSA form.
+
+.. _MachineInstr:
+
+The ``MachineInstr`` class
+--------------------------
+
+Target machine instructions are represented as instances of the ``MachineInstr``
+class.  This class is an extremely abstract way of representing machine
+instructions.  In particular, it only keeps track of an opcode number and a set
+of operands.
+
+The opcode number is a simple unsigned integer that only has meaning to a
+specific backend.  All of the instructions for a target should be defined in the
+``*InstrInfo.td`` file for the target. The opcode enum values are auto-generated
+from this description.  The ``MachineInstr`` class does not have any information
+about how to interpret the instruction (i.e., what the semantics of the
+instruction are); for that you must refer to the :raw-html:`<tt>`
+`TargetInstrInfo`_ :raw-html:`</tt>` class.
+
+The operands of a machine instruction can be of several different types: a
+register reference, a constant integer, a basic block reference, etc.  In
+addition, a machine operand should be marked as a def or a use of the value
+(though only registers are allowed to be defs).
+
+By convention, the LLVM code generator orders instruction operands so that all
+register definitions come before the register uses, even on architectures that
+are normally printed in other orders.  For example, the SPARC add instruction:
+"``add %i1, %i2, %i3``" adds the "%i1", and "%i2" registers and stores the
+result into the "%i3" register.  In the LLVM code generator, the operands should
+be stored as "``%i3, %i1, %i2``": with the destination first.
+
+Keeping destination (definition) operands at the beginning of the operand list
+has several advantages.  In particular, the debugging printer will print the
+instruction like this:
+
+.. code-block:: llvm
+
+  %r3 = add %i1, %i2
+
+Also if the first operand is a def, it is easier to `create instructions`_ whose
+only def is the first operand.
+
+.. _create instructions:
+
+Using the ``MachineInstrBuilder.h`` functions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Machine instructions are created by using the ``BuildMI`` functions, located in
+the ``include/llvm/CodeGen/MachineInstrBuilder.h`` file.  The ``BuildMI``
+functions make it easy to build arbitrary machine instructions.  Usage of the
+``BuildMI`` functions look like this:
+
+.. code-block:: c++
+
+  // Create a 'DestReg = mov 42' (rendered in X86 assembly as 'mov DestReg, 42')
+  // instruction and insert it at the end of the given MachineBasicBlock.
+  const TargetInstrInfo &TII = ...
+  MachineBasicBlock &MBB = ...
+  DebugLoc DL;
+  MachineInstr *MI = BuildMI(MBB, DL, TII.get(X86::MOV32ri), DestReg).addImm(42);
+
+  // Create the same instr, but insert it before a specified iterator point.
+  MachineBasicBlock::iterator MBBI = ...
+  BuildMI(MBB, MBBI, DL, TII.get(X86::MOV32ri), DestReg).addImm(42);
+
+  // Create a 'cmp Reg, 0' instruction, no destination reg.
+  MI = BuildMI(MBB, DL, TII.get(X86::CMP32ri8)).addReg(Reg).addImm(42);
+
+  // Create an 'sahf' instruction which takes no operands and stores nothing.
+  MI = BuildMI(MBB, DL, TII.get(X86::SAHF));
+
+  // Create a self looping branch instruction.
+  BuildMI(MBB, DL, TII.get(X86::JNE)).addMBB(&MBB);
+
+If you need to add a definition operand (other than the optional destination
+register), you must explicitly mark it as such:
+
+.. code-block:: c++
+
+  MI.addReg(Reg, RegState::Define);
+
+Fixed (preassigned) registers
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+One important issue that the code generator needs to be aware of is the presence
+of fixed registers.  In particular, there are often places in the instruction
+stream where the register allocator *must* arrange for a particular value to be
+in a particular register.  This can occur due to limitations of the instruction
+set (e.g., the X86 can only do a 32-bit divide with the ``EAX``/``EDX``
+registers), or external factors like calling conventions.  In any case, the
+instruction selector should emit code that copies a virtual register into or out
+of a physical register when needed.
+
+For example, consider this simple LLVM example:
+
+.. code-block:: llvm
+
+  define i32 @test(i32 %X, i32 %Y) {
+    %Z = sdiv i32 %X, %Y
+    ret i32 %Z
+  }
+
+The X86 instruction selector might produce this machine code for the ``div`` and
+``ret``:
+
+.. code-block:: text
+
+  ;; Start of div
+  %EAX = mov %reg1024           ;; Copy X (in reg1024) into EAX
+  %reg1027 = sar %reg1024, 31
+  %EDX = mov %reg1027           ;; Sign extend X into EDX
+  idiv %reg1025                 ;; Divide by Y (in reg1025)
+  %reg1026 = mov %EAX           ;; Read the result (Z) out of EAX
+
+  ;; Start of ret
+  %EAX = mov %reg1026           ;; 32-bit return value goes in EAX
+  ret
+
+By the end of code generation, the register allocator would coalesce the
+registers and delete the resultant identity moves producing the following
+code:
+
+.. code-block:: text
+
+  ;; X is in EAX, Y is in ECX
+  mov %EAX, %EDX
+  sar %EDX, 31
+  idiv %ECX
+  ret
+
+This approach is extremely general (if it can handle the X86 architecture, it
+can handle anything!) and allows all of the target specific knowledge about the
+instruction stream to be isolated in the instruction selector.  Note that
+physical registers should have a short lifetime for good code generation, and
+all physical registers are assumed dead on entry to and exit from basic blocks
+(before register allocation).  Thus, if you need a value to be live across basic
+block boundaries, it *must* live in a virtual register.
+
+Call-clobbered registers
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Some machine instructions, like calls, clobber a large number of physical
+registers.  Rather than adding ``<def,dead>`` operands for all of them, it is
+possible to use an ``MO_RegisterMask`` operand instead.  The register mask
+operand holds a bit mask of preserved registers, and everything else is
+considered to be clobbered by the instruction.
+
+Machine code in SSA form
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+``MachineInstr``'s are initially selected in SSA-form, and are maintained in
+SSA-form until register allocation happens.  For the most part, this is
+trivially simple since LLVM is already in SSA form; LLVM PHI nodes become
+machine code PHI nodes, and virtual registers are only allowed to have a single
+definition.
+
+After register allocation, machine code is no longer in SSA-form because there
+are no virtual registers left in the code.
+
+.. _MachineBasicBlock:
+
+The ``MachineBasicBlock`` class
+-------------------------------
+
+The ``MachineBasicBlock`` class contains a list of machine instructions
+(:raw-html:`<tt>` `MachineInstr`_ :raw-html:`</tt>` instances).  It roughly
+corresponds to the LLVM code input to the instruction selector, but there can be
+a one-to-many mapping (i.e. one LLVM basic block can map to multiple machine
+basic blocks). The ``MachineBasicBlock`` class has a "``getBasicBlock``" method,
+which returns the LLVM basic block that it comes from.
+
+.. _MachineFunction:
+
+The ``MachineFunction`` class
+-----------------------------
+
+The ``MachineFunction`` class contains a list of machine basic blocks
+(:raw-html:`<tt>` `MachineBasicBlock`_ :raw-html:`</tt>` instances).  It
+corresponds one-to-one with the LLVM function input to the instruction selector.
+In addition to a list of basic blocks, the ``MachineFunction`` contains a a
+``MachineConstantPool``, a ``MachineFrameInfo``, a ``MachineFunctionInfo``, and
+a ``MachineRegisterInfo``.  See ``include/llvm/CodeGen/MachineFunction.h`` for
+more information.
+
+``MachineInstr Bundles``
+------------------------
+
+LLVM code generator can model sequences of instructions as MachineInstr
+bundles. A MI bundle can model a VLIW group / pack which contains an arbitrary
+number of parallel instructions. It can also be used to model a sequential list
+of instructions (potentially with data dependencies) that cannot be legally
+separated (e.g. ARM Thumb2 IT blocks).
+
+Conceptually a MI bundle is a MI with a number of other MIs nested within:
+
+::
+
+  --------------
+  |   Bundle   | ---------
+  --------------          \
+         |           ----------------
+         |           |      MI      |
+         |           ----------------
+         |                   |
+         |           ----------------
+         |           |      MI      |
+         |           ----------------
+         |                   |
+         |           ----------------
+         |           |      MI      |
+         |           ----------------
+         |
+  --------------
+  |   Bundle   | --------
+  --------------         \
+         |           ----------------
+         |           |      MI      |
+         |           ----------------
+         |                   |
+         |           ----------------
+         |           |      MI      |
+         |           ----------------
+         |                   |
+         |                  ...
+         |
+  --------------
+  |   Bundle   | --------
+  --------------         \
+         |
+        ...
+
+MI bundle support does not change the physical representations of
+MachineBasicBlock and MachineInstr. All the MIs (including top level and nested
+ones) are stored as sequential list of MIs. The "bundled" MIs are marked with
+the 'InsideBundle' flag. A top level MI with the special BUNDLE opcode is used
+to represent the start of a bundle. It's legal to mix BUNDLE MIs with individual
+MIs that are not inside bundles nor represent bundles.
+
+MachineInstr passes should operate on a MI bundle as a single unit. Member
+methods have been taught to correctly handle bundles and MIs inside bundles.
+The MachineBasicBlock iterator has been modified to skip over bundled MIs to
+enforce the bundle-as-a-single-unit concept. An alternative iterator
+instr_iterator has been added to MachineBasicBlock to allow passes to iterate
+over all of the MIs in a MachineBasicBlock, including those which are nested
+inside bundles. The top level BUNDLE instruction must have the correct set of
+register MachineOperand's that represent the cumulative inputs and outputs of
+the bundled MIs.
+
+Packing / bundling of MachineInstr's should be done as part of the register
+allocation super-pass. More specifically, the pass which determines what MIs
+should be bundled together must be done after code generator exits SSA form
+(i.e. after two-address pass, PHI elimination, and copy coalescing).  Bundles
+should only be finalized (i.e. adding BUNDLE MIs and input and output register
+MachineOperands) after virtual registers have been rewritten into physical
+registers. This requirement eliminates the need to add virtual register operands
+to BUNDLE instructions which would effectively double the virtual register def
+and use lists.
+
+.. _MC Layer:
+
+The "MC" Layer
+==============
+
+The MC Layer is used to represent and process code at the raw machine code
+level, devoid of "high level" information like "constant pools", "jump tables",
+"global variables" or anything like that.  At this level, LLVM handles things
+like label names, machine instructions, and sections in the object file.  The
+code in this layer is used for a number of important purposes: the tail end of
+the code generator uses it to write a .s or .o file, and it is also used by the
+llvm-mc tool to implement standalone machine code assemblers and disassemblers.
+
+This section describes some of the important classes.  There are also a number
+of important subsystems that interact at this layer, they are described later in
+this manual.
+
+.. _MCStreamer:
+
+The ``MCStreamer`` API
+----------------------
+
+MCStreamer is best thought of as an assembler API.  It is an abstract API which
+is *implemented* in different ways (e.g. to output a .s file, output an ELF .o
+file, etc) but whose API correspond directly to what you see in a .s file.
+MCStreamer has one method per directive, such as EmitLabel, EmitSymbolAttribute,
+SwitchSection, EmitValue (for .byte, .word), etc, which directly correspond to
+assembly level directives.  It also has an EmitInstruction method, which is used
+to output an MCInst to the streamer.
+
+This API is most important for two clients: the llvm-mc stand-alone assembler is
+effectively a parser that parses a line, then invokes a method on MCStreamer. In
+the code generator, the `Code Emission`_ phase of the code generator lowers
+higher level LLVM IR and Machine* constructs down to the MC layer, emitting
+directives through MCStreamer.
+
+On the implementation side of MCStreamer, there are two major implementations:
+one for writing out a .s file (MCAsmStreamer), and one for writing out a .o
+file (MCObjectStreamer).  MCAsmStreamer is a straightforward implementation
+that prints out a directive for each method (e.g. ``EmitValue -> .byte``), but
+MCObjectStreamer implements a full assembler.
+
+For target specific directives, the MCStreamer has a MCTargetStreamer instance.
+Each target that needs it defines a class that inherits from it and is a lot
+like MCStreamer itself: It has one method per directive and two classes that
+inherit from it, a target object streamer and a target asm streamer. The target
+asm streamer just prints it (``emitFnStart -> .fnstart``), and the object
+streamer implement the assembler logic for it.
+
+To make llvm use these classes, the target initialization must call
+TargetRegistry::RegisterAsmStreamer and TargetRegistry::RegisterMCObjectStreamer
+passing callbacks that allocate the corresponding target streamer and pass it
+to createAsmStreamer or to the appropriate object streamer constructor.
+
+The ``MCContext`` class
+-----------------------
+
+The MCContext class is the owner of a variety of uniqued data structures at the
+MC layer, including symbols, sections, etc.  As such, this is the class that you
+interact with to create symbols and sections.  This class can not be subclassed.
+
+The ``MCSymbol`` class
+----------------------
+
+The MCSymbol class represents a symbol (aka label) in the assembly file.  There
+are two interesting kinds of symbols: assembler temporary symbols, and normal
+symbols.  Assembler temporary symbols are used and processed by the assembler
+but are discarded when the object file is produced.  The distinction is usually
+represented by adding a prefix to the label, for example "L" labels are
+assembler temporary labels in MachO.
+
+MCSymbols are created by MCContext and uniqued there.  This means that MCSymbols
+can be compared for pointer equivalence to find out if they are the same symbol.
+Note that pointer inequality does not guarantee the labels will end up at
+different addresses though.  It's perfectly legal to output something like this
+to the .s file:
+
+::
+
+  foo:
+  bar:
+    .byte 4
+
+In this case, both the foo and bar symbols will have the same address.
+
+The ``MCSection`` class
+-----------------------
+
+The ``MCSection`` class represents an object-file specific section. It is
+subclassed by object file specific implementations (e.g. ``MCSectionMachO``,
+``MCSectionCOFF``, ``MCSectionELF``) and these are created and uniqued by
+MCContext.  The MCStreamer has a notion of the current section, which can be
+changed with the SwitchToSection method (which corresponds to a ".section"
+directive in a .s file).
+
+.. _MCInst:
+
+The ``MCInst`` class
+--------------------
+
+The ``MCInst`` class is a target-independent representation of an instruction.
+It is a simple class (much more so than `MachineInstr`_) that holds a
+target-specific opcode and a vector of MCOperands.  MCOperand, in turn, is a
+simple discriminated union of three cases: 1) a simple immediate, 2) a target
+register ID, 3) a symbolic expression (e.g. "``Lfoo-Lbar+42``") as an MCExpr.
+
+MCInst is the common currency used to represent machine instructions at the MC
+layer.  It is the type used by the instruction encoder, the instruction printer,
+and the type generated by the assembly parser and disassembler.
+
+.. _Target-independent algorithms:
+.. _code generation algorithm:
+
+Target-independent code generation algorithms
+=============================================
+
+This section documents the phases described in the `high-level design of the
+code generator`_.  It explains how they work and some of the rationale behind
+their design.
+
+.. _Instruction Selection:
+.. _instruction selection section:
+
+Instruction Selection
+---------------------
+
+Instruction Selection is the process of translating LLVM code presented to the
+code generator into target-specific machine instructions.  There are several
+well-known ways to do this in the literature.  LLVM uses a SelectionDAG based
+instruction selector.
+
+Portions of the DAG instruction selector are generated from the target
+description (``*.td``) files.  Our goal is for the entire instruction selector
+to be generated from these ``.td`` files, though currently there are still
+things that require custom C++ code.
+
+.. _SelectionDAG:
+
+Introduction to SelectionDAGs
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The SelectionDAG provides an abstraction for code representation in a way that
+is amenable to instruction selection using automatic techniques
+(e.g. dynamic-programming based optimal pattern matching selectors). It is also
+well-suited to other phases of code generation; in particular, instruction
+scheduling (SelectionDAG's are very close to scheduling DAGs post-selection).
+Additionally, the SelectionDAG provides a host representation where a large
+variety of very-low-level (but target-independent) `optimizations`_ may be
+performed; ones which require extensive information about the instructions
+efficiently supported by the target.
+
+The SelectionDAG is a Directed-Acyclic-Graph whose nodes are instances of the
+``SDNode`` class.  The primary payload of the ``SDNode`` is its operation code
+(Opcode) that indicates what operation the node performs and the operands to the
+operation.  The various operation node types are described at the top of the
+``include/llvm/CodeGen/ISDOpcodes.h`` file.
+
+Although most operations define a single value, each node in the graph may
+define multiple values.  For example, a combined div/rem operation will define
+both the dividend and the remainder. Many other situations require multiple
+values as well.  Each node also has some number of operands, which are edges to
+the node defining the used value.  Because nodes may define multiple values,
+edges are represented by instances of the ``SDValue`` class, which is a
+``<SDNode, unsigned>`` pair, indicating the node and result value being used,
+respectively.  Each value produced by an ``SDNode`` has an associated ``MVT``
+(Machine Value Type) indicating what the type of the value is.
+
+SelectionDAGs contain two different kinds of values: those that represent data
+flow and those that represent control flow dependencies.  Data values are simple
+edges with an integer or floating point value type.  Control edges are
+represented as "chain" edges which are of type ``MVT::Other``.  These edges
+provide an ordering between nodes that have side effects (such as loads, stores,
+calls, returns, etc).  All nodes that have side effects should take a token
+chain as input and produce a new one as output.  By convention, token chain
+inputs are always operand #0, and chain results are always the last value
+produced by an operation. However, after instruction selection, the
+machine nodes have their chain after the instruction's operands, and
+may be followed by glue nodes.
+
+A SelectionDAG has designated "Entry" and "Root" nodes.  The Entry node is
+always a marker node with an Opcode of ``ISD::EntryToken``.  The Root node is
+the final side-effecting node in the token chain. For example, in a single basic
+block function it would be the return node.
+
+One important concept for SelectionDAGs is the notion of a "legal" vs.
+"illegal" DAG.  A legal DAG for a target is one that only uses supported
+operations and supported types.  On a 32-bit PowerPC, for example, a DAG with a
+value of type i1, i8, i16, or i64 would be illegal, as would a DAG that uses a
+SREM or UREM operation.  The `legalize types`_ and `legalize operations`_ phases
+are responsible for turning an illegal DAG into a legal DAG.
+
+.. _SelectionDAG-Process:
+
+SelectionDAG Instruction Selection Process
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+SelectionDAG-based instruction selection consists of the following steps:
+
+#. `Build initial DAG`_ --- This stage performs a simple translation from the
+   input LLVM code to an illegal SelectionDAG.
+
+#. `Optimize SelectionDAG`_ --- This stage performs simple optimizations on the
+   SelectionDAG to simplify it, and recognize meta instructions (like rotates
+   and ``div``/``rem`` pairs) for targets that support these meta operations.
+   This makes the resultant code more efficient and the `select instructions
+   from DAG`_ phase (below) simpler.
+
+#. `Legalize SelectionDAG Types`_ --- This stage transforms SelectionDAG nodes
+   to eliminate any types that are unsupported on the target.
+
+#. `Optimize SelectionDAG`_ --- The SelectionDAG optimizer is run to clean up
+   redundancies exposed by type legalization.
+
+#. `Legalize SelectionDAG Ops`_ --- This stage transforms SelectionDAG nodes to
+   eliminate any operations that are unsupported on the target.
+
+#. `Optimize SelectionDAG`_ --- The SelectionDAG optimizer is run to eliminate
+   inefficiencies introduced by operation legalization.
+
+#. `Select instructions from DAG`_ --- Finally, the target instruction selector
+   matches the DAG operations to target instructions.  This process translates
+   the target-independent input DAG into another DAG of target instructions.
+
+#. `SelectionDAG Scheduling and Formation`_ --- The last phase assigns a linear
+   order to the instructions in the target-instruction DAG and emits them into
+   the MachineFunction being compiled.  This step uses traditional prepass
+   scheduling techniques.
+
+After all of these steps are complete, the SelectionDAG is destroyed and the
+rest of the code generation passes are run.
+
+One great way to visualize what is going on here is to take advantage of a few
+LLC command line options.  The following options pop up a window displaying the
+SelectionDAG at specific times (if you only get errors printed to the console
+while using this, you probably `need to configure your
+system <ProgrammersManual.html#viewing-graphs-while-debugging-code>`_ to add support for it).
+
+* ``-view-dag-combine1-dags`` displays the DAG after being built, before the
+  first optimization pass.
+
+* ``-view-legalize-dags`` displays the DAG before Legalization.
+
+* ``-view-dag-combine2-dags`` displays the DAG before the second optimization
+  pass.
+
+* ``-view-isel-dags`` displays the DAG before the Select phase.
+
+* ``-view-sched-dags`` displays the DAG before Scheduling.
+
+The ``-view-sunit-dags`` displays the Scheduler's dependency graph.  This graph
+is based on the final SelectionDAG, with nodes that must be scheduled together
+bundled into a single scheduling-unit node, and with immediate operands and
+other nodes that aren't relevant for scheduling omitted.
+
+The option ``-filter-view-dags`` allows to select the name of the basic block
+that you are interested to visualize and filters all the previous
+``view-*-dags`` options.
+
+.. _Build initial DAG:
+
+Initial SelectionDAG Construction
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The initial SelectionDAG is na\ :raw-html:`ï`\ vely peephole expanded from
+the LLVM input by the ``SelectionDAGBuilder`` class.  The intent of this pass
+is to expose as much low-level, target-specific details to the SelectionDAG as
+possible.  This pass is mostly hard-coded (e.g. an LLVM ``add`` turns into an
+``SDNode add`` while a ``getelementptr`` is expanded into the obvious
+arithmetic). This pass requires target-specific hooks to lower calls, returns,
+varargs, etc.  For these features, the :raw-html:`<tt>` `TargetLowering`_
+:raw-html:`</tt>` interface is used.
+
+.. _legalize types:
+.. _Legalize SelectionDAG Types:
+.. _Legalize SelectionDAG Ops:
+
+SelectionDAG LegalizeTypes Phase
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The Legalize phase is in charge of converting a DAG to only use the types that
+are natively supported by the target.
+
+There are two main ways of converting values of unsupported scalar types to
+values of supported types: converting small types to larger types ("promoting"),
+and breaking up large integer types into smaller ones ("expanding").  For
+example, a target might require that all f32 values are promoted to f64 and that
+all i1/i8/i16 values are promoted to i32.  The same target might require that
+all i64 values be expanded into pairs of i32 values.  These changes can insert
+sign and zero extensions as needed to make sure that the final code has the same
+behavior as the input.
+
+There are two main ways of converting values of unsupported vector types to
+value of supported types: splitting vector types, multiple times if necessary,
+until a legal type is found, and extending vector types by adding elements to
+the end to round them out to legal types ("widening").  If a vector gets split
+all the way down to single-element parts with no supported vector type being
+found, the elements are converted to scalars ("scalarizing").
+
+A target implementation tells the legalizer which types are supported (and which
+register class to use for them) by calling the ``addRegisterClass`` method in
+its ``TargetLowering`` constructor.
+
+.. _legalize operations:
+.. _Legalizer:
+
+SelectionDAG Legalize Phase
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The Legalize phase is in charge of converting a DAG to only use the operations
+that are natively supported by the target.
+
+Targets often have weird constraints, such as not supporting every operation on
+every supported datatype (e.g. X86 does not support byte conditional moves and
+PowerPC does not support sign-extending loads from a 16-bit memory location).
+Legalize takes care of this by open-coding another sequence of operations to
+emulate the operation ("expansion"), by promoting one type to a larger type that
+supports the operation ("promotion"), or by using a target-specific hook to
+implement the legalization ("custom").
+
+A target implementation tells the legalizer which operations are not supported
+(and which of the above three actions to take) by calling the
+``setOperationAction`` method in its ``TargetLowering`` constructor.
+
+Prior to the existence of the Legalize passes, we required that every target
+`selector`_ supported and handled every operator and type even if they are not
+natively supported.  The introduction of the Legalize phases allows all of the
+canonicalization patterns to be shared across targets, and makes it very easy to
+optimize the canonicalized code because it is still in the form of a DAG.
+
+.. _optimizations:
+.. _Optimize SelectionDAG:
+.. _selector:
+
+SelectionDAG Optimization Phase: the DAG Combiner
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The SelectionDAG optimization phase is run multiple times for code generation,
+immediately after the DAG is built and once after each legalization.  The first
+run of the pass allows the initial code to be cleaned up (e.g. performing
+optimizations that depend on knowing that the operators have restricted type
+inputs).  Subsequent runs of the pass clean up the messy code generated by the
+Legalize passes, which allows Legalize to be very simple (it can focus on making
+code legal instead of focusing on generating *good* and legal code).
+
+One important class of optimizations performed is optimizing inserted sign and
+zero extension instructions.  We currently use ad-hoc techniques, but could move
+to more rigorous techniques in the future.  Here are some good papers on the
+subject:
+
+"`Widening integer arithmetic <http://www.eecs.harvard.edu/~nr/pubs/widen-abstract.html>`_" :raw-html:`<br>`
+Kevin Redwine and Norman Ramsey :raw-html:`<br>`
+International Conference on Compiler Construction (CC) 2004
+
+"`Effective sign extension elimination <http://portal.acm.org/citation.cfm?doid=512529.512552>`_"  :raw-html:`<br>`
+Motohiro Kawahito, Hideaki Komatsu, and Toshio Nakatani :raw-html:`<br>`
+Proceedings of the ACM SIGPLAN 2002 Conference on Programming Language Design
+and Implementation.
+
+.. _Select instructions from DAG:
+
+SelectionDAG Select Phase
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The Select phase is the bulk of the target-specific code for instruction
+selection.  This phase takes a legal SelectionDAG as input, pattern matches the
+instructions supported by the target to this DAG, and produces a new DAG of
+target code.  For example, consider the following LLVM fragment:
+
+.. code-block:: llvm
+
+  %t1 = fadd float %W, %X
+  %t2 = fmul float %t1, %Y
+  %t3 = fadd float %t2, %Z
+
+This LLVM code corresponds to a SelectionDAG that looks basically like this:
+
+.. code-block:: text
+
+  (fadd:f32 (fmul:f32 (fadd:f32 W, X), Y), Z)
+
+If a target supports floating point multiply-and-add (FMA) operations, one of
+the adds can be merged with the multiply.  On the PowerPC, for example, the
+output of the instruction selector might look like this DAG:
+
+::
+
+  (FMADDS (FADDS W, X), Y, Z)
+
+The ``FMADDS`` instruction is a ternary instruction that multiplies its first
+two operands and adds the third (as single-precision floating-point numbers).
+The ``FADDS`` instruction is a simple binary single-precision add instruction.
+To perform this pattern match, the PowerPC backend includes the following
+instruction definitions:
+
+.. code-block:: text
+  :emphasize-lines: 4-5,9
+
+  def FMADDS : AForm_1<59, 29,
+                      (ops F4RC:$FRT, F4RC:$FRA, F4RC:$FRC, F4RC:$FRB),
+                      "fmadds $FRT, $FRA, $FRC, $FRB",
+                      [(set F4RC:$FRT, (fadd (fmul F4RC:$FRA, F4RC:$FRC),
+                                             F4RC:$FRB))]>;
+  def FADDS : AForm_2<59, 21,
+                      (ops F4RC:$FRT, F4RC:$FRA, F4RC:$FRB),
+                      "fadds $FRT, $FRA, $FRB",
+                      [(set F4RC:$FRT, (fadd F4RC:$FRA, F4RC:$FRB))]>;
+
+The highlighted portion of the instruction definitions indicates the pattern
+used to match the instructions. The DAG operators (like ``fmul``/``fadd``)
+are defined in the ``include/llvm/Target/TargetSelectionDAG.td`` file.
+"``F4RC``" is the register class of the input and result values.
+
+The TableGen DAG instruction selector generator reads the instruction patterns
+in the ``.td`` file and automatically builds parts of the pattern matching code
+for your target.  It has the following strengths:
+
+* At compiler-compile time, it analyzes your instruction patterns and tells you
+  if your patterns make sense or not.
+
+* It can handle arbitrary constraints on operands for the pattern match.  In
+  particular, it is straight-forward to say things like "match any immediate
+  that is a 13-bit sign-extended value".  For examples, see the ``immSExt16``
+  and related ``tblgen`` classes in the PowerPC backend.
+
+* It knows several important identities for the patterns defined.  For example,
+  it knows that addition is commutative, so it allows the ``FMADDS`` pattern
+  above to match "``(fadd X, (fmul Y, Z))``" as well as "``(fadd (fmul X, Y),
+  Z)``", without the target author having to specially handle this case.
+
+* It has a full-featured type-inferencing system.  In particular, you should
+  rarely have to explicitly tell the system what type parts of your patterns
+  are.  In the ``FMADDS`` case above, we didn't have to tell ``tblgen`` that all
+  of the nodes in the pattern are of type 'f32'.  It was able to infer and
+  propagate this knowledge from the fact that ``F4RC`` has type 'f32'.
+
+* Targets can define their own (and rely on built-in) "pattern fragments".
+  Pattern fragments are chunks of reusable patterns that get inlined into your
+  patterns during compiler-compile time.  For example, the integer "``(not
+  x)``" operation is actually defined as a pattern fragment that expands as
+  "``(xor x, -1)``", since the SelectionDAG does not have a native '``not``'
+  operation.  Targets can define their own short-hand fragments as they see fit.
+  See the definition of '``not``' and '``ineg``' for examples.
+
+* In addition to instructions, targets can specify arbitrary patterns that map
+  to one or more instructions using the 'Pat' class.  For example, the PowerPC
+  has no way to load an arbitrary integer immediate into a register in one
+  instruction. To tell tblgen how to do this, it defines:
+
+  ::
+
+    // Arbitrary immediate support.  Implement in terms of LIS/ORI.
+    def : Pat<(i32 imm:$imm),
+              (ORI (LIS (HI16 imm:$imm)), (LO16 imm:$imm))>;
+
+  If none of the single-instruction patterns for loading an immediate into a
+  register match, this will be used.  This rule says "match an arbitrary i32
+  immediate, turning it into an ``ORI`` ('or a 16-bit immediate') and an ``LIS``
+  ('load 16-bit immediate, where the immediate is shifted to the left 16 bits')
+  instruction".  To make this work, the ``LO16``/``HI16`` node transformations
+  are used to manipulate the input immediate (in this case, take the high or low
+  16-bits of the immediate).
+
+* When using the 'Pat' class to map a pattern to an instruction that has one
+  or more complex operands (like e.g. `X86 addressing mode`_), the pattern may
+  either specify the operand as a whole using a ``ComplexPattern``, or else it
+  may specify the components of the complex operand separately.  The latter is
+  done e.g. for pre-increment instructions by the PowerPC back end:
+
+  ::
+
+    def STWU  : DForm_1<37, (outs ptr_rc:$ea_res), (ins GPRC:$rS, memri:$dst),
+                    "stwu $rS, $dst", LdStStoreUpd, []>,
+                    RegConstraint<"$dst.reg = $ea_res">, NoEncode<"$ea_res">;
+
+    def : Pat<(pre_store GPRC:$rS, ptr_rc:$ptrreg, iaddroff:$ptroff),
+              (STWU GPRC:$rS, iaddroff:$ptroff, ptr_rc:$ptrreg)>;
+
+  Here, the pair of ``ptroff`` and ``ptrreg`` operands is matched onto the
+  complex operand ``dst`` of class ``memri`` in the ``STWU`` instruction.
+
+* While the system does automate a lot, it still allows you to write custom C++
+  code to match special cases if there is something that is hard to
+  express.
+
+While it has many strengths, the system currently has some limitations,
+primarily because it is a work in progress and is not yet finished:
+
+* Overall, there is no way to define or match SelectionDAG nodes that define
+  multiple values (e.g. ``SMUL_LOHI``, ``LOAD``, ``CALL``, etc).  This is the
+  biggest reason that you currently still *have to* write custom C++ code
+  for your instruction selector.
+
+* There is no great way to support matching complex addressing modes yet.  In
+  the future, we will extend pattern fragments to allow them to define multiple
+  values (e.g. the four operands of the `X86 addressing mode`_, which are
+  currently matched with custom C++ code).  In addition, we'll extend fragments
+  so that a fragment can match multiple different patterns.
+
+* We don't automatically infer flags like ``isStore``/``isLoad`` yet.
+
+* We don't automatically generate the set of supported registers and operations
+  for the `Legalizer`_ yet.
+
+* We don't have a way of tying in custom legalized nodes yet.
+
+Despite these limitations, the instruction selector generator is still quite
+useful for most of the binary and logical operations in typical instruction
+sets.  If you run into any problems or can't figure out how to do something,
+please let Chris know!
+
+.. _Scheduling and Formation:
+.. _SelectionDAG Scheduling and Formation:
+
+SelectionDAG Scheduling and Formation Phase
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The scheduling phase takes the DAG of target instructions from the selection
+phase and assigns an order.  The scheduler can pick an order depending on
+various constraints of the machines (i.e. order for minimal register pressure or
+try to cover instruction latencies).  Once an order is established, the DAG is
+converted to a list of :raw-html:`<tt>` `MachineInstr`_\s :raw-html:`</tt>` and
+the SelectionDAG is destroyed.
+
+Note that this phase is logically separate from the instruction selection phase,
+but is tied to it closely in the code because it operates on SelectionDAGs.
+
+Future directions for the SelectionDAG
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+#. Optional function-at-a-time selection.
+
+#. Auto-generate entire selector from ``.td`` file.
+
+.. _SSA-based Machine Code Optimizations:
+
+SSA-based Machine Code Optimizations
+------------------------------------
+
+To Be Written
+
+Live Intervals
+--------------
+
+Live Intervals are the ranges (intervals) where a variable is *live*.  They are
+used by some `register allocator`_ passes to determine if two or more virtual
+registers which require the same physical register are live at the same point in
+the program (i.e., they conflict).  When this situation occurs, one virtual
+register must be *spilled*.
+
+Live Variable Analysis
+^^^^^^^^^^^^^^^^^^^^^^
+
+The first step in determining the live intervals of variables is to calculate
+the set of registers that are immediately dead after the instruction (i.e., the
+instruction calculates the value, but it is never used) and the set of registers
+that are used by the instruction, but are never used after the instruction
+(i.e., they are killed). Live variable information is computed for
+each *virtual* register and *register allocatable* physical register
+in the function.  This is done in a very efficient manner because it uses SSA to
+sparsely compute lifetime information for virtual registers (which are in SSA
+form) and only has to track physical registers within a block.  Before register
+allocation, LLVM can assume that physical registers are only live within a
+single basic block.  This allows it to do a single, local analysis to resolve
+physical register lifetimes within each basic block. If a physical register is
+not register allocatable (e.g., a stack pointer or condition codes), it is not
+tracked.
+
+Physical registers may be live in to or out of a function. Live in values are
+typically arguments in registers. Live out values are typically return values in
+registers. Live in values are marked as such, and are given a dummy "defining"
+instruction during live intervals analysis. If the last basic block of a
+function is a ``return``, then it's marked as using all live out values in the
+function.
+
+``PHI`` nodes need to be handled specially, because the calculation of the live
+variable information from a depth first traversal of the CFG of the function
+won't guarantee that a virtual register used by the ``PHI`` node is defined
+before it's used. When a ``PHI`` node is encountered, only the definition is
+handled, because the uses will be handled in other basic blocks.
+
+For each ``PHI`` node of the current basic block, we simulate an assignment at
+the end of the current basic block and traverse the successor basic blocks. If a
+successor basic block has a ``PHI`` node and one of the ``PHI`` node's operands
+is coming from the current basic block, then the variable is marked as *alive*
+within the current basic block and all of its predecessor basic blocks, until
+the basic block with the defining instruction is encountered.
+
+Live Intervals Analysis
+^^^^^^^^^^^^^^^^^^^^^^^
+
+We now have the information available to perform the live intervals analysis and
+build the live intervals themselves.  We start off by numbering the basic blocks
+and machine instructions.  We then handle the "live-in" values.  These are in
+physical registers, so the physical register is assumed to be killed by the end
+of the basic block.  Live intervals for virtual registers are computed for some
+ordering of the machine instructions ``[1, N]``.  A live interval is an interval
+``[i, j)``, where ``1 >= i >= j > N``, for which a variable is live.
+
+.. note::
+  More to come...
+
+.. _Register Allocation:
+.. _register allocator:
+
+Register Allocation
+-------------------
+
+The *Register Allocation problem* consists in mapping a program
+:raw-html:`<b><tt>` P\ :sub:`v`\ :raw-html:`</tt></b>`, that can use an unbounded
+number of virtual registers, to a program :raw-html:`<b><tt>` P\ :sub:`p`\
+:raw-html:`</tt></b>` that contains a finite (possibly small) number of physical
+registers. Each target architecture has a different number of physical
+registers. If the number of physical registers is not enough to accommodate all
+the virtual registers, some of them will have to be mapped into memory. These
+virtuals are called *spilled virtuals*.
+
+How registers are represented in LLVM
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In LLVM, physical registers are denoted by integer numbers that normally range
+from 1 to 1023. To see how this numbering is defined for a particular
+architecture, you can read the ``GenRegisterNames.inc`` file for that
+architecture. For instance, by inspecting
+``lib/Target/X86/X86GenRegisterInfo.inc`` we see that the 32-bit register
+``EAX`` is denoted by 43, and the MMX register ``MM0`` is mapped to 65.
+
+Some architectures contain registers that share the same physical location. A
+notable example is the X86 platform. For instance, in the X86 architecture, the
+registers ``EAX``, ``AX`` and ``AL`` share the first eight bits. These physical
+registers are marked as *aliased* in LLVM. Given a particular architecture, you
+can check which registers are aliased by inspecting its ``RegisterInfo.td``
+file. Moreover, the class ``MCRegAliasIterator`` enumerates all the physical
+registers aliased to a register.
+
+Physical registers, in LLVM, are grouped in *Register Classes*.  Elements in the
+same register class are functionally equivalent, and can be interchangeably
+used. Each virtual register can only be mapped to physical registers of a
+particular class. For instance, in the X86 architecture, some virtuals can only
+be allocated to 8 bit registers.  A register class is described by
+``TargetRegisterClass`` objects.  To discover if a virtual register is
+compatible with a given physical, this code can be used:
+
+.. code-block:: c++
+
+  bool RegMapping_Fer::compatible_class(MachineFunction &mf,
+                                        unsigned v_reg,
+                                        unsigned p_reg) {
+    assert(TargetRegisterInfo::isPhysicalRegister(p_reg) &&
+           "Target register must be physical");
+    const TargetRegisterClass *trc = mf.getRegInfo().getRegClass(v_reg);
+    return trc->contains(p_reg);
+  }
+
+Sometimes, mostly for debugging purposes, it is useful to change the number of
+physical registers available in the target architecture. This must be done
+statically, inside the ``TargetRegsterInfo.td`` file. Just ``grep`` for
+``RegisterClass``, the last parameter of which is a list of registers. Just
+commenting some out is one simple way to avoid them being used. A more polite
+way is to explicitly exclude some registers from the *allocation order*. See the
+definition of the ``GR8`` register class in
+``lib/Target/X86/X86RegisterInfo.td`` for an example of this.
+
+Virtual registers are also denoted by integer numbers. Contrary to physical
+registers, different virtual registers never share the same number. Whereas
+physical registers are statically defined in a ``TargetRegisterInfo.td`` file
+and cannot be created by the application developer, that is not the case with
+virtual registers. In order to create new virtual registers, use the method
+``MachineRegisterInfo::createVirtualRegister()``. This method will return a new
+virtual register. Use an ``IndexedMap<Foo, VirtReg2IndexFunctor>`` to hold
+information per virtual register. If you need to enumerate all virtual
+registers, use the function ``TargetRegisterInfo::index2VirtReg()`` to find the
+virtual register numbers:
+
+.. code-block:: c++
+
+    for (unsigned i = 0, e = MRI->getNumVirtRegs(); i != e; ++i) {
+      unsigned VirtReg = TargetRegisterInfo::index2VirtReg(i);
+      stuff(VirtReg);
+    }
+
+Before register allocation, the operands of an instruction are mostly virtual
+registers, although physical registers may also be used. In order to check if a
+given machine operand is a register, use the boolean function
+``MachineOperand::isRegister()``. To obtain the integer code of a register, use
+``MachineOperand::getReg()``. An instruction may define or use a register. For
+instance, ``ADD reg:1026 := reg:1025 reg:1024`` defines the registers 1024, and
+uses registers 1025 and 1026. Given a register operand, the method
+``MachineOperand::isUse()`` informs if that register is being used by the
+instruction. The method ``MachineOperand::isDef()`` informs if that registers is
+being defined.
+
+We will call physical registers present in the LLVM bitcode before register
+allocation *pre-colored registers*. Pre-colored registers are used in many
+different situations, for instance, to pass parameters of functions calls, and
+to store results of particular instructions. There are two types of pre-colored
+registers: the ones *implicitly* defined, and those *explicitly*
+defined. Explicitly defined registers are normal operands, and can be accessed
+with ``MachineInstr::getOperand(int)::getReg()``.  In order to check which
+registers are implicitly defined by an instruction, use the
+``TargetInstrInfo::get(opcode)::ImplicitDefs``, where ``opcode`` is the opcode
+of the target instruction. One important difference between explicit and
+implicit physical registers is that the latter are defined statically for each
+instruction, whereas the former may vary depending on the program being
+compiled. For example, an instruction that represents a function call will
+always implicitly define or use the same set of physical registers. To read the
+registers implicitly used by an instruction, use
+``TargetInstrInfo::get(opcode)::ImplicitUses``. Pre-colored registers impose
+constraints on any register allocation algorithm. The register allocator must
+make sure that none of them are overwritten by the values of virtual registers
+while still alive.
+
+Mapping virtual registers to physical registers
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+There are two ways to map virtual registers to physical registers (or to memory
+slots). The first way, that we will call *direct mapping*, is based on the use
+of methods of the classes ``TargetRegisterInfo``, and ``MachineOperand``. The
+second way, that we will call *indirect mapping*, relies on the ``VirtRegMap``
+class in order to insert loads and stores sending and getting values to and from
+memory.
+
+The direct mapping provides more flexibility to the developer of the register
+allocator; however, it is more error prone, and demands more implementation
+work.  Basically, the programmer will have to specify where load and store
+instructions should be inserted in the target function being compiled in order
+to get and store values in memory. To assign a physical register to a virtual
+register present in a given operand, use ``MachineOperand::setReg(p_reg)``. To
+insert a store instruction, use ``TargetInstrInfo::storeRegToStackSlot(...)``,
+and to insert a load instruction, use ``TargetInstrInfo::loadRegFromStackSlot``.
+
+The indirect mapping shields the application developer from the complexities of
+inserting load and store instructions. In order to map a virtual register to a
+physical one, use ``VirtRegMap::assignVirt2Phys(vreg, preg)``.  In order to map
+a certain virtual register to memory, use
+``VirtRegMap::assignVirt2StackSlot(vreg)``. This method will return the stack
+slot where ``vreg``'s value will be located.  If it is necessary to map another
+virtual register to the same stack slot, use
+``VirtRegMap::assignVirt2StackSlot(vreg, stack_location)``. One important point
+to consider when using the indirect mapping, is that even if a virtual register
+is mapped to memory, it still needs to be mapped to a physical register. This
+physical register is the location where the virtual register is supposed to be
+found before being stored or after being reloaded.
+
+If the indirect strategy is used, after all the virtual registers have been
+mapped to physical registers or stack slots, it is necessary to use a spiller
+object to place load and store instructions in the code. Every virtual that has
+been mapped to a stack slot will be stored to memory after being defined and will
+be loaded before being used. The implementation of the spiller tries to recycle
+load/store instructions, avoiding unnecessary instructions. For an example of
+how to invoke the spiller, see ``RegAllocLinearScan::runOnMachineFunction`` in
+``lib/CodeGen/RegAllocLinearScan.cpp``.
+
+Handling two address instructions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+With very rare exceptions (e.g., function calls), the LLVM machine code
+instructions are three address instructions. That is, each instruction is
+expected to define at most one register, and to use at most two registers.
+However, some architectures use two address instructions. In this case, the
+defined register is also one of the used registers. For instance, an instruction
+such as ``ADD %EAX, %EBX``, in X86 is actually equivalent to ``%EAX = %EAX +
+%EBX``.
+
+In order to produce correct code, LLVM must convert three address instructions
+that represent two address instructions into true two address instructions. LLVM
+provides the pass ``TwoAddressInstructionPass`` for this specific purpose. It
+must be run before register allocation takes place. After its execution, the
+resulting code may no longer be in SSA form. This happens, for instance, in
+situations where an instruction such as ``%a = ADD %b %c`` is converted to two
+instructions such as:
+
+::
+
+  %a = MOVE %b
+  %a = ADD %a %c
+
+Notice that, internally, the second instruction is represented as ``ADD
+%a[def/use] %c``. I.e., the register operand ``%a`` is both used and defined by
+the instruction.
+
+The SSA deconstruction phase
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+An important transformation that happens during register allocation is called
+the *SSA Deconstruction Phase*. The SSA form simplifies many analyses that are
+performed on the control flow graph of programs. However, traditional
+instruction sets do not implement PHI instructions. Thus, in order to generate
+executable code, compilers must replace PHI instructions with other instructions
+that preserve their semantics.
+
+There are many ways in which PHI instructions can safely be removed from the
+target code. The most traditional PHI deconstruction algorithm replaces PHI
+instructions with copy instructions. That is the strategy adopted by LLVM. The
+SSA deconstruction algorithm is implemented in
+``lib/CodeGen/PHIElimination.cpp``. In order to invoke this pass, the identifier
+``PHIEliminationID`` must be marked as required in the code of the register
+allocator.
+
+Instruction folding
+^^^^^^^^^^^^^^^^^^^
+
+*Instruction folding* is an optimization performed during register allocation
+that removes unnecessary copy instructions. For instance, a sequence of
+instructions such as:
+
+::
+
+  %EBX = LOAD %mem_address
+  %EAX = COPY %EBX
+
+can be safely substituted by the single instruction:
+
+::
+
+  %EAX = LOAD %mem_address
+
+Instructions can be folded with the
+``TargetRegisterInfo::foldMemoryOperand(...)`` method. Care must be taken when
+folding instructions; a folded instruction can be quite different from the
+original instruction. See ``LiveIntervals::addIntervalsForSpills`` in
+``lib/CodeGen/LiveIntervalAnalysis.cpp`` for an example of its use.
+
+Built in register allocators
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The LLVM infrastructure provides the application developer with three different
+register allocators:
+
+* *Fast* --- This register allocator is the default for debug builds. It
+  allocates registers on a basic block level, attempting to keep values in
+  registers and reusing registers as appropriate.
+
+* *Basic* --- This is an incremental approach to register allocation. Live
+  ranges are assigned to registers one at a time in an order that is driven by
+  heuristics. Since code can be rewritten on-the-fly during allocation, this
+  framework allows interesting allocators to be developed as extensions. It is
+  not itself a production register allocator but is a potentially useful
+  stand-alone mode for triaging bugs and as a performance baseline.
+
+* *Greedy* --- *The default allocator*. This is a highly tuned implementation of
+  the *Basic* allocator that incorporates global live range splitting. This
+  allocator works hard to minimize the cost of spill code.
+
+* *PBQP* --- A Partitioned Boolean Quadratic Programming (PBQP) based register
+  allocator. This allocator works by constructing a PBQP problem representing
+  the register allocation problem under consideration, solving this using a PBQP
+  solver, and mapping the solution back to a register assignment.
+
+The type of register allocator used in ``llc`` can be chosen with the command
+line option ``-regalloc=...``:
+
+.. code-block:: bash
+
+  $ llc -regalloc=linearscan file.bc -o ln.s
+  $ llc -regalloc=fast file.bc -o fa.s
+  $ llc -regalloc=pbqp file.bc -o pbqp.s
+
+.. _Prolog/Epilog Code Insertion:
+
+Prolog/Epilog Code Insertion
+----------------------------
+
+Compact Unwind
+
+Throwing an exception requires *unwinding* out of a function. The information on
+how to unwind a given function is traditionally expressed in DWARF unwind
+(a.k.a. frame) info. But that format was originally developed for debuggers to
+backtrace, and each Frame Description Entry (FDE) requires ~20-30 bytes per
+function. There is also the cost of mapping from an address in a function to the
+corresponding FDE at runtime. An alternative unwind encoding is called *compact
+unwind* and requires just 4-bytes per function.
+
+The compact unwind encoding is a 32-bit value, which is encoded in an
+architecture-specific way. It specifies which registers to restore and from
+where, and how to unwind out of the function. When the linker creates a final
+linked image, it will create a ``__TEXT,__unwind_info`` section. This section is
+a small and fast way for the runtime to access unwind info for any given
+function. If we emit compact unwind info for the function, that compact unwind
+info will be encoded in the ``__TEXT,__unwind_info`` section. If we emit DWARF
+unwind info, the ``__TEXT,__unwind_info`` section will contain the offset of the
+FDE in the ``__TEXT,__eh_frame`` section in the final linked image.
+
+For X86, there are three modes for the compact unwind encoding:
+
+*Function with a Frame Pointer (``EBP`` or ``RBP``)*
+  ``EBP/RBP``-based frame, where ``EBP/RBP`` is pushed onto the stack
+  immediately after the return address, then ``ESP/RSP`` is moved to
+  ``EBP/RBP``. Thus to unwind, ``ESP/RSP`` is restored with the current
+  ``EBP/RBP`` value, then ``EBP/RBP`` is restored by popping the stack, and the
+  return is done by popping the stack once more into the PC. All non-volatile
+  registers that need to be restored must have been saved in a small range on
+  the stack that starts ``EBP-4`` to ``EBP-1020`` (``RBP-8`` to
+  ``RBP-1020``). The offset (divided by 4 in 32-bit mode and 8 in 64-bit mode)
+  is encoded in bits 16-23 (mask: ``0x00FF0000``).  The registers saved are
+  encoded in bits 0-14 (mask: ``0x00007FFF``) as five 3-bit entries from the
+  following table:
+
+    ==============  =============  ===============
+    Compact Number  i386 Register  x86-64 Register
+    ==============  =============  ===============
+    1               ``EBX``        ``RBX``
+    2               ``ECX``        ``R12``
+    3               ``EDX``        ``R13``
+    4               ``EDI``        ``R14``
+    5               ``ESI``        ``R15``
+    6               ``EBP``        ``RBP``
+    ==============  =============  ===============
+
+*Frameless with a Small Constant Stack Size (``EBP`` or ``RBP`` is not used as a frame pointer)*
+  To return, a constant (encoded in the compact unwind encoding) is added to the
+  ``ESP/RSP``.  Then the return is done by popping the stack into the PC. All
+  non-volatile registers that need to be restored must have been saved on the
+  stack immediately after the return address. The stack size (divided by 4 in
+  32-bit mode and 8 in 64-bit mode) is encoded in bits 16-23 (mask:
+  ``0x00FF0000``). There is a maximum stack size of 1024 bytes in 32-bit mode
+  and 2048 in 64-bit mode. The number of registers saved is encoded in bits 9-12
+  (mask: ``0x00001C00``). Bits 0-9 (mask: ``0x000003FF``) contain which
+  registers were saved and their order. (See the
+  ``encodeCompactUnwindRegistersWithoutFrame()`` function in
+  ``lib/Target/X86FrameLowering.cpp`` for the encoding algorithm.)
+
+*Frameless with a Large Constant Stack Size (``EBP`` or ``RBP`` is not used as a frame pointer)*
+  This case is like the "Frameless with a Small Constant Stack Size" case, but
+  the stack size is too large to encode in the compact unwind encoding. Instead
+  it requires that the function contains "``subl $nnnnnn, %esp``" in its
+  prolog. The compact encoding contains the offset to the ``$nnnnnn`` value in
+  the function in bits 9-12 (mask: ``0x00001C00``).
+
+.. _Late Machine Code Optimizations:
+
+Late Machine Code Optimizations
+-------------------------------
+
+.. note::
+
+  To Be Written
+
+.. _Code Emission:
+
+Code Emission
+-------------
+
+The code emission step of code generation is responsible for lowering from the
+code generator abstractions (like `MachineFunction`_, `MachineInstr`_, etc) down
+to the abstractions used by the MC layer (`MCInst`_, `MCStreamer`_, etc).  This
+is done with a combination of several different classes: the (misnamed)
+target-independent AsmPrinter class, target-specific subclasses of AsmPrinter
+(such as SparcAsmPrinter), and the TargetLoweringObjectFile class.
+
+Since the MC layer works at the level of abstraction of object files, it doesn't
+have a notion of functions, global variables etc.  Instead, it thinks about
+labels, directives, and instructions.  A key class used at this time is the
+MCStreamer class.  This is an abstract API that is implemented in different ways
+(e.g. to output a .s file, output an ELF .o file, etc) that is effectively an
+"assembler API".  MCStreamer has one method per directive, such as EmitLabel,
+EmitSymbolAttribute, SwitchSection, etc, which directly correspond to assembly
+level directives.
+
+If you are interested in implementing a code generator for a target, there are
+three important things that you have to implement for your target:
+
+#. First, you need a subclass of AsmPrinter for your target.  This class
+   implements the general lowering process converting MachineFunction's into MC
+   label constructs.  The AsmPrinter base class provides a number of useful
+   methods and routines, and also allows you to override the lowering process in
+   some important ways.  You should get much of the lowering for free if you are
+   implementing an ELF, COFF, or MachO target, because the
+   TargetLoweringObjectFile class implements much of the common logic.
+
+#. Second, you need to implement an instruction printer for your target.  The
+   instruction printer takes an `MCInst`_ and renders it to a raw_ostream as
+   text.  Most of this is automatically generated from the .td file (when you
+   specify something like "``add $dst, $src1, $src2``" in the instructions), but
+   you need to implement routines to print operands.
+
+#. Third, you need to implement code that lowers a `MachineInstr`_ to an MCInst,
+   usually implemented in "<target>MCInstLower.cpp".  This lowering process is
+   often target specific, and is responsible for turning jump table entries,
+   constant pool indices, global variable addresses, etc into MCLabels as
+   appropriate.  This translation layer is also responsible for expanding pseudo
+   ops used by the code generator into the actual machine instructions they
+   correspond to. The MCInsts that are generated by this are fed into the
+   instruction printer or the encoder.
+
+Finally, at your choosing, you can also implement a subclass of MCCodeEmitter
+which lowers MCInst's into machine code bytes and relocations.  This is
+important if you want to support direct .o file emission, or would like to
+implement an assembler for your target.
+
+Emitting function stack size information
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A section containing metadata on function stack sizes will be emitted when
+``TargetLoweringObjectFile::StackSizesSection`` is not null, and
+``TargetOptions::EmitStackSizeSection`` is set (-stack-size-section). The
+section will contain an array of pairs of function symbol values (pointer size)
+and stack sizes (unsigned LEB128). The stack size values only include the space
+allocated in the function prologue. Functions with dynamic stack allocations are
+not included.
+
+VLIW Packetizer
+---------------
+
+In a Very Long Instruction Word (VLIW) architecture, the compiler is responsible
+for mapping instructions to functional-units available on the architecture. To
+that end, the compiler creates groups of instructions called *packets* or
+*bundles*. The VLIW packetizer in LLVM is a target-independent mechanism to
+enable the packetization of machine instructions.
+
+Mapping from instructions to functional units
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Instructions in a VLIW target can typically be mapped to multiple functional
+units. During the process of packetizing, the compiler must be able to reason
+about whether an instruction can be added to a packet. This decision can be
+complex since the compiler has to examine all possible mappings of instructions
+to functional units. Therefore to alleviate compilation-time complexity, the
+VLIW packetizer parses the instruction classes of a target and generates tables
+at compiler build time. These tables can then be queried by the provided
+machine-independent API to determine if an instruction can be accommodated in a
+packet.
+
+How the packetization tables are generated and used
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The packetizer reads instruction classes from a target's itineraries and creates
+a deterministic finite automaton (DFA) to represent the state of a packet. A DFA
+consists of three major elements: inputs, states, and transitions. The set of
+inputs for the generated DFA represents the instruction being added to a
+packet. The states represent the possible consumption of functional units by
+instructions in a packet. In the DFA, transitions from one state to another
+occur on the addition of an instruction to an existing packet. If there is a
+legal mapping of functional units to instructions, then the DFA contains a
+corresponding transition. The absence of a transition indicates that a legal
+mapping does not exist and that the instruction cannot be added to the packet.
+
+To generate tables for a VLIW target, add *Target*\ GenDFAPacketizer.inc as a
+target to the Makefile in the target directory. The exported API provides three
+functions: ``DFAPacketizer::clearResources()``,
+``DFAPacketizer::reserveResources(MachineInstr *MI)``, and
+``DFAPacketizer::canReserveResources(MachineInstr *MI)``. These functions allow
+a target packetizer to add an instruction to an existing packet and to check
+whether an instruction can be added to a packet. See
+``llvm/CodeGen/DFAPacketizer.h`` for more information.
+
+Implementing a Native Assembler
+===============================
+
+Though you're probably reading this because you want to write or maintain a
+compiler backend, LLVM also fully supports building a native assembler.
+We've tried hard to automate the generation of the assembler from the .td files
+(in particular the instruction syntax and encodings), which means that a large
+part of the manual and repetitive data entry can be factored and shared with the
+compiler.
+
+Instruction Parsing
+-------------------
+
+.. note::
+
+  To Be Written
+
+
+Instruction Alias Processing
+----------------------------
+
+Once the instruction is parsed, it enters the MatchInstructionImpl function.
+The MatchInstructionImpl function performs alias processing and then does actual
+matching.
+
+Alias processing is the phase that canonicalizes different lexical forms of the
+same instructions down to one representation.  There are several different kinds
+of alias that are possible to implement and they are listed below in the order
+that they are processed (which is in order from simplest/weakest to most
+complex/powerful).  Generally you want to use the first alias mechanism that
+meets the needs of your instruction, because it will allow a more concise
+description.
+
+Mnemonic Aliases
+^^^^^^^^^^^^^^^^
+
+The first phase of alias processing is simple instruction mnemonic remapping for
+classes of instructions which are allowed with two different mnemonics.  This
+phase is a simple and unconditionally remapping from one input mnemonic to one
+output mnemonic.  It isn't possible for this form of alias to look at the
+operands at all, so the remapping must apply for all forms of a given mnemonic.
+Mnemonic aliases are defined simply, for example X86 has:
+
+::
+
+  def : MnemonicAlias<"cbw",     "cbtw">;
+  def : MnemonicAlias<"smovq",   "movsq">;
+  def : MnemonicAlias<"fldcww",  "fldcw">;
+  def : MnemonicAlias<"fucompi", "fucomip">;
+  def : MnemonicAlias<"ud2a",    "ud2">;
+
+... and many others.  With a MnemonicAlias definition, the mnemonic is remapped
+simply and directly.  Though MnemonicAlias's can't look at any aspect of the
+instruction (such as the operands) they can depend on global modes (the same
+ones supported by the matcher), through a Requires clause:
+
+::
+
+  def : MnemonicAlias<"pushf", "pushfq">, Requires<[In64BitMode]>;
+  def : MnemonicAlias<"pushf", "pushfl">, Requires<[In32BitMode]>;
+
+In this example, the mnemonic gets mapped into a different one depending on
+the current instruction set.
+
+Instruction Aliases
+^^^^^^^^^^^^^^^^^^^
+
+The most general phase of alias processing occurs while matching is happening:
+it provides new forms for the matcher to match along with a specific instruction
+to generate.  An instruction alias has two parts: the string to match and the
+instruction to generate.  For example:
+
+::
+
+  def : InstAlias<"movsx $src, $dst", (MOVSX16rr8W GR16:$dst, GR8  :$src)>;
+  def : InstAlias<"movsx $src, $dst", (MOVSX16rm8W GR16:$dst, i8mem:$src)>;
+  def : InstAlias<"movsx $src, $dst", (MOVSX32rr8  GR32:$dst, GR8  :$src)>;
+  def : InstAlias<"movsx $src, $dst", (MOVSX32rr16 GR32:$dst, GR16 :$src)>;
+  def : InstAlias<"movsx $src, $dst", (MOVSX64rr8  GR64:$dst, GR8  :$src)>;
+  def : InstAlias<"movsx $src, $dst", (MOVSX64rr16 GR64:$dst, GR16 :$src)>;
+  def : InstAlias<"movsx $src, $dst", (MOVSX64rr32 GR64:$dst, GR32 :$src)>;
+
+This shows a powerful example of the instruction aliases, matching the same
+mnemonic in multiple different ways depending on what operands are present in
+the assembly.  The result of instruction aliases can include operands in a
+different order than the destination instruction, and can use an input multiple
+times, for example:
+
+::
+
+  def : InstAlias<"clrb $reg", (XOR8rr  GR8 :$reg, GR8 :$reg)>;
+  def : InstAlias<"clrw $reg", (XOR16rr GR16:$reg, GR16:$reg)>;
+  def : InstAlias<"clrl $reg", (XOR32rr GR32:$reg, GR32:$reg)>;
+  def : InstAlias<"clrq $reg", (XOR64rr GR64:$reg, GR64:$reg)>;
+
+This example also shows that tied operands are only listed once.  In the X86
+backend, XOR8rr has two input GR8's and one output GR8 (where an input is tied
+to the output).  InstAliases take a flattened operand list without duplicates
+for tied operands.  The result of an instruction alias can also use immediates
+and fixed physical registers which are added as simple immediate operands in the
+result, for example:
+
+::
+
+  // Fixed Immediate operand.
+  def : InstAlias<"aad", (AAD8i8 10)>;
+
+  // Fixed register operand.
+  def : InstAlias<"fcomi", (COM_FIr ST1)>;
+
+  // Simple alias.
+  def : InstAlias<"fcomi $reg", (COM_FIr RST:$reg)>;
+
+Instruction aliases can also have a Requires clause to make them subtarget
+specific.
+
+If the back-end supports it, the instruction printer can automatically emit the
+alias rather than what's being aliased. It typically leads to better, more
+readable code. If it's better to print out what's being aliased, then pass a '0'
+as the third parameter to the InstAlias definition.
+
+Instruction Matching
+--------------------
+
+.. note::
+
+  To Be Written
+
+.. _Implementations of the abstract target description interfaces:
+.. _implement the target description:
+
+Target-specific Implementation Notes
+====================================
+
+This section of the document explains features or design decisions that are
+specific to the code generator for a particular target.  First we start with a
+table that summarizes what features are supported by each target.
+
+.. _target-feature-matrix:
+
+Target Feature Matrix
+---------------------
+
+Note that this table does not list features that are not supported fully by any
+target yet.  It considers a feature to be supported if at least one subtarget
+supports it.  A feature being supported means that it is useful and works for
+most cases, it does not indicate that there are zero known bugs in the
+implementation.  Here is the key:
+
+: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>`
+:raw-html:`</tr>`
+:raw-html:`</table>`
+
+Here is the table:
+
+:raw-html:`<table width="689" border="1" cellspacing="0">`
+:raw-html:`<tr><td></td>`
+:raw-html:`<td colspan="13" align="center" style="background-color:#ffc">Target</td>`
+:raw-html:`</tr>`
+:raw-html:`<tr>`
+:raw-html:`<th>Feature</th>`
+:raw-html:`<th>ARM</th>`
+:raw-html:`<th>Hexagon</th>`
+:raw-html:`<th>MSP430</th>`
+:raw-html:`<th>Mips</th>`
+:raw-html:`<th>NVPTX</th>`
+:raw-html:`<th>PowerPC</th>`
+:raw-html:`<th>Sparc</th>`
+:raw-html:`<th>SystemZ</th>`
+:raw-html:`<th>X86</th>`
+:raw-html:`<th>XCore</th>`
+:raw-html:`<th>eBPF</th>`
+:raw-html:`</tr>`
+
+:raw-html:`<tr>`
+:raw-html:`<td><a href="#feat_reliable">is generally reliable</a></td>`
+:raw-html:`<td class="yes"></td> <!-- ARM -->`
+:raw-html:`<td class="yes"></td> <!-- Hexagon -->`
+:raw-html:`<td class="unknown"></td> <!-- MSP430 -->`
+:raw-html:`<td class="yes"></td> <!-- Mips -->`
+:raw-html:`<td class="yes"></td> <!-- NVPTX -->`
+:raw-html:`<td class="yes"></td> <!-- PowerPC -->`
+:raw-html:`<td class="yes"></td> <!-- Sparc -->`
+:raw-html:`<td class="yes"></td> <!-- SystemZ -->`
+:raw-html:`<td class="yes"></td> <!-- X86 -->`
+:raw-html:`<td class="yes"></td> <!-- XCore -->`
+:raw-html:`<td class="yes"></td> <!-- eBPF -->`
+:raw-html:`</tr>`
+
+:raw-html:`<tr>`
+:raw-html:`<td><a href="#feat_asmparser">assembly parser</a></td>`
+:raw-html:`<td class="no"></td> <!-- ARM -->`
+:raw-html:`<td class="no"></td> <!-- Hexagon -->`
+:raw-html:`<td class="no"></td> <!-- MSP430 -->`
+:raw-html:`<td class="no"></td> <!-- Mips -->`
+:raw-html:`<td class="no"></td> <!-- NVPTX -->`
+:raw-html:`<td class="no"></td> <!-- PowerPC -->`
+:raw-html:`<td class="no"></td> <!-- Sparc -->`
+:raw-html:`<td class="yes"></td> <!-- SystemZ -->`
+:raw-html:`<td class="yes"></td> <!-- X86 -->`
+:raw-html:`<td class="no"></td> <!-- XCore -->`
+:raw-html:`<td class="no"></td> <!-- eBPF -->`
+:raw-html:`</tr>`
+
+:raw-html:`<tr>`
+:raw-html:`<td><a href="#feat_disassembler">disassembler</a></td>`
+:raw-html:`<td class="yes"></td> <!-- ARM -->`
+:raw-html:`<td class="no"></td> <!-- Hexagon -->`
+:raw-html:`<td class="no"></td> <!-- MSP430 -->`
+:raw-html:`<td class="no"></td> <!-- Mips -->`
+:raw-html:`<td class="na"></td> <!-- NVPTX -->`
+:raw-html:`<td class="no"></td> <!-- PowerPC -->`
+:raw-html:`<td class="yes"></td> <!-- SystemZ -->`
+:raw-html:`<td class="no"></td> <!-- Sparc -->`
+:raw-html:`<td class="yes"></td> <!-- X86 -->`
+:raw-html:`<td class="yes"></td> <!-- XCore -->`
+:raw-html:`<td class="yes"></td> <!-- eBPF -->`
+:raw-html:`</tr>`
+
+:raw-html:`<tr>`
+:raw-html:`<td><a href="#feat_inlineasm">inline asm</a></td>`
+:raw-html:`<td class="yes"></td> <!-- ARM -->`
+:raw-html:`<td class="yes"></td> <!-- Hexagon -->`
+:raw-html:`<td class="unknown"></td> <!-- MSP430 -->`
+:raw-html:`<td class="no"></td> <!-- Mips -->`
+:raw-html:`<td class="yes"></td> <!-- NVPTX -->`
+:raw-html:`<td class="yes"></td> <!-- PowerPC -->`
+:raw-html:`<td class="unknown"></td> <!-- Sparc -->`
+:raw-html:`<td class="yes"></td> <!-- SystemZ -->`
+:raw-html:`<td class="yes"></td> <!-- X86 -->`
+:raw-html:`<td class="yes"></td> <!-- XCore -->`
+:raw-html:`<td class="no"></td> <!-- eBPF -->`
+:raw-html:`</tr>`
+
+:raw-html:`<tr>`
+:raw-html:`<td><a href="#feat_jit">jit</a></td>`
+:raw-html:`<td class="partial"><a href="#feat_jit_arm">*</a></td> <!-- ARM -->`
+:raw-html:`<td class="no"></td> <!-- Hexagon -->`
+:raw-html:`<td class="unknown"></td> <!-- MSP430 -->`
+:raw-html:`<td class="yes"></td> <!-- Mips -->`
+:raw-html:`<td class="na"></td> <!-- NVPTX -->`
+:raw-html:`<td class="yes"></td> <!-- PowerPC -->`
+:raw-html:`<td class="unknown"></td> <!-- Sparc -->`
+:raw-html:`<td class="yes"></td> <!-- SystemZ -->`
+:raw-html:`<td class="yes"></td> <!-- X86 -->`
+:raw-html:`<td class="no"></td> <!-- XCore -->`
+:raw-html:`<td class="yes"></td> <!-- eBPF -->`
+:raw-html:`</tr>`
+
+:raw-html:`<tr>`
+:raw-html:`<td><a href="#feat_objectwrite">.o file writing</a></td>`
+:raw-html:`<td class="no"></td> <!-- ARM -->`
+:raw-html:`<td class="no"></td> <!-- Hexagon -->`
+:raw-html:`<td class="no"></td> <!-- MSP430 -->`
+:raw-html:`<td class="no"></td> <!-- Mips -->`
+:raw-html:`<td class="na"></td> <!-- NVPTX -->`
+:raw-html:`<td class="no"></td> <!-- PowerPC -->`
+:raw-html:`<td class="no"></td> <!-- Sparc -->`
+:raw-html:`<td class="yes"></td> <!-- SystemZ -->`
+:raw-html:`<td class="yes"></td> <!-- X86 -->`
+:raw-html:`<td class="no"></td> <!-- XCore -->`
+:raw-html:`<td class="yes"></td> <!-- eBPF -->`
+:raw-html:`</tr>`
+
+:raw-html:`<tr>`
+:raw-html:`<td><a hr:raw-html:`ef="#feat_tailcall">tail calls</a></td>`
+:raw-html:`<td class="yes"></td> <!-- ARM -->`
+:raw-html:`<td class="yes"></td> <!-- Hexagon -->`
+:raw-html:`<td class="unknown"></td> <!-- MSP430 -->`
+:raw-html:`<td class="no"></td> <!-- Mips -->`
+:raw-html:`<td class="no"></td> <!-- NVPTX -->`
+:raw-html:`<td class="yes"></td> <!-- PowerPC -->`
+:raw-html:`<td class="unknown"></td> <!-- Sparc -->`
+:raw-html:`<td class="no"></td> <!-- SystemZ -->`
+:raw-html:`<td class="yes"></td> <!-- X86 -->`
+:raw-html:`<td class="no"></td> <!-- XCore -->`
+:raw-html:`<td class="no"></td> <!-- eBPF -->`
+:raw-html:`</tr>`
+
+:raw-html:`<tr>`
+:raw-html:`<td><a href="#feat_segstacks">segmented stacks</a></td>`
+:raw-html:`<td class="no"></td> <!-- ARM -->`
+:raw-html:`<td class="no"></td> <!-- Hexagon -->`
+:raw-html:`<td class="no"></td> <!-- MSP430 -->`
+:raw-html:`<td class="no"></td> <!-- Mips -->`
+:raw-html:`<td class="no"></td> <!-- NVPTX -->`
+:raw-html:`<td class="no"></td> <!-- PowerPC -->`
+:raw-html:`<td class="no"></td> <!-- Sparc -->`
+:raw-html:`<td class="no"></td> <!-- SystemZ -->`
+:raw-html:`<td class="partial"><a href="#feat_segstacks_x86">*</a></td> <!-- X86 -->`
+:raw-html:`<td class="no"></td> <!-- XCore -->`
+:raw-html:`<td class="no"></td> <!-- eBPF -->`
+:raw-html:`</tr>`
+
+:raw-html:`</table>`
+
+.. _feat_reliable:
+
+Is Generally Reliable
+^^^^^^^^^^^^^^^^^^^^^
+
+This box indicates whether the target is considered to be production quality.
+This indicates that the target has been used as a static compiler to compile
+large amounts of code by a variety of different people and is in continuous use.
+
+.. _feat_asmparser:
+
+Assembly Parser
+^^^^^^^^^^^^^^^
+
+This box indicates whether the target supports parsing target specific .s files
+by implementing the MCAsmParser interface.  This is required for llvm-mc to be
+able to act as a native assembler and is required for inline assembly support in
+the native .o file writer.
+
+.. _feat_disassembler:
+
+Disassembler
+^^^^^^^^^^^^
+
+This box indicates whether the target supports the MCDisassembler API for
+disassembling machine opcode bytes into MCInst's.
+
+.. _feat_inlineasm:
+
+Inline Asm
+^^^^^^^^^^
+
+This box indicates whether the target supports most popular inline assembly
+constraints and modifiers.
+
+.. _feat_jit:
+
+JIT Support
+^^^^^^^^^^^
+
+This box indicates whether the target supports the JIT compiler through the
+ExecutionEngine interface.
+
+.. _feat_jit_arm:
+
+The ARM backend has basic support for integer code in ARM codegen mode, but
+lacks NEON and full Thumb support.
+
+.. _feat_objectwrite:
+
+.o File Writing
+^^^^^^^^^^^^^^^
+
+This box indicates whether the target supports writing .o files (e.g. MachO,
+ELF, and/or COFF) files directly from the target.  Note that the target also
+must include an assembly parser and general inline assembly support for full
+inline assembly support in the .o writer.
+
+Targets that don't support this feature can obviously still write out .o files,
+they just rely on having an external assembler to translate from a .s file to a
+.o file (as is the case for many C compilers).
+
+.. _feat_tailcall:
+
+Tail Calls
+^^^^^^^^^^
+
+This box indicates whether the target supports guaranteed tail calls.  These are
+calls marked "`tail <LangRef.html#i_call>`_" and use the fastcc calling
+convention.  Please see the `tail call section`_ for more details.
+
+.. _feat_segstacks:
+
+Segmented Stacks
+^^^^^^^^^^^^^^^^
+
+This box indicates whether the target supports segmented stacks. This replaces
+the traditional large C stack with many linked segments. It is compatible with
+the `gcc implementation <http://gcc.gnu.org/wiki/SplitStacks>`_ used by the Go
+front end.
+
+.. _feat_segstacks_x86:
+
+Basic support exists on the X86 backend. Currently vararg doesn't work and the
+object files are not marked the way the gold linker expects, but simple Go
+programs can be built by dragonegg.
+
+.. _tail call section:
+
+Tail call optimization
+----------------------
+
+Tail call optimization, callee reusing the stack of the caller, is currently
+supported on x86/x86-64 and PowerPC. It is performed if:
+
+* Caller and callee have the calling convention ``fastcc``, ``cc 10`` (GHC
+  calling convention) or ``cc 11`` (HiPE calling convention).
+
+* The call is a tail call - in tail position (ret immediately follows call and
+  ret uses value of call or is void).
+
+* Option ``-tailcallopt`` is enabled.
+
+* Platform-specific constraints are met.
+
+x86/x86-64 constraints:
+
+* No variable argument lists are used.
+
+* On x86-64 when generating GOT/PIC code only module-local calls (visibility =
+  hidden or protected) are supported.
+
+PowerPC constraints:
+
+* No variable argument lists are used.
+
+* No byval parameters are used.
+
+* On ppc32/64 GOT/PIC only module-local calls (visibility = hidden or protected)
+  are supported.
+
+Example:
+
+Call as ``llc -tailcallopt test.ll``.
+
+.. code-block:: llvm
+
+  declare fastcc i32 @tailcallee(i32 inreg %a1, i32 inreg %a2, i32 %a3, i32 %a4)
+
+  define fastcc i32 @tailcaller(i32 %in1, i32 %in2) {
+    %l1 = add i32 %in1, %in2
+    %tmp = tail call fastcc i32 @tailcallee(i32 %in1 inreg, i32 %in2 inreg, i32 %in1, i32 %l1)
+    ret i32 %tmp
+  }
+
+Implications of ``-tailcallopt``:
+
+To support tail call optimization in situations where the callee has more
+arguments than the caller a 'callee pops arguments' convention is used. This
+currently causes each ``fastcc`` call that is not tail call optimized (because
+one or more of above constraints are not met) to be followed by a readjustment
+of the stack. So performance might be worse in such cases.
+
+Sibling call optimization
+-------------------------
+
+Sibling call optimization is a restricted form of tail call optimization.
+Unlike tail call optimization described in the previous section, it can be
+performed automatically on any tail calls when ``-tailcallopt`` option is not
+specified.
+
+Sibling call optimization is currently performed on x86/x86-64 when the
+following constraints are met:
+
+* Caller and callee have the same calling convention. It can be either ``c`` or
+  ``fastcc``.
+
+* The call is a tail call - in tail position (ret immediately follows call and
+  ret uses value of call or is void).
+
+* Caller and callee have matching return type or the callee result is not used.
+
+* If any of the callee arguments are being passed in stack, they must be
+  available in caller's own incoming argument stack and the frame offsets must
+  be the same.
+
+Example:
+
+.. code-block:: llvm
+
+  declare i32 @bar(i32, i32)
+
+  define i32 @foo(i32 %a, i32 %b, i32 %c) {
+  entry:
+    %0 = tail call i32 @bar(i32 %a, i32 %b)
+    ret i32 %0
+  }
+
+The X86 backend
+---------------
+
+The X86 code generator lives in the ``lib/Target/X86`` directory.  This code
+generator is capable of targeting a variety of x86-32 and x86-64 processors, and
+includes support for ISA extensions such as MMX and SSE.
+
+X86 Target Triples supported
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following are the known target triples that are supported by the X86
+backend.  This is not an exhaustive list, and it would be useful to add those
+that people test.
+
+* **i686-pc-linux-gnu** --- Linux
+
+* **i386-unknown-freebsd5.3** --- FreeBSD 5.3
+
+* **i686-pc-cygwin** --- Cygwin on Win32
+
+* **i686-pc-mingw32** --- MingW on Win32
+
+* **i386-pc-mingw32msvc** --- MingW crosscompiler on Linux
+
+* **i686-apple-darwin*** --- Apple Darwin on X86
+
+* **x86_64-unknown-linux-gnu** --- Linux
+
+X86 Calling Conventions supported
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following target-specific calling conventions are known to backend:
+
+* **x86_StdCall** --- stdcall calling convention seen on Microsoft Windows
+  platform (CC ID = 64).
+
+* **x86_FastCall** --- fastcall calling convention seen on Microsoft Windows
+  platform (CC ID = 65).
+
+* **x86_ThisCall** --- Similar to X86_StdCall. Passes first argument in ECX,
+  others via stack. Callee is responsible for stack cleaning. This convention is
+  used by MSVC by default for methods in its ABI (CC ID = 70).
+
+.. _X86 addressing mode:
+
+Representing X86 addressing modes in MachineInstrs
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The x86 has a very flexible way of accessing memory.  It is capable of forming
+memory addresses of the following expression directly in integer instructions
+(which use ModR/M addressing):
+
+::
+
+  SegmentReg: Base + [1,2,4,8] * IndexReg + Disp32
+
+In order to represent this, LLVM tracks no less than 5 operands for each memory
+operand of this form.  This means that the "load" form of '``mov``' has the
+following ``MachineOperand``\s in this order:
+
+::
+
+  Index:        0     |    1        2       3           4          5
+  Meaning:   DestReg, | BaseReg,  Scale, IndexReg, Displacement Segment
+  OperandTy: VirtReg, | VirtReg, UnsImm, VirtReg,   SignExtImm  PhysReg
+
+Stores, and all other instructions, treat the four memory operands in the same
+way and in the same order.  If the segment register is unspecified (regno = 0),
+then no segment override is generated.  "Lea" operations do not have a segment
+register specified, so they only have 4 operands for their memory reference.
+
+X86 address spaces supported
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+x86 has a feature which provides the ability to perform loads and stores to
+different address spaces via the x86 segment registers.  A segment override
+prefix byte on an instruction causes the instruction's memory access to go to
+the specified segment.  LLVM address space 0 is the default address space, which
+includes the stack, and any unqualified memory accesses in a program.  Address
+spaces 1-255 are currently reserved for user-defined code.  The GS-segment is
+represented by address space 256, the FS-segment is represented by address space
+257, and the SS-segment is represented by address space 258. Other x86 segments
+have yet to be allocated address space numbers.
+
+While these address spaces may seem similar to TLS via the ``thread_local``
+keyword, and often use the same underlying hardware, there are some fundamental
+differences.
+
+The ``thread_local`` keyword applies to global variables and specifies that they
+are to be allocated in thread-local memory. There are no type qualifiers
+involved, and these variables can be pointed to with normal pointers and
+accessed with normal loads and stores.  The ``thread_local`` keyword is
+target-independent at the LLVM IR level (though LLVM doesn't yet have
+implementations of it for some configurations)
+
+Special address spaces, in contrast, apply to static types. Every load and store
+has a particular address space in its address operand type, and this is what
+determines which address space is accessed.  LLVM ignores these special address
+space qualifiers on global variables, and does not provide a way to directly
+allocate storage in them.  At the LLVM IR level, the behavior of these special
+address spaces depends in part on the underlying OS or runtime environment, and
+they are specific to x86 (and LLVM doesn't yet handle them correctly in some
+cases).
+
+Some operating systems and runtime environments use (or may in the future use)
+the FS/GS-segment registers for various low-level purposes, so care should be
+taken when considering them.
+
+Instruction naming
+^^^^^^^^^^^^^^^^^^
+
+An instruction name consists of the base name, a default operand size, and a a
+character per operand with an optional special size. For example:
+
+::
+
+  ADD8rr      -> add, 8-bit register, 8-bit register
+  IMUL16rmi   -> imul, 16-bit register, 16-bit memory, 16-bit immediate
+  IMUL16rmi8  -> imul, 16-bit register, 16-bit memory, 8-bit immediate
+  MOVSX32rm16 -> movsx, 32-bit register, 16-bit memory
+
+The PowerPC backend
+-------------------
+
+The PowerPC code generator lives in the lib/Target/PowerPC directory.  The code
+generation is retargetable to several variations or *subtargets* of the PowerPC
+ISA; including ppc32, ppc64 and altivec.
+
+LLVM PowerPC ABI
+^^^^^^^^^^^^^^^^
+
+LLVM follows the AIX PowerPC ABI, with two deviations. LLVM uses a PC relative
+(PIC) or static addressing for accessing global values, so no TOC (r2) is
+used. Second, r31 is used as a frame pointer to allow dynamic growth of a stack
+frame.  LLVM takes advantage of having no TOC to provide space to save the frame
+pointer in the PowerPC linkage area of the caller frame.  Other details of
+PowerPC ABI can be found at `PowerPC ABI
+<http://developer.apple.com/documentation/DeveloperTools/Conceptual/LowLevelABI/Articles/32bitPowerPC.html>`_\
+. Note: This link describes the 32 bit ABI.  The 64 bit ABI is similar except
+space for GPRs are 8 bytes wide (not 4) and r13 is reserved for system use.
+
+Frame Layout
+^^^^^^^^^^^^
+
+The size of a PowerPC frame is usually fixed for the duration of a function's
+invocation.  Since the frame is fixed size, all references into the frame can be
+accessed via fixed offsets from the stack pointer.  The exception to this is
+when dynamic alloca or variable sized arrays are present, then a base pointer
+(r31) is used as a proxy for the stack pointer and stack pointer is free to grow
+or shrink.  A base pointer is also used if llvm-gcc is not passed the
+-fomit-frame-pointer flag. The stack pointer is always aligned to 16 bytes, so
+that space allocated for altivec vectors will be properly aligned.
+
+An invocation frame is laid out as follows (low memory at top):
+
+:raw-html:`<table border="1" cellspacing="0">`
+:raw-html:`<tr>`
+:raw-html:`<td>Linkage<br><br></td>`
+:raw-html:`</tr>`
+:raw-html:`<tr>`
+:raw-html:`<td>Parameter area<br><br></td>`
+:raw-html:`</tr>`
+:raw-html:`<tr>`
+:raw-html:`<td>Dynamic area<br><br></td>`
+:raw-html:`</tr>`
+:raw-html:`<tr>`
+:raw-html:`<td>Locals area<br><br></td>`
+:raw-html:`</tr>`
+:raw-html:`<tr>`
+:raw-html:`<td>Saved registers area<br><br></td>`
+:raw-html:`</tr>`
+:raw-html:`<tr style="border-style: none hidden none hidden;">`
+:raw-html:`<td><br></td>`
+:raw-html:`</tr>`
+:raw-html:`<tr>`
+:raw-html:`<td>Previous Frame<br><br></td>`
+:raw-html:`</tr>`
+:raw-html:`</table>`
+
+The *linkage* area is used by a callee to save special registers prior to
+allocating its own frame.  Only three entries are relevant to LLVM. The first
+entry is the previous stack pointer (sp), aka link.  This allows probing tools
+like gdb or exception handlers to quickly scan the frames in the stack.  A
+function epilog can also use the link to pop the frame from the stack.  The
+third entry in the linkage area is used to save the return address from the lr
+register. Finally, as mentioned above, the last entry is used to save the
+previous frame pointer (r31.)  The entries in the linkage area are the size of a
+GPR, thus the linkage area is 24 bytes long in 32 bit mode and 48 bytes in 64
+bit mode.
+
+32 bit linkage area:
+
+:raw-html:`<table  border="1" cellspacing="0">`
+:raw-html:`<tr>`
+:raw-html:`<td>0</td>`
+:raw-html:`<td>Saved SP (r1)</td>`
+:raw-html:`</tr>`
+:raw-html:`<tr>`
+:raw-html:`<td>4</td>`
+:raw-html:`<td>Saved CR</td>`
+:raw-html:`</tr>`
+:raw-html:`<tr>`
+:raw-html:`<td>8</td>`
+:raw-html:`<td>Saved LR</td>`
+:raw-html:`</tr>`
+:raw-html:`<tr>`
+:raw-html:`<td>12</td>`
+:raw-html:`<td>Reserved</td>`
+:raw-html:`</tr>`
+:raw-html:`<tr>`
+:raw-html:`<td>16</td>`
+:raw-html:`<td>Reserved</td>`
+:raw-html:`</tr>`
+:raw-html:`<tr>`
+:raw-html:`<td>20</td>`
+:raw-html:`<td>Saved FP (r31)</td>`
+:raw-html:`</tr>`
+:raw-html:`</table>`
+
+64 bit linkage area:
+
+:raw-html:`<table border="1" cellspacing="0">`
+:raw-html:`<tr>`
+:raw-html:`<td>0</td>`
+:raw-html:`<td>Saved SP (r1)</td>`
+:raw-html:`</tr>`
+:raw-html:`<tr>`
+:raw-html:`<td>8</td>`
+:raw-html:`<td>Saved CR</td>`
+:raw-html:`</tr>`
+:raw-html:`<tr>`
+:raw-html:`<td>16</td>`
+:raw-html:`<td>Saved LR</td>`
+:raw-html:`</tr>`
+:raw-html:`<tr>`
+:raw-html:`<td>24</td>`
+:raw-html:`<td>Reserved</td>`
+:raw-html:`</tr>`
+:raw-html:`<tr>`
+:raw-html:`<td>32</td>`
+:raw-html:`<td>Reserved</td>`
+:raw-html:`</tr>`
+:raw-html:`<tr>`
+:raw-html:`<td>40</td>`
+:raw-html:`<td>Saved FP (r31)</td>`
+:raw-html:`</tr>`
+:raw-html:`</table>`
+
+The *parameter area* is used to store arguments being passed to a callee
+function.  Following the PowerPC ABI, the first few arguments are actually
+passed in registers, with the space in the parameter area unused.  However, if
+there are not enough registers or the callee is a thunk or vararg function,
+these register arguments can be spilled into the parameter area.  Thus, the
+parameter area must be large enough to store all the parameters for the largest
+call sequence made by the caller.  The size must also be minimally large enough
+to spill registers r3-r10.  This allows callees blind to the call signature,
+such as thunks and vararg functions, enough space to cache the argument
+registers.  Therefore, the parameter area is minimally 32 bytes (64 bytes in 64
+bit mode.)  Also note that since the parameter area is a fixed offset from the
+top of the frame, that a callee can access its spilt arguments using fixed
+offsets from the stack pointer (or base pointer.)
+
+Combining the information about the linkage, parameter areas and alignment. A
+stack frame is minimally 64 bytes in 32 bit mode and 128 bytes in 64 bit mode.
+
+The *dynamic area* starts out as size zero.  If a function uses dynamic alloca
+then space is added to the stack, the linkage and parameter areas are shifted to
+top of stack, and the new space is available immediately below the linkage and
+parameter areas.  The cost of shifting the linkage and parameter areas is minor
+since only the link value needs to be copied.  The link value can be easily
+fetched by adding the original frame size to the base pointer.  Note that
+allocations in the dynamic space need to observe 16 byte alignment.
+
+The *locals area* is where the llvm compiler reserves space for local variables.
+
+The *saved registers area* is where the llvm compiler spills callee saved
+registers on entry to the callee.
+
+Prolog/Epilog
+^^^^^^^^^^^^^
+
+The llvm prolog and epilog are the same as described in the PowerPC ABI, with
+the following exceptions.  Callee saved registers are spilled after the frame is
+created.  This allows the llvm epilog/prolog support to be common with other
+targets.  The base pointer callee saved register r31 is saved in the TOC slot of
+linkage area.  This simplifies allocation of space for the base pointer and
+makes it convenient to locate programmatically and during debugging.
+
+Dynamic Allocation
+^^^^^^^^^^^^^^^^^^
+
+.. note::
+
+  TODO - More to come.
+
+The NVPTX backend
+-----------------
+
+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).
+
+This target is of production quality and should be completely compatible with
+the official NVIDIA toolchain.
+
+Code Generator Options:
+
+:raw-html:`<table border="1" cellspacing="0">`
+:raw-html:`<tr>`
+:raw-html:`<th>Option</th>`
+:raw-html:`<th>Description</th>`
+:raw-html:`</tr>`
+:raw-html:`<tr>`
+: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>ptx30</td>`
+:raw-html:`<td align="left">Target PTX 3.0</td>`
+:raw-html:`</tr>`
+:raw-html:`<tr>`
+:raw-html:`<td>ptx31</td>`
+:raw-html:`<td align="left">Target PTX 3.1</td>`
+:raw-html:`</tr>`
+:raw-html:`</table>`
+
+The extended Berkeley Packet Filter (eBPF) backend
+--------------------------------------------------
+
+Extended BPF (or eBPF) is similar to the original ("classic") BPF (cBPF) used
+to filter network packets.  The
+`bpf() system call <http://man7.org/linux/man-pages/man2/bpf.2.html>`_
+performs a range of operations related to eBPF.  For both cBPF and eBPF
+programs, the Linux kernel statically analyzes the programs before loading
+them, in order to ensure that they cannot harm the running system.  eBPF is
+a 64-bit RISC instruction set designed for one to one mapping to 64-bit CPUs.
+Opcodes are 8-bit encoded, and 87 instructions are defined.  There are 10
+registers, grouped by function as outlined below.
+
+::
+
+  R0        return value from in-kernel functions; exit value for eBPF program
+  R1 - R5   function call arguments to in-kernel functions
+  R6 - R9   callee-saved registers preserved by in-kernel functions
+  R10       stack frame pointer (read only)
+
+Instruction encoding (arithmetic and jump)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+eBPF is reusing most of the opcode encoding from classic to simplify conversion
+of classic BPF to eBPF.  For arithmetic and jump instructions the 8-bit 'code'
+field is divided into three parts:
+
+::
+
+  +----------------+--------+--------------------+
+  |   4 bits       |  1 bit |   3 bits           |
+  | operation code | source | instruction class  |
+  +----------------+--------+--------------------+
+  (MSB)                                      (LSB)
+
+Three LSB bits store instruction class which is one of:
+
+::
+
+  BPF_LD     0x0
+  BPF_LDX    0x1
+  BPF_ST     0x2
+  BPF_STX    0x3
+  BPF_ALU    0x4
+  BPF_JMP    0x5
+  (unused)   0x6
+  BPF_ALU64  0x7
+
+When BPF_CLASS(code) == BPF_ALU or BPF_ALU64 or BPF_JMP,
+4th bit encodes source operand
+
+::
+
+  BPF_X     0x0  use src_reg register as source operand
+  BPF_K     0x1  use 32 bit immediate as source operand
+
+and four MSB bits store operation code
+
+::
+
+  BPF_ADD   0x0  add
+  BPF_SUB   0x1  subtract
+  BPF_MUL   0x2  multiply
+  BPF_DIV   0x3  divide
+  BPF_OR    0x4  bitwise logical OR
+  BPF_AND   0x5  bitwise logical AND
+  BPF_LSH   0x6  left shift
+  BPF_RSH   0x7  right shift (zero extended)
+  BPF_NEG   0x8  arithmetic negation
+  BPF_MOD   0x9  modulo
+  BPF_XOR   0xa  bitwise logical XOR
+  BPF_MOV   0xb  move register to register
+  BPF_ARSH  0xc  right shift (sign extended)
+  BPF_END   0xd  endianness conversion
+
+If BPF_CLASS(code) == BPF_JMP, BPF_OP(code) is one of
+
+::
+
+  BPF_JA    0x0  unconditional jump
+  BPF_JEQ   0x1  jump ==
+  BPF_JGT   0x2  jump >
+  BPF_JGE   0x3  jump >=
+  BPF_JSET  0x4  jump if (DST & SRC)
+  BPF_JNE   0x5  jump !=
+  BPF_JSGT  0x6  jump signed >
+  BPF_JSGE  0x7  jump signed >=
+  BPF_CALL  0x8  function call
+  BPF_EXIT  0x9  function return
+
+Instruction encoding (load, store)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+For load and store instructions the 8-bit 'code' field is divided as:
+
+::
+
+  +--------+--------+-------------------+
+  | 3 bits | 2 bits |   3 bits          |
+  |  mode  |  size  | instruction class |
+  +--------+--------+-------------------+
+  (MSB)                             (LSB)
+
+Size modifier is one of
+
+::
+
+  BPF_W       0x0  word
+  BPF_H       0x1  half word
+  BPF_B       0x2  byte
+  BPF_DW      0x3  double word
+
+Mode modifier is one of
+
+::
+
+  BPF_IMM     0x0  immediate
+  BPF_ABS     0x1  used to access packet data
+  BPF_IND     0x2  used to access packet data
+  BPF_MEM     0x3  memory
+  (reserved)  0x4
+  (reserved)  0x5
+  BPF_XADD    0x6  exclusive add
+
+
+Packet data access (BPF_ABS, BPF_IND)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Two non-generic instructions: (BPF_ABS | <size> | BPF_LD) and
+(BPF_IND | <size> | BPF_LD) which are used to access packet data.
+Register R6 is an implicit input that must contain pointer to sk_buff.
+Register R0 is an implicit output which contains the data fetched
+from the packet.  Registers R1-R5 are scratch registers and must not
+be used to store the data across BPF_ABS | BPF_LD or BPF_IND | BPF_LD
+instructions.  These instructions have implicit program exit condition
+as well.  When eBPF program is trying to access the data beyond
+the packet boundary, the interpreter will abort the execution of the program.
+
+BPF_IND | BPF_W | BPF_LD is equivalent to:
+  R0 = ntohl(\*(u32 \*) (((struct sk_buff \*) R6)->data + src_reg + imm32))
+
+eBPF maps
+^^^^^^^^^
+
+eBPF maps are provided for sharing data between kernel and user-space.
+Currently implemented types are hash and array, with potential extension to
+support bloom filters, radix trees, etc.  A map is defined by its type,
+maximum number of elements, key size and value size in bytes.  eBPF syscall
+supports create, update, find and delete functions on maps.
+
+Function calls
+^^^^^^^^^^^^^^
+
+Function call arguments are passed using up to five registers (R1 - R5).
+The return value is passed in a dedicated register (R0).  Four additional
+registers (R6 - R9) are callee-saved, and the values in these registers
+are preserved within kernel functions.  R0 - R5 are scratch registers within
+kernel functions, and eBPF programs must therefor store/restore values in
+these registers if needed across function calls.  The stack can be accessed
+using the read-only frame pointer R10.  eBPF registers map 1:1 to hardware
+registers on x86_64 and other 64-bit architectures.  For example, x86_64
+in-kernel JIT maps them as
+
+::
+
+  R0 - rax
+  R1 - rdi
+  R2 - rsi
+  R3 - rdx
+  R4 - rcx
+  R5 - r8
+  R6 - rbx
+  R7 - r13
+  R8 - r14
+  R9 - r15
+  R10 - rbp
+
+since x86_64 ABI mandates rdi, rsi, rdx, rcx, r8, r9 for argument passing
+and rbx, r12 - r15 are callee saved.
+
+Program start
+^^^^^^^^^^^^^
+
+An eBPF program receives a single argument and contains
+a single eBPF main routine; the program does not contain eBPF functions.
+Function calls are limited to a predefined set of kernel functions.  The size
+of a program is limited to 4K instructions:  this ensures fast termination and
+a limited number of kernel function calls.  Prior to running an eBPF program,
+a verifier performs static analysis to prevent loops in the code and
+to ensure valid register usage and operand types.
+
+The AMDGPU backend
+------------------
+
+The AMDGPU code generator lives in the ``lib/Target/AMDGPU``
+directory. This code generator is capable of targeting a variety of
+AMD GPU processors. Refer to :doc:`AMDGPUUsage` for more information.

Added: www-releases/trunk/8.0.1/docs/_sources/CodeOfConduct.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.1/docs/_sources/CodeOfConduct.rst.txt?rev=368037&view=auto
==============================================================================
--- www-releases/trunk/8.0.1/docs/_sources/CodeOfConduct.rst.txt (added)
+++ www-releases/trunk/8.0.1/docs/_sources/CodeOfConduct.rst.txt Tue Aug  6 06:51:02 2019
@@ -0,0 +1,112 @@
+==============================
+LLVM Community Code of Conduct
+==============================
+
+.. note::
+
+   This document is currently a **DRAFT** document while it is being discussed
+   by the community.
+
+The LLVM community has always worked to be a welcoming and respectful
+community, and we want to ensure that doesn't change as we grow and evolve. To
+that end, we have a few ground rules that we ask people to adhere to:
+
+* `be friendly and patient`_,
+* `be welcoming`_,
+* `be considerate`_,
+* `be respectful`_,
+* `be careful in the words that you choose and be kind to others`_, and
+* `when we disagree, try to understand why`_.
+
+This isn't an exhaustive list of things that you can't do. Rather, take it in
+the spirit in which it's intended - a guide to make it easier to communicate
+and participate in the community.
+
+This code of conduct applies to all spaces managed by the LLVM project or The
+LLVM Foundation. This includes IRC channels, mailing lists, bug trackers, LLVM
+events such as the developer meetings and socials, and any other forums created
+by the project that the community uses for communication. It applies to all of
+your communication and conduct in these spaces, including emails, chats, things
+you say, slides, videos, posters, signs, or even t-shirts you display in these
+spaces. In addition, violations of this code outside these spaces may, in rare
+cases, affect a person's ability to participate within them, when the conduct
+amounts to an egregious violation of this code.
+
+If you believe someone is violating the code of conduct, we ask that you report
+it by emailing conduct at llvm.org. For more details please see our
+:doc:`Reporting Guide <ReportingGuide>`.
+
+.. _be friendly and patient:
+
+* **Be friendly and patient.**
+
+.. _be welcoming:
+
+* **Be welcoming.** We strive to be a community that welcomes and supports
+  people of all backgrounds and identities. This includes, but is not limited
+  to members of any race, ethnicity, culture, national origin, colour,
+  immigration status, social and economic class, educational level, sex, sexual
+  orientation, gender identity and expression, age, size, family status,
+  political belief, religion or lack thereof, and mental and physical ability.
+
+.. _be considerate:
+
+* **Be considerate.** Your work will be used by other people, and you in turn
+  will depend on the work of others. Any decision you take will affect users
+  and colleagues, and you should take those consequences into account. Remember
+  that we're a world-wide community, so you might not be communicating in
+  someone else's primary language.
+
+.. _be respectful:
+
+* **Be respectful.** Not all of us will agree all the time, but disagreement is
+  no excuse for poor behavior and poor manners. We might all experience some
+  frustration now and then, but we cannot allow that frustration to turn into
+  a personal attack. It's important to remember that a community where people
+  feel uncomfortable or threatened is not a productive one. Members of the LLVM
+  community should be respectful when dealing with other members as well as
+  with people outside the LLVM community.
+
+.. _be careful in the words that you choose and be kind to others:
+
+* **Be careful in the words that you choose and be kind to others.** Do not
+  insult or put down other participants. Harassment and other exclusionary
+  behavior aren't acceptable. This includes, but is not limited to:
+
+  * Violent threats or language directed against another person.
+  * Discriminatory jokes and language.
+  * Posting sexually explicit or violent material.
+  * Posting (or threatening to post) other people's personally identifying
+    information ("doxing").
+  * Personal insults, especially those using racist or sexist terms.
+  * Unwelcome sexual attention.
+  * Advocating for, or encouraging, any of the above behavior.
+
+  In general, if someone asks you to stop, then stop. Persisting in such
+  behavior after being asked to stop is considered harassment.
+
+.. _when we disagree, try to understand why:
+
+* **When we disagree, try to understand why.** Disagreements, both social and
+  technical, happen all the time and LLVM is no exception. It is important that
+  we resolve disagreements and differing views constructively. Remember that
+  we're different. The strength of LLVM comes from its varied community, people
+  from a wide range of backgrounds. Different people have different
+  perspectives on issues. Being unable to understand why someone holds
+  a viewpoint doesn't mean that they're wrong. Don't forget that it is human to
+  err and blaming each other doesn't get us anywhere. Instead, focus on helping
+  to resolve issues and learning from mistakes.
+
+Questions?
+==========
+
+If you have questions, please feel free to contact the LLVM Foundation Code of
+Conduct Advisory Committee by emailing conduct at llvm.org.
+
+
+(This text is based on the `Django Project`_ Code of Conduct, which is in turn
+based on wording from the `Speak Up! project`_.)
+
+.. _Django Project: https://www.djangoproject.com/conduct/
+.. _Speak Up! project: http://speakup.io/coc.html
+

Added: www-releases/trunk/8.0.1/docs/_sources/CodingStandards.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.1/docs/_sources/CodingStandards.rst.txt?rev=368037&view=auto
==============================================================================
--- www-releases/trunk/8.0.1/docs/_sources/CodingStandards.rst.txt (added)
+++ www-releases/trunk/8.0.1/docs/_sources/CodingStandards.rst.txt Tue Aug  6 06:51:02 2019
@@ -0,0 +1,1730 @@
+=====================
+LLVM Coding Standards
+=====================
+
+.. contents::
+   :local:
+
+Introduction
+============
+
+This document attempts to describe a few coding standards that are being used in
+the LLVM source tree.  Although no coding standards should be regarded as
+absolute requirements to be followed in all instances, coding standards are
+particularly important for large-scale code bases that follow a library-based
+design (like LLVM).
+
+While this document may provide guidance for some mechanical formatting issues,
+whitespace, or other "microscopic details", these are not fixed standards.
+Always follow the golden rule:
+
+.. _Golden Rule:
+
+    **If you are extending, enhancing, or bug fixing already implemented code,
+    use the style that is already being used so that the source is uniform and
+    easy to follow.**
+
+Note that some code bases (e.g. ``libc++``) have really good reasons to deviate
+from the coding standards.  In the case of ``libc++``, this is because the
+naming and other conventions are dictated by the C++ standard.  If you think
+there is a specific good reason to deviate from the standards here, please bring
+it up on the LLVM-dev mailing list.
+
+There are some conventions that are not uniformly followed in the code base
+(e.g. the naming convention).  This is because they are relatively new, and a
+lot of code was written before they were put in place.  Our long term goal is
+for the entire codebase to follow the convention, but we explicitly *do not*
+want patches that do large-scale reformatting of existing code.  On the other
+hand, it is reasonable to rename the methods of a class if you're about to
+change it in some other way.  Just do the reformatting as a separate commit
+from the functionality change.
+  
+The ultimate goal of these guidelines is to increase the readability and
+maintainability of our common source base. If you have suggestions for topics to
+be included, please mail them to `Chris <mailto:sabre at nondot.org>`_.
+
+Languages, Libraries, and Standards
+===================================
+
+Most source code in LLVM and other LLVM projects using these coding standards
+is C++ code. There are some places where C code is used either due to
+environment restrictions, historical restrictions, or due to third-party source
+code imported into the tree. Generally, our preference is for standards
+conforming, modern, and portable C++ code as the implementation language of
+choice.
+
+C++ Standard Versions
+---------------------
+
+LLVM, Clang, and LLD are currently written using C++11 conforming code,
+although we restrict ourselves to features which are available in the major
+toolchains supported as host compilers. The LLDB project is even more
+aggressive in the set of host compilers supported and thus uses still more
+features. Regardless of the supported features, code is expected to (when
+reasonable) be standard, portable, and modern C++11 code. We avoid unnecessary
+vendor-specific extensions, etc.
+
+C++ Standard Library
+--------------------
+
+Use the C++ standard library facilities whenever they are available for
+a particular task. LLVM and related projects emphasize and rely on the standard
+library facilities for as much as possible. Common support libraries providing
+functionality missing from the standard library for which there are standard
+interfaces or active work on adding standard interfaces will often be
+implemented in the LLVM namespace following the expected standard interface.
+
+There are some exceptions such as the standard I/O streams library which are
+avoided. Also, there is much more detailed information on these subjects in the
+:doc:`ProgrammersManual`.
+
+Supported C++11 Language and Library Features
+---------------------------------------------
+
+While LLVM, Clang, and LLD use C++11, not all features are available in all of
+the toolchains which we support. The set of features supported for use in LLVM
+is the intersection of those supported in the minimum requirements described
+in the :doc:`GettingStarted` page, section `Software`.
+The ultimate definition of this set is what build bots with those respective
+toolchains accept. Don't argue with the build bots. However, we have some
+guidance below to help you know what to expect.
+
+Each toolchain provides a good reference for what it accepts:
+
+* Clang: https://clang.llvm.org/cxx_status.html
+* GCC: https://gcc.gnu.org/projects/cxx-status.html#cxx11
+* MSVC: https://msdn.microsoft.com/en-us/library/hh567368.aspx
+
+In most cases, the MSVC list will be the dominating factor. Here is a summary
+of the features that are expected to work. Features not on this list are
+unlikely to be supported by our host compilers.
+
+* Rvalue references: N2118_
+
+  * But *not* Rvalue references for ``*this`` or member qualifiers (N2439_)
+
+* Static assert: N1720_
+* ``auto`` type deduction: N1984_, N1737_
+* Trailing return types: N2541_
+* Lambdas: N2927_
+
+  * But *not* lambdas with default arguments.
+
+* ``decltype``: N2343_
+* Nested closing right angle brackets: N1757_
+* Extern templates: N1987_
+* ``nullptr``: N2431_
+* Strongly-typed and forward declarable enums: N2347_, N2764_
+* Local and unnamed types as template arguments: N2657_
+* Range-based for-loop: N2930_
+
+  * But ``{}`` are required around inner ``do {} while()`` loops.  As a result,
+    ``{}`` are required around function-like macros inside range-based for
+    loops.
+
+* ``override`` and ``final``: N2928_, N3206_, N3272_
+* Atomic operations and the C++11 memory model: N2429_
+* Variadic templates: N2242_
+* Explicit conversion operators: N2437_
+* Defaulted and deleted functions: N2346_
+* Initializer lists: N2627_
+* Delegating constructors: N1986_
+* Default member initializers (non-static data member initializers): N2756_
+
+  * Feel free to use these wherever they make sense and where the `=`
+    syntax is allowed. Don't use braced initialization syntax.
+
+.. _N2118: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n2118.html
+.. _N2439: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2439.htm
+.. _N1720: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2004/n1720.html
+.. _N1984: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n1984.pdf
+.. _N1737: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2004/n1737.pdf
+.. _N2541: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2541.htm
+.. _N2927: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2009/n2927.pdf
+.. _N2343: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2343.pdf
+.. _N1757: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1757.html
+.. _N1987: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n1987.htm
+.. _N2431: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2431.pdf
+.. _N2347: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2347.pdf
+.. _N2764: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2764.pdf
+.. _N2657: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2657.htm
+.. _N2930: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2009/n2930.html
+.. _N2928: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2009/n2928.htm
+.. _N3206: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2010/n3206.htm
+.. _N3272: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2011/n3272.htm
+.. _N2429: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2429.htm
+.. _N2242: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2242.pdf
+.. _N2437: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2437.pdf
+.. _N2346: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2346.htm
+.. _N2627: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2672.htm
+.. _N1986: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n1986.pdf
+.. _N2756: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2756.htm
+
+The supported features in the C++11 standard libraries are less well tracked,
+but also much greater. Most of the standard libraries implement most of C++11's
+library. The most likely lowest common denominator is Linux support. For
+libc++, the support is just poorly tested and undocumented but expected to be
+largely complete. YMMV. For libstdc++, the support is documented in detail in
+`the libstdc++ manual`_. There are some very minor missing facilities that are
+unlikely to be common problems, and there are a few larger gaps that are worth
+being aware of:
+
+* Not all of the type traits are implemented
+* No regular expression library.
+* While most of the atomics library is well implemented, the fences are
+  missing. Fortunately, they are rarely needed.
+* The locale support is incomplete.
+
+Other than these areas you should assume the standard library is available and
+working as expected until some build bot tells you otherwise. If you're in an
+uncertain area of one of the above points, but you cannot test on a Linux
+system, your best approach is to minimize your use of these features, and watch
+the Linux build bots to find out if your usage triggered a bug. For example, if
+you hit a type trait which doesn't work we can then add support to LLVM's
+traits header to emulate it.
+
+.. _the libstdc++ manual:
+  https://gcc.gnu.org/onlinedocs/gcc-4.8.0/libstdc++/manual/manual/status.html#status.iso.2011
+
+Other Languages
+---------------
+
+Any code written in the Go programming language is not subject to the
+formatting rules below. Instead, we adopt the formatting rules enforced by
+the `gofmt`_ tool.
+
+Go code should strive to be idiomatic. Two good sets of guidelines for what
+this means are `Effective Go`_ and `Go Code Review Comments`_.
+
+.. _gofmt:
+  https://golang.org/cmd/gofmt/
+
+.. _Effective Go:
+  https://golang.org/doc/effective_go.html
+
+.. _Go Code Review Comments:
+  https://github.com/golang/go/wiki/CodeReviewComments
+
+Mechanical Source Issues
+========================
+
+Source Code Formatting
+----------------------
+
+Commenting
+^^^^^^^^^^
+
+Comments are one critical part of readability and maintainability.  Everyone
+knows they should comment their code, and so should you.  When writing comments,
+write them as English prose, which means they should use proper capitalization,
+punctuation, etc.  Aim to describe what the code is trying to do and why, not
+*how* it does it at a micro level. Here are a few critical things to document:
+
+.. _header file comment:
+
+File Headers
+""""""""""""
+
+Every source file should have a header on it that describes the basic purpose of
+the file.  If a file does not have a header, it should not be checked into the
+tree.  The standard header looks like this:
+
+.. code-block:: c++
+
+  //===-- llvm/Instruction.h - Instruction class definition -------*- C++ -*-===//
+  //
+  //                     The LLVM Compiler Infrastructure
+  //
+  // This file is distributed under the University of Illinois Open Source
+  // License. See LICENSE.TXT for details.
+  //
+  //===----------------------------------------------------------------------===//
+  ///
+  /// \file
+  /// This file contains the declaration of the Instruction class, which is the
+  /// base class for all of the VM instructions.
+  ///
+  //===----------------------------------------------------------------------===//
+
+A few things to note about this particular format: The "``-*- C++ -*-``" string
+on the first line is there to tell Emacs that the source file is a C++ file, not
+a C file (Emacs assumes ``.h`` files are C files by default).
+
+.. note::
+
+    This tag is not necessary in ``.cpp`` files.  The name of the file is also
+    on the first line, along with a very short description of the purpose of the
+    file.  This is important when printing out code and flipping though lots of
+    pages.
+
+The next section in the file is a concise note that defines the license that the
+file is released under.  This makes it perfectly clear what terms the source
+code can be distributed under and should not be modified in any way.
+
+The main body is a ``doxygen`` comment (identified by the ``///`` comment
+marker instead of the usual ``//``) describing the purpose of the file.  The
+first sentence (or a passage beginning with ``\brief``) is used as an abstract.
+Any additional information should be separated by a blank line.  If an
+algorithm is being implemented or something tricky is going on, a reference
+to the paper where it is published should be included, as well as any notes or
+*gotchas* in the code to watch out for.
+
+Class overviews
+"""""""""""""""
+
+Classes are one fundamental part of a good object oriented design.  As such, a
+class definition should have a comment block that explains what the class is
+used for and how it works.  Every non-trivial class is expected to have a
+``doxygen`` comment block.
+
+Method information
+""""""""""""""""""
+
+Methods defined in a class (as well as any global functions) should also be
+documented properly.  A quick note about what it does and a description of the
+borderline behaviour is all that is necessary here (unless something
+particularly tricky or insidious is going on).  The hope is that people can
+figure out how to use your interfaces without reading the code itself.
+
+Good things to talk about here are what happens when something unexpected
+happens: does the method return null?  Abort?  Format your hard disk?
+
+Comment Formatting
+^^^^^^^^^^^^^^^^^^
+
+In general, prefer C++ style comments (``//`` for normal comments, ``///`` for
+``doxygen`` documentation comments).  They take less space, require
+less typing, don't have nesting problems, etc.  There are a few cases when it is
+useful to use C style (``/* */``) comments however:
+
+#. When writing C code: Obviously if you are writing C code, use C style
+   comments.
+
+#. When writing a header file that may be ``#include``\d by a C source file.
+
+#. When writing a source file that is used by a tool that only accepts C style
+   comments.
+
+#. When documenting the significance of constants used as actual parameters in
+   a call. This is most helpful for ``bool`` parameters, or passing ``0`` or
+   ``nullptr``. Typically you add the formal parameter name, which ought to be
+   meaningful. For example, it's not clear what the parameter means in this call:
+
+   .. code-block:: c++
+
+     Object.emitName(nullptr);
+
+   An in-line C-style comment makes the intent obvious:
+
+   .. code-block:: c++
+
+     Object.emitName(/*Prefix=*/nullptr);
+
+Commenting out large blocks of code is discouraged, but if you really have to do
+this (for documentation purposes or as a suggestion for debug printing), use
+``#if 0`` and ``#endif``. These nest properly and are better behaved in general
+than C style comments.
+
+Doxygen Use in Documentation Comments
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Use the ``\file`` command to turn the standard file header into a file-level
+comment.
+
+Include descriptive paragraphs for all public interfaces (public classes,
+member and non-member functions).  Don't just restate the information that can
+be inferred from the API name.  The first sentence (or a paragraph beginning
+with ``\brief``) is used as an abstract. Try to use a single sentence as the
+``\brief`` adds visual clutter.  Put detailed discussion into separate
+paragraphs.
+
+To refer to parameter names inside a paragraph, use the ``\p name`` command.
+Don't use the ``\arg name`` command since it starts a new paragraph that
+contains documentation for the parameter.
+
+Wrap non-inline code examples in ``\code ... \endcode``.
+
+To document a function parameter, start a new paragraph with the
+``\param name`` command.  If the parameter is used as an out or an in/out
+parameter, use the ``\param [out] name`` or ``\param [in,out] name`` command,
+respectively.
+
+To describe function return value, start a new paragraph with the ``\returns``
+command.
+
+A minimal documentation comment:
+
+.. code-block:: c++
+
+  /// Sets the xyzzy property to \p Baz.
+  void setXyzzy(bool Baz);
+
+A documentation comment that uses all Doxygen features in a preferred way:
+
+.. code-block:: c++
+
+  /// Does foo and bar.
+  ///
+  /// Does not do foo the usual way if \p Baz is true.
+  ///
+  /// Typical usage:
+  /// \code
+  ///   fooBar(false, "quux", Res);
+  /// \endcode
+  ///
+  /// \param Quux kind of foo to do.
+  /// \param [out] Result filled with bar sequence on foo success.
+  ///
+  /// \returns true on success.
+  bool fooBar(bool Baz, StringRef Quux, std::vector<int> &Result);
+
+Don't duplicate the documentation comment in the header file and in the
+implementation file.  Put the documentation comments for public APIs into the
+header file.  Documentation comments for private APIs can go to the
+implementation file.  In any case, implementation files can include additional
+comments (not necessarily in Doxygen markup) to explain implementation details
+as needed.
+
+Don't duplicate function or class name at the beginning of the comment.
+For humans it is obvious which function or class is being documented;
+automatic documentation processing tools are smart enough to bind the comment
+to the correct declaration.
+
+Wrong:
+
+.. code-block:: c++
+
+  // In Something.h:
+
+  /// Something - An abstraction for some complicated thing.
+  class Something {
+  public:
+    /// fooBar - Does foo and bar.
+    void fooBar();
+  };
+
+  // In Something.cpp:
+
+  /// fooBar - Does foo and bar.
+  void Something::fooBar() { ... }
+
+Correct:
+
+.. code-block:: c++
+
+  // In Something.h:
+
+  /// An abstraction for some complicated thing.
+  class Something {
+  public:
+    /// Does foo and bar.
+    void fooBar();
+  };
+
+  // In Something.cpp:
+
+  // Builds a B-tree in order to do foo.  See paper by...
+  void Something::fooBar() { ... }
+
+It is not required to use additional Doxygen features, but sometimes it might
+be a good idea to do so.
+
+Consider:
+
+* adding comments to any narrow namespace containing a collection of
+  related functions or types;
+
+* using top-level groups to organize a collection of related functions at
+  namespace scope where the grouping is smaller than the namespace;
+
+* using member groups and additional comments attached to member
+  groups to organize within a class.
+
+For example:
+
+.. code-block:: c++
+
+  class Something {
+    /// \name Functions that do Foo.
+    /// @{
+    void fooBar();
+    void fooBaz();
+    /// @}
+    ...
+  };
+
+``#include`` Style
+^^^^^^^^^^^^^^^^^^
+
+Immediately after the `header file comment`_ (and include guards if working on a
+header file), the `minimal list of #includes`_ required by the file should be
+listed.  We prefer these ``#include``\s to be listed in this order:
+
+.. _Main Module Header:
+.. _Local/Private Headers:
+
+#. Main Module Header
+#. Local/Private Headers
+#. LLVM project/subproject headers (``clang/...``, ``lldb/...``, ``llvm/...``, etc)
+#. System ``#include``\s
+
+and each category should be sorted lexicographically by the full path.
+
+The `Main Module Header`_ file applies to ``.cpp`` files which implement an
+interface defined by a ``.h`` file.  This ``#include`` should always be included
+**first** regardless of where it lives on the file system.  By including a
+header file first in the ``.cpp`` files that implement the interfaces, we ensure
+that the header does not have any hidden dependencies which are not explicitly
+``#include``\d in the header, but should be. It is also a form of documentation
+in the ``.cpp`` file to indicate where the interfaces it implements are defined.
+
+LLVM project and subproject headers should be grouped from most specific to least
+specific, for the same reasons described above.  For example, LLDB depends on
+both clang and LLVM, and clang depends on LLVM.  So an LLDB source file should
+include ``lldb`` headers first, followed by ``clang`` headers, followed by
+``llvm`` headers, to reduce the possibility (for example) of an LLDB header
+accidentally picking up a missing include due to the previous inclusion of that
+header in the main source file or some earlier header file.  clang should
+similarly include its own headers before including llvm headers.  This rule
+applies to all LLVM subprojects.
+
+.. _fit into 80 columns:
+
+Source Code Width
+^^^^^^^^^^^^^^^^^
+
+Write your code to fit within 80 columns of text.  This helps those of us who
+like to print out code and look at your code in an ``xterm`` without resizing
+it.
+
+The longer answer is that there must be some limit to the width of the code in
+order to reasonably allow developers to have multiple files side-by-side in
+windows on a modest display.  If you are going to pick a width limit, it is
+somewhat arbitrary but you might as well pick something standard.  Going with 90
+columns (for example) instead of 80 columns wouldn't add any significant value
+and would be detrimental to printing out code.  Also many other projects have
+standardized on 80 columns, so some people have already configured their editors
+for it (vs something else, like 90 columns).
+
+This is one of many contentious issues in coding standards, but it is not up for
+debate.
+
+Whitespace
+^^^^^^^^^^
+
+In all cases, prefer spaces to tabs in source files.  People have different
+preferred indentation levels, and different styles of indentation that they
+like; this is fine.  What isn't fine is that different editors/viewers expand
+tabs out to different tab stops.  This can cause your code to look completely
+unreadable, and it is not worth dealing with.
+
+As always, follow the `Golden Rule`_ above: follow the style of
+existing code if you are modifying and extending it.  If you like four spaces of
+indentation, **DO NOT** do that in the middle of a chunk of code with two spaces
+of indentation.  Also, do not reindent a whole source file: it makes for
+incredible diffs that are absolutely worthless.
+
+Do not commit changes that include trailing whitespace. If you find trailing
+whitespace in a file, do not remove it unless you're otherwise changing that
+line of code. Some common editors will automatically remove trailing whitespace
+when saving a file which causes unrelated changes to appear in diffs and
+commits.
+
+Indent Code Consistently
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Okay, in your first year of programming you were told that indentation is
+important. If you didn't believe and internalize this then, now is the time.
+Just do it. With the introduction of C++11, there are some new formatting
+challenges that merit some suggestions to help have consistent, maintainable,
+and tool-friendly formatting and indentation.
+
+Format Lambdas Like Blocks Of Code
+""""""""""""""""""""""""""""""""""
+
+When formatting a multi-line lambda, format it like a block of code, that's
+what it is. If there is only one multi-line lambda in a statement, and there
+are no expressions lexically after it in the statement, drop the indent to the
+standard two space indent for a block of code, as if it were an if-block opened
+by the preceding part of the statement:
+
+.. code-block:: c++
+
+  std::sort(foo.begin(), foo.end(), [&](Foo a, Foo b) -> bool {
+    if (a.blah < b.blah)
+      return true;
+    if (a.baz < b.baz)
+      return true;
+    return a.bam < b.bam;
+  });
+
+To take best advantage of this formatting, if you are designing an API which
+accepts a continuation or single callable argument (be it a functor, or
+a ``std::function``), it should be the last argument if at all possible.
+
+If there are multiple multi-line lambdas in a statement, or there is anything
+interesting after the lambda in the statement, indent the block two spaces from
+the indent of the ``[]``:
+
+.. code-block:: c++
+
+  dyn_switch(V->stripPointerCasts(),
+             [] (PHINode *PN) {
+               // process phis...
+             },
+             [] (SelectInst *SI) {
+               // process selects...
+             },
+             [] (LoadInst *LI) {
+               // process loads...
+             },
+             [] (AllocaInst *AI) {
+               // process allocas...
+             });
+
+Braced Initializer Lists
+""""""""""""""""""""""""
+
+With C++11, there are significantly more uses of braced lists to perform
+initialization. These allow you to easily construct aggregate temporaries in
+expressions among other niceness. They now have a natural way of ending up
+nested within each other and within function calls in order to build up
+aggregates (such as option structs) from local variables. To make matters
+worse, we also have many more uses of braces in an expression context that are
+*not* performing initialization.
+
+The historically common formatting of braced initialization of aggregate
+variables does not mix cleanly with deep nesting, general expression contexts,
+function arguments, and lambdas. We suggest new code use a simple rule for
+formatting braced initialization lists: act as-if the braces were parentheses
+in a function call. The formatting rules exactly match those already well
+understood for formatting nested function calls. Examples:
+
+.. code-block:: c++
+
+  foo({a, b, c}, {1, 2, 3});
+
+  llvm::Constant *Mask[] = {
+      llvm::ConstantInt::get(llvm::Type::getInt32Ty(getLLVMContext()), 0),
+      llvm::ConstantInt::get(llvm::Type::getInt32Ty(getLLVMContext()), 1),
+      llvm::ConstantInt::get(llvm::Type::getInt32Ty(getLLVMContext()), 2)};
+
+This formatting scheme also makes it particularly easy to get predictable,
+consistent, and automatic formatting with tools like `Clang Format`_.
+
+.. _Clang Format: https://clang.llvm.org/docs/ClangFormat.html
+
+Language and Compiler Issues
+----------------------------
+
+Treat Compiler Warnings Like Errors
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If your code has compiler warnings in it, something is wrong --- you aren't
+casting values correctly, you have "questionable" constructs in your code, or
+you are doing something legitimately wrong.  Compiler warnings can cover up
+legitimate errors in output and make dealing with a translation unit difficult.
+
+It is not possible to prevent all warnings from all compilers, nor is it
+desirable.  Instead, pick a standard compiler (like ``gcc``) that provides a
+good thorough set of warnings, and stick to it.  At least in the case of
+``gcc``, it is possible to work around any spurious errors by changing the
+syntax of the code slightly.  For example, a warning that annoys me occurs when
+I write code like this:
+
+.. code-block:: c++
+
+  if (V = getValue()) {
+    ...
+  }
+
+``gcc`` will warn me that I probably want to use the ``==`` operator, and that I
+probably mistyped it.  In most cases, I haven't, and I really don't want the
+spurious errors.  To fix this particular problem, I rewrite the code like
+this:
+
+.. code-block:: c++
+
+  if ((V = getValue())) {
+    ...
+  }
+
+which shuts ``gcc`` up.  Any ``gcc`` warning that annoys you can be fixed by
+massaging the code appropriately.
+
+Write Portable Code
+^^^^^^^^^^^^^^^^^^^
+
+In almost all cases, it is possible and within reason to write completely
+portable code.  If there are cases where it isn't possible to write portable
+code, isolate it behind a well defined (and well documented) interface.
+
+In practice, this means that you shouldn't assume much about the host compiler
+(and Visual Studio tends to be the lowest common denominator).  If advanced
+features are used, they should only be an implementation detail of a library
+which has a simple exposed API, and preferably be buried in ``libSystem``.
+
+Do not use RTTI or Exceptions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In an effort to reduce code and executable size, LLVM does not use RTTI
+(e.g. ``dynamic_cast<>;``) or exceptions.  These two language features violate
+the general C++ principle of *"you only pay for what you use"*, causing
+executable bloat even if exceptions are never used in the code base, or if RTTI
+is never used for a class.  Because of this, we turn them off globally in the
+code.
+
+That said, LLVM does make extensive use of a hand-rolled form of RTTI that use
+templates like :ref:`isa\<>, cast\<>, and dyn_cast\<> <isa>`.
+This form of RTTI is opt-in and can be
+:doc:`added to any class <HowToSetUpLLVMStyleRTTI>`. It is also
+substantially more efficient than ``dynamic_cast<>``.
+
+.. _static constructor:
+
+Do not use Static Constructors
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Static constructors and destructors (e.g. global variables whose types have a
+constructor or destructor) should not be added to the code base, and should be
+removed wherever possible.  Besides `well known problems
+<https://yosefk.com/c++fqa/ctors.html#fqa-10.12>`_ where the order of
+initialization is undefined between globals in different source files, the
+entire concept of static constructors is at odds with the common use case of
+LLVM as a library linked into a larger application.
+  
+Consider the use of LLVM as a JIT linked into another application (perhaps for
+`OpenGL, custom languages <https://llvm.org/Users.html>`_, `shaders in movies
+<https://llvm.org/devmtg/2010-11/Gritz-OpenShadingLang.pdf>`_, etc). Due to the
+design of static constructors, they must be executed at startup time of the
+entire application, regardless of whether or how LLVM is used in that larger
+application.  There are two problems with this:
+
+* The time to run the static constructors impacts startup time of applications
+  --- a critical time for GUI apps, among others.
+  
+* The static constructors cause the app to pull many extra pages of memory off
+  the disk: both the code for the constructor in each ``.o`` file and the small
+  amount of data that gets touched. In addition, touched/dirty pages put more
+  pressure on the VM system on low-memory machines.
+
+We would really like for there to be zero cost for linking in an additional LLVM
+target or other library into an application, but static constructors violate
+this goal.
+  
+That said, LLVM unfortunately does contain static constructors.  It would be a
+`great project <https://llvm.org/PR11944>`_ for someone to purge all static
+constructors from LLVM, and then enable the ``-Wglobal-constructors`` warning
+flag (when building with Clang) to ensure we do not regress in the future.
+
+Use of ``class`` and ``struct`` Keywords
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In C++, the ``class`` and ``struct`` keywords can be used almost
+interchangeably. The only difference is when they are used to declare a class:
+``class`` makes all members private by default while ``struct`` makes all
+members public by default.
+
+Unfortunately, not all compilers follow the rules and some will generate
+different symbols based on whether ``class`` or ``struct`` was used to declare
+the symbol (e.g., MSVC).  This can lead to problems at link time.
+
+* All declarations and definitions of a given ``class`` or ``struct`` must use
+  the same keyword.  For example:
+
+.. code-block:: c++
+
+  class Foo;
+
+  // Breaks mangling in MSVC.
+  struct Foo { int Data; };
+
+* As a rule of thumb, ``struct`` should be kept to structures where *all*
+  members are declared public.
+
+.. code-block:: c++
+
+  // Foo feels like a class... this is strange.
+  struct Foo {
+  private:
+    int Data;
+  public:
+    Foo() : Data(0) { }
+    int getData() const { return Data; }
+    void setData(int D) { Data = D; }
+  };
+
+  // Bar isn't POD, but it does look like a struct.
+  struct Bar {
+    int Data;
+    Bar() : Data(0) { }
+  };
+
+Do not use Braced Initializer Lists to Call a Constructor
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In C++11 there is a "generalized initialization syntax" which allows calling
+constructors using braced initializer lists. Do not use these to call
+constructors with any interesting logic or if you care that you're calling some
+*particular* constructor. Those should look like function calls using
+parentheses rather than like aggregate initialization. Similarly, if you need
+to explicitly name the type and call its constructor to create a temporary,
+don't use a braced initializer list. Instead, use a braced initializer list
+(without any type for temporaries) when doing aggregate initialization or
+something notionally equivalent. Examples:
+
+.. code-block:: c++
+
+  class Foo {
+  public:
+    // Construct a Foo by reading data from the disk in the whizbang format, ...
+    Foo(std::string filename);
+
+    // Construct a Foo by looking up the Nth element of some global data ...
+    Foo(int N);
+
+    // ...
+  };
+
+  // The Foo constructor call is very deliberate, no braces.
+  std::fill(foo.begin(), foo.end(), Foo("name"));
+
+  // The pair is just being constructed like an aggregate, use braces.
+  bar_map.insert({my_key, my_value});
+
+If you use a braced initializer list when initializing a variable, use an equals before the open curly brace:
+
+.. code-block:: c++
+
+  int data[] = {0, 1, 2, 3};
+
+Use ``auto`` Type Deduction to Make Code More Readable
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Some are advocating a policy of "almost always ``auto``" in C++11, however LLVM
+uses a more moderate stance. Use ``auto`` if and only if it makes the code more
+readable or easier to maintain. Don't "almost always" use ``auto``, but do use
+``auto`` with initializers like ``cast<Foo>(...)`` or other places where the
+type is already obvious from the context. Another time when ``auto`` works well
+for these purposes is when the type would have been abstracted away anyways,
+often behind a container's typedef such as ``std::vector<T>::iterator``.
+
+Beware unnecessary copies with ``auto``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The convenience of ``auto`` makes it easy to forget that its default behavior
+is a copy.  Particularly in range-based ``for`` loops, careless copies are
+expensive.
+
+As a rule of thumb, use ``auto &`` unless you need to copy the result, and use
+``auto *`` when copying pointers.
+
+.. code-block:: c++
+
+  // Typically there's no reason to copy.
+  for (const auto &Val : Container) { observe(Val); }
+  for (auto &Val : Container) { Val.change(); }
+
+  // Remove the reference if you really want a new copy.
+  for (auto Val : Container) { Val.change(); saveSomewhere(Val); }
+
+  // Copy pointers, but make it clear that they're pointers.
+  for (const auto *Ptr : Container) { observe(*Ptr); }
+  for (auto *Ptr : Container) { Ptr->change(); }
+
+Beware of non-determinism due to ordering of pointers
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In general, there is no relative ordering among pointers. As a result,
+when unordered containers like sets and maps are used with pointer keys
+the iteration order is undefined. Hence, iterating such containers may
+result in non-deterministic code generation. While the generated code
+might not necessarily be "wrong code", this non-determinism might result
+in unexpected runtime crashes or simply hard to reproduce bugs on the
+customer side making it harder to debug and fix.
+
+As a rule of thumb, in case an ordered result is expected, remember to
+sort an unordered container before iteration. Or use ordered containers
+like vector/MapVector/SetVector if you want to iterate pointer keys.
+
+Beware of non-deterministic sorting order of equal elements
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+std::sort uses a non-stable sorting algorithm in which the order of equal
+elements is not guaranteed to be preserved. Thus using std::sort for a
+container having equal elements may result in non-determinstic behavior.
+To uncover such instances of non-determinism, LLVM has introduced a new
+llvm::sort wrapper function. For an EXPENSIVE_CHECKS build this will randomly
+shuffle the container before sorting. As a rule of thumb, always make sure to
+use llvm::sort instead of std::sort.
+
+Style Issues
+============
+
+The High-Level Issues
+---------------------
+
+Self-contained Headers
+^^^^^^^^^^^^^^^^^^^^^^
+
+Header files should be self-contained (compile on their own) and end in .h.
+Non-header files that are meant for inclusion should end in .inc and be used
+sparingly.
+
+All header files should be self-contained. Users and refactoring tools should
+not have to adhere to special conditions to include the header. Specifically, a
+header should have header guards and include all other headers it needs.
+
+There are rare cases where a file designed to be included is not
+self-contained. These are typically intended to be included at unusual
+locations, such as the middle of another file. They might not use header
+guards, and might not include their prerequisites. Name such files with the
+.inc extension. Use sparingly, and prefer self-contained headers when possible.
+
+In general, a header should be implemented by one or more ``.cpp`` files.  Each
+of these ``.cpp`` files should include the header that defines their interface
+first.  This ensures that all of the dependences of the header have been
+properly added to the header itself, and are not implicit.  System headers
+should be included after user headers for a translation unit.
+
+Library Layering
+^^^^^^^^^^^^^^^^
+
+A directory of header files (for example ``include/llvm/Foo``) defines a
+library (``Foo``). Dependencies between libraries are defined by the
+``LLVMBuild.txt`` file in their implementation (``lib/Foo``). One library (both
+its headers and implementation) should only use things from the libraries
+listed in its dependencies.
+
+Some of this constraint can be enforced by classic Unix linkers (Mac & Windows
+linkers, as well as lld, do not enforce this constraint). A Unix linker
+searches left to right through the libraries specified on its command line and
+never revisits a library. In this way, no circular dependencies between
+libraries can exist.
+
+This doesn't fully enforce all inter-library dependencies, and importantly
+doesn't enforce header file circular dependencies created by inline functions.
+A good way to answer the "is this layered correctly" would be to consider
+whether a Unix linker would succeed at linking the program if all inline
+functions were defined out-of-line. (& for all valid orderings of dependencies
+- since linking resolution is linear, it's possible that some implicit
+dependencies can sneak through: A depends on B and C, so valid orderings are
+"C B A" or "B C A", in both cases the explicit dependencies come before their
+use. But in the first case, B could still link successfully if it implicitly
+depended on C, or the opposite in the second case)
+
+.. _minimal list of #includes:
+
+``#include`` as Little as Possible
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``#include`` hurts compile time performance.  Don't do it unless you have to,
+especially in header files.
+
+But wait! Sometimes you need to have the definition of a class to use it, or to
+inherit from it.  In these cases go ahead and ``#include`` that header file.  Be
+aware however that there are many cases where you don't need to have the full
+definition of a class.  If you are using a pointer or reference to a class, you
+don't need the header file.  If you are simply returning a class instance from a
+prototyped function or method, you don't need it.  In fact, for most cases, you
+simply don't need the definition of a class. And not ``#include``\ing speeds up
+compilation.
+
+It is easy to try to go too overboard on this recommendation, however.  You
+**must** include all of the header files that you are using --- you can include
+them either directly or indirectly through another header file.  To make sure
+that you don't accidentally forget to include a header file in your module
+header, make sure to include your module header **first** in the implementation
+file (as mentioned above).  This way there won't be any hidden dependencies that
+you'll find out about later.
+
+Keep "Internal" Headers Private
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Many modules have a complex implementation that causes them to use more than one
+implementation (``.cpp``) file.  It is often tempting to put the internal
+communication interface (helper classes, extra functions, etc) in the public
+module header file.  Don't do this!
+
+If you really need to do something like this, put a private header file in the
+same directory as the source files, and include it locally.  This ensures that
+your private interface remains private and undisturbed by outsiders.
+
+.. note::
+
+    It's okay to put extra implementation methods in a public class itself. Just
+    make them private (or protected) and all is well.
+
+.. _early exits:
+
+Use Early Exits and ``continue`` to Simplify Code
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When reading code, keep in mind how much state and how many previous decisions
+have to be remembered by the reader to understand a block of code.  Aim to
+reduce indentation where possible when it doesn't make it more difficult to
+understand the code.  One great way to do this is by making use of early exits
+and the ``continue`` keyword in long loops.  As an example of using an early
+exit from a function, consider this "bad" code:
+
+.. code-block:: c++
+
+  Value *doSomething(Instruction *I) {
+    if (!I->isTerminator() &&
+        I->hasOneUse() && doOtherThing(I)) {
+      ... some long code ....
+    }
+
+    return 0;
+  }
+
+This code has several problems if the body of the ``'if'`` is large.  When
+you're looking at the top of the function, it isn't immediately clear that this
+*only* does interesting things with non-terminator instructions, and only
+applies to things with the other predicates.  Second, it is relatively difficult
+to describe (in comments) why these predicates are important because the ``if``
+statement makes it difficult to lay out the comments.  Third, when you're deep
+within the body of the code, it is indented an extra level.  Finally, when
+reading the top of the function, it isn't clear what the result is if the
+predicate isn't true; you have to read to the end of the function to know that
+it returns null.
+
+It is much preferred to format the code like this:
+
+.. code-block:: c++
+
+  Value *doSomething(Instruction *I) {
+    // Terminators never need 'something' done to them because ... 
+    if (I->isTerminator())
+      return 0;
+
+    // We conservatively avoid transforming instructions with multiple uses
+    // because goats like cheese.
+    if (!I->hasOneUse())
+      return 0;
+
+    // This is really just here for example.
+    if (!doOtherThing(I))
+      return 0;
+    
+    ... some long code ....
+  }
+
+This fixes these problems.  A similar problem frequently happens in ``for``
+loops.  A silly example is something like this:
+
+.. code-block:: c++
+
+  for (Instruction &I : BB) {
+    if (auto *BO = dyn_cast<BinaryOperator>(&I)) {
+      Value *LHS = BO->getOperand(0);
+      Value *RHS = BO->getOperand(1);
+      if (LHS != RHS) {
+        ...
+      }
+    }
+  }
+
+When you have very, very small loops, this sort of structure is fine. But if it
+exceeds more than 10-15 lines, it becomes difficult for people to read and
+understand at a glance. The problem with this sort of code is that it gets very
+nested very quickly. Meaning that the reader of the code has to keep a lot of
+context in their brain to remember what is going immediately on in the loop,
+because they don't know if/when the ``if`` conditions will have ``else``\s etc.
+It is strongly preferred to structure the loop like this:
+
+.. code-block:: c++
+
+  for (Instruction &I : BB) {
+    auto *BO = dyn_cast<BinaryOperator>(&I);
+    if (!BO) continue;
+
+    Value *LHS = BO->getOperand(0);
+    Value *RHS = BO->getOperand(1);
+    if (LHS == RHS) continue;
+
+    ...
+  }
+
+This has all the benefits of using early exits for functions: it reduces nesting
+of the loop, it makes it easier to describe why the conditions are true, and it
+makes it obvious to the reader that there is no ``else`` coming up that they
+have to push context into their brain for.  If a loop is large, this can be a
+big understandability win.
+
+Don't use ``else`` after a ``return``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+For similar reasons above (reduction of indentation and easier reading), please
+do not use ``'else'`` or ``'else if'`` after something that interrupts control
+flow --- like ``return``, ``break``, ``continue``, ``goto``, etc. For
+example, this is *bad*:
+
+.. code-block:: c++
+
+  case 'J': {
+    if (Signed) {
+      Type = Context.getsigjmp_bufType();
+      if (Type.isNull()) {
+        Error = ASTContext::GE_Missing_sigjmp_buf;
+        return QualType();
+      } else {
+        break;
+      }
+    } else {
+      Type = Context.getjmp_bufType();
+      if (Type.isNull()) {
+        Error = ASTContext::GE_Missing_jmp_buf;
+        return QualType();
+      } else {
+        break;
+      }
+    }
+  }
+
+It is better to write it like this:
+
+.. code-block:: c++
+
+  case 'J':
+    if (Signed) {
+      Type = Context.getsigjmp_bufType();
+      if (Type.isNull()) {
+        Error = ASTContext::GE_Missing_sigjmp_buf;
+        return QualType();
+      }
+    } else {
+      Type = Context.getjmp_bufType();
+      if (Type.isNull()) {
+        Error = ASTContext::GE_Missing_jmp_buf;
+        return QualType();
+      }
+    }
+    break;
+
+Or better yet (in this case) as:
+
+.. code-block:: c++
+
+  case 'J':
+    if (Signed)
+      Type = Context.getsigjmp_bufType();
+    else
+      Type = Context.getjmp_bufType();
+    
+    if (Type.isNull()) {
+      Error = Signed ? ASTContext::GE_Missing_sigjmp_buf :
+                       ASTContext::GE_Missing_jmp_buf;
+      return QualType();
+    }
+    break;
+
+The idea is to reduce indentation and the amount of code you have to keep track
+of when reading the code.
+              
+Turn Predicate Loops into Predicate Functions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+It is very common to write small loops that just compute a boolean value.  There
+are a number of ways that people commonly write these, but an example of this
+sort of thing is:
+
+.. code-block:: c++
+
+  bool FoundFoo = false;
+  for (unsigned I = 0, E = BarList.size(); I != E; ++I)
+    if (BarList[I]->isFoo()) {
+      FoundFoo = true;
+      break;
+    }
+
+  if (FoundFoo) {
+    ...
+  }
+
+This sort of code is awkward to write, and is almost always a bad sign.  Instead
+of this sort of loop, we strongly prefer to use a predicate function (which may
+be `static`_) that uses `early exits`_ to compute the predicate.  We prefer the
+code to be structured like this:
+
+.. code-block:: c++
+
+  /// \returns true if the specified list has an element that is a foo.
+  static bool containsFoo(const std::vector<Bar*> &List) {
+    for (unsigned I = 0, E = List.size(); I != E; ++I)
+      if (List[I]->isFoo())
+        return true;
+    return false;
+  }
+  ...
+
+  if (containsFoo(BarList)) {
+    ...
+  }
+
+There are many reasons for doing this: it reduces indentation and factors out
+code which can often be shared by other code that checks for the same predicate.
+More importantly, it *forces you to pick a name* for the function, and forces
+you to write a comment for it.  In this silly example, this doesn't add much
+value.  However, if the condition is complex, this can make it a lot easier for
+the reader to understand the code that queries for this predicate.  Instead of
+being faced with the in-line details of how we check to see if the BarList
+contains a foo, we can trust the function name and continue reading with better
+locality.
+
+The Low-Level Issues
+--------------------
+
+Name Types, Functions, Variables, and Enumerators Properly
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Poorly-chosen names can mislead the reader and cause bugs. We cannot stress
+enough how important it is to use *descriptive* names.  Pick names that match
+the semantics and role of the underlying entities, within reason.  Avoid
+abbreviations unless they are well known.  After picking a good name, make sure
+to use consistent capitalization for the name, as inconsistency requires clients
+to either memorize the APIs or to look it up to find the exact spelling.
+
+In general, names should be in camel case (e.g. ``TextFileReader`` and
+``isLValue()``).  Different kinds of declarations have different rules:
+
+* **Type names** (including classes, structs, enums, typedefs, etc) should be
+  nouns and start with an upper-case letter (e.g. ``TextFileReader``).
+
+* **Variable names** should be nouns (as they represent state).  The name should
+  be camel case, and start with an upper case letter (e.g. ``Leader`` or
+  ``Boats``).
+  
+* **Function names** should be verb phrases (as they represent actions), and
+  command-like function should be imperative.  The name should be camel case,
+  and start with a lower case letter (e.g. ``openFile()`` or ``isFoo()``).
+
+* **Enum declarations** (e.g. ``enum Foo {...}``) are types, so they should
+  follow the naming conventions for types.  A common use for enums is as a
+  discriminator for a union, or an indicator of a subclass.  When an enum is
+  used for something like this, it should have a ``Kind`` suffix
+  (e.g. ``ValueKind``).
+  
+* **Enumerators** (e.g. ``enum { Foo, Bar }``) and **public member variables**
+  should start with an upper-case letter, just like types.  Unless the
+  enumerators are defined in their own small namespace or inside a class,
+  enumerators should have a prefix corresponding to the enum declaration name.
+  For example, ``enum ValueKind { ... };`` may contain enumerators like
+  ``VK_Argument``, ``VK_BasicBlock``, etc.  Enumerators that are just
+  convenience constants are exempt from the requirement for a prefix.  For
+  instance:
+
+  .. code-block:: c++
+
+      enum {
+        MaxSize = 42,
+        Density = 12
+      };
+  
+As an exception, classes that mimic STL classes can have member names in STL's
+style of lower-case words separated by underscores (e.g. ``begin()``,
+``push_back()``, and ``empty()``). Classes that provide multiple
+iterators should add a singular prefix to ``begin()`` and ``end()``
+(e.g. ``global_begin()`` and ``use_begin()``).
+
+Here are some examples of good and bad names:
+
+.. code-block:: c++
+
+  class VehicleMaker {
+    ...
+    Factory<Tire> F;            // Bad -- abbreviation and non-descriptive.
+    Factory<Tire> Factory;      // Better.
+    Factory<Tire> TireFactory;  // Even better -- if VehicleMaker has more than one
+                                // kind of factories.
+  };
+
+  Vehicle makeVehicle(VehicleType Type) {
+    VehicleMaker M;                         // Might be OK if having a short life-span.
+    Tire Tmp1 = M.makeTire();               // Bad -- 'Tmp1' provides no information.
+    Light Headlight = M.makeLight("head");  // Good -- descriptive.
+    ...
+  }
+
+Assert Liberally
+^^^^^^^^^^^^^^^^
+
+Use the "``assert``" macro to its fullest.  Check all of your preconditions and
+assumptions, you never know when a bug (not necessarily even yours) might be
+caught early by an assertion, which reduces debugging time dramatically.  The
+"``<cassert>``" header file is probably already included by the header files you
+are using, so it doesn't cost anything to use it.
+
+To further assist with debugging, make sure to put some kind of error message in
+the assertion statement, which is printed if the assertion is tripped. This
+helps the poor debugger make sense of why an assertion is being made and
+enforced, and hopefully what to do about it.  Here is one complete example:
+
+.. code-block:: c++
+
+  inline Value *getOperand(unsigned I) {
+    assert(I < Operands.size() && "getOperand() out of range!");
+    return Operands[I];
+  }
+
+Here are more examples:
+
+.. code-block:: c++
+
+  assert(Ty->isPointerType() && "Can't allocate a non-pointer type!");
+
+  assert((Opcode == Shl || Opcode == Shr) && "ShiftInst Opcode invalid!");
+
+  assert(idx < getNumSuccessors() && "Successor # out of range!");
+
+  assert(V1.getType() == V2.getType() && "Constant types must be identical!");
+
+  assert(isa<PHINode>(Succ->front()) && "Only works on PHId BBs!");
+
+You get the idea.
+
+In the past, asserts were used to indicate a piece of code that should not be
+reached.  These were typically of the form:
+
+.. code-block:: c++
+
+  assert(0 && "Invalid radix for integer literal");
+
+This has a few issues, the main one being that some compilers might not
+understand the assertion, or warn about a missing return in builds where
+assertions are compiled out.
+
+Today, we have something much better: ``llvm_unreachable``:
+
+.. code-block:: c++
+
+  llvm_unreachable("Invalid radix for integer literal");
+
+When assertions are enabled, this will print the message if it's ever reached
+and then exit the program. When assertions are disabled (i.e. in release
+builds), ``llvm_unreachable`` becomes a hint to compilers to skip generating
+code for this branch. If the compiler does not support this, it will fall back
+to the "abort" implementation.
+
+Neither assertions or ``llvm_unreachable`` will abort the program on a release
+build. If the error condition can be triggered by user input then the
+recoverable error mechanism described in :doc:`ProgrammersManual` should be
+used instead. In cases where this is not practical, ``report_fatal_error`` may
+be used.
+
+Another issue is that values used only by assertions will produce an "unused
+value" warning when assertions are disabled.  For example, this code will warn:
+
+.. code-block:: c++
+
+  unsigned Size = V.size();
+  assert(Size > 42 && "Vector smaller than it should be");
+
+  bool NewToSet = Myset.insert(Value);
+  assert(NewToSet && "The value shouldn't be in the set yet");
+
+These are two interesting different cases. In the first case, the call to
+``V.size()`` is only useful for the assert, and we don't want it executed when
+assertions are disabled.  Code like this should move the call into the assert
+itself.  In the second case, the side effects of the call must happen whether
+the assert is enabled or not.  In this case, the value should be cast to void to
+disable the warning.  To be specific, it is preferred to write the code like
+this:
+
+.. code-block:: c++
+
+  assert(V.size() > 42 && "Vector smaller than it should be");
+
+  bool NewToSet = Myset.insert(Value); (void)NewToSet;
+  assert(NewToSet && "The value shouldn't be in the set yet");
+
+Do Not Use ``using namespace std``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In LLVM, we prefer to explicitly prefix all identifiers from the standard
+namespace with an "``std::``" prefix, rather than rely on "``using namespace
+std;``".
+
+In header files, adding a ``'using namespace XXX'`` directive pollutes the
+namespace of any source file that ``#include``\s the header.  This is clearly a
+bad thing.
+
+In implementation files (e.g. ``.cpp`` files), the rule is more of a stylistic
+rule, but is still important.  Basically, using explicit namespace prefixes
+makes the code **clearer**, because it is immediately obvious what facilities
+are being used and where they are coming from. And **more portable**, because
+namespace clashes cannot occur between LLVM code and other namespaces.  The
+portability rule is important because different standard library implementations
+expose different symbols (potentially ones they shouldn't), and future revisions
+to the C++ standard will add more symbols to the ``std`` namespace.  As such, we
+never use ``'using namespace std;'`` in LLVM.
+
+The exception to the general rule (i.e. it's not an exception for the ``std``
+namespace) is for implementation files.  For example, all of the code in the
+LLVM project implements code that lives in the 'llvm' namespace.  As such, it is
+ok, and actually clearer, for the ``.cpp`` files to have a ``'using namespace
+llvm;'`` directive at the top, after the ``#include``\s.  This reduces
+indentation in the body of the file for source editors that indent based on
+braces, and keeps the conceptual context cleaner.  The general form of this rule
+is that any ``.cpp`` file that implements code in any namespace may use that
+namespace (and its parents'), but should not use any others.
+
+Provide a Virtual Method Anchor for Classes in Headers
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If a class is defined in a header file and has a vtable (either it has virtual
+methods or it derives from classes with virtual methods), it must always have at
+least one out-of-line virtual method in the class.  Without this, the compiler
+will copy the vtable and RTTI into every ``.o`` file that ``#include``\s the
+header, bloating ``.o`` file sizes and increasing link times.
+
+Don't use default labels in fully covered switches over enumerations
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``-Wswitch`` warns if a switch, without a default label, over an enumeration
+does not cover every enumeration value. If you write a default label on a fully
+covered switch over an enumeration then the ``-Wswitch`` warning won't fire
+when new elements are added to that enumeration. To help avoid adding these
+kinds of defaults, Clang has the warning ``-Wcovered-switch-default`` which is
+off by default but turned on when building LLVM with a version of Clang that
+supports the warning.
+
+A knock-on effect of this stylistic requirement is that when building LLVM with
+GCC you may get warnings related to "control may reach end of non-void function"
+if you return from each case of a covered switch-over-enum because GCC assumes
+that the enum expression may take any representable value, not just those of
+individual enumerators. To suppress this warning, use ``llvm_unreachable`` after
+the switch.
+
+Use range-based ``for`` loops wherever possible
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The introduction of range-based ``for`` loops in C++11 means that explicit
+manipulation of iterators is rarely necessary. We use range-based ``for``
+loops wherever possible for all newly added code. For example:
+
+.. code-block:: c++
+
+  BasicBlock *BB = ...
+  for (Instruction &I : *BB)
+    ... use I ...
+
+Don't evaluate ``end()`` every time through a loop
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In cases where range-based ``for`` loops can't be used and it is necessary
+to write an explicit iterator-based loop, pay close attention to whether
+``end()`` is re-evaluted on each loop iteration. One common mistake is to
+write a loop in this style:
+
+.. code-block:: c++
+
+  BasicBlock *BB = ...
+  for (auto I = BB->begin(); I != BB->end(); ++I)
+    ... use I ...
+
+The problem with this construct is that it evaluates "``BB->end()``" every time
+through the loop.  Instead of writing the loop like this, we strongly prefer
+loops to be written so that they evaluate it once before the loop starts.  A
+convenient way to do this is like so:
+
+.. code-block:: c++
+
+  BasicBlock *BB = ...
+  for (auto I = BB->begin(), E = BB->end(); I != E; ++I)
+    ... use I ...
+
+The observant may quickly point out that these two loops may have different
+semantics: if the container (a basic block in this case) is being mutated, then
+"``BB->end()``" may change its value every time through the loop and the second
+loop may not in fact be correct.  If you actually do depend on this behavior,
+please write the loop in the first form and add a comment indicating that you
+did it intentionally.
+
+Why do we prefer the second form (when correct)?  Writing the loop in the first
+form has two problems. First it may be less efficient than evaluating it at the
+start of the loop.  In this case, the cost is probably minor --- a few extra
+loads every time through the loop.  However, if the base expression is more
+complex, then the cost can rise quickly.  I've seen loops where the end
+expression was actually something like: "``SomeMap[X]->end()``" and map lookups
+really aren't cheap.  By writing it in the second form consistently, you
+eliminate the issue entirely and don't even have to think about it.
+
+The second (even bigger) issue is that writing the loop in the first form hints
+to the reader that the loop is mutating the container (a fact that a comment
+would handily confirm!).  If you write the loop in the second form, it is
+immediately obvious without even looking at the body of the loop that the
+container isn't being modified, which makes it easier to read the code and
+understand what it does.
+
+While the second form of the loop is a few extra keystrokes, we do strongly
+prefer it.
+
+``#include <iostream>`` is Forbidden
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The use of ``#include <iostream>`` in library files is hereby **forbidden**,
+because many common implementations transparently inject a `static constructor`_
+into every translation unit that includes it.
+  
+Note that using the other stream headers (``<sstream>`` for example) is not
+problematic in this regard --- just ``<iostream>``. However, ``raw_ostream``
+provides various APIs that are better performing for almost every use than
+``std::ostream`` style APIs.
+
+.. note::
+
+  New code should always use `raw_ostream`_ for writing, or the
+  ``llvm::MemoryBuffer`` API for reading files.
+
+.. _raw_ostream:
+
+Use ``raw_ostream``
+^^^^^^^^^^^^^^^^^^^
+
+LLVM includes a lightweight, simple, and efficient stream implementation in
+``llvm/Support/raw_ostream.h``, which provides all of the common features of
+``std::ostream``.  All new code should use ``raw_ostream`` instead of
+``ostream``.
+
+Unlike ``std::ostream``, ``raw_ostream`` is not a template and can be forward
+declared as ``class raw_ostream``.  Public headers should generally not include
+the ``raw_ostream`` header, but use forward declarations and constant references
+to ``raw_ostream`` instances.
+
+Avoid ``std::endl``
+^^^^^^^^^^^^^^^^^^^
+
+The ``std::endl`` modifier, when used with ``iostreams`` outputs a newline to
+the output stream specified.  In addition to doing this, however, it also
+flushes the output stream.  In other words, these are equivalent:
+
+.. code-block:: c++
+
+  std::cout << std::endl;
+  std::cout << '\n' << std::flush;
+
+Most of the time, you probably have no reason to flush the output stream, so
+it's better to use a literal ``'\n'``.
+
+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
+-------------------
+
+This section describes preferred low-level formatting guidelines along with
+reasoning on why we prefer them.
+
+Spaces Before Parentheses
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+We prefer to put a space before an open parenthesis only in control flow
+statements, but not in normal function call expressions and function-like
+macros.  For example, this is good:
+
+.. code-block:: c++
+
+  if (X) ...
+  for (I = 0; I != 100; ++I) ...
+  while (LLVMRocks) ...
+
+  somefunc(42);
+  assert(3 != 4 && "laws of math are failing me");
+  
+  A = foo(42, 92) + bar(X);
+
+and this is bad:
+
+.. code-block:: c++
+
+  if(X) ...
+  for(I = 0; I != 100; ++I) ...
+  while(LLVMRocks) ...
+
+  somefunc (42);
+  assert (3 != 4 && "laws of math are failing me");
+  
+  A = foo (42, 92) + bar (X);
+
+The reason for doing this is not completely arbitrary.  This style makes control
+flow operators stand out more, and makes expressions flow better. The function
+call operator binds very tightly as a postfix operator.  Putting a space after a
+function name (as in the last example) makes it appear that the code might bind
+the arguments of the left-hand-side of a binary operator with the argument list
+of a function and the name of the right side.  More specifically, it is easy to
+misread the "``A``" example as:
+
+.. code-block:: c++
+
+  A = foo ((42, 92) + bar) (X);
+
+when skimming through the code.  By avoiding a space in a function, we avoid
+this misinterpretation.
+
+Prefer Preincrement
+^^^^^^^^^^^^^^^^^^^
+
+Hard fast rule: Preincrement (``++X``) may be no slower than postincrement
+(``X++``) and could very well be a lot faster than it.  Use preincrementation
+whenever possible.
+
+The semantics of postincrement include making a copy of the value being
+incremented, returning it, and then preincrementing the "work value".  For
+primitive types, this isn't a big deal. But for iterators, it can be a huge
+issue (for example, some iterators contains stack and set objects in them...
+copying an iterator could invoke the copy ctor's of these as well).  In general,
+get in the habit of always using preincrement, and you won't have a problem.
+
+
+Namespace Indentation
+^^^^^^^^^^^^^^^^^^^^^
+
+In general, we strive to reduce indentation wherever possible.  This is useful
+because we want code to `fit into 80 columns`_ without wrapping horribly, but
+also because it makes it easier to understand the code. To facilitate this and
+avoid some insanely deep nesting on occasion, don't indent namespaces. If it
+helps readability, feel free to add a comment indicating what namespace is
+being closed by a ``}``.  For example:
+
+.. code-block:: c++
+
+  namespace llvm {
+  namespace knowledge {
+
+  /// This class represents things that Smith can have an intimate
+  /// understanding of and contains the data associated with it.
+  class Grokable {
+  ...
+  public:
+    explicit Grokable() { ... }
+    virtual ~Grokable() = 0;
+  
+    ...
+
+  };
+
+  } // end namespace knowledge
+  } // end namespace llvm
+
+
+Feel free to skip the closing comment when the namespace being closed is
+obvious for any reason. For example, the outer-most namespace in a header file
+is rarely a source of confusion. But namespaces both anonymous and named in
+source files that are being closed half way through the file probably could use
+clarification.
+
+.. _static:
+
+Anonymous Namespaces
+^^^^^^^^^^^^^^^^^^^^
+
+After talking about namespaces in general, you may be wondering about anonymous
+namespaces in particular.  Anonymous namespaces are a great language feature
+that tells the C++ compiler that the contents of the namespace are only visible
+within the current translation unit, allowing more aggressive optimization and
+eliminating the possibility of symbol name collisions.  Anonymous namespaces are
+to C++ as "static" is to C functions and global variables.  While "``static``"
+is available in C++, anonymous namespaces are more general: they can make entire
+classes private to a file.
+
+The problem with anonymous namespaces is that they naturally want to encourage
+indentation of their body, and they reduce locality of reference: if you see a
+random function definition in a C++ file, it is easy to see if it is marked
+static, but seeing if it is in an anonymous namespace requires scanning a big
+chunk of the file.
+
+Because of this, we have a simple guideline: make anonymous namespaces as small
+as possible, and only use them for class declarations.  For example, this is
+good:
+
+.. code-block:: c++
+
+  namespace {
+  class StringSort {
+  ...
+  public:
+    StringSort(...)
+    bool operator<(const char *RHS) const;
+  };
+  } // end anonymous namespace
+
+  static void runHelper() { 
+    ... 
+  }
+
+  bool StringSort::operator<(const char *RHS) const {
+    ...
+  }
+
+This is bad:
+
+.. code-block:: c++
+
+  namespace {
+
+  class StringSort {
+  ...
+  public:
+    StringSort(...)
+    bool operator<(const char *RHS) const;
+  };
+
+  void runHelper() { 
+    ... 
+  }
+
+  bool StringSort::operator<(const char *RHS) const {
+    ...
+  }
+
+  } // end anonymous namespace
+
+This is bad specifically because if you're looking at "``runHelper``" in the middle
+of a large C++ file, that you have no immediate way to tell if it is local to
+the file.  When it is marked static explicitly, this is immediately obvious.
+Also, there is no reason to enclose the definition of "``operator<``" in the
+namespace just because it was declared there.
+
+See Also
+========
+
+A lot of these comments and recommendations have been culled from other sources.
+Two particularly important books for our work are:
+
+#. `Effective C++
+   <https://www.amazon.com/Effective-Specific-Addison-Wesley-Professional-Computing/dp/0321334876>`_
+   by Scott Meyers.  Also interesting and useful are "More Effective C++" and
+   "Effective STL" by the same author.
+
+#. `Large-Scale C++ Software Design
+   <https://www.amazon.com/Large-Scale-Software-Design-John-Lakos/dp/0201633620>`_
+   by John Lakos
+
+If you get some free time, and you haven't read them: do so, you might learn
+something.

Added: www-releases/trunk/8.0.1/docs/_sources/CommandGuide/FileCheck.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.1/docs/_sources/CommandGuide/FileCheck.rst.txt?rev=368037&view=auto
==============================================================================
--- www-releases/trunk/8.0.1/docs/_sources/CommandGuide/FileCheck.rst.txt (added)
+++ www-releases/trunk/8.0.1/docs/_sources/CommandGuide/FileCheck.rst.txt Tue Aug  6 06:51:02 2019
@@ -0,0 +1,603 @@
+FileCheck - Flexible pattern matching file verifier
+===================================================
+
+SYNOPSIS
+--------
+
+:program:`FileCheck` *match-filename* [*--check-prefix=XXX*] [*--strict-whitespace*]
+
+DESCRIPTION
+-----------
+
+:program:`FileCheck` reads two files (one from standard input, and one
+specified on the command line) and uses one to verify the other.  This
+behavior is particularly useful for the testsuite, which wants to verify that
+the output of some tool (e.g. :program:`llc`) contains the expected information
+(for example, a movsd from esp or whatever is interesting).  This is similar to
+using :program:`grep`, but it is optimized for matching multiple different
+inputs in one file in a specific order.
+
+The ``match-filename`` file specifies the file that contains the patterns to
+match.  The file to verify is read from standard input unless the
+:option:`--input-file` option is used.
+
+OPTIONS
+-------
+
+Options are parsed from the environment variable ``FILECHECK_OPTS``
+and from the command line.
+
+.. option:: -help
+
+ Print a summary of command line options.
+
+.. option:: --check-prefix prefix
+
+ FileCheck searches the contents of ``match-filename`` for patterns to
+ match.  By default, these patterns are prefixed with "``CHECK:``".
+ If you'd like to use a different prefix (e.g. because the same input
+ file is checking multiple different tool or options), the
+ :option:`--check-prefix` argument allows you to specify one or more
+ prefixes to match. Multiple prefixes are useful for tests which might
+ change for different run options, but most lines remain the same.
+
+.. option:: --check-prefixes prefix1,prefix2,...
+
+ An alias of :option:`--check-prefix` that allows multiple prefixes to be
+ specified as a comma separated list.
+
+.. option:: --input-file filename
+
+  File to check (defaults to stdin).
+
+.. option:: --match-full-lines
+
+ By default, FileCheck allows matches of anywhere on a line. This
+ option will require all positive matches to cover an entire
+ line. Leading and trailing whitespace is ignored, unless
+ :option:`--strict-whitespace` is also specified. (Note: negative
+ matches from ``CHECK-NOT`` are not affected by this option!)
+
+ Passing this option is equivalent to inserting ``{{^ *}}`` or
+ ``{{^}}`` before, and ``{{ *$}}`` or ``{{$}}`` after every positive
+ check pattern.
+
+.. option:: --strict-whitespace
+
+ By default, FileCheck canonicalizes input horizontal whitespace (spaces and
+ tabs) which causes it to ignore these differences (a space will match a tab).
+ The :option:`--strict-whitespace` argument disables this behavior. End-of-line
+ sequences are canonicalized to UNIX-style ``\n`` in all modes.
+
+.. option:: --implicit-check-not check-pattern
+
+  Adds implicit negative checks for the specified patterns between positive
+  checks. The option allows writing stricter tests without stuffing them with
+  ``CHECK-NOT``\ s.
+
+  For example, "``--implicit-check-not warning:``" can be useful when testing
+  diagnostic messages from tools that don't have an option similar to ``clang
+  -verify``. With this option FileCheck will verify that input does not contain
+  warnings not covered by any ``CHECK:`` patterns.
+
+.. option:: --dump-input <mode>
+
+  Dump input to stderr, adding annotations representing currently enabled
+  diagnostics.  Do this either 'always', on 'fail', or 'never'.  Specify 'help'
+  to explain the dump format and quit.
+
+.. option:: --dump-input-on-failure
+
+  When the check fails, dump all of the original input.  This option is
+  deprecated in favor of `--dump-input=fail`.
+
+.. option:: --enable-var-scope
+
+  Enables scope for regex variables.
+
+  Variables with names that start with ``$`` are considered global and
+  remain set throughout the file.
+
+  All other variables get undefined after each encountered ``CHECK-LABEL``.
+
+.. option:: -D<VAR=VALUE>
+
+  Sets a filecheck variable ``VAR`` with value ``VALUE`` that can be used in
+  ``CHECK:`` lines.
+
+.. option:: -version
+
+ Show the version number of this program.
+
+.. option:: -v
+
+  Print directive pattern matches.
+
+.. option:: -vv
+
+  Print information helpful in diagnosing internal FileCheck issues, such as
+  discarded overlapping ``CHECK-DAG:`` matches, implicit EOF pattern matches,
+  and ``CHECK-NOT:`` patterns that do not have matches.  Implies ``-v``.
+
+.. option:: --allow-deprecated-dag-overlap
+
+  Enable overlapping among matches in a group of consecutive ``CHECK-DAG:``
+  directives.  This option is deprecated and is only provided for convenience
+  as old tests are migrated to the new non-overlapping ``CHECK-DAG:``
+  implementation.
+
+.. option:: --color
+
+  Use colors in output (autodetected by default).
+
+EXIT STATUS
+-----------
+
+If :program:`FileCheck` verifies that the file matches the expected contents,
+it exits with 0.  Otherwise, if not, or if an error occurs, it will exit with a
+non-zero value.
+
+TUTORIAL
+--------
+
+FileCheck is typically used from LLVM regression tests, being invoked on the RUN
+line of the test.  A simple example of using FileCheck from a RUN line looks
+like this:
+
+.. code-block:: llvm
+
+   ; RUN: llvm-as < %s | llc -march=x86-64 | FileCheck %s
+
+This syntax says to pipe the current file ("``%s``") into ``llvm-as``, pipe
+that into ``llc``, then pipe the output of ``llc`` into ``FileCheck``.  This
+means that FileCheck will be verifying its standard input (the llc output)
+against the filename argument specified (the original ``.ll`` file specified by
+"``%s``").  To see how this works, let's look at the rest of the ``.ll`` file
+(after the RUN line):
+
+.. code-block:: llvm
+
+   define void @sub1(i32* %p, i32 %v) {
+   entry:
+   ; CHECK: sub1:
+   ; CHECK: subl
+           %0 = tail call i32 @llvm.atomic.load.sub.i32.p0i32(i32* %p, i32 %v)
+           ret void
+   }
+
+   define void @inc4(i64* %p) {
+   entry:
+   ; CHECK: inc4:
+   ; CHECK: incq
+           %0 = tail call i64 @llvm.atomic.load.add.i64.p0i64(i64* %p, i64 1)
+           ret void
+   }
+
+Here you can see some "``CHECK:``" lines specified in comments.  Now you can
+see how the file is piped into ``llvm-as``, then ``llc``, and the machine code
+output is what we are verifying.  FileCheck checks the machine code output to
+verify that it matches what the "``CHECK:``" lines specify.
+
+The syntax of the "``CHECK:``" lines is very simple: they are fixed strings that
+must occur in order.  FileCheck defaults to ignoring horizontal whitespace
+differences (e.g. a space is allowed to match a tab) but otherwise, the contents
+of the "``CHECK:``" line is required to match some thing in the test file exactly.
+
+One nice thing about FileCheck (compared to grep) is that it allows merging
+test cases together into logical groups.  For example, because the test above
+is checking for the "``sub1:``" and "``inc4:``" labels, it will not match
+unless there is a "``subl``" in between those labels.  If it existed somewhere
+else in the file, that would not count: "``grep subl``" matches if "``subl``"
+exists anywhere in the file.
+
+The FileCheck -check-prefix option
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The FileCheck `-check-prefix` option allows multiple test
+configurations to be driven from one `.ll` file.  This is useful in many
+circumstances, for example, testing different architectural variants with
+:program:`llc`.  Here's a simple example:
+
+.. code-block:: llvm
+
+   ; RUN: llvm-as < %s | llc -mtriple=i686-apple-darwin9 -mattr=sse41 \
+   ; RUN:              | FileCheck %s -check-prefix=X32
+   ; RUN: llvm-as < %s | llc -mtriple=x86_64-apple-darwin9 -mattr=sse41 \
+   ; RUN:              | FileCheck %s -check-prefix=X64
+
+   define <4 x i32> @pinsrd_1(i32 %s, <4 x i32> %tmp) nounwind {
+           %tmp1 = insertelement <4 x i32>; %tmp, i32 %s, i32 1
+           ret <4 x i32> %tmp1
+   ; X32: pinsrd_1:
+   ; X32:    pinsrd $1, 4(%esp), %xmm0
+
+   ; X64: pinsrd_1:
+   ; X64:    pinsrd $1, %edi, %xmm0
+   }
+
+In this case, we're testing that we get the expected code generation with
+both 32-bit and 64-bit code generation.
+
+The "CHECK-NEXT:" directive
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Sometimes you want to match lines and would like to verify that matches
+happen on exactly consecutive lines with no other lines in between them.  In
+this case, you can use "``CHECK:``" and "``CHECK-NEXT:``" directives to specify
+this.  If you specified a custom check prefix, just use "``<PREFIX>-NEXT:``".
+For example, something like this works as you'd expect:
+
+.. code-block:: llvm
+
+   define void @t2(<2 x double>* %r, <2 x double>* %A, double %B) {
+ 	%tmp3 = load <2 x double>* %A, align 16
+ 	%tmp7 = insertelement <2 x double> undef, double %B, i32 0
+ 	%tmp9 = shufflevector <2 x double> %tmp3,
+                               <2 x double> %tmp7,
+                               <2 x i32> < i32 0, i32 2 >
+ 	store <2 x double> %tmp9, <2 x double>* %r, align 16
+ 	ret void
+
+   ; CHECK:          t2:
+   ; CHECK: 	        movl	8(%esp), %eax
+   ; CHECK-NEXT: 	movapd	(%eax), %xmm0
+   ; CHECK-NEXT: 	movhpd	12(%esp), %xmm0
+   ; CHECK-NEXT: 	movl	4(%esp), %eax
+   ; CHECK-NEXT: 	movapd	%xmm0, (%eax)
+   ; CHECK-NEXT: 	ret
+   }
+
+"``CHECK-NEXT:``" directives reject the input unless there is exactly one
+newline between it and the previous directive.  A "``CHECK-NEXT:``" cannot be
+the first directive in a file.
+
+The "CHECK-SAME:" directive
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Sometimes you want to match lines and would like to verify that matches happen
+on the same line as the previous match.  In this case, you can use "``CHECK:``"
+and "``CHECK-SAME:``" directives to specify this.  If you specified a custom
+check prefix, just use "``<PREFIX>-SAME:``".
+
+"``CHECK-SAME:``" is particularly powerful in conjunction with "``CHECK-NOT:``"
+(described below).
+
+For example, the following works like you'd expect:
+
+.. code-block:: llvm
+
+   !0 = !DILocation(line: 5, scope: !1, inlinedAt: !2)
+
+   ; CHECK:       !DILocation(line: 5,
+   ; CHECK-NOT:               column:
+   ; CHECK-SAME:              scope: ![[SCOPE:[0-9]+]]
+
+"``CHECK-SAME:``" directives reject the input if there are any newlines between
+it and the previous directive.  A "``CHECK-SAME:``" cannot be the first
+directive in a file.
+
+The "CHECK-EMPTY:" directive
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you need to check that the next line has nothing on it, not even whitespace,
+you can use the "``CHECK-EMPTY:``" directive.
+
+.. code-block:: llvm
+
+   declare void @foo()
+
+   declare void @bar()
+   ; CHECK: foo
+   ; CHECK-EMPTY:
+   ; CHECK-NEXT: bar
+
+Just like "``CHECK-NEXT:``" the directive will fail if there is more than one
+newline before it finds the next blank line, and it cannot be the first
+directive in a file.
+
+The "CHECK-NOT:" directive
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The "``CHECK-NOT:``" directive is used to verify that a string doesn't occur
+between two matches (or before the first match, or after the last match).  For
+example, to verify that a load is removed by a transformation, a test like this
+can be used:
+
+.. code-block:: llvm
+
+   define i8 @coerce_offset0(i32 %V, i32* %P) {
+     store i32 %V, i32* %P
+
+     %P2 = bitcast i32* %P to i8*
+     %P3 = getelementptr i8* %P2, i32 2
+
+     %A = load i8* %P3
+     ret i8 %A
+   ; CHECK: @coerce_offset0
+   ; CHECK-NOT: load
+   ; CHECK: ret i8
+   }
+
+The "CHECK-COUNT:" directive
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you need to match multiple lines with the same pattern over and over again
+you can repeat a plain ``CHECK:`` as many times as needed. If that looks too
+boring you can instead use a counted check "``CHECK-COUNT-<num>:``", where
+``<num>`` is a positive decimal number. It will match the pattern exactly
+``<num>`` times, no more and no less. If you specified a custom check prefix,
+just use "``<PREFIX>-COUNT-<num>:``" for the same effect.
+Here is a simple example:
+
+.. code-block:: text
+
+   Loop at depth 1
+   Loop at depth 1
+   Loop at depth 1
+   Loop at depth 1
+     Loop at depth 2
+       Loop at depth 3
+
+   ; CHECK-COUNT-6: Loop at depth {{[0-9]+}}
+   ; CHECK-NOT:     Loop at depth {{[0-9]+}}
+
+The "CHECK-DAG:" directive
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If it's necessary to match strings that don't occur in a strictly sequential
+order, "``CHECK-DAG:``" could be used to verify them between two matches (or
+before the first match, or after the last match). For example, clang emits
+vtable globals in reverse order. Using ``CHECK-DAG:``, we can keep the checks
+in the natural order:
+
+.. code-block:: c++
+
+    // RUN: %clang_cc1 %s -emit-llvm -o - | FileCheck %s
+
+    struct Foo { virtual void method(); };
+    Foo f;  // emit vtable
+    // CHECK-DAG: @_ZTV3Foo =
+
+    struct Bar { virtual void method(); };
+    Bar b;
+    // CHECK-DAG: @_ZTV3Bar =
+
+``CHECK-NOT:`` directives could be mixed with ``CHECK-DAG:`` directives to
+exclude strings between the surrounding ``CHECK-DAG:`` directives. As a result,
+the surrounding ``CHECK-DAG:`` directives cannot be reordered, i.e. all
+occurrences matching ``CHECK-DAG:`` before ``CHECK-NOT:`` must not fall behind
+occurrences matching ``CHECK-DAG:`` after ``CHECK-NOT:``. For example,
+
+.. code-block:: llvm
+
+   ; CHECK-DAG: BEFORE
+   ; CHECK-NOT: NOT
+   ; CHECK-DAG: AFTER
+
+This case will reject input strings where ``BEFORE`` occurs after ``AFTER``.
+
+With captured variables, ``CHECK-DAG:`` is able to match valid topological
+orderings of a DAG with edges from the definition of a variable to its use.
+It's useful, e.g., when your test cases need to match different output
+sequences from the instruction scheduler. For example,
+
+.. code-block:: llvm
+
+   ; CHECK-DAG: add [[REG1:r[0-9]+]], r1, r2
+   ; CHECK-DAG: add [[REG2:r[0-9]+]], r3, r4
+   ; CHECK:     mul r5, [[REG1]], [[REG2]]
+
+In this case, any order of that two ``add`` instructions will be allowed.
+
+If you are defining `and` using variables in the same ``CHECK-DAG:`` block,
+be aware that the definition rule can match `after` its use.
+
+So, for instance, the code below will pass:
+
+.. code-block:: text
+
+  ; CHECK-DAG: vmov.32 [[REG2:d[0-9]+]][0]
+  ; CHECK-DAG: vmov.32 [[REG2]][1]
+  vmov.32 d0[1]
+  vmov.32 d0[0]
+
+While this other code, will not:
+
+.. code-block:: text
+
+  ; CHECK-DAG: vmov.32 [[REG2:d[0-9]+]][0]
+  ; CHECK-DAG: vmov.32 [[REG2]][1]
+  vmov.32 d1[1]
+  vmov.32 d0[0]
+
+While this can be very useful, it's also dangerous, because in the case of
+register sequence, you must have a strong order (read before write, copy before
+use, etc). If the definition your test is looking for doesn't match (because
+of a bug in the compiler), it may match further away from the use, and mask
+real bugs away.
+
+In those cases, to enforce the order, use a non-DAG directive between DAG-blocks.
+
+A ``CHECK-DAG:`` directive skips matches that overlap the matches of any
+preceding ``CHECK-DAG:`` directives in the same ``CHECK-DAG:`` block.  Not only
+is this non-overlapping behavior consistent with other directives, but it's
+also necessary to handle sets of non-unique strings or patterns.  For example,
+the following directives look for unordered log entries for two tasks in a
+parallel program, such as the OpenMP runtime:
+
+.. code-block:: text
+
+    // CHECK-DAG: [[THREAD_ID:[0-9]+]]: task_begin
+    // CHECK-DAG: [[THREAD_ID]]: task_end
+    //
+    // CHECK-DAG: [[THREAD_ID:[0-9]+]]: task_begin
+    // CHECK-DAG: [[THREAD_ID]]: task_end
+
+The second pair of directives is guaranteed not to match the same log entries
+as the first pair even though the patterns are identical and even if the text
+of the log entries is identical because the thread ID manages to be reused.
+
+The "CHECK-LABEL:" directive
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Sometimes in a file containing multiple tests divided into logical blocks, one
+or more ``CHECK:`` directives may inadvertently succeed by matching lines in a
+later block. While an error will usually eventually be generated, the check
+flagged as causing the error may not actually bear any relationship to the
+actual source of the problem.
+
+In order to produce better error messages in these cases, the "``CHECK-LABEL:``"
+directive can be used. It is treated identically to a normal ``CHECK``
+directive except that FileCheck makes an additional assumption that a line
+matched by the directive cannot also be matched by any other check present in
+``match-filename``; this is intended to be used for lines containing labels or
+other unique identifiers. Conceptually, the presence of ``CHECK-LABEL`` divides
+the input stream into separate blocks, each of which is processed independently,
+preventing a ``CHECK:`` directive in one block matching a line in another block.
+If ``--enable-var-scope`` is in effect, all local variables are cleared at the
+beginning of the block.
+
+For example,
+
+.. code-block:: llvm
+
+  define %struct.C* @C_ctor_base(%struct.C* %this, i32 %x) {
+  entry:
+  ; CHECK-LABEL: C_ctor_base:
+  ; CHECK: mov [[SAVETHIS:r[0-9]+]], r0
+  ; CHECK: bl A_ctor_base
+  ; CHECK: mov r0, [[SAVETHIS]]
+    %0 = bitcast %struct.C* %this to %struct.A*
+    %call = tail call %struct.A* @A_ctor_base(%struct.A* %0)
+    %1 = bitcast %struct.C* %this to %struct.B*
+    %call2 = tail call %struct.B* @B_ctor_base(%struct.B* %1, i32 %x)
+    ret %struct.C* %this
+  }
+
+  define %struct.D* @D_ctor_base(%struct.D* %this, i32 %x) {
+  entry:
+  ; CHECK-LABEL: D_ctor_base:
+
+The use of ``CHECK-LABEL:`` directives in this case ensures that the three
+``CHECK:`` directives only accept lines corresponding to the body of the
+``@C_ctor_base`` function, even if the patterns match lines found later in
+the file. Furthermore, if one of these three ``CHECK:`` directives fail,
+FileCheck will recover by continuing to the next block, allowing multiple test
+failures to be detected in a single invocation.
+
+There is no requirement that ``CHECK-LABEL:`` directives contain strings that
+correspond to actual syntactic labels in a source or output language: they must
+simply uniquely match a single line in the file being verified.
+
+``CHECK-LABEL:`` directives cannot contain variable definitions or uses.
+
+FileCheck Pattern Matching Syntax
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+All FileCheck directives take a pattern to match.
+For most uses of FileCheck, fixed string matching is perfectly sufficient.  For
+some things, a more flexible form of matching is desired.  To support this,
+FileCheck allows you to specify regular expressions in matching strings,
+surrounded by double braces: ``{{yourregex}}``. FileCheck implements a POSIX
+regular expression matcher; it supports Extended POSIX regular expressions
+(ERE). Because we want to use fixed string matching for a majority of what we
+do, FileCheck has been designed to support mixing and matching fixed string
+matching with regular expressions.  This allows you to write things like this:
+
+.. code-block:: llvm
+
+   ; CHECK: movhpd	{{[0-9]+}}(%esp), {{%xmm[0-7]}}
+
+In this case, any offset from the ESP register will be allowed, and any xmm
+register will be allowed.
+
+Because regular expressions are enclosed with double braces, they are
+visually distinct, and you don't need to use escape characters within the double
+braces like you would in C.  In the rare case that you want to match double
+braces explicitly from the input, you can use something ugly like
+``{{[{][{]}}`` as your pattern.
+
+FileCheck Variables
+~~~~~~~~~~~~~~~~~~~
+
+It is often useful to match a pattern and then verify that it occurs again
+later in the file.  For codegen tests, this can be useful to allow any register,
+but verify that that register is used consistently later.  To do this,
+:program:`FileCheck` allows named variables to be defined and substituted into
+patterns.  Here is a simple example:
+
+.. code-block:: llvm
+
+   ; CHECK: test5:
+   ; CHECK:    notw	[[REGISTER:%[a-z]+]]
+   ; CHECK:    andw	{{.*}}[[REGISTER]]
+
+The first check line matches a regex ``%[a-z]+`` and captures it into the
+variable ``REGISTER``.  The second line verifies that whatever is in
+``REGISTER`` occurs later in the file after an "``andw``".  :program:`FileCheck`
+variable references are always contained in ``[[ ]]`` pairs, and their names can
+be formed with the regex ``[a-zA-Z_][a-zA-Z0-9_]*``.  If a colon follows the name,
+then it is a definition of the variable; otherwise, it is a use.
+
+:program:`FileCheck` variables can be defined multiple times, and uses always
+get the latest value.  Variables can also be used later on the same line they
+were defined on. For example:
+
+.. code-block:: llvm
+
+    ; CHECK: op [[REG:r[0-9]+]], [[REG]]
+
+Can be useful if you want the operands of ``op`` to be the same register,
+and don't care exactly which register it is.
+
+If ``--enable-var-scope`` is in effect, variables with names that
+start with ``$`` are considered to be global. All others variables are
+local.  All local variables get undefined at the beginning of each
+CHECK-LABEL block. Global variables are not affected by CHECK-LABEL.
+This makes it easier to ensure that individual tests are not affected
+by variables set in preceding tests.
+
+FileCheck Expressions
+~~~~~~~~~~~~~~~~~~~~~
+
+Sometimes there's a need to verify output which refers line numbers of the
+match file, e.g. when testing compiler diagnostics.  This introduces a certain
+fragility of the match file structure, as "``CHECK:``" lines contain absolute
+line numbers in the same file, which have to be updated whenever line numbers
+change due to text addition or deletion.
+
+To support this case, FileCheck allows using ``[[@LINE]]``,
+``[[@LINE+<offset>]]``, ``[[@LINE-<offset>]]`` expressions in patterns. These
+expressions expand to a number of the line where a pattern is located (with an
+optional integer offset).
+
+This way match patterns can be put near the relevant test lines and include
+relative line number references, for example:
+
+.. code-block:: c++
+
+   // CHECK: test.cpp:[[@LINE+4]]:6: error: expected ';' after top level declarator
+   // CHECK-NEXT: {{^int a}}
+   // CHECK-NEXT: {{^     \^}}
+   // CHECK-NEXT: {{^     ;}}
+   int a
+
+Matching Newline Characters
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To match newline characters in regular expressions the character class
+``[[:space:]]`` can be used. For example, the following pattern:
+
+.. code-block:: c++
+
+   // CHECK: DW_AT_location [DW_FORM_sec_offset] ([[DLOC:0x[0-9a-f]+]]){{[[:space:]].*}}"intd"
+
+matches output of the form (from llvm-dwarfdump):
+
+.. code-block:: text
+
+       DW_AT_location [DW_FORM_sec_offset]   (0x00000233)
+       DW_AT_name [DW_FORM_strp]  ( .debug_str[0x000000c9] = "intd")
+
+letting us set the :program:`FileCheck` variable ``DLOC`` to the desired value 
+``0x00000233``, extracted from the line immediately preceding "``intd``".

Added: www-releases/trunk/8.0.1/docs/_sources/CommandGuide/bugpoint.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.1/docs/_sources/CommandGuide/bugpoint.rst.txt?rev=368037&view=auto
==============================================================================
--- www-releases/trunk/8.0.1/docs/_sources/CommandGuide/bugpoint.rst.txt (added)
+++ www-releases/trunk/8.0.1/docs/_sources/CommandGuide/bugpoint.rst.txt Tue Aug  6 06:51:02 2019
@@ -0,0 +1,196 @@
+bugpoint - automatic test case reduction tool
+=============================================
+
+SYNOPSIS
+--------
+
+**bugpoint** [*options*] [*input LLVM ll/bc files*] [*LLVM passes*] **--args**
+*program arguments*
+
+DESCRIPTION
+-----------
+
+**bugpoint** narrows down the source of problems in LLVM tools and passes.  It
+can be used to debug three types of failures: optimizer crashes, miscompilations
+by optimizers, or bad native code generation (including problems in the static
+and JIT compilers).  It aims to reduce large test cases to small, useful ones.
+For more information on the design and inner workings of **bugpoint**, as well as
+advice for using bugpoint, see :doc:`/Bugpoint` in the LLVM
+distribution.
+
+OPTIONS
+-------
+
+**--additional-so** *library*
+
+ Load the dynamic shared object *library* into the test program whenever it is
+ run.  This is useful if you are debugging programs which depend on non-LLVM
+ libraries (such as the X or curses libraries) to run.
+
+**--append-exit-code**\ =\ *{true,false}*
+
+ Append the test programs exit code to the output file so that a change in exit
+ code is considered a test failure. Defaults to false.
+
+**--args** *program args*
+
+ Pass all arguments specified after **--args** to the test program whenever it runs.
+ Note that if any of the *program args* start with a "``-``", you should use:
+
+ .. code-block:: bash
+
+      bugpoint [bugpoint args] --args -- [program args]
+
+ The "``--``" right after the **--args** option tells **bugpoint** to consider
+ any options starting with "``-``" to be part of the **--args** option, not as
+ options to **bugpoint** itself.
+
+**--tool-args** *tool args*
+
+ Pass all arguments specified after **--tool-args** to the LLVM tool under test
+ (**llc**, **lli**, etc.) whenever it runs.  You should use this option in the
+ following way:
+
+ .. code-block:: bash
+
+      bugpoint [bugpoint args] --tool-args -- [tool args]
+
+ The "``--``" right after the **--tool-args** option tells **bugpoint** to
+ consider any options starting with "``-``" to be part of the **--tool-args**
+ option, not as options to **bugpoint** itself. (See **--args**, above.)
+
+**--safe-tool-args** *tool args*
+
+ Pass all arguments specified after **--safe-tool-args** to the "safe" execution
+ tool.
+
+**--gcc-tool-args** *gcc tool args*
+
+ Pass all arguments specified after **--gcc-tool-args** to the invocation of
+ **gcc**.
+
+**--opt-args** *opt args*
+
+ Pass all arguments specified after **--opt-args** to the invocation of **opt**.
+
+**--disable-{dce,simplifycfg}**
+
+ Do not run the specified passes to clean up and reduce the size of the test
+ program. By default, **bugpoint** uses these passes internally when attempting to
+ reduce test programs.  If you're trying to find a bug in one of these passes,
+ **bugpoint** may crash.
+
+**--enable-valgrind**
+
+ Use valgrind to find faults in the optimization phase. This will allow
+ bugpoint to find otherwise asymptomatic problems caused by memory
+ mis-management.
+
+**-find-bugs**
+
+ Continually randomize the specified passes and run them on the test program
+ until a bug is found or the user kills **bugpoint**.
+
+**-help**
+
+ Print a summary of command line options.
+
+**--input** *filename*
+
+ Open *filename* and redirect the standard input of the test program, whenever
+ it runs, to come from that file.
+
+**--load** *plugin*
+
+ Load the dynamic object *plugin* into **bugpoint** itself.  This object should
+ register new optimization passes.  Once loaded, the object will add new command
+ line options to enable various optimizations.  To see the new complete list of
+ optimizations, use the **-help** and **--load** options together; for example:
+
+
+ .. code-block:: bash
+
+      bugpoint --load myNewPass.so -help
+
+**--mlimit** *megabytes*
+
+ Specifies an upper limit on memory usage of the optimization and codegen. Set
+ to zero to disable the limit.
+
+**--output** *filename*
+
+ Whenever the test program produces output on its standard output stream, it
+ should match the contents of *filename* (the "reference output"). If you
+ do not use this option, **bugpoint** will attempt to generate a reference output
+ by compiling the program with the "safe" backend and running it.
+
+**--run-{int,jit,llc,custom}**
+
+ Whenever the test program is compiled, **bugpoint** should generate code for it
+ using the specified code generator.  These options allow you to choose the
+ interpreter, the JIT compiler, the static native code compiler, or a
+ custom command (see **--exec-command**) respectively.
+
+**--safe-{llc,custom}**
+
+ When debugging a code generator, **bugpoint** should use the specified code
+ generator as the "safe" code generator. This is a known-good code generator
+ used to generate the "reference output" if it has not been provided, and to
+ compile portions of the program that as they are excluded from the testcase.
+ These options allow you to choose the
+ static native code compiler, or a custom command, (see **--exec-command**)
+ respectively. The interpreter and the JIT backends cannot currently
+ be used as the "safe" backends.
+
+**--exec-command** *command*
+
+ This option defines the command to use with the **--run-custom** and
+ **--safe-custom** options to execute the bitcode testcase. This can
+ be useful for cross-compilation.
+
+**--compile-command** *command*
+
+ This option defines the command to use with the **--compile-custom**
+ option to compile the bitcode testcase. The command should exit with a
+ failure exit code if the file is "interesting" and should exit with a
+ success exit code (i.e. 0) otherwise (this is the same as if it crashed on
+ "interesting" inputs).
+
+ This can be useful for
+ testing compiler output without running any link or execute stages. To
+ generate a reduced unit test, you may add CHECK directives to the
+ testcase and pass the name of an executable compile-command script in this form:
+
+ .. code-block:: sh
+
+      #!/bin/sh
+      llc "$@"
+      not FileCheck [bugpoint input file].ll < bugpoint-test-program.s
+
+ This script will "fail" as long as FileCheck passes. So the result
+ will be the minimum bitcode that passes FileCheck.
+
+**--safe-path** *path*
+
+ This option defines the path to the command to execute with the
+ **--safe-{int,jit,llc,custom}**
+ option.
+
+**--verbose-errors**\ =\ *{true,false}*
+
+ The default behavior of bugpoint is to print "<crash>" when it finds a reduced
+ test that crashes compilation. This flag prints the output of the crashing
+ program to stderr. This is useful to make sure it is the same error being
+ tracked down and not a different error that happens to crash the compiler as
+ well. Defaults to false.
+
+EXIT STATUS
+-----------
+
+If **bugpoint** succeeds in finding a problem, it will exit with 0.  Otherwise,
+if an error occurs, it will exit with a non-zero value.
+
+SEE ALSO
+--------
+
+opt|opt

Added: www-releases/trunk/8.0.1/docs/_sources/CommandGuide/dsymutil.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.1/docs/_sources/CommandGuide/dsymutil.rst.txt?rev=368037&view=auto
==============================================================================
--- www-releases/trunk/8.0.1/docs/_sources/CommandGuide/dsymutil.rst.txt (added)
+++ www-releases/trunk/8.0.1/docs/_sources/CommandGuide/dsymutil.rst.txt Tue Aug  6 06:51:02 2019
@@ -0,0 +1,115 @@
+dsymutil - manipulate archived DWARF debug symbol files
+=======================================================
+
+SYNOPSIS
+--------
+
+| :program:`dsymutil` [*options*] *executable*
+
+DESCRIPTION
+-----------
+
+:program:`dsymutil` links the DWARF debug information found in the object files
+for an executable *executable* by using debug symbols information contained in
+its symbol table. By default, the linked debug information is placed in a
+``.dSYM`` bundle with the same name as the executable.
+
+OPTIONS
+-------
+.. option:: --arch=<arch>
+
+ Link DWARF debug information only for specified CPU architecture types.
+ Architectures may be specified by name. When using this option, an error will
+ be returned if any architectures can not be properly linked.  This option can
+ be specified multiple times, once for each desired architecture. All CPU
+ architectures will be linked by default and any architectures that can't be
+ properly linked will cause :program:`dsymutil` to return an error.
+
+.. option:: --dump-debug-map
+
+ Dump the *executable*'s debug-map (the list of the object files containing the
+ debug information) in YAML format and exit. Not DWARF link will take place.
+
+.. option:: -f, --flat
+
+ Produce a flat dSYM file. A ``.dwarf`` extension will be appended to the
+ executable name unless the output file is specified using the -o option.
+
+
+.. option:: -z, --minimize
+
+ When used when creating a dSYM file, this option will suppress the emission of
+ the .debug_inlines, .debug_pubnames, and .debug_pubtypes sections since
+ dsymutil currently has better equivalents: .apple_names and .apple_types. When
+ used in conjunction with --update option, this option will cause redundant
+ accelerator tables to be removed.
+
+.. option:: --no-odr
+
+ Do not use ODR (One Definition Rule) for uniquing C++ types.
+
+.. option:: --no-output
+
+ Do the link in memory, but do not emit the result file.
+
+.. option:: --no-swiftmodule-timestamp
+
+ Don't check the timestamp for swiftmodule files.
+
+.. option:: -j <n>, --num-threads=<n>
+
+ Specifies the maximum number (``n``) of simultaneous threads to use when
+ linking multiple architectures.
+
+.. option:: -o <filename>
+
+ Specifies an alternate ``path`` to place the dSYM bundle. The default dSYM
+ bundle path is created by appending ``.dSYM`` to the executable name.
+
+.. option:: --oso-prepend-path=<path>
+
+ Specifies a ``path`` to prepend to all debug symbol object file paths.
+
+.. option:: --papertrail
+
+ When running dsymutil as part of your build system, it can be desirable for
+ warnings to be part of the end product, rather than just being emitted to the
+ output stream. When enabled warnings are embedded in the linked DWARF debug
+ information.
+
+.. option:: -s, --symtab
+
+ Dumps the symbol table found in *executable* or object file(s) and exits.
+
+.. option:: --toolchain
+
+ Embed the toolchain in the dSYM bundle's property list.
+
+.. option:: -u, --update
+
+ Update an existing dSYM file to contain the latest accelerator tables and
+ other DWARF optimizations. This option will rebuild the '.apple_names' and
+ '.apple_types' hashed accelerator tables.
+
+.. option:: -v, --verbose
+
+ Display verbose information when linking.
+
+.. option:: --version
+
+ Display the version of the tool.
+
+.. option:: -y
+
+ Treat *executable* as a YAML debug-map rather than an executable.
+
+EXIT STATUS
+-----------
+
+:program:`dsymutil` returns 0 if the DWARF debug information was linked
+successfully. Otherwise, it returns 1.
+
+SEE ALSO
+--------
+
+:manpage:`llvm-dwarfdump(1)`

Added: www-releases/trunk/8.0.1/docs/_sources/CommandGuide/index.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.1/docs/_sources/CommandGuide/index.rst.txt?rev=368037&view=auto
==============================================================================
--- www-releases/trunk/8.0.1/docs/_sources/CommandGuide/index.rst.txt (added)
+++ www-releases/trunk/8.0.1/docs/_sources/CommandGuide/index.rst.txt Tue Aug  6 06:51:02 2019
@@ -0,0 +1,60 @@
+LLVM Command Guide
+------------------
+
+The following documents are command descriptions for all of the LLVM tools.
+These pages describe how to use the LLVM commands and what their options are.
+Note that these pages do not describe all of the options available for all
+tools. To get a complete listing, pass the ``--help`` (general options) or
+``--help-hidden`` (general and debugging options) arguments to the tool you are
+interested in.
+
+Basic Commands
+~~~~~~~~~~~~~~
+
+.. toctree::
+   :maxdepth: 1
+
+   llvm-as
+   llvm-dis
+   opt
+   llc
+   lli
+   llvm-link
+   llvm-ar
+   llvm-lib
+   llvm-nm
+   llvm-objdump
+   llvm-config
+   llvm-cxxmap
+   llvm-diff
+   llvm-cov
+   llvm-profdata
+   llvm-stress
+   llvm-symbolizer
+   llvm-dwarfdump
+   dsymutil
+   llvm-mca
+
+Debugging Tools
+~~~~~~~~~~~~~~~
+
+.. toctree::
+   :maxdepth: 1
+
+   bugpoint
+   llvm-extract
+   llvm-bcanalyzer
+
+Developer Tools
+~~~~~~~~~~~~~~~
+
+.. toctree::
+   :maxdepth: 1
+
+   FileCheck
+   tblgen
+   lit
+   llvm-build
+   llvm-exegesis
+   llvm-pdbutil
+   llvm-readobj

Added: www-releases/trunk/8.0.1/docs/_sources/CommandGuide/lit.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.1/docs/_sources/CommandGuide/lit.rst.txt?rev=368037&view=auto
==============================================================================
--- www-releases/trunk/8.0.1/docs/_sources/CommandGuide/lit.rst.txt (added)
+++ www-releases/trunk/8.0.1/docs/_sources/CommandGuide/lit.rst.txt Tue Aug  6 06:51:02 2019
@@ -0,0 +1,482 @@
+lit - LLVM Integrated Tester
+============================
+
+SYNOPSIS
+--------
+
+:program:`lit` [*options*] [*tests*]
+
+DESCRIPTION
+-----------
+
+:program:`lit` is a portable tool for executing LLVM and Clang style test
+suites, summarizing their results, and providing indication of failures.
+:program:`lit` is designed to be a lightweight testing tool with as simple a
+user interface as possible.
+
+:program:`lit` should be run with one or more *tests* to run specified on the
+command line.  Tests can be either individual test files or directories to
+search for tests (see :ref:`test-discovery`).
+
+Each specified test will be executed (potentially in parallel) and once all
+tests have been run :program:`lit` will print summary information on the number
+of tests which passed or failed (see :ref:`test-status-results`).  The
+:program:`lit` program will execute with a non-zero exit code if any tests
+fail.
+
+By default :program:`lit` will use a succinct progress display and will only
+print summary information for test failures.  See :ref:`output-options` for
+options controlling the :program:`lit` progress display and output.
+
+:program:`lit` also includes a number of options for controlling how tests are
+executed (specific features may depend on the particular test format).  See
+:ref:`execution-options` for more information.
+
+Finally, :program:`lit` also supports additional options for only running a
+subset of the options specified on the command line, see
+:ref:`selection-options` for more information.
+
+Users interested in the :program:`lit` architecture or designing a
+:program:`lit` testing implementation should see :ref:`lit-infrastructure`.
+
+GENERAL OPTIONS
+---------------
+
+.. option:: -h, --help
+
+ Show the :program:`lit` help message.
+
+.. option:: -j N, --threads=N
+
+ Run ``N`` tests in parallel.  By default, this is automatically chosen to
+ match the number of detected available CPUs.
+
+.. option:: --config-prefix=NAME
+
+ Search for :file:`{NAME}.cfg` and :file:`{NAME}.site.cfg` when searching for
+ test suites, instead of :file:`lit.cfg` and :file:`lit.site.cfg`.
+
+.. option:: -D NAME[=VALUE], --param NAME[=VALUE]
+
+ Add a user defined parameter ``NAME`` with the given ``VALUE`` (or the empty
+ string if not given).  The meaning and use of these parameters is test suite
+ dependent.
+
+.. _output-options:
+
+OUTPUT OPTIONS
+--------------
+
+.. option:: -q, --quiet
+
+ Suppress any output except for test failures.
+
+.. option:: -s, --succinct
+
+ Show less output, for example don't show information on tests that pass.
+
+.. option:: -v, --verbose
+
+ Show more information on test failures, for example the entire test output
+ instead of just the test result.
+
+.. option:: -vv, --echo-all-commands
+
+ Echo all commands to stdout, as they are being executed.
+ This can be valuable for debugging test failures, as the last echoed command
+ will be the one which has failed.
+ :program:`lit` normally inserts a no-op command (``:`` in the case of bash)
+ with argument ``'RUN: at line N'`` before each command pipeline, and this
+ option also causes those no-op commands to be echoed to stdout to help you
+ locate the source line of the failed command.
+ This option implies ``--verbose``.
+
+.. option:: -a, --show-all
+
+ Show more information about all tests, for example the entire test
+ commandline and output.
+
+.. option:: --no-progress-bar
+
+ Do not use curses based progress bar.
+
+.. option:: --show-unsupported
+
+ Show the names of unsupported tests.
+
+.. option:: --show-xfail
+
+ Show the names of tests that were expected to fail.
+
+.. _execution-options:
+
+EXECUTION OPTIONS
+-----------------
+
+.. option:: --path=PATH
+
+ Specify an additional ``PATH`` to use when searching for executables in tests.
+
+.. option:: --vg
+
+ Run individual tests under valgrind (using the memcheck tool).  The
+ ``--error-exitcode`` argument for valgrind is used so that valgrind failures
+ will cause the program to exit with a non-zero status.
+
+ When this option is enabled, :program:`lit` will also automatically provide a
+ "``valgrind``" feature that can be used to conditionally disable (or expect
+ failure in) certain tests.
+
+.. option:: --vg-arg=ARG
+
+ When :option:`--vg` is used, specify an additional argument to pass to
+ :program:`valgrind` itself.
+
+.. option:: --vg-leak
+
+ When :option:`--vg` is used, enable memory leak checks.  When this option is
+ enabled, :program:`lit` will also automatically provide a "``vg_leak``"
+ feature that can be used to conditionally disable (or expect failure in)
+ certain tests.
+
+.. option:: --time-tests
+
+ Track the wall time individual tests take to execute and includes the results
+ in the summary output.  This is useful for determining which tests in a test
+ suite take the most time to execute.  Note that this option is most useful
+ with ``-j 1``.
+
+.. _selection-options:
+
+SELECTION OPTIONS
+-----------------
+
+.. option:: --max-tests=N
+
+ Run at most ``N`` tests and then terminate.
+
+.. option:: --max-time=N
+
+ Spend at most ``N`` seconds (approximately) running tests and then terminate.
+
+.. option:: --shuffle
+
+ Run the tests in a random order.
+
+.. option:: --num-shards=M
+
+ Divide the set of selected tests into ``M`` equal-sized subsets or
+ "shards", and run only one of them.  Must be used with the
+ ``--run-shard=N`` option, which selects the shard to run. The environment
+ variable ``LIT_NUM_SHARDS`` can also be used in place of this
+ option. These two options provide a coarse mechanism for paritioning large
+ testsuites, for parallel execution on separate machines (say in a large
+ testing farm).
+
+.. option:: --run-shard=N
+
+ Select which shard to run, assuming the ``--num-shards=M`` option was
+ provided. The two options must be used together, and the value of ``N``
+ must be in the range ``1..M``. The environment variable
+ ``LIT_RUN_SHARD`` can also be used in place of this option.
+
+.. option:: --filter=REGEXP
+
+  Run only those tests whose name matches the regular expression specified in
+  ``REGEXP``. The environment variable ``LIT_FILTER`` can be also used in place
+  of this option, which is especially useful in environments where the call
+  to ``lit`` is issued indirectly.
+
+ADDITIONAL OPTIONS
+------------------
+
+.. option:: --debug
+
+ Run :program:`lit` in debug mode, for debugging configuration issues and
+ :program:`lit` itself.
+
+.. option:: --show-suites
+
+ List the discovered test suites and exit.
+
+.. option:: --show-tests
+
+ List all of the discovered tests and exit.
+
+EXIT STATUS
+-----------
+
+:program:`lit` will exit with an exit code of 1 if there are any FAIL or XPASS
+results.  Otherwise, it will exit with the status 0.  Other exit codes are used
+for non-test related failures (for example a user error or an internal program
+error).
+
+.. _test-discovery:
+
+TEST DISCOVERY
+--------------
+
+The inputs passed to :program:`lit` can be either individual tests, or entire
+directories or hierarchies of tests to run.  When :program:`lit` starts up, the
+first thing it does is convert the inputs into a complete list of tests to run
+as part of *test discovery*.
+
+In the :program:`lit` model, every test must exist inside some *test suite*.
+:program:`lit` resolves the inputs specified on the command line to test suites
+by searching upwards from the input path until it finds a :file:`lit.cfg` or
+:file:`lit.site.cfg` file.  These files serve as both a marker of test suites
+and as configuration files which :program:`lit` loads in order to understand
+how to find and run the tests inside the test suite.
+
+Once :program:`lit` has mapped the inputs into test suites it traverses the
+list of inputs adding tests for individual files and recursively searching for
+tests in directories.
+
+This behavior makes it easy to specify a subset of tests to run, while still
+allowing the test suite configuration to control exactly how tests are
+interpreted.  In addition, :program:`lit` always identifies tests by the test
+suite they are in, and their relative path inside the test suite.  For
+appropriately configured projects, this allows :program:`lit` to provide
+convenient and flexible support for out-of-tree builds.
+
+.. _test-status-results:
+
+TEST STATUS RESULTS
+-------------------
+
+Each test ultimately produces one of the following six results:
+
+**PASS**
+
+ The test succeeded.
+
+**XFAIL**
+
+ The test failed, but that is expected.  This is used for test formats which allow
+ specifying that a test does not currently work, but wish to leave it in the test
+ suite.
+
+**XPASS**
+
+ The test succeeded, but it was expected to fail.  This is used for tests which
+ were specified as expected to fail, but are now succeeding (generally because
+ the feature they test was broken and has been fixed).
+
+**FAIL**
+
+ The test failed.
+
+**UNRESOLVED**
+
+ The test result could not be determined.  For example, this occurs when the test
+ could not be run, the test itself is invalid, or the test was interrupted.
+
+**UNSUPPORTED**
+
+ The test is not supported in this environment.  This is used by test formats
+ which can report unsupported tests.
+
+Depending on the test format tests may produce additional information about
+their status (generally only for failures).  See the :ref:`output-options`
+section for more information.
+
+.. _lit-infrastructure:
+
+LIT INFRASTRUCTURE
+------------------
+
+This section describes the :program:`lit` testing architecture for users interested in
+creating a new :program:`lit` testing implementation, or extending an existing one.
+
+:program:`lit` proper is primarily an infrastructure for discovering and running
+arbitrary tests, and to expose a single convenient interface to these
+tests. :program:`lit` itself doesn't know how to run tests, rather this logic is
+defined by *test suites*.
+
+TEST SUITES
+~~~~~~~~~~~
+
+As described in :ref:`test-discovery`, tests are always located inside a *test
+suite*.  Test suites serve to define the format of the tests they contain, the
+logic for finding those tests, and any additional information to run the tests.
+
+:program:`lit` identifies test suites as directories containing ``lit.cfg`` or
+``lit.site.cfg`` files (see also :option:`--config-prefix`).  Test suites are
+initially discovered by recursively searching up the directory hierarchy for
+all the input files passed on the command line.  You can use
+:option:`--show-suites` to display the discovered test suites at startup.
+
+Once a test suite is discovered, its config file is loaded.  Config files
+themselves are Python modules which will be executed.  When the config file is
+executed, two important global variables are predefined:
+
+**lit_config**
+
+ The global **lit** configuration object (a *LitConfig* instance), which defines
+ the builtin test formats, global configuration parameters, and other helper
+ routines for implementing test configurations.
+
+**config**
+
+ This is the config object (a *TestingConfig* instance) for the test suite,
+ which the config file is expected to populate.  The following variables are also
+ available on the *config* object, some of which must be set by the config and
+ others are optional or predefined:
+
+ **name** *[required]* The name of the test suite, for use in reports and
+ diagnostics.
+
+ **test_format** *[required]* The test format object which will be used to
+ discover and run tests in the test suite.  Generally this will be a builtin test
+ format available from the *lit.formats* module.
+
+ **test_source_root** The filesystem path to the test suite root.  For out-of-dir
+ builds this is the directory that will be scanned for tests.
+
+ **test_exec_root** For out-of-dir builds, the path to the test suite root inside
+ the object directory.  This is where tests will be run and temporary output files
+ placed.
+
+ **environment** A dictionary representing the environment to use when executing
+ 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*.
+
+ **substitutions** For **lit** test formats which substitute variables into a test
+ 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*.
+
+ **parent** The parent configuration, this is the config object for the directory
+ containing the test suite, or None.
+
+ **root** The root configuration.  This is the top-most :program:`lit` configuration in
+ the project.
+
+ **pipefail** Normally a test using a shell pipe fails if any of the commands
+ on the pipe fail. If this is not desired, setting this variable to false
+ makes the test fail only if the last command in the pipe fails.
+
+ **available_features** A set of features that can be used in `XFAIL`,
+ `REQUIRES`, and `UNSUPPORTED` directives.
+
+TEST DISCOVERY
+~~~~~~~~~~~~~~
+
+Once test suites are located, :program:`lit` recursively traverses the source
+directory (following *test_source_root*) looking for tests.  When :program:`lit`
+enters a sub-directory, it first checks to see if a nested test suite is
+defined in that directory.  If so, it loads that test suite recursively,
+otherwise it instantiates a local test config for the directory (see
+:ref:`local-configuration-files`).
+
+Tests are identified by the test suite they are contained within, and the
+relative path inside that suite.  Note that the relative path may not refer to
+an actual file on disk; some test formats (such as *GoogleTest*) define
+"virtual tests" which have a path that contains both the path to the actual
+test file and a subpath to identify the virtual test.
+
+.. _local-configuration-files:
+
+LOCAL CONFIGURATION FILES
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When :program:`lit` loads a subdirectory in a test suite, it instantiates a
+local test configuration by cloning the configuration for the parent directory
+--- the root of this configuration chain will always be a test suite.  Once the
+test configuration is cloned :program:`lit` checks for a *lit.local.cfg* file
+in the subdirectory.  If present, this file will be loaded and can be used to
+specialize the configuration for each individual directory.  This facility can
+be used to define subdirectories of optional tests, or to change other
+configuration parameters --- for example, to change the test format, or the
+suffixes which identify test files.
+
+PRE-DEFINED SUBSTITUTIONS
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+:program:`lit` provides various patterns that can be used with the RUN command.
+These are defined in TestRunner.py. The base set of substitutions are:
+
+ ========== ==============
+  Macro      Substitution
+ ========== ==============
+ %s         source path (path to the file currently being run)
+ %S         source dir (directory of the file currently being run)
+ %p         same as %S
+ %{pathsep} path separator
+ %t         temporary file name unique to the test
+ %T         parent directory of %t (not unique, deprecated, do not use)
+ %%         %
+ ========== ==============
+
+Other substitutions are provided that are variations on this base set and
+further substitution patterns can be defined by each test module. See the
+modules :ref:`local-configuration-files`.
+
+More detailed information on substitutions can be found in the
+:doc:`../TestingGuide`.
+
+TEST RUN OUTPUT FORMAT
+~~~~~~~~~~~~~~~~~~~~~~
+
+The :program:`lit` output for a test run conforms to the following schema, in
+both short and verbose modes (although in short mode no PASS lines will be
+shown).  This schema has been chosen to be relatively easy to reliably parse by
+a machine (for example in buildbot log scraping), and for other tools to
+generate.
+
+Each test result is expected to appear on a line that matches:
+
+.. code-block:: none
+
+  <result code>: <test name> (<progress info>)
+
+where ``<result-code>`` is a standard test result such as PASS, FAIL, XFAIL,
+XPASS, UNRESOLVED, or UNSUPPORTED.  The performance result codes of IMPROVED and
+REGRESSED are also allowed.
+
+The ``<test name>`` field can consist of an arbitrary string containing no
+newline.
+
+The ``<progress info>`` field can be used to report progress information such
+as (1/300) or can be empty, but even when empty the parentheses are required.
+
+Each test result may include additional (multiline) log information in the
+following format:
+
+.. code-block:: none
+
+  <log delineator> TEST '(<test name>)' <trailing delineator>
+  ... log message ...
+  <log delineator>
+
+where ``<test name>`` should be the name of a preceding reported test, ``<log
+delineator>`` is a string of "*" characters *at least* four characters long
+(the recommended length is 20), and ``<trailing delineator>`` is an arbitrary
+(unparsed) string.
+
+The following is an example of a test run output which consists of four tests A,
+B, C, and D, and a log message for the failing test C:
+
+.. code-block:: none
+
+  PASS: A (1 of 4)
+  PASS: B (2 of 4)
+  FAIL: C (3 of 4)
+  ******************** TEST 'C' FAILED ********************
+  Test 'C' failed as a result of exit code 1.
+  ********************
+  PASS: D (4 of 4)
+
+LIT EXAMPLE TESTS
+~~~~~~~~~~~~~~~~~
+
+The :program:`lit` distribution contains several example implementations of
+test suites in the *ExampleTests* directory.
+
+SEE ALSO
+--------
+
+valgrind(1)

Added: www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llc.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llc.rst.txt?rev=368037&view=auto
==============================================================================
--- www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llc.rst.txt (added)
+++ www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llc.rst.txt Tue Aug  6 06:51:02 2019
@@ -0,0 +1,204 @@
+llc - LLVM static compiler
+==========================
+
+SYNOPSIS
+--------
+
+:program:`llc` [*options*] [*filename*]
+
+DESCRIPTION
+-----------
+
+The :program:`llc` command compiles LLVM source inputs into assembly language
+for a specified architecture.  The assembly language output can then be passed
+through a native assembler and linker to generate a native executable.
+
+The choice of architecture for the output assembly code is automatically
+determined from the input file, unless the :option:`-march` option is used to
+override the default.
+
+OPTIONS
+-------
+
+If ``filename`` is "``-``" or omitted, :program:`llc` reads from standard input.
+Otherwise, it will from ``filename``.  Inputs can be in either the LLVM assembly
+language format (``.ll``) or the LLVM bitcode format (``.bc``).
+
+If the :option:`-o` option is omitted, then :program:`llc` will send its output
+to standard output if the input is from standard input.  If the :option:`-o`
+option specifies "``-``", then the output will also be sent to standard output.
+
+If no :option:`-o` option is specified and an input file other than "``-``" is
+specified, then :program:`llc` creates the output filename by taking the input
+filename, removing any existing ``.bc`` extension, and adding a ``.s`` suffix.
+
+Other :program:`llc` options are described below.
+
+End-user Options
+~~~~~~~~~~~~~~~~
+
+.. option:: -help
+
+ Print a summary of command line options.
+
+.. option:: -O=uint
+
+ Generate code at different optimization levels.  These correspond to the
+ ``-O0``, ``-O1``, ``-O2``, and ``-O3`` optimization levels used by
+ :program:`clang`.
+
+.. option:: -mtriple=<target triple>
+
+ Override the target triple specified in the input file with the specified
+ string.
+
+.. option:: -march=<arch>
+
+ Specify the architecture for which to generate assembly, overriding the target
+ encoded in the input file.  See the output of ``llc -help`` for a list of
+ valid architectures.  By default this is inferred from the target triple or
+ autodetected to the current architecture.
+
+.. option:: -mcpu=<cpuname>
+
+ Specify a specific chip in the current architecture to generate code for.
+ By default this is inferred from the target triple and autodetected to
+ the current architecture.  For a list of available CPUs, use:
+
+ .. code-block:: none
+
+   llvm-as < /dev/null | llc -march=xyz -mcpu=help
+
+.. option:: -filetype=<output file type>
+
+ Specify what kind of output ``llc`` should generated.  Options are: ``asm``
+ for textual assembly ( ``'.s'``), ``obj`` for native object files (``'.o'``)
+ and ``null`` for not emitting anything (for performance testing).
+
+ Note that not all targets support all options.
+
+.. option:: -mattr=a1,+a2,-a3,...
+
+ Override or control specific attributes of the target, such as whether SIMD
+ operations are enabled or not.  The default set of attributes is set by the
+ current CPU.  For a list of available attributes, use:
+
+ .. code-block:: none
+
+   llvm-as < /dev/null | llc -march=xyz -mattr=help
+
+.. option:: --frame-pointer
+
+ Specify effect of frame pointer elimination optimization (all,non-leaf,none).
+
+.. option:: --disable-excess-fp-precision
+
+ Disable optimizations that may produce excess precision for floating point.
+ Note that this option can dramatically slow down code on some systems
+ (e.g. X86).
+
+.. option:: --enable-no-infs-fp-math
+
+ Enable optimizations that assume no Inf values.
+
+.. option:: --enable-no-nans-fp-math
+
+ Enable optimizations that assume no NAN values.
+
+.. option:: --enable-unsafe-fp-math
+
+ Enable optimizations that make unsafe assumptions about IEEE math (e.g. that
+ addition is associative) or may not work for all input ranges.  These
+ optimizations allow the code generator to make use of some instructions which
+ would otherwise not be usable (such as ``fsin`` on X86).
+
+.. option:: --stats
+
+ Print statistics recorded by code-generation passes.
+
+.. option:: --time-passes
+
+ Record the amount of time needed for each pass and print a report to standard
+ error.
+
+.. option:: --load=<dso_path>
+
+ Dynamically load ``dso_path`` (a path to a dynamically shared object) that
+ implements an LLVM target.  This will permit the target name to be used with
+ the :option:`-march` option so that code can be generated for that target.
+
+.. option:: -meabi=[default|gnu|4|5]
+
+ Specify which EABI version should conform to.  Valid EABI versions are *gnu*,
+ *4* and *5*.  Default value (*default*) depends on the triple.
+
+.. option:: -stack-size-section
+
+ Emit the .stack_sizes section which contains stack size metadata. The section
+ contains an array of pairs of function symbol values (pointer size) and stack
+ sizes (unsigned LEB128). The stack size values only include the space allocated
+ in the function prologue. Functions with dynamic stack allocations are not
+ included.
+
+
+Tuning/Configuration Options
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. option:: --print-machineinstrs
+
+ Print generated machine code between compilation phases (useful for debugging).
+
+.. option:: --regalloc=<allocator>
+
+ Specify the register allocator to use.
+ Valid register allocators are:
+
+ *basic*
+
+  Basic register allocator.
+
+ *fast*
+
+  Fast register allocator. It is the default for unoptimized code.
+
+ *greedy*
+
+  Greedy register allocator. It is the default for optimized code.
+
+ *pbqp*
+
+  Register allocator based on 'Partitioned Boolean Quadratic Programming'.
+
+.. option:: --spiller=<spiller>
+
+ Specify the spiller to use for register allocators that support it.  Currently
+ this option is used only by the linear scan register allocator.  The default
+ ``spiller`` is *local*.  Valid spillers are:
+
+ *simple*
+
+  Simple spiller
+
+ *local*
+
+  Local spiller
+
+Intel IA-32-specific Options
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. option:: --x86-asm-syntax=[att|intel]
+
+ Specify whether to emit assembly code in AT&T syntax (the default) or Intel
+ syntax.
+
+EXIT STATUS
+-----------
+
+If :program:`llc` succeeds, it will exit with 0.  Otherwise, if an error
+occurs, it will exit with a non-zero value.
+
+SEE ALSO
+--------
+
+lli
+

Added: www-releases/trunk/8.0.1/docs/_sources/CommandGuide/lli.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.1/docs/_sources/CommandGuide/lli.rst.txt?rev=368037&view=auto
==============================================================================
--- www-releases/trunk/8.0.1/docs/_sources/CommandGuide/lli.rst.txt (added)
+++ www-releases/trunk/8.0.1/docs/_sources/CommandGuide/lli.rst.txt Tue Aug  6 06:51:02 2019
@@ -0,0 +1,215 @@
+lli - directly execute programs from LLVM bitcode
+=================================================
+
+SYNOPSIS
+--------
+
+:program:`lli` [*options*] [*filename*] [*program args*]
+
+DESCRIPTION
+-----------
+
+:program:`lli` directly executes programs in LLVM bitcode format.  It takes a program
+in LLVM bitcode format and executes it using a just-in-time compiler or an
+interpreter.
+
+:program:`lli` is *not* an emulator. It will not execute IR of different architectures
+and it can only interpret (or JIT-compile) for the host architecture.
+
+The JIT compiler takes the same arguments as other tools, like :program:`llc`,
+but they don't necessarily work for the interpreter.
+
+If `filename` is not specified, then :program:`lli` reads the LLVM bitcode for the
+program from standard input.
+
+The optional *args* specified on the command line are passed to the program as
+arguments.
+
+GENERAL OPTIONS
+---------------
+
+.. option:: -fake-argv0=executable
+
+ Override the ``argv[0]`` value passed into the executing program.
+
+.. option:: -force-interpreter={false,true}
+
+ If set to true, use the interpreter even if a just-in-time compiler is available
+ for this architecture. Defaults to false.
+
+.. option:: -help
+
+ Print a summary of command line options.
+
+.. option:: -load=pluginfilename
+
+ Causes :program:`lli` to load the plugin (shared object) named *pluginfilename* and use
+ it for optimization.
+
+.. option:: -stats
+
+ Print statistics from the code-generation passes. This is only meaningful for
+ the just-in-time compiler, at present.
+
+.. option:: -time-passes
+
+ Record the amount of time needed for each code-generation pass and print it to
+ standard error.
+
+.. option:: -version
+
+ Print out the version of :program:`lli` and exit without doing anything else.
+
+TARGET OPTIONS
+--------------
+
+.. option:: -mtriple=target triple
+
+ Override the target triple specified in the input bitcode file with the
+ specified string.  This may result in a crash if you pick an
+ architecture which is not compatible with the current system.
+
+.. option:: -march=arch
+
+ Specify the architecture for which to generate assembly, overriding the target
+ encoded in the bitcode file.  See the output of **llc -help** for a list of
+ valid architectures.  By default this is inferred from the target triple or
+ autodetected to the current architecture.
+
+.. option:: -mcpu=cpuname
+
+ Specify a specific chip in the current architecture to generate code for.
+ By default this is inferred from the target triple and autodetected to
+ the current architecture.  For a list of available CPUs, use:
+ **llvm-as < /dev/null | llc -march=xyz -mcpu=help**
+
+.. option:: -mattr=a1,+a2,-a3,...
+
+ Override or control specific attributes of the target, such as whether SIMD
+ operations are enabled or not.  The default set of attributes is set by the
+ current CPU.  For a list of available attributes, use:
+ **llvm-as < /dev/null | llc -march=xyz -mattr=help**
+
+FLOATING POINT OPTIONS
+----------------------
+
+.. option:: -disable-excess-fp-precision
+
+ Disable optimizations that may increase floating point precision.
+
+.. option:: -enable-no-infs-fp-math
+
+ Enable optimizations that assume no Inf values.
+
+.. option:: -enable-no-nans-fp-math
+
+ Enable optimizations that assume no NAN values.
+
+.. option:: -enable-unsafe-fp-math
+
+ Causes :program:`lli` to enable optimizations that may decrease floating point
+ precision.
+
+.. option:: -soft-float
+
+ Causes :program:`lli` to generate software floating point library calls instead of
+ equivalent hardware instructions.
+
+CODE GENERATION OPTIONS
+-----------------------
+
+.. option:: -code-model=model
+
+ Choose the code model from:
+
+ .. code-block:: text
+
+      default: Target default code model
+      tiny: Tiny code model
+      small: Small code model
+      kernel: Kernel code model
+      medium: Medium code model
+      large: Large code model
+
+.. option:: -disable-post-RA-scheduler
+
+ Disable scheduling after register allocation.
+
+.. option:: -disable-spill-fusing
+
+ Disable fusing of spill code into instructions.
+
+.. option:: -jit-enable-eh
+
+ Exception handling should be enabled in the just-in-time compiler.
+
+.. option:: -join-liveintervals
+
+ Coalesce copies (default=true).
+
+.. option:: -nozero-initialized-in-bss
+
+  Don't place zero-initialized symbols into the BSS section.
+
+.. option:: -pre-RA-sched=scheduler
+
+ Instruction schedulers available (before register allocation):
+
+ .. code-block:: text
+
+      =default: Best scheduler for the target
+      =none: No scheduling: breadth first sequencing
+      =simple: Simple two pass scheduling: minimize critical path and maximize processor utilization
+      =simple-noitin: Simple two pass scheduling: Same as simple except using generic latency
+      =list-burr: Bottom-up register reduction list scheduling
+      =list-tdrr: Top-down register reduction list scheduling
+      =list-td: Top-down list scheduler -print-machineinstrs - Print generated machine code
+
+.. option:: -regalloc=allocator
+
+ Register allocator to use (default=linearscan)
+
+ .. code-block:: text
+
+      =bigblock: Big-block register allocator
+      =linearscan: linear scan register allocator =local -   local register allocator
+      =simple: simple register allocator
+
+.. option:: -relocation-model=model
+
+ Choose relocation model from:
+
+ .. code-block:: text
+
+      =default: Target default relocation model
+      =static: Non-relocatable code =pic -   Fully relocatable, position independent code
+      =dynamic-no-pic: Relocatable external references, non-relocatable code
+
+.. option:: -spiller
+
+ Spiller to use (default=local)
+
+ .. code-block:: text
+
+      =simple: simple spiller
+      =local: local spiller
+
+.. option:: -x86-asm-syntax=syntax
+
+ Choose style of code to emit from X86 backend:
+
+ .. code-block:: text
+
+      =att: Emit AT&T-style assembly
+      =intel: Emit Intel-style assembly
+
+EXIT STATUS
+-----------
+
+If :program:`lli` fails to load the program, it will exit with an exit code of 1.
+Otherwise, it will return the exit code of the program it executes.
+
+SEE ALSO
+--------
+
+:program:`llc`

Added: www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-addr2line.md.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-addr2line.md.txt?rev=368037&view=auto
==============================================================================
--- www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-addr2line.md.txt (added)
+++ www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-addr2line.md.txt Tue Aug  6 06:51:02 2019
@@ -0,0 +1,28 @@
+# llvm-addr2line - a drop-in replacement for addr2line
+
+## SYNOPSIS
+
+**llvm-addr2line** [*options*]
+
+## DESCRIPTION
+
+**llvm-addr2line** is an alias for the [llvm-symbolizer](llvm-symbolizer) tool
+with different defaults. The goal is to make it a drop-in replacement for
+GNU's **addr2line**.
+
+Here are some of those differences:
+
+* Defaults not to print function names. Use [-f](llvm-symbolizer-opt-f)
+  to enable that.
+
+* Defaults not to demangle function names. Use [-C](llvm-symbolizer-opt-C)
+  to switch the demangling on.
+
+* Defaults not to print inlined frames. Use [-i](llvm-symbolizer-opt-i)
+  to show inlined frames for a source code location in an inlined function.
+
+* Uses [--output-style=GNU](llvm-symbolizer-opt-output-style) by default.
+
+## SEE ALSO
+
+Refer to [llvm-symbolizer](llvm-symbolizer) for additional information.

Added: www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-ar.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-ar.rst.txt?rev=368037&view=auto
==============================================================================
--- www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-ar.rst.txt (added)
+++ www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-ar.rst.txt Tue Aug  6 06:51:02 2019
@@ -0,0 +1,367 @@
+llvm-ar - LLVM archiver
+=======================
+
+
+SYNOPSIS
+--------
+
+
+**llvm-ar** [-]{dmpqrtx}[Rabfikou] [relpos] [count] <archive> [files...]
+
+
+DESCRIPTION
+-----------
+
+
+The **llvm-ar** command is similar to the common Unix utility, ``ar``. It
+archives several files together into a single file. The intent for this is
+to produce archive libraries by LLVM bitcode that can be linked into an
+LLVM program. However, the archive can contain any kind of file. By default,
+**llvm-ar** generates a symbol table that makes linking faster because
+only the symbol table needs to be consulted, not each individual file member
+of the archive.
+
+The **llvm-ar** command can be used to *read* SVR4, GNU and BSD style archive
+files. However, right now it can only write in the GNU format. If an
+SVR4 or BSD style archive is used with the ``r`` (replace) or ``q`` (quick
+update) operations, the archive will be reconstructed in GNU format.
+
+Here's where **llvm-ar** departs from previous ``ar`` implementations:
+
+
+*Symbol Table*
+
+ Since **llvm-ar** supports bitcode files. The symbol table it creates
+ is in GNU format and includes both native and bitcode files.
+
+
+*Long Paths*
+
+ Currently **llvm-ar** can read GNU and BSD long file names, but only writes
+ archives with the GNU format.
+
+
+
+OPTIONS
+-------
+
+
+The options to **llvm-ar** are compatible with other ``ar`` implementations.
+However, there are a few modifiers (*R*) that are not found in other ``ar``
+implementations. The options to **llvm-ar** specify a single basic operation to
+perform on the archive, a variety of modifiers for that operation, the name of
+the archive file, and an optional list of file names. These options are used to
+determine how **llvm-ar** should process the archive file.
+
+The Operations and Modifiers are explained in the sections below. The minimal
+set of options is at least one operator and the name of the archive. Typically
+archive files end with a ``.a`` suffix, but this is not required. Following
+the *archive-name* comes a list of *files* that indicate the specific members
+of the archive to operate on. If the *files* option is not specified, it
+generally means either "none" or "all" members, depending on the operation.
+
+Operations
+~~~~~~~~~~
+
+
+
+d
+
+ Delete files from the archive. No modifiers are applicable to this operation.
+ The *files* options specify which members should be removed from the
+ archive. It is not an error if a specified file does not appear in the archive.
+ If no *files* are specified, the archive is not modified.
+
+
+
+m[abi]
+
+ Move files from one location in the archive to another. The *a*, *b*, and
+ *i* modifiers apply to this operation. The *files* will all be moved
+ to the location given by the modifiers. If no modifiers are used, the files
+ will be moved to the end of the archive. If no *files* are specified, the
+ archive is not modified.
+
+
+
+p
+
+ Print files to the standard output. This operation simply prints the
+ *files* indicated to the standard output. If no *files* are
+ specified, the entire  archive is printed.  Printing bitcode files is
+ ill-advised as they might confuse your terminal settings. The *p*
+ operation never modifies the archive.
+
+
+
+q
+
+ Quickly append files to the end of the archive.  This operation quickly adds the
+ *files* to the archive without checking for duplicates that should be
+ removed first. If no *files* are specified, the archive is not modified.
+ Because of the way that **llvm-ar** constructs the archive file, its dubious
+ whether the *q* operation is any faster than the *r* operation.
+
+
+
+r[abu]
+
+ Replace or insert file members. The *a*, *b*,  and *u*
+ modifiers apply to this operation. This operation will replace existing
+ *files* or insert them at the end of the archive if they do not exist. If no
+ *files* are specified, the archive is not modified.
+
+
+
+t[v]
+
+ Print the table of contents. Without any modifiers, this operation just prints
+ the names of the members to the standard output. With the *v* modifier,
+ **llvm-ar** also prints out the file type (B=bitcode, S=symbol
+ table, blank=regular file), the permission mode, the owner and group, the
+ size, and the date. If any *files* are specified, the listing is only for
+ those files. If no *files* are specified, the table of contents for the
+ whole archive is printed.
+
+
+
+x[oP]
+
+ Extract archive members back to files. The *o* modifier applies to this
+ operation. This operation retrieves the indicated *files* from the archive
+ and writes them back to the operating system's file system. If no
+ *files* are specified, the entire archive is extract.
+
+
+
+
+Modifiers (operation specific)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+The modifiers below are specific to certain operations. See the Operations
+section (above) to determine which modifiers are applicable to which operations.
+
+
+[a]
+
+ When inserting or moving member files, this option specifies the destination of
+ the new files as being after the *relpos* member. If *relpos* is not found,
+ the files are placed at the end of the archive.
+
+
+
+[b]
+
+ When inserting or moving member files, this option specifies the destination of
+ the new files as being before the *relpos* member. If *relpos* is not
+ found, the files are placed at the end of the archive. This modifier is
+ identical to the *i* modifier.
+
+
+
+[i]
+
+ A synonym for the *b* option.
+
+
+
+[o]
+
+ When extracting files, this option will cause **llvm-ar** to preserve the
+ original modification times of the files it writes.
+
+
+
+[u]
+
+ When replacing existing files in the archive, only replace those files that have
+ a time stamp than the time stamp of the member in the archive.
+
+
+
+
+Modifiers (generic)
+~~~~~~~~~~~~~~~~~~~
+
+
+The modifiers below may be applied to any operation.
+
+
+[c]
+
+ For all operations, **llvm-ar** will always create the archive if it doesn't
+ exist. Normally, **llvm-ar** will print a warning message indicating that the
+ archive is being created. Using this modifier turns off that warning.
+
+
+
+[s]
+
+ This modifier requests that an archive index (or symbol table) be added to the
+ archive. This is the default mode of operation. The symbol table will contain
+ all the externally visible functions and global variables defined by all the
+ bitcode files in the archive.
+
+
+
+[S]
+
+ This modifier is the opposite of the *s* modifier. It instructs **llvm-ar** to
+ not build the symbol table. If both *s* and *S* are used, the last modifier to
+ occur in the options will prevail.
+
+
+
+[v]
+
+ This modifier instructs **llvm-ar** to be verbose about what it is doing. Each
+ editing operation taken against the archive will produce a line of output saying
+ what is being done.
+
+
+
+
+
+STANDARDS
+---------
+
+
+The **llvm-ar** utility is intended to provide a superset of the IEEE Std 1003.2
+(POSIX.2) functionality for ``ar``. **llvm-ar** can read both SVR4 and BSD4.4 (or
+Mac OS X) archives. If the ``f`` modifier is given to the ``x`` or ``r`` operations
+then **llvm-ar** will write SVR4 compatible archives. Without this modifier,
+**llvm-ar** will write BSD4.4 compatible archives that have long names
+immediately after the header and indicated using the "#1/ddd" notation for the
+name in the header.
+
+
+FILE FORMAT
+-----------
+
+
+The file format for LLVM Archive files is similar to that of BSD 4.4 or Mac OSX
+archive files. In fact, except for the symbol table, the ``ar`` commands on those
+operating systems should be able to read LLVM archive files. The details of the
+file format follow.
+
+Each archive begins with the archive magic number which is the eight printable
+characters "!<arch>\n" where \n represents the newline character (0x0A).
+Following the magic number, the file is composed of even length members that
+begin with an archive header and end with a \n padding character if necessary
+(to make the length even). Each file member is composed of a header (defined
+below), an optional newline-terminated "long file name" and the contents of
+the file.
+
+The fields of the header are described in the items below. All fields of the
+header contain only ASCII characters, are left justified and are right padded
+with space characters.
+
+
+name - char[16]
+
+ This field of the header provides the name of the archive member. If the name is
+ longer than 15 characters or contains a slash (/) character, then this field
+ contains ``#1/nnn`` where ``nnn`` provides the length of the name and the ``#1/``
+ is literal.  In this case, the actual name of the file is provided in the ``nnn``
+ bytes immediately following the header. If the name is 15 characters or less, it
+ is contained directly in this field and terminated with a slash (/) character.
+
+
+
+date - char[12]
+
+ This field provides the date of modification of the file in the form of a
+ decimal encoded number that provides the number of seconds since the epoch
+ (since 00:00:00 Jan 1, 1970) per Posix specifications.
+
+
+
+uid - char[6]
+
+ This field provides the user id of the file encoded as a decimal ASCII string.
+ This field might not make much sense on non-Unix systems. On Unix, it is the
+ same value as the st_uid field of the stat structure returned by the stat(2)
+ operating system call.
+
+
+
+gid - char[6]
+
+ This field provides the group id of the file encoded as a decimal ASCII string.
+ This field might not make much sense on non-Unix systems. On Unix, it is the
+ same value as the st_gid field of the stat structure returned by the stat(2)
+ operating system call.
+
+
+
+mode - char[8]
+
+ This field provides the access mode of the file encoded as an octal ASCII
+ string. This field might not make much sense on non-Unix systems. On Unix, it
+ is the same value as the st_mode field of the stat structure returned by the
+ stat(2) operating system call.
+
+
+
+size - char[10]
+
+ This field provides the size of the file, in bytes, encoded as a decimal ASCII
+ string.
+
+
+
+fmag - char[2]
+
+ This field is the archive file member magic number. Its content is always the
+ two characters back tick (0x60) and newline (0x0A). This provides some measure
+ utility in identifying archive files that have been corrupted.
+
+
+offset - vbr encoded 32-bit integer
+
+ The offset item provides the offset into the archive file where the bitcode
+ member is stored that is associated with the symbol. The offset value is 0
+ based at the start of the first "normal" file member. To derive the actual
+ file offset of the member, you must add the number of bytes occupied by the file
+ signature (8 bytes) and the symbol tables. The value of this item is encoded
+ using variable bit rate encoding to reduce the size of the symbol table.
+ Variable bit rate encoding uses the high bit (0x80) of each byte to indicate
+ if there are more bytes to follow. The remaining 7 bits in each byte carry bits
+ from the value. The final byte does not have the high bit set.
+
+
+
+length - vbr encoded 32-bit integer
+
+ The length item provides the length of the symbol that follows. Like this
+ *offset* item, the length is variable bit rate encoded.
+
+
+
+symbol - character array
+
+ The symbol item provides the text of the symbol that is associated with the
+ *offset*. The symbol is not terminated by any character. Its length is provided
+ by the *length* field. Note that is allowed (but unwise) to use non-printing
+ characters (even 0x00) in the symbol. This allows for multiple encodings of
+ symbol names.
+
+
+
+
+EXIT STATUS
+-----------
+
+
+If **llvm-ar** succeeds, it will exit with 0.  A usage error, results
+in an exit code of 1. A hard (file system typically) error results in an
+exit code of 2. Miscellaneous or unknown errors result in an
+exit code of 3.
+
+
+SEE ALSO
+--------
+
+
+ar(1)

Added: www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-as.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-as.rst.txt?rev=368037&view=auto
==============================================================================
--- www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-as.rst.txt (added)
+++ www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-as.rst.txt Tue Aug  6 06:51:02 2019
@@ -0,0 +1,56 @@
+llvm-as - LLVM assembler
+========================
+
+SYNOPSIS
+--------
+
+**llvm-as** [*options*] [*filename*]
+
+DESCRIPTION
+-----------
+
+**llvm-as** is the LLVM assembler.  It reads a file containing human-readable
+LLVM assembly language, translates it to LLVM bitcode, and writes the result
+into a file or to standard output.
+
+If *filename* is omitted or is ``-``, then **llvm-as** reads its input from
+standard input.
+
+If an output file is not specified with the **-o** option, then
+**llvm-as** sends its output to a file or standard output by following
+these rules:
+
+* If the input is standard input, then the output is standard output.
+
+* If the input is a file that ends with ``.ll``, then the output file is of the
+  same name, except that the suffix is changed to ``.bc``.
+
+* If the input is a file that does not end with the ``.ll`` suffix, then the
+  output file has the same name as the input file, except that the ``.bc``
+  suffix is appended.
+
+OPTIONS
+-------
+
+**-f**
+ Enable binary output on terminals.  Normally, **llvm-as** will refuse to
+ write raw bitcode output if the output stream is a terminal. With this option,
+ **llvm-as** will write raw bitcode regardless of the output device.
+
+**-help**
+ Print a summary of command line options.
+
+**-o** *filename*
+ Specify the output file name.  If *filename* is ``-``, then **llvm-as**
+ sends its output to standard output.
+
+EXIT STATUS
+-----------
+
+If **llvm-as** succeeds, it will exit with 0.  Otherwise, if an error occurs, it
+will exit with a non-zero value.
+
+SEE ALSO
+--------
+
+llvm-dis|llvm-dis, gccas|gccas

Added: www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-bcanalyzer.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-bcanalyzer.rst.txt?rev=368037&view=auto
==============================================================================
--- www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-bcanalyzer.rst.txt (added)
+++ www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-bcanalyzer.rst.txt Tue Aug  6 06:51:02 2019
@@ -0,0 +1,305 @@
+llvm-bcanalyzer - LLVM bitcode analyzer
+=======================================
+
+SYNOPSIS
+--------
+
+:program:`llvm-bcanalyzer` [*options*] [*filename*]
+
+DESCRIPTION
+-----------
+
+The :program:`llvm-bcanalyzer` command is a small utility for analyzing bitcode
+files.  The tool reads a bitcode file (such as generated with the
+:program:`llvm-as` tool) and produces a statistical report on the contents of
+the bitcode file.  The tool can also dump a low level but human readable
+version of the bitcode file.  This tool is probably not of much interest or
+utility except for those working directly with the bitcode file format.  Most
+LLVM users can just ignore this tool.
+
+If *filename* is omitted or is ``-``, then :program:`llvm-bcanalyzer` reads its
+input from standard input.  This is useful for combining the tool into a
+pipeline.  Output is written to the standard output.
+
+OPTIONS
+-------
+
+.. program:: llvm-bcanalyzer
+
+.. option:: -nodetails
+
+ Causes :program:`llvm-bcanalyzer` to abbreviate its output by writing out only
+ a module level summary.  The details for individual functions are not
+ displayed.
+
+.. option:: -dump
+
+ Causes :program:`llvm-bcanalyzer` to dump the bitcode in a human readable
+ format.  This format is significantly different from LLVM assembly and
+ provides details about the encoding of the bitcode file.
+
+.. option:: -verify
+
+ Causes :program:`llvm-bcanalyzer` to verify the module produced by reading the
+ bitcode.  This ensures that the statistics generated are based on a consistent
+ module.
+
+.. option:: -help
+
+ Print a summary of command line options.
+
+EXIT STATUS
+-----------
+
+If :program:`llvm-bcanalyzer` succeeds, it will exit with 0.  Otherwise, if an
+error occurs, it will exit with a non-zero value, usually 1.
+
+SUMMARY OUTPUT DEFINITIONS
+--------------------------
+
+The following items are always printed by llvm-bcanalyzer.  They comprize the
+summary output.
+
+**Bitcode Analysis Of Module**
+
+ This just provides the name of the module for which bitcode analysis is being
+ generated.
+
+**Bitcode Version Number**
+
+ The bitcode version (not LLVM version) of the file read by the analyzer.
+
+**File Size**
+
+ The size, in bytes, of the entire bitcode file.
+
+**Module Bytes**
+
+ The size, in bytes, of the module block.  Percentage is relative to File Size.
+
+**Function Bytes**
+
+ The size, in bytes, of all the function blocks.  Percentage is relative to File
+ Size.
+
+**Global Types Bytes**
+
+ The size, in bytes, of the Global Types Pool.  Percentage is relative to File
+ Size.  This is the size of the definitions of all types in the bitcode file.
+
+**Constant Pool Bytes**
+
+ The size, in bytes, of the Constant Pool Blocks Percentage is relative to File
+ Size.
+
+**Module Globals Bytes**
+
+ Ths size, in bytes, of the Global Variable Definitions and their initializers.
+ Percentage is relative to File Size.
+
+**Instruction List Bytes**
+
+ The size, in bytes, of all the instruction lists in all the functions.
+ Percentage is relative to File Size.  Note that this value is also included in
+ the Function Bytes.
+
+**Compaction Table Bytes**
+
+ The size, in bytes, of all the compaction tables in all the functions.
+ Percentage is relative to File Size.  Note that this value is also included in
+ the Function Bytes.
+
+**Symbol Table Bytes**
+
+ The size, in bytes, of all the symbol tables in all the functions.  Percentage is
+ relative to File Size.  Note that this value is also included in the Function
+ Bytes.
+
+**Dependent Libraries Bytes**
+
+ The size, in bytes, of the list of dependent libraries in the module.  Percentage
+ is relative to File Size.  Note that this value is also included in the Module
+ Global Bytes.
+
+**Number Of Bitcode Blocks**
+
+ The total number of blocks of any kind in the bitcode file.
+
+**Number Of Functions**
+
+ The total number of function definitions in the bitcode file.
+
+**Number Of Types**
+
+ The total number of types defined in the Global Types Pool.
+
+**Number Of Constants**
+
+ The total number of constants (of any type) defined in the Constant Pool.
+
+**Number Of Basic Blocks**
+
+ The total number of basic blocks defined in all functions in the bitcode file.
+
+**Number Of Instructions**
+
+ The total number of instructions defined in all functions in the bitcode file.
+
+**Number Of Long Instructions**
+
+ The total number of long instructions defined in all functions in the bitcode
+ file.  Long instructions are those taking greater than 4 bytes.  Typically long
+ instructions are GetElementPtr with several indices, PHI nodes, and calls to
+ functions with large numbers of arguments.
+
+**Number Of Operands**
+
+ The total number of operands used in all instructions in the bitcode file.
+
+**Number Of Compaction Tables**
+
+ The total number of compaction tables in all functions in the bitcode file.
+
+**Number Of Symbol Tables**
+
+ The total number of symbol tables in all functions in the bitcode file.
+
+**Number Of Dependent Libs**
+
+ The total number of dependent libraries found in the bitcode file.
+
+**Total Instruction Size**
+
+ The total size of the instructions in all functions in the bitcode file.
+
+**Average Instruction Size**
+
+ The average number of bytes per instruction across all functions in the bitcode
+ file.  This value is computed by dividing Total Instruction Size by Number Of
+ Instructions.
+
+**Maximum Type Slot Number**
+
+ The maximum value used for a type's slot number.  Larger slot number values take
+ more bytes to encode.
+
+**Maximum Value Slot Number**
+
+ The maximum value used for a value's slot number.  Larger slot number values take
+ more bytes to encode.
+
+**Bytes Per Value**
+
+ The average size of a Value definition (of any type).  This is computed by
+ dividing File Size by the total number of values of any type.
+
+**Bytes Per Global**
+
+ The average size of a global definition (constants and global variables).
+
+**Bytes Per Function**
+
+ The average number of bytes per function definition.  This is computed by
+ dividing Function Bytes by Number Of Functions.
+
+**# of VBR 32-bit Integers**
+
+ The total number of 32-bit integers encoded using the Variable Bit Rate
+ encoding scheme.
+
+**# of VBR 64-bit Integers**
+
+ The total number of 64-bit integers encoded using the Variable Bit Rate encoding
+ scheme.
+
+**# of VBR Compressed Bytes**
+
+ The total number of bytes consumed by the 32-bit and 64-bit integers that use
+ the Variable Bit Rate encoding scheme.
+
+**# of VBR Expanded Bytes**
+
+ The total number of bytes that would have been consumed by the 32-bit and 64-bit
+ integers had they not been compressed with the Variable Bit Rage encoding
+ scheme.
+
+**Bytes Saved With VBR**
+
+ The total number of bytes saved by using the Variable Bit Rate encoding scheme.
+ The percentage is relative to # of VBR Expanded Bytes.
+
+DETAILED OUTPUT DEFINITIONS
+---------------------------
+
+The following definitions occur only if the -nodetails option was not given.
+The detailed output provides additional information on a per-function basis.
+
+**Type**
+
+ The type signature of the function.
+
+**Byte Size**
+
+ The total number of bytes in the function's block.
+
+**Basic Blocks**
+
+ The number of basic blocks defined by the function.
+
+**Instructions**
+
+ The number of instructions defined by the function.
+
+**Long Instructions**
+
+ The number of instructions using the long instruction format in the function.
+
+**Operands**
+
+ The number of operands used by all instructions in the function.
+
+**Instruction Size**
+
+ The number of bytes consumed by instructions in the function.
+
+**Average Instruction Size**
+
+ The average number of bytes consumed by the instructions in the function.
+ This value is computed by dividing Instruction Size by Instructions.
+
+**Bytes Per Instruction**
+
+ The average number of bytes used by the function per instruction.  This value
+ is computed by dividing Byte Size by Instructions.  Note that this is not the
+ same as Average Instruction Size.  It computes a number relative to the total
+ function size not just the size of the instruction list.
+
+**Number of VBR 32-bit Integers**
+
+ The total number of 32-bit integers found in this function (for any use).
+
+**Number of VBR 64-bit Integers**
+
+ The total number of 64-bit integers found in this function (for any use).
+
+**Number of VBR Compressed Bytes**
+
+ The total number of bytes in this function consumed by the 32-bit and 64-bit
+ integers that use the Variable Bit Rate encoding scheme.
+
+**Number of VBR Expanded Bytes**
+
+ The total number of bytes in this function that would have been consumed by
+ the 32-bit and 64-bit integers had they not been compressed with the Variable
+ Bit Rate encoding scheme.
+
+**Bytes Saved With VBR**
+
+ The total number of bytes saved in this function by using the Variable Bit
+ Rate encoding scheme.  The percentage is relative to # of VBR Expanded Bytes.
+
+SEE ALSO
+--------
+
+:doc:`/CommandGuide/llvm-dis`, :doc:`/BitCodeFormat`
+

Added: www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-build.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-build.rst.txt?rev=368037&view=auto
==============================================================================
--- www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-build.rst.txt (added)
+++ www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-build.rst.txt Tue Aug  6 06:51:02 2019
@@ -0,0 +1,102 @@
+llvm-build - LLVM Project Build Utility
+=======================================
+
+
+SYNOPSIS
+--------
+
+
+**llvm-build** [*options*]
+
+
+DESCRIPTION
+-----------
+
+
+**llvm-build** is a tool for working with LLVM projects that use the LLVMBuild
+system for describing their components.
+
+At heart, **llvm-build** is responsible for loading, verifying, and manipulating
+the project's component data. The tool is primarily designed for use in
+implementing build systems and tools which need access to the project structure
+information.
+
+
+OPTIONS
+-------
+
+
+
+**-h**, **--help**
+
+ Print the builtin program help.
+
+
+
+**--source-root**\ =\ *PATH*
+
+ If given, load the project at the given source root path. If this option is not
+ given, the location of the project sources will be inferred from the location of
+ the **llvm-build** script itself.
+
+
+
+**--print-tree**
+
+ Print the component tree for the project.
+
+
+
+**--write-library-table**
+
+ Write out the C++ fragment which defines the components, library names, and
+ required libraries. This C++ fragment is built into llvm-config|llvm-config
+ in order to provide clients with the list of required libraries for arbitrary
+ component combinations.
+
+
+
+**--write-llvmbuild**
+
+ Write out new *LLVMBuild.txt* files based on the loaded components. This is
+ useful for auto-upgrading the schema of the files. **llvm-build** will try to a
+ limited extent to preserve the comments which were written in the original
+ source file, although at this time it only preserves block comments that precede
+ the section names in the *LLVMBuild* files.
+
+
+
+**--write-cmake-fragment**
+
+ Write out the LLVMBuild in the form of a CMake fragment, so it can easily be
+ consumed by the CMake based build system. The exact contents and format of this
+ file are closely tied to how LLVMBuild is integrated with CMake, see LLVM's
+ top-level CMakeLists.txt.
+
+
+
+**--write-make-fragment**
+
+ Write out the LLVMBuild in the form of a Makefile fragment, so it can easily be
+ consumed by a Make based build system. The exact contents and format of this
+ file are closely tied to how LLVMBuild is integrated with the Makefiles, see
+ LLVM's Makefile.rules.
+
+
+
+**--llvmbuild-source-root**\ =\ *PATH*
+
+ If given, expect the *LLVMBuild* files for the project to be rooted at the
+ given path, instead of inside the source tree itself. This option is primarily
+ designed for use in conjunction with **--write-llvmbuild** to test changes to
+ *LLVMBuild* schema.
+
+
+
+
+EXIT STATUS
+-----------
+
+
+**llvm-build** exits with 0 if operation was successful. Otherwise, it will exist
+with a non-zero value.

Added: www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-config.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-config.rst.txt?rev=368037&view=auto
==============================================================================
--- www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-config.rst.txt (added)
+++ www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-config.rst.txt Tue Aug  6 06:51:02 2019
@@ -0,0 +1,176 @@
+llvm-config - Print LLVM compilation options
+============================================
+
+
+SYNOPSIS
+--------
+
+
+**llvm-config** *option* [*components*...]
+
+
+DESCRIPTION
+-----------
+
+
+**llvm-config** makes it easier to build applications that use LLVM.  It can
+print the compiler flags, linker flags and object libraries needed to link
+against LLVM.
+
+
+EXAMPLES
+--------
+
+
+To link against the JIT:
+
+
+.. code-block:: sh
+
+   g++ `llvm-config --cxxflags` -o HowToUseJIT.o -c HowToUseJIT.cpp
+   g++ `llvm-config --ldflags` -o HowToUseJIT HowToUseJIT.o \
+       `llvm-config --libs engine bcreader scalaropts`
+
+
+
+OPTIONS
+-------
+
+
+
+**--version**
+
+ Print the version number of LLVM.
+
+
+
+**-help**
+
+ Print a summary of **llvm-config** arguments.
+
+
+
+**--prefix**
+
+ Print the installation prefix for LLVM.
+
+
+
+**--src-root**
+
+ Print the source root from which LLVM was built.
+
+
+
+**--obj-root**
+
+ Print the object root used to build LLVM.
+
+
+
+**--bindir**
+
+ Print the installation directory for LLVM binaries.
+
+
+
+**--includedir**
+
+ Print the installation directory for LLVM headers.
+
+
+
+**--libdir**
+
+ Print the installation directory for LLVM libraries.
+
+
+
+**--cxxflags**
+
+ Print the C++ compiler flags needed to use LLVM headers.
+
+
+
+**--ldflags**
+
+ Print the flags needed to link against LLVM libraries.
+
+
+
+**--libs**
+
+ Print all the libraries needed to link against the specified LLVM
+ *components*, including any dependencies.
+
+
+
+**--libnames**
+
+ Similar to **--libs**, but prints the bare filenames of the libraries
+ without **-l** or pathnames.  Useful for linking against a not-yet-installed
+ copy of LLVM.
+
+
+
+**--libfiles**
+
+ Similar to **--libs**, but print the full path to each library file.  This is
+ useful when creating makefile dependencies, to ensure that a tool is relinked if
+ any library it uses changes.
+
+
+
+**--components**
+
+ Print all valid component names.
+
+
+
+**--targets-built**
+
+ Print the component names for all targets supported by this copy of LLVM.
+
+
+
+**--build-mode**
+
+ Print the build mode used when LLVM was built (e.g. Debug or Release)
+
+
+
+
+COMPONENTS
+----------
+
+
+To print a list of all available components, run **llvm-config
+--components**.  In most cases, components correspond directly to LLVM
+libraries.  Useful "virtual" components include:
+
+
+**all**
+
+ Includes all LLVM libraries.  The default if no components are specified.
+
+
+
+**backend**
+
+ Includes either a native backend or the C backend.
+
+
+
+**engine**
+
+ Includes either a native JIT or the bitcode interpreter.
+
+
+
+
+EXIT STATUS
+-----------
+
+
+If **llvm-config** succeeds, it will exit with 0.  Otherwise, if an error
+occurs, it will exit with a non-zero value.

Added: www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-cov.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-cov.rst.txt?rev=368037&view=auto
==============================================================================
--- www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-cov.rst.txt (added)
+++ www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-cov.rst.txt Tue Aug  6 06:51:02 2019
@@ -0,0 +1,416 @@
+llvm-cov - emit coverage information
+====================================
+
+SYNOPSIS
+--------
+
+:program:`llvm-cov` *command* [*args...*]
+
+DESCRIPTION
+-----------
+
+The :program:`llvm-cov` tool shows code coverage information for
+programs that are instrumented to emit profile data. It can be used to
+work with ``gcov``\-style coverage or with ``clang``\'s instrumentation
+based profiling.
+
+If the program is invoked with a base name of ``gcov``, it will behave as if
+the :program:`llvm-cov gcov` command were called. Otherwise, a command should
+be provided.
+
+COMMANDS
+--------
+
+* :ref:`gcov <llvm-cov-gcov>`
+* :ref:`show <llvm-cov-show>`
+* :ref:`report <llvm-cov-report>`
+* :ref:`export <llvm-cov-export>`
+
+.. program:: llvm-cov gcov
+
+.. _llvm-cov-gcov:
+
+GCOV COMMAND
+------------
+
+SYNOPSIS
+^^^^^^^^
+
+:program:`llvm-cov gcov` [*options*] *SOURCEFILE*
+
+DESCRIPTION
+^^^^^^^^^^^
+
+The :program:`llvm-cov gcov` tool reads code coverage data files and displays
+the coverage information for a specified source file. It is compatible with the
+``gcov`` tool from version 4.2 of ``GCC`` and may also be compatible with some
+later versions of ``gcov``.
+
+To use :program:`llvm-cov gcov`, you must first build an instrumented version
+of your application that collects coverage data as it runs. Compile with the
+``-fprofile-arcs`` and ``-ftest-coverage`` options to add the
+instrumentation. (Alternatively, you can use the ``--coverage`` option, which
+includes both of those other options.) You should compile with debugging
+information (``-g``) and without optimization (``-O0``); otherwise, the
+coverage data cannot be accurately mapped back to the source code.
+
+At the time you compile the instrumented code, a ``.gcno`` data file will be
+generated for each object file. These ``.gcno`` files contain half of the
+coverage data. The other half of the data comes from ``.gcda`` files that are
+generated when you run the instrumented program, with a separate ``.gcda``
+file for each object file. Each time you run the program, the execution counts
+are summed into any existing ``.gcda`` files, so be sure to remove any old
+files if you do not want their contents to be included.
+
+By default, the ``.gcda`` files are written into the same directory as the
+object files, but you can override that by setting the ``GCOV_PREFIX`` and
+``GCOV_PREFIX_STRIP`` environment variables. The ``GCOV_PREFIX_STRIP``
+variable specifies a number of directory components to be removed from the
+start of the absolute path to the object file directory. After stripping those
+directories, the prefix from the ``GCOV_PREFIX`` variable is added. These
+environment variables allow you to run the instrumented program on a machine
+where the original object file directories are not accessible, but you will
+then need to copy the ``.gcda`` files back to the object file directories
+where :program:`llvm-cov gcov` expects to find them.
+
+Once you have generated the coverage data files, run :program:`llvm-cov gcov`
+for each main source file where you want to examine the coverage results. This
+should be run from the same directory where you previously ran the
+compiler. The results for the specified source file are written to a file named
+by appending a ``.gcov`` suffix. A separate output file is also created for
+each file included by the main source file, also with a ``.gcov`` suffix added.
+
+The basic content of an ``.gcov`` output file is a copy of the source file with
+an execution count and line number prepended to every line. The execution
+count is shown as ``-`` if a line does not contain any executable code. If
+a line contains code but that code was never executed, the count is displayed
+as ``#####``.
+
+OPTIONS
+^^^^^^^
+
+.. option:: -a, --all-blocks
+
+ Display all basic blocks. If there are multiple blocks for a single line of
+ source code, this option causes llvm-cov to show the count for each block
+ instead of just one count for the entire line.
+
+.. option:: -b, --branch-probabilities
+
+ Display conditional branch probabilities and a summary of branch information.
+
+.. option:: -c, --branch-counts
+
+ Display branch counts instead of probabilities (requires -b).
+
+.. option:: -f, --function-summaries
+
+ Show a summary of coverage for each function instead of just one summary for
+ an entire source file.
+
+.. option:: --help
+
+ Display available options (--help-hidden for more).
+
+.. option:: -l, --long-file-names
+
+ For coverage output of files included from the main source file, add the
+ main file name followed by ``##`` as a prefix to the output file names. This
+ can be combined with the --preserve-paths option to use complete paths for
+ both the main file and the included file.
+
+.. option:: -n, --no-output
+
+ Do not output any ``.gcov`` files. Summary information is still
+ displayed.
+
+.. option:: -o=<DIR|FILE>, --object-directory=<DIR>, --object-file=<FILE>
+
+ Find objects in DIR or based on FILE's path. If you specify a particular
+ object file, the coverage data files are expected to have the same base name
+ with ``.gcno`` and ``.gcda`` extensions. If you specify a directory, the
+ files are expected in that directory with the same base name as the source
+ file.
+
+.. option:: -p, --preserve-paths
+
+ Preserve path components when naming the coverage output files. In addition
+ to the source file name, include the directories from the path to that
+ file. The directories are separate by ``#`` characters, with ``.`` directories
+ removed and ``..`` directories replaced by ``^`` characters. When used with
+ the --long-file-names option, this applies to both the main file name and the
+ included file name.
+
+.. option:: -u, --unconditional-branches
+
+ Include unconditional branches in the output for the --branch-probabilities
+ option.
+
+.. option:: -version
+
+ Display the version of llvm-cov.
+
+EXIT STATUS
+^^^^^^^^^^^
+
+:program:`llvm-cov gcov` returns 1 if it cannot read input files.  Otherwise,
+it exits with zero.
+
+
+.. program:: llvm-cov show
+
+.. _llvm-cov-show:
+
+SHOW COMMAND
+------------
+
+SYNOPSIS
+^^^^^^^^
+
+:program:`llvm-cov show` [*options*] -instr-profile *PROFILE* *BIN* [*-object BIN,...*] [[*-object BIN*]] [*SOURCES*]
+
+DESCRIPTION
+^^^^^^^^^^^
+
+The :program:`llvm-cov show` command shows line by line coverage of the
+binaries *BIN*,...  using the profile data *PROFILE*. It can optionally be
+filtered to only show the coverage for the files listed in *SOURCES*.
+
+To use :program:`llvm-cov show`, you need a program that is compiled with
+instrumentation to emit profile and coverage data. To build such a program with
+``clang`` use the ``-fprofile-instr-generate`` and ``-fcoverage-mapping``
+flags. If linking with the ``clang`` driver, pass ``-fprofile-instr-generate``
+to the link stage to make sure the necessary runtime libraries are linked in.
+
+The coverage information is stored in the built executable or library itself,
+and this is what you should pass to :program:`llvm-cov show` as a *BIN*
+argument. The profile data is generated by running this instrumented program
+normally. When the program exits it will write out a raw profile file,
+typically called ``default.profraw``, which can be converted to a format that
+is suitable for the *PROFILE* argument using the :program:`llvm-profdata merge`
+tool.
+
+OPTIONS
+^^^^^^^
+
+.. option:: -show-line-counts
+
+ Show the execution counts for each line. Defaults to true, unless another
+ ``-show`` option is used.
+
+.. option:: -show-expansions
+
+ Expand inclusions, such as preprocessor macros or textual inclusions, inline
+ in the display of the source file. Defaults to false.
+
+.. option:: -show-instantiations
+
+ For source regions that are instantiated multiple times, such as templates in
+ ``C++``, show each instantiation separately as well as the combined summary.
+ Defaults to true.
+
+.. option:: -show-regions
+
+ Show the execution counts for each region by displaying a caret that points to
+ the character where the region starts. Defaults to false.
+
+.. option:: -show-line-counts-or-regions
+
+ Show the execution counts for each line if there is only one region on the
+ line, but show the individual regions if there are multiple on the line.
+ Defaults to false.
+
+.. option:: -use-color
+
+ Enable or disable color output. By default this is autodetected.
+
+.. option:: -arch=[*NAMES*]
+
+ Specify a list of architectures such that the Nth entry in the list
+ corresponds to the Nth specified binary. If the covered object is a universal
+ binary, this specifies the architecture to use. It is an error to specify an
+ architecture that is not included in the universal binary or to use an
+ architecture that does not match a non-universal binary.
+
+.. option:: -name=<NAME>
+
+ Show code coverage only for functions with the given name.
+
+.. option:: -name-whitelist=<FILE>
+
+ Show code coverage only for functions listed in the given file. Each line in
+ the file should start with `whitelist_fun:`, immediately followed by the name
+ of the function to accept. This name can be a wildcard expression.
+
+.. option:: -name-regex=<PATTERN>
+
+ Show code coverage only for functions that match the given regular expression.
+
+.. option:: -ignore-filename-regex=<PATTERN>
+
+ Skip source code files with file paths that match the given regular expression.
+
+.. option:: -format=<FORMAT>
+
+ Use the specified output format. The supported formats are: "text", "html".
+
+.. option:: -tab-size=<TABSIZE>
+
+ Replace tabs with <TABSIZE> spaces when preparing reports. Currently, this is
+ only supported for the html format.
+
+.. option:: -output-dir=PATH
+
+ Specify a directory to write coverage reports into. If the directory does not
+ exist, it is created. When used in function view mode (i.e when -name or
+ -name-regex are used to select specific functions), the report is written to
+ PATH/functions.EXTENSION. When used in file view mode, a report for each file
+ is written to PATH/REL_PATH_TO_FILE.EXTENSION.
+
+.. option:: -Xdemangler=<TOOL>|<TOOL-OPTION>
+
+ Specify a symbol demangler. This can be used to make reports more
+ human-readable. This option can be specified multiple times to supply
+ arguments to the demangler (e.g `-Xdemangler c++filt -Xdemangler -n` for C++).
+ The demangler is expected to read a newline-separated list of symbols from
+ stdin and write a newline-separated list of the same length to stdout.
+
+.. option:: -num-threads=N, -j=N
+
+ Use N threads to write file reports (only applicable when -output-dir is
+ specified). When N=0, llvm-cov auto-detects an appropriate number of threads to
+ use. This is the default.
+
+.. option:: -line-coverage-gt=<N>
+
+ Show code coverage only for functions with line coverage greater than the
+ given threshold.
+
+.. option:: -line-coverage-lt=<N>
+
+ Show code coverage only for functions with line coverage less than the given
+ threshold.
+
+.. option:: -region-coverage-gt=<N>
+
+ Show code coverage only for functions with region coverage greater than the
+ given threshold.
+
+.. option:: -region-coverage-lt=<N>
+
+ Show code coverage only for functions with region coverage less than the given
+ threshold.
+
+.. option:: -path-equivalence=<from>,<to>
+
+ Map the paths in the coverage data to local source file paths. This allows you
+ to generate the coverage data on one machine, and then use llvm-cov on a
+ different machine where you have the same files on a different path.
+
+.. program:: llvm-cov report
+
+.. _llvm-cov-report:
+
+REPORT COMMAND
+--------------
+
+SYNOPSIS
+^^^^^^^^
+
+:program:`llvm-cov report` [*options*] -instr-profile *PROFILE* *BIN* [*-object BIN,...*] [[*-object BIN*]] [*SOURCES*]
+
+DESCRIPTION
+^^^^^^^^^^^
+
+The :program:`llvm-cov report` command displays a summary of the coverage of
+the binaries *BIN*,... using the profile data *PROFILE*. It can optionally be
+filtered to only show the coverage for the files listed in *SOURCES*.
+
+If no source files are provided, a summary line is printed for each file in the
+coverage data. If any files are provided, summaries can be shown for each
+function in the listed files if the ``-show-functions`` option is enabled.
+
+For information on compiling programs for coverage and generating profile data,
+see :ref:`llvm-cov-show`.
+
+OPTIONS
+^^^^^^^
+
+.. option:: -use-color[=VALUE]
+
+ Enable or disable color output. By default this is autodetected.
+
+.. option:: -arch=<name>
+
+ If the covered binary is a universal binary, select the architecture to use.
+ It is an error to specify an architecture that is not included in the
+ universal binary or to use an architecture that does not match a
+ non-universal binary.
+
+.. option:: -show-functions
+
+ Show coverage summaries for each function. Defaults to false.
+
+.. option:: -show-instantiation-summary
+
+ Show statistics for all function instantiations. Defaults to false.
+
+.. option:: -ignore-filename-regex=<PATTERN>
+
+ Skip source code files with file paths that match the given regular expression.
+
+.. program:: llvm-cov export
+
+.. _llvm-cov-export:
+
+EXPORT COMMAND
+--------------
+
+SYNOPSIS
+^^^^^^^^
+
+:program:`llvm-cov export` [*options*] -instr-profile *PROFILE* *BIN* [*-object BIN,...*] [[*-object BIN*]] [*SOURCES*]
+
+DESCRIPTION
+^^^^^^^^^^^
+
+The :program:`llvm-cov export` command exports coverage data of the binaries
+*BIN*,... using the profile data *PROFILE* in either JSON or lcov trace file
+format.
+
+When exporting JSON, the regions, functions, expansions, and summaries of the
+coverage data will be exported. When exporting an lcov trace file, the
+line-based coverage and summaries will be exported.
+
+The exported data can optionally be filtered to only export the coverage
+for the files listed in *SOURCES*.
+
+For information on compiling programs for coverage and generating profile data,
+see :ref:`llvm-cov-show`.
+
+OPTIONS
+^^^^^^^
+
+.. option:: -arch=<name>
+
+ If the covered binary is a universal binary, select the architecture to use.
+ It is an error to specify an architecture that is not included in the
+ universal binary or to use an architecture that does not match a
+ non-universal binary.
+
+.. option:: -format=<FORMAT>
+
+ Use the specified output format. The supported formats are: "text" (JSON),
+ "lcov".
+
+.. option:: -summary-only
+
+ Export only summary information for each file in the coverage data. This mode
+ will not export coverage information for smaller units such as individual
+ functions or regions. The result will contain the same information as produced
+ by the :program:`llvm-cov report` command, but presented in JSON or lcov
+ format rather than text.
+
+.. option:: -ignore-filename-regex=<PATTERN>
+
+ Skip source code files with file paths that match the given regular expression.

Added: www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-cxxfilt.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-cxxfilt.rst.txt?rev=368037&view=auto
==============================================================================
--- www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-cxxfilt.rst.txt (added)
+++ www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-cxxfilt.rst.txt Tue Aug  6 06:51:02 2019
@@ -0,0 +1,81 @@
+llvm-cxxfilt - LLVM symbol name demangler
+=========================================
+
+.. program:: llvm-cxxfilt
+
+SYNOPSIS
+--------
+
+:program:`llvm-cxxfilt` [*options*] [*mangled names...*]
+
+DESCRIPTION
+-----------
+
+:program:`llvm-cxxfilt` is a symbol demangler that can be used as a replacement
+for the GNU :program:`c++filt` tool. It takes a series of symbol names and
+prints their demangled form on the standard output stream. If a name cannot be
+demangled, it is simply printed as is.
+
+If no names are specified on the command-line, names are read interactively from
+the standard input stream. When reading names from standard input, each input
+line is split on characters that are not part of valid Itanium name manglings,
+i.e. characters that are not alphanumeric, '.', '$', or '_'. Separators between
+names are copied to the output as is.
+
+EXAMPLE
+-------
+
+.. code-block:: console
+
+  $ llvm-cxxfilt _Z3foov _Z3bari not_mangled
+  foo()
+  bar(int)
+  not_mangled
+  $ cat input.txt
+  | _Z3foov *** _Z3bari *** not_mangled |
+  $ llvm-cxxfilt < input.txt
+  | foo() *** bar(int) *** not_mangled |
+
+OPTIONS
+-------
+
+.. option:: --format=<value>, -s
+
+  Mangling scheme to assume. Valid values are ``auto`` (default, auto-detect the
+  style) and ``gnu`` (assume GNU/Itanium style).
+
+.. option:: --help, -h
+
+ Print a summary of command line options.
+
+.. option:: --help-list
+
+ Print an uncategorized summary of command line options.
+
+.. option:: --strip-underscore, -_
+
+  Discard a single leading underscore, if present, from each input name before
+  demangling.
+
+.. option:: --types, -t
+
+  Attempt to demangle names as type names as well as function names.
+
+.. option:: --version
+
+  Display the version of this program.
+
+.. option:: @<FILE>
+
+ Read command-line options from response file `<FILE>`.
+
+EXIT STATUS
+-----------
+
+:program:`llvm-cxxfilt` returns 0 unless it encounters a usage error, in which
+case a non-zero exit code is returned.
+
+SEE ALSO
+--------
+
+:manpage:`llvm-nm(1)`

Added: www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-cxxmap.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-cxxmap.rst.txt?rev=368037&view=auto
==============================================================================
--- www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-cxxmap.rst.txt (added)
+++ www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-cxxmap.rst.txt Tue Aug  6 06:51:02 2019
@@ -0,0 +1,91 @@
+llvm-cxxmap - Mangled name remapping tool
+=========================================
+
+SYNOPSIS
+--------
+
+:program:`llvm-cxxmap` [*options*] *symbol-file-1* *symbol-file-2*
+
+DESCRIPTION
+-----------
+
+The :program:`llvm-cxxmap` tool performs fuzzy matching of C++ mangled names,
+based on a file describing name components that should be considered equivalent.
+
+The symbol files should contain a list of C++ mangled names (one per line).
+Blank lines and lines starting with ``#`` are ignored. The output is a list
+of pairs of equivalent symbols, one per line, of the form
+
+.. code-block:: none
+
+  <symbol-1> <symbol-2>
+
+where ``<symbol-1>`` is a symbol from *symbol-file-1* and ``<symbol-2>`` is
+a symbol from *symbol-file-2*. Mappings for which the two symbols are identical
+are omitted.
+
+OPTIONS
+-------
+
+.. program:: llvm-cxxmap
+
+.. option:: -remapping-file=file, -r=file
+
+ Specify a file containing a list of equivalence rules that should be used
+ to determine whether two symbols are equivalent. Required.
+ See :ref:`remapping-file`.
+
+.. option:: -output=file, -o=file
+
+ Specify a file to write the list of matched names to. If unspecified, the
+ list will be written to stdout.
+
+.. option:: -Wambiguous
+
+ Produce a warning if there are multiple equivalent (but distinct) symbols in
+ *symbol-file-2*.
+
+.. option:: -Wincomplete
+
+ Produce a warning if *symbol-file-1* contains a symbol for which there is no
+ equivalent symbol in *symbol-file-2*.
+
+.. _remapping-file:
+
+REMAPPING FILE
+--------------
+
+The remapping file is a text file containing lines of the form
+
+.. code-block:: none
+
+  fragmentkind fragment1 fragment2
+
+where ``fragmentkind`` is one of ``name``, ``type``, or ``encoding``,
+indicating whether the following mangled name fragments are
+<`name <http://itanium-cxx-abi.github.io/cxx-abi/abi.html#mangle.name>`_>s,
+<`type <http://itanium-cxx-abi.github.io/cxx-abi/abi.html#mangle.type>`_>s, or
+<`encoding <http://itanium-cxx-abi.github.io/cxx-abi/abi.html#mangle.encoding>`_>s,
+respectively.
+Blank lines and lines starting with ``#`` are ignored.
+
+For convenience, built-in <substitution>s such as ``St`` and ``Ss``
+are accepted as <name>s (even though they technically are not <name>s).
+
+For example, to specify that ``absl::string_view`` and ``std::string_view``
+should be treated as equivalent, the following remapping file could be used:
+
+.. code-block:: none
+
+  # absl::string_view is considered equivalent to std::string_view
+  type N4absl11string_viewE St17basic_string_viewIcSt11char_traitsIcEE
+
+  # std:: might be std::__1:: in libc++ or std::__cxx11:: in libstdc++
+  name St St3__1
+  name St St7__cxx11
+
+.. note::
+
+  Symbol remapping is currently only supported for C++ mangled names
+  following the Itanium C++ ABI mangling scheme. This covers all C++ targets
+  supported by Clang other than Windows targets.

Added: www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-diff.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-diff.rst.txt?rev=368037&view=auto
==============================================================================
--- www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-diff.rst.txt (added)
+++ www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-diff.rst.txt Tue Aug  6 06:51:02 2019
@@ -0,0 +1,56 @@
+llvm-diff - LLVM structural 'diff'
+==================================
+
+
+SYNOPSIS
+--------
+
+
+**llvm-diff** [*options*] *module 1* *module 2* [*global name ...*]
+
+
+DESCRIPTION
+-----------
+
+
+**llvm-diff** compares the structure of two LLVM modules, primarily
+focusing on differences in function definitions.  Insignificant
+differences, such as changes in the ordering of globals or in the
+names of local values, are ignored.
+
+An input module will be interpreted as an assembly file if its name
+ends in '.ll';  otherwise it will be read in as a bitcode file.
+
+If a list of global names is given, just the values with those names
+are compared; otherwise, all global values are compared, and
+diagnostics are produced for globals which only appear in one module
+or the other.
+
+**llvm-diff** compares two functions by comparing their basic blocks,
+beginning with the entry blocks.  If the terminators seem to match,
+then the corresponding successors are compared; otherwise they are
+ignored.  This algorithm is very sensitive to changes in control flow,
+which tend to stop any downstream changes from being detected.
+
+**llvm-diff** is intended as a debugging tool for writers of LLVM
+passes and frontends.  It does not have a stable output format.
+
+
+EXIT STATUS
+-----------
+
+
+If **llvm-diff** finds no differences between the modules, it will exit
+with 0 and produce no output.  Otherwise it will exit with a non-zero
+value.
+
+
+BUGS
+----
+
+
+Many important differences, like changes in linkage or function
+attributes, are not diagnosed.
+
+Changes in memory behavior (for example, coalescing loads) can cause
+massive detected differences in blocks.

Added: www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-dis.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-dis.rst.txt?rev=368037&view=auto
==============================================================================
--- www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-dis.rst.txt (added)
+++ www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-dis.rst.txt Tue Aug  6 06:51:02 2019
@@ -0,0 +1,69 @@
+llvm-dis - LLVM disassembler
+============================
+
+
+SYNOPSIS
+--------
+
+
+**llvm-dis** [*options*] [*filename*]
+
+
+DESCRIPTION
+-----------
+
+
+The **llvm-dis** command is the LLVM disassembler.  It takes an LLVM
+bitcode file and converts it into human-readable LLVM assembly language.
+
+If filename is omitted or specified as ``-``, **llvm-dis** reads its
+input from standard input.
+
+If the input is being read from standard input, then **llvm-dis**
+will send its output to standard output by default.  Otherwise, the
+output will be written to a file named after the input file, with
+a ``.ll`` suffix added (any existing ``.bc`` suffix will first be
+removed).  You can override the choice of output file using the
+**-o** option.
+
+
+OPTIONS
+-------
+
+
+
+**-f**
+
+ Enable binary output on terminals.  Normally, **llvm-dis** will refuse to
+ write raw bitcode output if the output stream is a terminal. With this option,
+ **llvm-dis** will write raw bitcode regardless of the output device.
+
+
+
+**-help**
+
+ Print a summary of command line options.
+
+
+
+**-o** *filename*
+
+ Specify the output file name.  If *filename* is -, then the output is sent
+ to standard output.
+
+
+
+
+EXIT STATUS
+-----------
+
+
+If **llvm-dis** succeeds, it will exit with 0.  Otherwise, if an error
+occurs, it will exit with a non-zero value.
+
+
+SEE ALSO
+--------
+
+
+llvm-as|llvm-as

Added: www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-dwarfdump.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-dwarfdump.rst.txt?rev=368037&view=auto
==============================================================================
--- www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-dwarfdump.rst.txt (added)
+++ www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-dwarfdump.rst.txt Tue Aug  6 06:51:02 2019
@@ -0,0 +1,142 @@
+llvm-dwarfdump - dump and verify DWARF debug information
+========================================================
+
+SYNOPSIS
+--------
+
+:program:`llvm-dwarfdump` [*options*] [*filename ...*]
+
+DESCRIPTION
+-----------
+
+:program:`llvm-dwarfdump` parses DWARF sections in object files,
+archives, and `.dSYM` bundles and prints their contents in
+human-readable form. Only the .debug_info section is printed unless one of
+the section-specific options or :option:`--all` is specified.
+
+OPTIONS
+-------
+
+.. option:: -a, --all
+
+            Disassemble all supported DWARF sections.
+
+.. option:: --arch=<arch>
+
+            Dump DWARF debug information for the specified CPU architecture.
+            Architectures may be specified by name or by number.  This
+            option can be specified multiple times, once for each desired
+            architecture.  All CPU architectures will be printed by
+            default.
+
+.. option:: -c, --show-children
+
+            Show a debug info entry's children when using
+            the :option:`--debug-info`, :option:`--find`,
+            and :option:`--name` options.
+
+.. option:: -f <name>, --find=<name>
+
+            Search for the exact text <name> in the accelerator tables
+            and print the matching debug information entries.
+            When there is no accelerator tables or the name of the DIE
+            you are looking for is not found in the accelerator tables,
+            try using the slower but more complete :option:`--name` option.
+
+.. option:: -F, --show-form
+
+            Show DWARF form types after the DWARF attribute types.
+
+.. option:: -h, --help
+
+            Show help and usage for this command.
+
+.. option:: -i, --ignore-case
+
+            Ignore case distinctions in when searching entries by name
+            or by regular expression.
+
+.. option:: -n <pattern>, --name=<pattern>
+
+            Find and print all debug info entries whose name
+            (`DW_AT_name` attribute) matches the exact text in
+            <pattern>. Use the :option:`--regex` option to have
+            <pattern> become a regular expression for more flexible
+            pattern matching.
+
+.. option:: --lookup=<address>
+
+            Lookup <address> in the debug information and print out the file,
+            function, block, and line table details.
+
+.. option:: -o <path>, --out-file=<path>
+
+            Redirect output to a file specified by <path>.
+
+.. option:: -p, --show-parents
+
+            Show a debug info entry's parent objects when using the
+            :option:`--debug-info`, :option:`--find`, and
+            :option:`--name` options.
+
+.. option:: -r <n>, --recurse-depth=<n>
+
+            Only recurse to a maximum depth of <n> when dumping debug info
+            entries.
+
+.. option:: --statistics
+
+            Collect debug info quality metrics and print the results
+            as machine-readable single-line JSON output.
+
+.. option:: -x, --regex
+
+            Treat any <pattern> strings as regular expressions when searching
+            instead of just as an exact string match.
+
+.. option:: -u, --uuid
+
+            Show the UUID for each architecture.
+
+.. option:: --diff
+
+            Dump the output in a format that is more friendly for comparing
+            DWARF output from two different files.
+
+.. option:: -v, --verbose
+
+            Display verbose information when dumping. This can help to debug
+            DWARF issues.
+
+.. option:: --verify
+
+            Verify the structure of the DWARF information by verifying the
+            compile unit chains, DIE relationships graph, address
+            ranges, and more.
+
+.. option:: --version
+
+            Display the version of the tool.
+
+.. option:: --debug-abbrev, --debug-aranges, --debug-cu-index, --debug-frame [=<offset>], --debug-gnu-pubnames, --debug-gnu-pubtypes, --debug-info [=<offset>], --debug-line [=<offset>], --debug-loc [=<offset>], --debug-macro, --debug-pubnames, --debug-pubtypes, --debug-ranges, --debug-str, --debug-str-offsets, --debug-tu-index, --debug-types, --eh-frame, --gdb-index, --apple-names, --apple-types, --apple-namespaces, --apple-objc
+
+            Dump the specified DWARF section by name. Only the
+            `.debug_info` section is shown by default. Some entries
+            support adding an `=<offset>` as a way to provide an
+            optional offset of the exact entry to dump within the
+            respective section. When an offset is provided, only the
+            entry at that offset will be dumped, else the entire
+            section will be dumped. Children of items at a specific
+            offset can be dumped by also using the
+            :option:`--show-children` option where applicable.
+
+EXIT STATUS
+-----------
+
+:program:`llvm-dwarfdump` returns 0 if the input files were parsed and dumped
+successfully. Otherwise, it returns 1.
+
+SEE ALSO
+--------
+
+:manpage:`dsymutil(1)`

Added: www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-exegesis.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-exegesis.rst.txt?rev=368037&view=auto
==============================================================================
--- www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-exegesis.rst.txt (added)
+++ www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-exegesis.rst.txt Tue Aug  6 06:51:02 2019
@@ -0,0 +1,236 @@
+llvm-exegesis - LLVM Machine Instruction Benchmark
+==================================================
+
+SYNOPSIS
+--------
+
+:program:`llvm-exegesis` [*options*]
+
+DESCRIPTION
+-----------
+
+:program:`llvm-exegesis` is a benchmarking tool that uses information available
+in LLVM to measure host machine instruction characteristics like latency or port
+decomposition.
+
+Given an LLVM opcode name and a benchmarking mode, :program:`llvm-exegesis`
+generates a code snippet that makes execution as serial (resp. as parallel) as
+possible so that we can measure the latency (resp. uop decomposition) of the
+instruction.
+The code snippet is jitted and executed on the host subtarget. The time taken
+(resp. resource usage) is measured using hardware performance counters. The
+result is printed out as YAML to the standard output.
+
+The main goal of this tool is to automatically (in)validate the LLVM's TableDef
+scheduling models. To that end, we also provide analysis of the results.
+
+:program:`llvm-exegesis` can also benchmark arbitrary user-provided code
+snippets.
+
+EXAMPLE 1: benchmarking instructions
+------------------------------------
+
+Assume you have an X86-64 machine. To measure the latency of a single
+instruction, run:
+
+.. code-block:: bash
+
+    $ llvm-exegesis -mode=latency -opcode-name=ADD64rr
+
+Measuring the uop decomposition of an instruction works similarly:
+
+.. code-block:: bash
+
+    $ llvm-exegesis -mode=uops -opcode-name=ADD64rr
+
+The output is a YAML document (the default is to write to stdout, but you can
+redirect the output to a file using `-benchmarks-file`):
+
+.. code-block:: none
+
+  ---
+  key:
+    opcode_name:     ADD64rr
+    mode:            latency
+    config:          ''
+  cpu_name:        haswell
+  llvm_triple:     x86_64-unknown-linux-gnu
+  num_repetitions: 10000
+  measurements:
+    - { key: latency, value: 1.0058, debug_string: '' }
+  error:           ''
+  info:            'explicit self cycles, selecting one aliasing configuration.
+  Snippet:
+  ADD64rr R8, R8, R10
+  '
+  ...
+
+To measure the latency of all instructions for the host architecture, run:
+
+.. code-block:: bash
+
+  #!/bin/bash
+  readonly INSTRUCTIONS=$(($(grep INSTRUCTION_LIST_END build/lib/Target/X86/X86GenInstrInfo.inc | cut -f2 -d=) - 1))
+  for INSTRUCTION in $(seq 1 ${INSTRUCTIONS});
+  do
+    ./build/bin/llvm-exegesis -mode=latency -opcode-index=${INSTRUCTION} | sed -n '/---/,$p'
+  done
+
+FIXME: Provide an :program:`llvm-exegesis` option to test all instructions.
+
+
+EXAMPLE 2: benchmarking a custom code snippet
+---------------------------------------------
+
+To measure the latency/uops of a custom piece of code, you can specify the
+`snippets-file` option (`-` reads from standard input).
+
+.. code-block:: bash
+
+    $ echo "vzeroupper" | llvm-exegesis -mode=uops -snippets-file=-
+
+Real-life code snippets typically depend on registers or memory.
+:program:`llvm-exegesis` checks the liveliness of registers (i.e. any register
+use has a corresponding def or is a "live in"). If your code depends on the
+value of some registers, you have two options:
+
+- Mark the register as requiring a definition. :program:`llvm-exegesis` will
+  automatically assign a value to the register. This can be done using the
+  directive `LLVM-EXEGESIS-DEFREG <reg name> <hex_value>`, where `<hex_value>`
+  is a bit pattern used to fill `<reg_name>`. If `<hex_value>` is smaller than
+  the register width, it will be sign-extended.
+- Mark the register as a "live in". :program:`llvm-exegesis` will benchmark
+  using whatever value was in this registers on entry. This can be done using
+  the directive `LLVM-EXEGESIS-LIVEIN <reg name>`.
+
+For example, the following code snippet depends on the values of XMM1 (which
+will be set by the tool) and the memory buffer passed in RDI (live in).
+
+.. code-block:: none
+
+  # LLVM-EXEGESIS-LIVEIN RDI
+  # LLVM-EXEGESIS-DEFREG XMM1 42
+  vmulps	(%rdi), %xmm1, %xmm2
+  vhaddps	%xmm2, %xmm2, %xmm3
+  addq $0x10, %rdi
+
+
+EXAMPLE 3: analysis
+-------------------
+
+Assuming you have a set of benchmarked instructions (either latency or uops) as
+YAML in file `/tmp/benchmarks.yaml`, you can analyze the results using the
+following command:
+
+.. code-block:: bash
+
+    $ llvm-exegesis -mode=analysis \
+  -benchmarks-file=/tmp/benchmarks.yaml \
+  -analysis-clusters-output-file=/tmp/clusters.csv \
+  -analysis-inconsistencies-output-file=/tmp/inconsistencies.html
+
+This will group the instructions into clusters with the same performance
+characteristics. The clusters will be written out to `/tmp/clusters.csv` in the
+following format:
+
+.. code-block:: none
+
+  cluster_id,opcode_name,config,sched_class
+  ...
+  2,ADD32ri8_DB,,WriteALU,1.00
+  2,ADD32ri_DB,,WriteALU,1.01
+  2,ADD32rr,,WriteALU,1.01
+  2,ADD32rr_DB,,WriteALU,1.00
+  2,ADD32rr_REV,,WriteALU,1.00
+  2,ADD64i32,,WriteALU,1.01
+  2,ADD64ri32,,WriteALU,1.01
+  2,MOVSX64rr32,,BSWAP32r_BSWAP64r_MOVSX64rr32,1.00
+  2,VPADDQYrr,,VPADDBYrr_VPADDDYrr_VPADDQYrr_VPADDWYrr_VPSUBBYrr_VPSUBDYrr_VPSUBQYrr_VPSUBWYrr,1.02
+  2,VPSUBQYrr,,VPADDBYrr_VPADDDYrr_VPADDQYrr_VPADDWYrr_VPSUBBYrr_VPSUBDYrr_VPSUBQYrr_VPSUBWYrr,1.01
+  2,ADD64ri8,,WriteALU,1.00
+  2,SETBr,,WriteSETCC,1.01
+  ...
+
+:program:`llvm-exegesis` will also analyze the clusters to point out
+inconsistencies in the scheduling information. The output is an html file. For
+example, `/tmp/inconsistencies.html` will contain messages like the following :
+
+.. image:: llvm-exegesis-analysis.png
+  :align: center
+
+Note that the scheduling class names will be resolved only when
+:program:`llvm-exegesis` is compiled in debug mode, else only the class id will
+be shown. This does not invalidate any of the analysis results though.
+
+
+OPTIONS
+-------
+
+.. option:: -help
+
+ Print a summary of command line options.
+
+.. option:: -opcode-index=<LLVM opcode index>
+
+ Specify the opcode to measure, by index. See example 1 for details.
+ Either `opcode-index`, `opcode-name` or `snippets-file` must be set.
+
+.. option:: -opcode-name=<opcode name 1>,<opcode name 2>,...
+
+ Specify the opcode to measure, by name. Several opcodes can be specified as
+ a comma-separated list. See example 1 for details.
+ Either `opcode-index`, `opcode-name` or `snippets-file` must be set.
+
+ .. option:: -snippets-file=<filename>
+
+  Specify the custom code snippet to measure. See example 2 for details.
+  Either `opcode-index`, `opcode-name` or `snippets-file` must be set.
+
+.. option:: -mode=[latency|uops|analysis]
+
+ Specify the run mode.
+
+.. option:: -num-repetitions=<Number of repetition>
+
+ Specify the number of repetitions of the asm snippet.
+ Higher values lead to more accurate measurements but lengthen the benchmark.
+
+.. option:: -benchmarks-file=</path/to/file>
+
+ File to read (`analysis` mode) or write (`latency`/`uops` modes) benchmark
+ results. "-" uses stdin/stdout.
+
+.. option:: -analysis-clusters-output-file=</path/to/file>
+
+ If provided, write the analysis clusters as CSV to this file. "-" prints to
+ stdout.
+
+.. option:: -analysis-inconsistencies-output-file=</path/to/file>
+
+ If non-empty, write inconsistencies found during analysis to this file. `-`
+ prints to stdout.
+
+.. option:: -analysis-numpoints=<dbscan numPoints parameter>
+
+ Specify the numPoints parameters to be used for DBSCAN clustering
+ (`analysis` mode).
+
+.. option:: -analysis-espilon=<dbscan epsilon parameter>
+
+ Specify the numPoints parameters to be used for DBSCAN clustering
+ (`analysis` mode).
+
+.. option:: -ignore-invalid-sched-class=false
+
+ If set, ignore instructions that do not have a sched class (class idx = 0).
+
+ .. option:: -mcpu=<cpu name>
+
+  If set, measure the cpu characteristics using the counters for this CPU. This
+  is useful when creating new sched models (the host CPU is unknown to LLVM).
+
+EXIT STATUS
+-----------
+
+:program:`llvm-exegesis` returns 0 on success. Otherwise, an error message is
+printed to standard error, and the tool returns a non 0 value.

Added: www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-extract.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-extract.rst.txt?rev=368037&view=auto
==============================================================================
--- www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-extract.rst.txt (added)
+++ www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-extract.rst.txt Tue Aug  6 06:51:02 2019
@@ -0,0 +1,79 @@
+llvm-extract - extract a function from an LLVM module
+=====================================================
+
+SYNOPSIS
+--------
+
+:program:`llvm-extract` [*options*] **--func** *function-name* [*filename*]
+
+DESCRIPTION
+-----------
+
+The :program:`llvm-extract` command takes the name of a function and extracts
+it from the specified LLVM bitcode file.  It is primarily used as a debugging
+tool to reduce test cases from larger programs that are triggering a bug.
+
+In addition to extracting the bitcode of the specified function,
+:program:`llvm-extract` will also remove unreachable global variables,
+prototypes, and unused types.
+
+The :program:`llvm-extract` command reads its input from standard input if
+filename is omitted or if filename is ``-``.  The output is always written to
+standard output, unless the **-o** option is specified (see below).
+
+OPTIONS
+-------
+
+**-f**
+
+ Enable binary output on terminals.  Normally, :program:`llvm-extract` will
+ refuse to write raw bitcode output if the output stream is a terminal.  With
+ this option, :program:`llvm-extract` will write raw bitcode regardless of the
+ output device.
+
+**--func** *function-name*
+
+ Extract the function named *function-name* from the LLVM bitcode.  May be
+ specified multiple times to extract multiple functions at once.
+
+**--rfunc** *function-regular-expr*
+
+ Extract the function(s) matching *function-regular-expr* from the LLVM bitcode.
+ All functions matching the regular expression will be extracted.  May be
+ specified multiple times.
+
+**--glob** *global-name*
+
+ Extract the global variable named *global-name* from the LLVM bitcode.  May be
+ specified multiple times to extract multiple global variables at once.
+
+**--rglob** *glob-regular-expr*
+
+ Extract the global variable(s) matching *global-regular-expr* from the LLVM
+ bitcode.  All global variables matching the regular expression will be
+ extracted.  May be specified multiple times.
+
+**-help**
+
+ Print a summary of command line options.
+
+**-o** *filename*
+
+ Specify the output filename.  If filename is "-" (the default), then
+ :program:`llvm-extract` sends its output to standard output.
+
+**-S**
+
+ Write output in LLVM intermediate language (instead of bitcode).
+
+EXIT STATUS
+-----------
+
+If :program:`llvm-extract` succeeds, it will exit with 0.  Otherwise, if an error
+occurs, it will exit with a non-zero value.
+
+SEE ALSO
+--------
+
+bugpoint
+

Added: www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-lib.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-lib.rst.txt?rev=368037&view=auto
==============================================================================
--- www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-lib.rst.txt (added)
+++ www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-lib.rst.txt Tue Aug  6 06:51:02 2019
@@ -0,0 +1,31 @@
+llvm-lib - LLVM lib.exe compatible library tool
+===============================================
+
+
+SYNOPSIS
+--------
+
+
+**llvm-lib** [/libpath:<path>] [/out:<output>] [/llvmlibthin]
+[/ignore] [/machine] [/nologo] [files...]
+
+
+DESCRIPTION
+-----------
+
+
+The **llvm-lib** command is intended to be a ``lib.exe`` compatible
+tool. See https://msdn.microsoft.com/en-us/library/7ykb2k5f for the
+general description.
+
+**llvm-lib** has the following extensions:
+
+* Bitcode files in symbol tables.
+  **llvm-lib** includes symbols from both bitcode files and regular
+  object files in the symbol table.
+
+* Creating thin archives.
+  The /llvmlibthin option causes **llvm-lib** to create thin archive
+  that contain only the symbol table and the header for the various
+  members. These files are much smaller, but are not compatible with
+  link.exe (lld can handle them).

Added: www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-link.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-link.rst.txt?rev=368037&view=auto
==============================================================================
--- www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-link.rst.txt (added)
+++ www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-link.rst.txt Tue Aug  6 06:51:02 2019
@@ -0,0 +1,56 @@
+llvm-link - LLVM bitcode linker
+===============================
+
+SYNOPSIS
+--------
+
+:program:`llvm-link` [*options*] *filename ...*
+
+DESCRIPTION
+-----------
+
+:program:`llvm-link` takes several LLVM bitcode files and links them together
+into a single LLVM bitcode file.  It writes the output file to standard output,
+unless the :option:`-o` option is used to specify a filename.
+
+OPTIONS
+-------
+
+.. option:: -f
+
+ Enable binary output on terminals.  Normally, :program:`llvm-link` will refuse
+ to write raw bitcode output if the output stream is a terminal. With this
+ option, :program:`llvm-link` will write raw bitcode regardless of the output
+ device.
+
+.. option:: -o filename
+
+ Specify the output file name.  If ``filename`` is "``-``", then
+ :program:`llvm-link` will write its output to standard output.
+
+.. option:: -S
+
+ Write output in LLVM intermediate language (instead of bitcode).
+
+.. option:: -d
+
+ If specified, :program:`llvm-link` prints a human-readable version of the
+ output bitcode file to standard error.
+
+.. option:: -help
+
+ Print a summary of command line options.
+
+.. option:: -v
+
+ Verbose mode.  Print information about what :program:`llvm-link` is doing.
+ This typically includes a message for each bitcode file linked in and for each
+ library found.
+
+EXIT STATUS
+-----------
+
+If :program:`llvm-link` succeeds, it will exit with 0.  Otherwise, if an error
+occurs, it will exit with a non-zero value.
+
+

Added: www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-lipo.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-lipo.rst.txt?rev=368037&view=auto
==============================================================================
--- www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-lipo.rst.txt (added)
+++ www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-lipo.rst.txt Tue Aug  6 06:51:02 2019
@@ -0,0 +1,41 @@
+llvm-lipo - LLVM tool for manipulating universal binaries
+=========================================================
+
+.. program:: llvm-lipo
+
+SYNOPSIS
+--------
+
+:program:`llvm-lipo` [*filenames...*] [*options*]
+
+DESCRIPTION
+-----------
+:program:`llvm-lipo` can create universal binaries from Mach-O files, extract regular object files from universal binaries, and display architecture information about both universal and regular files.
+
+COMMANDS
+--------
+:program:`llvm-lipo` supports the following mutually exclusive commands:
+
+.. option:: -help, -h
+
+  Display usage information and exit. 
+
+.. option:: -version
+
+  Display the version of this program. 
+
+.. option:: -verify_arch  <architecture 1> [<architecture 2> ...]
+
+  Take a single input file and verify the specified architectures are present in the file. 
+  If so then exit with a status of 0 else exit with a status of 1.
+
+.. option:: -archs
+
+  Take a single input file and display the architectures present in the file.
+  Each architecture is separated by a single whitespace.
+  Unknown architectures are displayed as unknown(CPUtype,CPUsubtype).
+
+BUGS
+----
+
+To report bugs, please visit <http://llvm.org/bugs/>.

Added: www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-mca.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-mca.rst.txt?rev=368037&view=auto
==============================================================================
--- www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-mca.rst.txt (added)
+++ www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-mca.rst.txt Tue Aug  6 06:51:02 2019
@@ -0,0 +1,769 @@
+llvm-mca - LLVM Machine Code Analyzer
+=====================================
+
+SYNOPSIS
+--------
+
+:program:`llvm-mca` [*options*] [input]
+
+DESCRIPTION
+-----------
+
+:program:`llvm-mca` is a performance analysis tool that uses information
+available in LLVM (e.g. scheduling models) to statically measure the performance
+of machine code in a specific CPU.
+
+Performance is measured in terms of throughput as well as processor resource
+consumption. The tool currently works for processors with an out-of-order
+backend, for which there is a scheduling model available in LLVM.
+
+The main goal of this tool is not just to predict the performance of the code
+when run on the target, but also help with diagnosing potential performance
+issues.
+
+Given an assembly code sequence, :program:`llvm-mca` estimates the Instructions
+Per Cycle (IPC), as well as hardware resource pressure. The analysis and
+reporting style were inspired by the IACA tool from Intel.
+
+For example, you can compile code with clang, output assembly, and pipe it
+directly into :program:`llvm-mca` for analysis:
+
+.. code-block:: bash
+
+  $ clang foo.c -O2 -target x86_64-unknown-unknown -S -o - | llvm-mca -mcpu=btver2
+
+Or for Intel syntax:
+
+.. code-block:: bash
+
+  $ clang foo.c -O2 -target x86_64-unknown-unknown -mllvm -x86-asm-syntax=intel -S -o - | llvm-mca -mcpu=btver2
+
+OPTIONS
+-------
+
+If ``input`` is "``-``" or omitted, :program:`llvm-mca` reads from standard
+input. Otherwise, it will read from the specified filename.
+
+If the :option:`-o` option is omitted, then :program:`llvm-mca` will send its output
+to standard output if the input is from standard input.  If the :option:`-o`
+option specifies "``-``", then the output will also be sent to standard output.
+
+
+.. option:: -help
+
+ Print a summary of command line options.
+
+.. option:: -mtriple=<target triple>
+
+ Specify a target triple string.
+
+.. option:: -march=<arch>
+
+ Specify the architecture for which to analyze the code. It defaults to the
+ host default target.
+
+.. option:: -mcpu=<cpuname>
+
+  Specify the processor for which to analyze the code.  By default, the cpu name
+  is autodetected from the host.
+
+.. option:: -output-asm-variant=<variant id>
+
+ Specify the output assembly variant for the report generated by the tool.
+ On x86, possible values are [0, 1]. A value of 0 (vic. 1) for this flag enables
+ the AT&T (vic. Intel) assembly format for the code printed out by the tool in
+ the analysis report.
+
+.. option:: -dispatch=<width>
+
+ Specify a different dispatch width for the processor. The dispatch width
+ defaults to field 'IssueWidth' in the processor scheduling model.  If width is
+ zero, then the default dispatch width is used.
+
+.. option:: -register-file-size=<size>
+
+ Specify the size of the register file. When specified, this flag limits how
+ many physical registers are available for register renaming purposes. A value
+ of zero for this flag means "unlimited number of physical registers".
+
+.. option:: -iterations=<number of iterations>
+
+ Specify the number of iterations to run. If this flag is set to 0, then the
+ tool sets the number of iterations to a default value (i.e. 100).
+
+.. option:: -noalias=<bool>
+
+  If set, the tool assumes that loads and stores don't alias. This is the
+  default behavior.
+
+.. option:: -lqueue=<load queue size>
+
+  Specify the size of the load queue in the load/store unit emulated by the tool.
+  By default, the tool assumes an unbound number of entries in the load queue.
+  A value of zero for this flag is ignored, and the default load queue size is
+  used instead. 
+
+.. option:: -squeue=<store queue size>
+
+  Specify the size of the store queue in the load/store unit emulated by the
+  tool. By default, the tool assumes an unbound number of entries in the store
+  queue. A value of zero for this flag is ignored, and the default store queue
+  size is used instead.
+
+.. option:: -timeline
+
+  Enable the timeline view.
+
+.. option:: -timeline-max-iterations=<iterations>
+
+  Limit the number of iterations to print in the timeline view. By default, the
+  timeline view prints information for up to 10 iterations.
+
+.. option:: -timeline-max-cycles=<cycles>
+
+  Limit the number of cycles in the timeline view. By default, the number of
+  cycles is set to 80.
+
+.. option:: -resource-pressure
+
+  Enable the resource pressure view. This is enabled by default.
+
+.. option:: -register-file-stats
+
+  Enable register file usage statistics.
+
+.. option:: -dispatch-stats
+
+  Enable extra dispatch statistics. This view collects and analyzes instruction
+  dispatch events, as well as static/dynamic dispatch stall events. This view
+  is disabled by default.
+
+.. option:: -scheduler-stats
+
+  Enable extra scheduler statistics. This view collects and analyzes instruction
+  issue events. This view is disabled by default.
+
+.. option:: -retire-stats
+
+  Enable extra retire control unit statistics. This view is disabled by default.
+
+.. option:: -instruction-info
+
+  Enable the instruction info view. This is enabled by default.
+
+.. option:: -all-stats
+
+  Print all hardware statistics. This enables extra statistics related to the
+  dispatch logic, the hardware schedulers, the register file(s), and the retire
+  control unit. This option is disabled by default.
+
+.. option:: -all-views
+
+  Enable all the view.
+
+.. option:: -instruction-tables
+
+  Prints resource pressure information based on the static information
+  available from the processor model. This differs from the resource pressure
+  view because it doesn't require that the code is simulated. It instead prints
+  the theoretical uniform distribution of resource pressure for every
+  instruction in sequence.
+
+
+EXIT STATUS
+-----------
+
+:program:`llvm-mca` returns 0 on success. Otherwise, an error message is printed
+to standard error, and the tool returns 1.
+
+USING MARKERS TO ANALYZE SPECIFIC CODE BLOCKS
+---------------------------------------------
+:program:`llvm-mca` allows for the optional usage of special code comments to
+mark regions of the assembly code to be analyzed.  A comment starting with
+substring ``LLVM-MCA-BEGIN`` marks the beginning of a code region. A comment
+starting with substring ``LLVM-MCA-END`` marks the end of a code region.  For
+example:
+
+.. code-block:: none
+
+  # LLVM-MCA-BEGIN My Code Region
+    ...
+  # LLVM-MCA-END
+
+Multiple regions can be specified provided that they do not overlap.  A code
+region can have an optional description. If no user-defined region is specified,
+then :program:`llvm-mca` assumes a default region which contains every
+instruction in the input file.  Every region is analyzed in isolation, and the
+final performance report is the union of all the reports generated for every
+code region.
+
+Inline assembly directives may be used from source code to annotate the
+assembly text:
+
+.. code-block:: c++
+
+  int foo(int a, int b) {
+    __asm volatile("# LLVM-MCA-BEGIN foo");
+    a += 42;
+    __asm volatile("# LLVM-MCA-END");
+    a *= b;
+    return a;
+  }
+
+HOW LLVM-MCA WORKS
+------------------
+
+:program:`llvm-mca` takes assembly code as input. The assembly code is parsed
+into a sequence of MCInst with the help of the existing LLVM target assembly
+parsers. The parsed sequence of MCInst is then analyzed by a ``Pipeline`` module
+to generate a performance report.
+
+The Pipeline module simulates the execution of the machine code sequence in a
+loop of iterations (default is 100). During this process, the pipeline collects
+a number of execution related statistics. At the end of this process, the
+pipeline generates and prints a report from the collected statistics.
+
+Here is an example of a performance report generated by the tool for a
+dot-product of two packed float vectors of four elements. The analysis is
+conducted for target x86, cpu btver2.  The following result can be produced via
+the following command using the example located at
+``test/tools/llvm-mca/X86/BtVer2/dot-product.s``:
+
+.. code-block:: bash
+
+  $ llvm-mca -mtriple=x86_64-unknown-unknown -mcpu=btver2 -iterations=300 dot-product.s
+
+.. code-block:: none
+
+  Iterations:        300
+  Instructions:      900
+  Total Cycles:      610
+  Total uOps:        900
+
+  Dispatch Width:    2
+  uOps Per Cycle:    1.48
+  IPC:               1.48
+  Block RThroughput: 2.0
+
+
+  Instruction Info:
+  [1]: #uOps
+  [2]: Latency
+  [3]: RThroughput
+  [4]: MayLoad
+  [5]: MayStore
+  [6]: HasSideEffects (U)
+
+  [1]    [2]    [3]    [4]    [5]    [6]    Instructions:
+   1      2     1.00                        vmulps	%xmm0, %xmm1, %xmm2
+   1      3     1.00                        vhaddps	%xmm2, %xmm2, %xmm3
+   1      3     1.00                        vhaddps	%xmm3, %xmm3, %xmm4
+
+
+  Resources:
+  [0]   - JALU0
+  [1]   - JALU1
+  [2]   - JDiv
+  [3]   - JFPA
+  [4]   - JFPM
+  [5]   - JFPU0
+  [6]   - JFPU1
+  [7]   - JLAGU
+  [8]   - JMul
+  [9]   - JSAGU
+  [10]  - JSTC
+  [11]  - JVALU0
+  [12]  - JVALU1
+  [13]  - JVIMUL
+
+
+  Resource pressure per iteration:
+  [0]    [1]    [2]    [3]    [4]    [5]    [6]    [7]    [8]    [9]    [10]   [11]   [12]   [13]
+   -      -      -     2.00   1.00   2.00   1.00    -      -      -      -      -      -      -
+
+  Resource pressure by instruction:
+  [0]    [1]    [2]    [3]    [4]    [5]    [6]    [7]    [8]    [9]    [10]   [11]   [12]   [13]   Instructions:
+   -      -      -      -     1.00    -     1.00    -      -      -      -      -      -      -     vmulps	%xmm0, %xmm1, %xmm2
+   -      -      -     1.00    -     1.00    -      -      -      -      -      -      -      -     vhaddps	%xmm2, %xmm2, %xmm3
+   -      -      -     1.00    -     1.00    -      -      -      -      -      -      -      -     vhaddps	%xmm3, %xmm3, %xmm4
+
+According to this report, the dot-product kernel has been executed 300 times,
+for a total of 900 simulated instructions. The total number of simulated micro
+opcodes (uOps) is also 900.
+
+The report is structured in three main sections.  The first section collects a
+few performance numbers; the goal of this section is to give a very quick
+overview of the performance throughput. Important performance indicators are
+**IPC**, **uOps Per Cycle**, and  **Block RThroughput** (Block Reciprocal
+Throughput).
+
+IPC is computed dividing the total number of simulated instructions by the total
+number of cycles. In the absence of loop-carried data dependencies, the
+observed IPC tends to a theoretical maximum which can be computed by dividing
+the number of instructions of a single iteration by the *Block RThroughput*.
+
+Field 'uOps Per Cycle' is computed dividing the total number of simulated micro
+opcodes by the total number of cycles. A delta between Dispatch Width and this
+field is an indicator of a performance issue. In the absence of loop-carried
+data dependencies, the observed 'uOps Per Cycle' should tend to a theoretical
+maximum throughput which can be computed by dividing the number of uOps of a
+single iteration by the *Block RThroughput*.
+
+Field *uOps Per Cycle* is bounded from above by the dispatch width. That is
+because the dispatch width limits the maximum size of a dispatch group. Both IPC
+and 'uOps Per Cycle' are limited by the amount of hardware parallelism. The
+availability of hardware resources affects the resource pressure distribution,
+and it limits the number of instructions that can be executed in parallel every
+cycle.  A delta between Dispatch Width and the theoretical maximum uOps per
+Cycle (computed by dividing the number of uOps of a single iteration by the
+*Block RTrhoughput*) is an indicator of a performance bottleneck caused by the
+lack of hardware resources.
+In general, the lower the Block RThroughput, the better.
+
+In this example, ``uOps per iteration/Block RThroughput`` is 1.50. Since there
+are no loop-carried dependencies, the observed *uOps Per Cycle* is expected to
+approach 1.50 when the number of iterations tends to infinity. The delta between
+the Dispatch Width (2.00), and the theoretical maximum uOp throughput (1.50) is
+an indicator of a performance bottleneck caused by the lack of hardware
+resources, and the *Resource pressure view* can help to identify the problematic
+resource usage.
+
+The second section of the report shows the latency and reciprocal
+throughput of every instruction in the sequence. That section also reports
+extra information related to the number of micro opcodes, and opcode properties
+(i.e., 'MayLoad', 'MayStore', and 'HasSideEffects').
+
+The third section is the *Resource pressure view*.  This view reports
+the average number of resource cycles consumed every iteration by instructions
+for every processor resource unit available on the target.  Information is
+structured in two tables. The first table reports the number of resource cycles
+spent on average every iteration. The second table correlates the resource
+cycles to the machine instruction in the sequence. For example, every iteration
+of the instruction vmulps always executes on resource unit [6]
+(JFPU1 - floating point pipeline #1), consuming an average of 1 resource cycle
+per iteration.  Note that on AMD Jaguar, vector floating-point multiply can
+only be issued to pipeline JFPU1, while horizontal floating-point additions can
+only be issued to pipeline JFPU0.
+
+The resource pressure view helps with identifying bottlenecks caused by high
+usage of specific hardware resources.  Situations with resource pressure mainly
+concentrated on a few resources should, in general, be avoided.  Ideally,
+pressure should be uniformly distributed between multiple resources.
+
+Timeline View
+^^^^^^^^^^^^^
+The timeline view produces a detailed report of each instruction's state
+transitions through an instruction pipeline.  This view is enabled by the
+command line option ``-timeline``.  As instructions transition through the
+various stages of the pipeline, their states are depicted in the view report.
+These states are represented by the following characters:
+
+* D : Instruction dispatched.
+* e : Instruction executing.
+* E : Instruction executed.
+* R : Instruction retired.
+* = : Instruction already dispatched, waiting to be executed.
+* \- : Instruction executed, waiting to be retired.
+
+Below is the timeline view for a subset of the dot-product example located in
+``test/tools/llvm-mca/X86/BtVer2/dot-product.s`` and processed by
+:program:`llvm-mca` using the following command:
+
+.. code-block:: bash
+
+  $ llvm-mca -mtriple=x86_64-unknown-unknown -mcpu=btver2 -iterations=3 -timeline dot-product.s
+
+.. code-block:: none
+
+  Timeline view:
+                      012345
+  Index     0123456789
+
+  [0,0]     DeeER.    .    .   vmulps	%xmm0, %xmm1, %xmm2
+  [0,1]     D==eeeER  .    .   vhaddps	%xmm2, %xmm2, %xmm3
+  [0,2]     .D====eeeER    .   vhaddps	%xmm3, %xmm3, %xmm4
+  [1,0]     .DeeE-----R    .   vmulps	%xmm0, %xmm1, %xmm2
+  [1,1]     . D=eeeE---R   .   vhaddps	%xmm2, %xmm2, %xmm3
+  [1,2]     . D====eeeER   .   vhaddps	%xmm3, %xmm3, %xmm4
+  [2,0]     .  DeeE-----R  .   vmulps	%xmm0, %xmm1, %xmm2
+  [2,1]     .  D====eeeER  .   vhaddps	%xmm2, %xmm2, %xmm3
+  [2,2]     .   D======eeeER   vhaddps	%xmm3, %xmm3, %xmm4
+
+
+  Average Wait times (based on the timeline view):
+  [0]: Executions
+  [1]: Average time spent waiting in a scheduler's queue
+  [2]: Average time spent waiting in a scheduler's queue while ready
+  [3]: Average time elapsed from WB until retire stage
+
+        [0]    [1]    [2]    [3]
+  0.     3     1.0    1.0    3.3       vmulps	%xmm0, %xmm1, %xmm2
+  1.     3     3.3    0.7    1.0       vhaddps	%xmm2, %xmm2, %xmm3
+  2.     3     5.7    0.0    0.0       vhaddps	%xmm3, %xmm3, %xmm4
+
+The timeline view is interesting because it shows instruction state changes
+during execution.  It also gives an idea of how the tool processes instructions
+executed on the target, and how their timing information might be calculated.
+
+The timeline view is structured in two tables.  The first table shows
+instructions changing state over time (measured in cycles); the second table
+(named *Average Wait times*) reports useful timing statistics, which should
+help diagnose performance bottlenecks caused by long data dependencies and
+sub-optimal usage of hardware resources.
+
+An instruction in the timeline view is identified by a pair of indices, where
+the first index identifies an iteration, and the second index is the
+instruction index (i.e., where it appears in the code sequence).  Since this
+example was generated using 3 iterations: ``-iterations=3``, the iteration
+indices range from 0-2 inclusively.
+
+Excluding the first and last column, the remaining columns are in cycles.
+Cycles are numbered sequentially starting from 0.
+
+From the example output above, we know the following:
+
+* Instruction [1,0] was dispatched at cycle 1.
+* Instruction [1,0] started executing at cycle 2.
+* Instruction [1,0] reached the write back stage at cycle 4.
+* Instruction [1,0] was retired at cycle 10.
+
+Instruction [1,0] (i.e., vmulps from iteration #1) does not have to wait in the
+scheduler's queue for the operands to become available. By the time vmulps is
+dispatched, operands are already available, and pipeline JFPU1 is ready to
+serve another instruction.  So the instruction can be immediately issued on the
+JFPU1 pipeline. That is demonstrated by the fact that the instruction only
+spent 1cy in the scheduler's queue.
+
+There is a gap of 5 cycles between the write-back stage and the retire event.
+That is because instructions must retire in program order, so [1,0] has to wait
+for [0,2] to be retired first (i.e., it has to wait until cycle 10).
+
+In the example, all instructions are in a RAW (Read After Write) dependency
+chain.  Register %xmm2 written by vmulps is immediately used by the first
+vhaddps, and register %xmm3 written by the first vhaddps is used by the second
+vhaddps.  Long data dependencies negatively impact the ILP (Instruction Level
+Parallelism).
+
+In the dot-product example, there are anti-dependencies introduced by
+instructions from different iterations.  However, those dependencies can be
+removed at register renaming stage (at the cost of allocating register aliases,
+and therefore consuming physical registers).
+
+Table *Average Wait times* helps diagnose performance issues that are caused by
+the presence of long latency instructions and potentially long data dependencies
+which may limit the ILP.  Note that :program:`llvm-mca`, by default, assumes at
+least 1cy between the dispatch event and the issue event.
+
+When the performance is limited by data dependencies and/or long latency
+instructions, the number of cycles spent while in the *ready* state is expected
+to be very small when compared with the total number of cycles spent in the
+scheduler's queue.  The difference between the two counters is a good indicator
+of how large of an impact data dependencies had on the execution of the
+instructions.  When performance is mostly limited by the lack of hardware
+resources, the delta between the two counters is small.  However, the number of
+cycles spent in the queue tends to be larger (i.e., more than 1-3cy),
+especially when compared to other low latency instructions.
+
+Extra Statistics to Further Diagnose Performance Issues
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The ``-all-stats`` command line option enables extra statistics and performance
+counters for the dispatch logic, the reorder buffer, the retire control unit,
+and the register file.
+
+Below is an example of ``-all-stats`` output generated by  :program:`llvm-mca`
+for 300 iterations of the dot-product example discussed in the previous
+sections.
+
+.. code-block:: none
+
+  Dynamic Dispatch Stall Cycles:
+  RAT     - Register unavailable:                      0
+  RCU     - Retire tokens unavailable:                 0
+  SCHEDQ  - Scheduler full:                            272  (44.6%)
+  LQ      - Load queue full:                           0
+  SQ      - Store queue full:                          0
+  GROUP   - Static restrictions on the dispatch group: 0
+
+
+  Dispatch Logic - number of cycles where we saw N micro opcodes dispatched:
+  [# dispatched], [# cycles]
+   0,              24  (3.9%)
+   1,              272  (44.6%)
+   2,              314  (51.5%)
+
+
+  Schedulers - number of cycles where we saw N instructions issued:
+  [# issued], [# cycles]
+   0,          7  (1.1%)
+   1,          306  (50.2%)
+   2,          297  (48.7%)
+
+  Scheduler's queue usage:
+  [1] Resource name.
+  [2] Average number of used buffer entries.
+  [3] Maximum number of used buffer entries.
+  [4] Total number of buffer entries.
+
+   [1]            [2]        [3]        [4]
+  JALU01           0          0          20
+  JFPU01           17         18         18
+  JLSAGU           0          0          12
+
+
+  Retire Control Unit - number of cycles where we saw N instructions retired:
+  [# retired], [# cycles]
+   0,           109  (17.9%)
+   1,           102  (16.7%)
+   2,           399  (65.4%)
+
+  Total ROB Entries:                64
+  Max Used ROB Entries:             35  ( 54.7% )
+  Average Used ROB Entries per cy:  32  ( 50.0% )
+
+
+  Register File statistics:
+  Total number of mappings created:    900
+  Max number of mappings used:         35
+
+  *  Register File #1 -- JFpuPRF:
+     Number of physical registers:     72
+     Total number of mappings created: 900
+     Max number of mappings used:      35
+
+  *  Register File #2 -- JIntegerPRF:
+     Number of physical registers:     64
+     Total number of mappings created: 0
+     Max number of mappings used:      0
+
+If we look at the *Dynamic Dispatch Stall Cycles* table, we see the counter for
+SCHEDQ reports 272 cycles.  This counter is incremented every time the dispatch
+logic is unable to dispatch a full group because the scheduler's queue is full.
+
+Looking at the *Dispatch Logic* table, we see that the pipeline was only able to
+dispatch two micro opcodes 51.5% of the time.  The dispatch group was limited to
+one micro opcode 44.6% of the cycles, which corresponds to 272 cycles.  The
+dispatch statistics are displayed by either using the command option
+``-all-stats`` or ``-dispatch-stats``.
+
+The next table, *Schedulers*, presents a histogram displaying a count,
+representing the number of instructions issued on some number of cycles.  In
+this case, of the 610 simulated cycles, single instructions were issued 306
+times (50.2%) and there were 7 cycles where no instructions were issued.
+
+The *Scheduler's queue usage* table shows that the average and maximum number of
+buffer entries (i.e., scheduler queue entries) used at runtime.  Resource JFPU01
+reached its maximum (18 of 18 queue entries). Note that AMD Jaguar implements
+three schedulers:
+
+* JALU01 - A scheduler for ALU instructions.
+* JFPU01 - A scheduler floating point operations.
+* JLSAGU - A scheduler for address generation.
+
+The dot-product is a kernel of three floating point instructions (a vector
+multiply followed by two horizontal adds).  That explains why only the floating
+point scheduler appears to be used.
+
+A full scheduler queue is either caused by data dependency chains or by a
+sub-optimal usage of hardware resources.  Sometimes, resource pressure can be
+mitigated by rewriting the kernel using different instructions that consume
+different scheduler resources.  Schedulers with a small queue are less resilient
+to bottlenecks caused by the presence of long data dependencies.  The scheduler
+statistics are displayed by using the command option ``-all-stats`` or
+``-scheduler-stats``.
+
+The next table, *Retire Control Unit*, presents a histogram displaying a count,
+representing the number of instructions retired on some number of cycles.  In
+this case, of the 610 simulated cycles, two instructions were retired during the
+same cycle 399 times (65.4%) and there were 109 cycles where no instructions
+were retired.  The retire statistics are displayed by using the command option
+``-all-stats`` or ``-retire-stats``.
+
+The last table presented is *Register File statistics*.  Each physical register
+file (PRF) used by the pipeline is presented in this table.  In the case of AMD
+Jaguar, there are two register files, one for floating-point registers (JFpuPRF)
+and one for integer registers (JIntegerPRF).  The table shows that of the 900
+instructions processed, there were 900 mappings created.  Since this dot-product
+example utilized only floating point registers, the JFPuPRF was responsible for
+creating the 900 mappings.  However, we see that the pipeline only used a
+maximum of 35 of 72 available register slots at any given time. We can conclude
+that the floating point PRF was the only register file used for the example, and
+that it was never resource constrained.  The register file statistics are
+displayed by using the command option ``-all-stats`` or
+``-register-file-stats``.
+
+In this example, we can conclude that the IPC is mostly limited by data
+dependencies, and not by resource pressure.
+
+Instruction Flow
+^^^^^^^^^^^^^^^^
+This section describes the instruction flow through the default pipeline of
+:program:`llvm-mca`, as well as the functional units involved in the process.
+
+The default pipeline implements the following sequence of stages used to
+process instructions.
+
+* Dispatch (Instruction is dispatched to the schedulers).
+* Issue (Instruction is issued to the processor pipelines).
+* Write Back (Instruction is executed, and results are written back).
+* Retire (Instruction is retired; writes are architecturally committed).
+
+The default pipeline only models the out-of-order portion of a processor.
+Therefore, the instruction fetch and decode stages are not modeled. Performance
+bottlenecks in the frontend are not diagnosed. :program:`llvm-mca` assumes that
+instructions have all been decoded and placed into a queue before the simulation
+start.  Also, :program:`llvm-mca` does not model branch prediction.
+
+Instruction Dispatch
+""""""""""""""""""""
+During the dispatch stage, instructions are picked in program order from a
+queue of already decoded instructions, and dispatched in groups to the
+simulated hardware schedulers.
+
+The size of a dispatch group depends on the availability of the simulated
+hardware resources.  The processor dispatch width defaults to the value
+of the ``IssueWidth`` in LLVM's scheduling model.
+
+An instruction can be dispatched if:
+
+* The size of the dispatch group is smaller than processor's dispatch width.
+* There are enough entries in the reorder buffer.
+* There are enough physical registers to do register renaming.
+* The schedulers are not full.
+
+Scheduling models can optionally specify which register files are available on
+the processor. :program:`llvm-mca` uses that information to initialize register
+file descriptors.  Users can limit the number of physical registers that are
+globally available for register renaming by using the command option
+``-register-file-size``.  A value of zero for this option means *unbounded*. By
+knowing how many registers are available for renaming, the tool can predict
+dispatch stalls caused by the lack of physical registers.
+
+The number of reorder buffer entries consumed by an instruction depends on the
+number of micro-opcodes specified for that instruction by the target scheduling
+model.  The reorder buffer is responsible for tracking the progress of
+instructions that are "in-flight", and retiring them in program order.  The
+number of entries in the reorder buffer defaults to the value specified by field
+`MicroOpBufferSize` in the target scheduling model.
+
+Instructions that are dispatched to the schedulers consume scheduler buffer
+entries. :program:`llvm-mca` queries the scheduling model to determine the set
+of buffered resources consumed by an instruction.  Buffered resources are
+treated like scheduler resources.
+
+Instruction Issue
+"""""""""""""""""
+Each processor scheduler implements a buffer of instructions.  An instruction
+has to wait in the scheduler's buffer until input register operands become
+available.  Only at that point, does the instruction becomes eligible for
+execution and may be issued (potentially out-of-order) for execution.
+Instruction latencies are computed by :program:`llvm-mca` with the help of the
+scheduling model.
+
+:program:`llvm-mca`'s scheduler is designed to simulate multiple processor
+schedulers.  The scheduler is responsible for tracking data dependencies, and
+dynamically selecting which processor resources are consumed by instructions.
+It delegates the management of processor resource units and resource groups to a
+resource manager.  The resource manager is responsible for selecting resource
+units that are consumed by instructions.  For example, if an instruction
+consumes 1cy of a resource group, the resource manager selects one of the
+available units from the group; by default, the resource manager uses a
+round-robin selector to guarantee that resource usage is uniformly distributed
+between all units of a group.
+
+:program:`llvm-mca`'s scheduler internally groups instructions into three sets:
+
+* WaitSet: a set of instructions whose operands are not ready.
+* ReadySet: a set of instructions ready to execute.
+* IssuedSet: a set of instructions executing.
+
+Depending on the operands availability, instructions that are dispatched to the
+scheduler are either placed into the WaitSet or into the ReadySet.
+
+Every cycle, the scheduler checks if instructions can be moved from the WaitSet
+to the ReadySet, and if instructions from the ReadySet can be issued to the
+underlying pipelines. The algorithm prioritizes older instructions over younger
+instructions.
+
+Write-Back and Retire Stage
+"""""""""""""""""""""""""""
+Issued instructions are moved from the ReadySet to the IssuedSet.  There,
+instructions wait until they reach the write-back stage.  At that point, they
+get removed from the queue and the retire control unit is notified.
+
+When instructions are executed, the retire control unit flags the instruction as
+"ready to retire."
+
+Instructions are retired in program order.  The register file is notified of the
+retirement so that it can free the physical registers that were allocated for
+the instruction during the register renaming stage.
+
+Load/Store Unit and Memory Consistency Model
+""""""""""""""""""""""""""""""""""""""""""""
+To simulate an out-of-order execution of memory operations, :program:`llvm-mca`
+utilizes a simulated load/store unit (LSUnit) to simulate the speculative
+execution of loads and stores.
+
+Each load (or store) consumes an entry in the load (or store) queue. Users can
+specify flags ``-lqueue`` and ``-squeue`` to limit the number of entries in the
+load and store queues respectively. The queues are unbounded by default.
+
+The LSUnit implements a relaxed consistency model for memory loads and stores.
+The rules are:
+
+1. A younger load is allowed to pass an older load only if there are no
+   intervening stores or barriers between the two loads.
+2. A younger load is allowed to pass an older store provided that the load does
+   not alias with the store.
+3. A younger store is not allowed to pass an older store.
+4. A younger store is not allowed to pass an older load.
+
+By default, the LSUnit optimistically assumes that loads do not alias
+(`-noalias=true`) store operations.  Under this assumption, younger loads are
+always allowed to pass older stores.  Essentially, the LSUnit does not attempt
+to run any alias analysis to predict when loads and stores do not alias with
+each other.
+
+Note that, in the case of write-combining memory, rule 3 could be relaxed to
+allow reordering of non-aliasing store operations.  That being said, at the
+moment, there is no way to further relax the memory model (``-noalias`` is the
+only option).  Essentially, there is no option to specify a different memory
+type (e.g., write-back, write-combining, write-through; etc.) and consequently
+to weaken, or strengthen, the memory model.
+
+Other limitations are:
+
+* The LSUnit does not know when store-to-load forwarding may occur.
+* The LSUnit does not know anything about cache hierarchy and memory types.
+* The LSUnit does not know how to identify serializing operations and memory
+  fences.
+
+The LSUnit does not attempt to predict if a load or store hits or misses the L1
+cache.  It only knows if an instruction "MayLoad" and/or "MayStore."  For
+loads, the scheduling model provides an "optimistic" load-to-use latency (which
+usually matches the load-to-use latency for when there is a hit in the L1D).
+
+:program:`llvm-mca` does not know about serializing operations or memory-barrier
+like instructions.  The LSUnit conservatively assumes that an instruction which
+has both "MayLoad" and unmodeled side effects behaves like a "soft"
+load-barrier.  That means, it serializes loads without forcing a flush of the
+load queue.  Similarly, instructions that "MayStore" and have unmodeled side
+effects are treated like store barriers.  A full memory barrier is a "MayLoad"
+and "MayStore" instruction with unmodeled side effects.  This is inaccurate, but
+it is the best that we can do at the moment with the current information
+available in LLVM.
+
+A load/store barrier consumes one entry of the load/store queue.  A load/store
+barrier enforces ordering of loads/stores.  A younger load cannot pass a load
+barrier.  Also, a younger store cannot pass a store barrier.  A younger load
+has to wait for the memory/load barrier to execute.  A load/store barrier is
+"executed" when it becomes the oldest entry in the load/store queue(s). That
+also means, by construction, all of the older loads/stores have been executed.
+
+In conclusion, the full set of load/store consistency rules are:
+
+#. A store may not pass a previous store.
+#. A store may not pass a previous load (regardless of ``-noalias``).
+#. A store has to wait until an older store barrier is fully executed.
+#. A load may pass a previous load.
+#. A load may not pass a previous store unless ``-noalias`` is set.
+#. A load has to wait until an older load barrier is fully executed.

Added: www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-nm.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-nm.rst.txt?rev=368037&view=auto
==============================================================================
--- www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-nm.rst.txt (added)
+++ www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-nm.rst.txt Tue Aug  6 06:51:02 2019
@@ -0,0 +1,152 @@
+llvm-nm - list LLVM bitcode and object file's symbol table
+==========================================================
+
+SYNOPSIS
+--------
+
+:program:`llvm-nm` [*options*] [*filenames...*]
+
+DESCRIPTION
+-----------
+
+The :program:`llvm-nm` utility lists the names of symbols from the LLVM bitcode
+files, object files, or :program:`ar` archives containing them, named on the
+command line.  Each symbol is listed along with some simple information about
+its provenance.  If no file name is specified, or *-* is used as a file name,
+:program:`llvm-nm` will process a file on its standard input stream.
+
+:program:`llvm-nm`'s default output format is the traditional BSD :program:`nm`
+output format.  Each such output record consists of an (optional) 8-digit
+hexadecimal address, followed by a type code character, followed by a name, for
+each symbol.  One record is printed per line; fields are separated by spaces.
+When the address is omitted, it is replaced by 8 spaces.
+
+Type code characters currently supported, and their meanings, are as follows:
+
+U
+
+ Named object is referenced but undefined in this bitcode file
+
+C
+
+ Common (multiple definitions link together into one def)
+
+W
+
+ Weak reference (multiple definitions link together into zero or one definitions)
+
+t
+
+ Local function (text) object
+
+T
+
+ Global function (text) object
+
+d
+
+ Local data object
+
+D
+
+ Global data object
+
+?
+
+ Something unrecognizable
+
+Because LLVM bitcode files typically contain objects that are not considered to
+have addresses until they are linked into an executable image or dynamically
+compiled "just-in-time", :program:`llvm-nm` does not print an address for any
+symbol in an LLVM bitcode file, even symbols which are defined in the bitcode
+file.
+
+OPTIONS
+-------
+
+.. program:: llvm-nm
+
+.. option:: -B    (default)
+
+ Use BSD output format.  Alias for `--format=bsd`.
+
+.. option:: -P
+
+ Use POSIX.2 output format.  Alias for `--format=posix`.
+
+.. option:: --debug-syms, -a
+
+ Show all symbols, even debugger only.
+
+.. option:: --defined-only
+
+ Print only symbols defined in this file (as opposed to
+ symbols which may be referenced by objects in this file, but not
+ defined in this file.)
+
+.. option:: --dynamic, -D
+
+ Display dynamic symbols instead of normal symbols.
+
+.. option:: --extern-only, -g
+
+ Print only symbols whose definitions are external; that is, accessible
+ from other files.
+
+.. option:: --no-weak, -W
+
+ Don't print any weak symbols in the output.
+
+.. option:: --format=format, -f format
+
+ Select an output format; *format* may be *sysv*, *posix*, or *bsd*.  The default
+ is *bsd*.
+
+.. option:: -help
+
+ Print a summary of command-line options and their meanings.
+
+.. option:: --no-sort, -p
+
+ Shows symbols in order encountered.
+
+.. option:: --numeric-sort, -n, -v
+
+ Sort symbols by address.
+
+.. option:: --print-file-name, -A, -o
+
+ Precede each symbol with the file it came from.
+
+.. option:: --print-size, -S
+
+ Show symbol size instead of address.
+
+.. option:: --size-sort
+
+ Sort symbols by size.
+
+.. option:: --undefined-only, -u
+
+ Print only symbols referenced but not defined in this file.
+
+.. option:: --radix=RADIX, -t
+
+ Specify the radix of the symbol address(es). Values accepted d(decimal),
+ x(hexadecomal) and o(octal).
+
+BUGS
+----
+
+ * :program:`llvm-nm` does not support the full set of arguments that GNU
+   :program:`nm` does.
+
+EXIT STATUS
+-----------
+
+:program:`llvm-nm` exits with an exit code of zero.
+
+SEE ALSO
+--------
+
+llvm-dis, ar(1), nm(1)

Added: www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-objcopy.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-objcopy.rst.txt?rev=368037&view=auto
==============================================================================
--- www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-objcopy.rst.txt (added)
+++ www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-objcopy.rst.txt Tue Aug  6 06:51:02 2019
@@ -0,0 +1,497 @@
+llvm-objcopy - object copying and editing tool
+==============================================
+
+.. program:: llvm-objcopy
+
+SYNOPSIS
+--------
+
+:program:`llvm-objcopy` [*options*] *input* [*output*]
+
+DESCRIPTION
+-----------
+
+:program:`llvm-objcopy` is a tool to copy and manipulate objects. In basic
+usage, it makes a semantic copy of the input to the output. If any options are
+specified, the output may be modified along the way, e.g. by removing sections.
+
+If no output file is specified, the input file is modified in-place. If "-" is
+specified for the input file, the input is read from the program's standard
+input stream. If "-" is specified for the output file, the output is written to
+the standard output stream of the program.
+
+If the input is an archive, any requested operations will be applied to each
+archive member individually.
+
+The tool is still in active development, but in most scenarios it works as a
+drop-in replacement for GNU's :program:`objcopy`.
+
+GENERIC AND CROSS-PLATFORM OPTIONS
+----------------------------------
+
+The following options are either agnostic of the file format, or apply to
+multiple file formats.
+
+.. option:: --add-gnu-debuglink <debug-file>
+
+ Add a .gnu_debuglink section for ``<debug-file>`` to the output.
+
+.. option:: --disable-deterministic-archives, -U
+
+ Use real values for UIDs, GIDs and timestamps when updating archive member
+ headers.
+
+.. option:: --discard-all, -x
+
+ Remove most local symbols from the output. Different file formats may limit
+ this to a subset of the local symbols. For example, file and section symbols in
+ ELF objects will not be discarded.
+
+.. option:: --enable-deterministic-archives, -D
+
+ Enable deterministic mode when copying archives, i.e. use 0 for archive member
+ header UIDs, GIDs and timestamp fields. On by default.
+
+.. option:: --help, -h
+
+ Print a summary of command line options.
+
+.. option:: --only-section <section>, -j
+
+ Remove all sections from the output, except for sections named ``<section>``.
+ Can be specified multiple times to keep multiple sections.
+
+.. option:: --regex
+
+ If specified, symbol and section names specified by other switches are treated
+ as extended POSIX regular expression patterns.
+
+.. option:: --remove-section <section>, -R
+
+ Remove the specified section from the output. Can be specified multiple times
+ to remove multiple sections simultaneously.
+
+.. option:: --strip-all-gnu
+
+ Remove all symbols, debug sections and relocations from the output. This option
+ is equivalent to GNU :program:`objcopy`'s ``--strip-all`` switch.
+
+.. option:: --strip-all, -S
+
+ For ELF objects, remove from the output all symbols and non-alloc sections not
+ within segments, except for .gnu.warning sections and the section name table.
+
+ For COFF objects, remove all symbols, debug sections, and relocations from the
+ output.
+
+.. option:: --strip-debug, -g
+
+ Remove all debug sections from the output.
+
+.. option:: --strip-symbol <symbol>, -N
+
+ Remove all symbols named ``<symbol>`` from the output. Can be specified
+ multiple times to remove multiple symbols.
+
+.. option:: --strip-symbols <filename>
+
+ Remove all symbols whose names appear in the file ``<filename>``, from the
+ output. In the file, each line represents a single symbol name, with leading
+ and trailing whitespace ignored, as is anything following a '#'. Can be
+ specified multiple times to read names from multiple files.
+
+.. option:: --strip-unneeded-symbol <symbol>
+
+ Remove from the output all symbols named ``<symbol>`` that are local or
+ undefined and are not required by any relocation.
+
+.. option:: --strip-unneeded-symbols <filename>
+
+ Remove all symbols whose names appear in the file ``<filename>``, from the
+ output, if they are local or undefined and are not required by any relocation.
+ In the file, each line represents a single symbol name, with leading and
+ trailing whitespace ignored, as is anything following a '#'. Can be specified
+ multiple times to read names from multiple files.
+
+.. option:: --strip-unneeded
+
+ Remove from the output all local or undefined symbols that are not required by
+ relocations.
+
+.. option:: --version, -V
+
+  Display the version of this program.
+
+COFF-SPECIFIC OPTIONS
+---------------------
+
+The following options are implemented only for COFF objects. If used with other
+objects, :program:`llvm-objcopy` will either emit an error or silently ignore
+them.
+
+.. option:: --only-keep-debug
+
+ Remove the contents of non-debug sections from the output, but keep the section
+ headers.
+
+ELF-SPECIFIC OPTIONS
+--------------------
+
+The following options are implemented only for ELF objects. If used with other
+objects, :program:`llvm-objcopy` will either emit an error or silently ignore
+them.
+
+.. option:: --add-section <section=file>
+
+ Add a section named ``<section>`` with the contents of ``<file>`` to the
+ output. The section will be of type `SHT_NOTE`, if the name starts with
+ ".note". Otherwise, it will have type `SHT_PROGBITS`. Can be specified multiple
+ times to add multiple sections.
+
+.. option:: --add-symbol <name>=[<section>:]<value>[,<flags>]
+
+ Add a new symbol called ``<name>`` to the output symbol table, in the section
+ named ``<section>``, with value ``<value>``. If ``<section>`` is not specified,
+ the symbol is added as an absolute symbol. The ``<flags>`` affect the symbol
+ properties. Accepted values are:
+
+ - `global` = the symbol will have global binding.
+ - `local` = the symbol will have local binding.
+ - `weak` = the symbol will have weak binding.
+ - `default` = the symbol will have default visibility.
+ - `hidden` = the symbol will have hidden visibility.
+ - `file` = the symbol will be an `STT_FILE` symbol.
+ - `section` = the symbol will be an `STT_SECTION` symbol.
+ - `object` = the symbol will be an `STT_OBJECT` symbol.
+ - `function` = the symbol will be an `STT_FUNC` symbol.
+ - `indirect-function` = the symbol will be an `STT_GNU_IFUNC` symbol.
+
+ Additionally, the following flags are accepted but ignored: `debug`,
+ `constructor`, `warning`, `indirect`, `synthetic`, `unique-object`, `before`.
+
+ Can be specified multiple times to add multiple symbols.
+
+.. option:: --allow-broken-links
+
+ Allow llvm-objcopy to remove sections even if it would leave invalid section
+ references. Any invalid sh_link fields will be set to zero.
+
+.. option:: --binary-architecture <arch>, -B
+
+ Specify the architecture to use, when transforming an architecture-less format
+ (e.g. binary) to another format. Valid options are:
+
+ - `aarch64`
+ - `arm`
+ - `i386`
+ - `i386:x86-64`
+ - `mips`
+ - `powerpc:common64`
+ - `riscv:rv32`
+ - `riscv:rv64`
+ - `sparc`
+ - `sparcel`
+ - `x86-64`
+
+.. option:: --build-id-link-dir <dir>
+
+ Set the directory used by :option:`--build-id-link-input` and
+ :option:`--build-id-link-output`.
+
+.. option:: --build-id-link-input <suffix>
+
+ Hard-link the input to ``<dir>/xx/xxx<suffix>``, where ``<dir>`` is the directory
+ specified by :option:`--build-id-link-dir`. The path used is derived from the
+ hex build ID.
+
+.. option:: --build-id-link-output <suffix>
+
+ Hard-link the output to ``<dir>/xx/xxx<suffix>``, where ``<dir>`` is the directory
+ specified by :option:`--build-id-link-dir`. The path used is derived from the
+ hex build ID.
+
+.. option:: --change-start <incr>, --adjust-start
+
+ Add ``<incr>`` to the program's start address. Can be specified multiple
+ times, in which case the values will be applied cumulatively.
+
+.. option:: --compress-debug-sections [<style>]
+
+ Compress DWARF debug sections in the output, using the specified style.
+ Supported styles are `zlib-gnu` and `zlib`. Defaults to `zlib` if no style is
+ specified.
+
+.. option:: --decompress-debug-sections
+
+ Decompress any compressed DWARF debug sections in the output.
+
+.. option:: --discard-locals, -X
+
+ Remove local symbols starting with ".L" from the output.
+
+.. option:: --dump-section <section>=<file>
+
+ Dump the contents of section ``<section>`` into the file ``<file>``. Can be
+ specified multiple times to dump multiple sections to different files.
+ ``<file>`` is unrelated to the input and output files provided to
+ :program:`llvm-objcopy` and as such the normal copying and editing
+ operations will still be performed. No operations are performed on the sections
+ prior to dumping them.
+
+.. option:: --extract-dwo
+
+ Remove all sections that are not DWARF .dwo sections from the output.
+
+.. option:: --extract-main-partition
+
+ Extract the main partition from the output.
+
+.. option:: --extract-partition <name>
+
+ Extract the named partition from the output.
+
+.. option:: --globalize-symbol <symbol>
+
+ Mark any defined symbols named ``<symbol>`` as global symbols in the output.
+ Can be specified multiple times to mark multiple symbols.
+
+.. option:: --globalize-symbols <filename>
+
+ Read a list of names from the file ``<filename>`` and mark defined symbols with
+ those names as global in the output. In the file, each line represents a single
+ symbol, with leading and trailing whitespace ignored, as is anything following
+ a '#'. Can be specified multiple times to read names from multiple files.
+
+.. option:: --input-target <format>, -I
+
+ Read the input as the specified format. See `SUPPORTED FORMATS`_ for a list of
+ valid ``<format>`` values. If unspecified, :program:`llvm-objcopy` will attempt
+ to determine the format automatically.
+
+.. option:: --keep-file-symbols
+
+ Keep symbols of type `STT_FILE`, even if they would otherwise be stripped.
+
+.. option:: --keep-global-symbol <symbol>
+
+ Make all symbols local in the output, except for symbols with the name
+ ``<symbol>``. Can be specified multiple times to ignore multiple symbols.
+
+.. option:: --keep-global-symbols <filename>
+
+ Make all symbols local in the output, except for symbols named in the file
+ ``<filename>``. In the file, each line represents a single symbol, with leading
+ and trailing whitespace ignored, as is anything following a '#'. Can be
+ specified multiple times to read names from multiple files.
+
+.. option:: --keep-section <section>
+
+ When removing sections from the output, do not remove sections named
+ ``<section>``. Can be specified multiple times to keep multiple sections.
+
+.. option:: --keep-symbol <symbol>, -K
+
+ When removing symbols from the output, do not remove symbols named
+ ``<symbol>``. Can be specified multiple times to keep multiple symbols.
+
+.. option:: --keep-symbols <filename>
+
+ When removing symbols from the output do not remove symbols named in the file
+ ``<filename>``. In the file, each line represents a single symbol, with leading
+ and trailing whitespace ignored, as is anything following a '#'. Can be
+ specified multiple times to read names from multiple files.
+
+.. option:: --localize-hidden
+
+ Make all symbols with hidden or internal visibility local in the output.
+
+.. option:: --localize-symbol <symbol>, -L
+
+ Mark any defined non-common symbol named ``<symbol>`` as a local symbol in the
+ output. Can be specified multiple times to mark multiple symbols as local.
+
+.. option:: --localize-symbols <filename>
+
+ Read a list of names from the file ``<filename>`` and mark defined non-common
+ symbols with those names as local in the output. In the file, each line
+ represents a single symbol, with leading and trailing whitespace ignored, as is
+ anything following a '#'. Can be specified multiple times to read names from
+ multiple files.
+
+.. option:: --output-target <format>, -O
+
+ Write the output as the specified format. See `SUPPORTED FORMATS`_ for a list
+ of valid ``<format>`` values. If unspecified, the output format is assumed to
+ be the same as the input file's format.
+
+.. option:: --prefix-alloc-sections <prefix>
+
+ Add ``<prefix>`` to the front of the names of all allocatable sections in the
+ output.
+
+.. option:: --prefix-symbols <prefix>
+
+ Add ``<prefix>`` to the front of every symbol name in the output.
+
+.. option:: --preserve-dates, -p
+
+ Preserve access and modification timestamps in the output.
+
+.. option:: --redefine-sym <old>=<new>
+
+ Rename symbols called ``<old>`` to ``<new>`` in the output. Can be specified
+ multiple times to rename multiple symbols.
+
+.. option:: --redefine-syms <filename>
+
+ Rename symbols in the output as described in the file ``<filename>``. In the
+ file, each line represents a single symbol to rename, with the old name and new
+ name separated by an equals sign. Leading and trailing whitespace is ignored,
+ as is anything following a '#'. Can be specified multiple times to read names
+ from multiple files.
+
+.. option:: --rename-section <old>=<new>[,<flag>,...]
+
+ Rename sections called ``<old>`` to ``<new>`` in the output, and apply any
+ specified ``<flag>`` values. See :option:`--set-section-flags` for a list of
+ supported flags. Can be specified multiple times to rename multiple sections.
+
+.. option:: --set-section-flags <section>=<flag>[,<flag>,...]
+
+ Set section properties in the output of section ``<section>`` based on the
+ specified ``<flag>`` values. Can be specified multiple times to update multiple
+ sections.
+
+ Following is a list of supported flags and their effects:
+
+ - `alloc` = add the `SHF_ALLOC` flag.
+ - `load` = if the section has `SHT_NOBITS` type, mark it as a `SHT_PROGBITS`
+   section.
+ - `readonly` = if this flag is not specified, add the `SHF_WRITE` flag.
+ - `code` = add the `SHF_EXECINSTR` flag.
+ - `merge` = add the `SHF_MERGE` flag.
+ - `strings` = add the `SHF_STRINGS` flag.
+ - `contents` = if the section has `SHT_NOBITS` type, mark it as a `SHT_PROGBITS`
+   section.
+
+ The following flags are also accepted, but are ignored for GNU compatibility:
+ `noload`, `debug`, `data`, `rom`, `share`.
+
+.. option:: --set-start-addr <addr>
+
+ Set the start address of the output to ``<addr>``. Overrides any previously
+ specified :option:`--change-start` or :option:`--adjust-start` options.
+
+.. option:: --split-dwo <dwo-file>
+
+ Equivalent to running :program:`llvm-objcopy` with :option:`--extract-dwo` and
+ ``<dwo-file>`` as the output file and no other options, and then with
+ :option:`--strip-dwo` on the input file.
+
+.. option:: --strip-dwo
+
+ Remove all DWARF .dwo sections from the output.
+
+.. option:: --strip-non-alloc
+
+ Remove from the output all non-allocatable sections that are not within
+ segments.
+
+.. option:: --strip-sections
+
+ Remove from the output all section headers and all section data not within
+ segments. Note that many tools will not be able to use an object without
+ section headers.
+
+.. option:: --target <format>, -F
+
+ Equivalent to :option:`--input-target` and :option:`--output-target` for the
+ specified format. See `SUPPORTED FORMATS`_ for a list of valid ``<format>``
+ values.
+
+.. option:: --weaken-symbol <symbol>, -W
+
+ Mark any global symbol named ``<symbol>`` as a weak symbol in the output. Can
+ be specified multiple times to mark multiple symbols as weak.
+
+.. option:: --weaken-symbols <filename>
+
+ Read a list of names from the file ``<filename>`` and mark global symbols with
+ those names as weak in the output. In the file, each line represents a single
+ symbol, with leading and trailing whitespace ignored, as is anything following
+ a '#'. Can be specified multiple times to read names from multiple files.
+
+.. option:: --weaken
+
+ Mark all defined global symbols as weak in the output.
+
+SUPPORTED FORMATS
+-----------------
+
+The following values are currently supported by :program:`llvm-objcopy` for the
+:option:`--input-target`, :option:`--output-target`, and :option:`--target`
+options. For GNU :program:`objcopy` compatibility, the values are all bfdnames.
+
+- `binary`
+- `ihex`
+- `elf32-i386`
+- `elf32-x86-64`
+- `elf64-x86-64`
+- `elf32-iamcu`
+- `elf32-littlearm`
+- `elf64-aarch64`
+- `elf64-littleaarch64`
+- `elf32-littleriscv`
+- `elf64-littleriscv`
+- `elf32-powerpc`
+- `elf32-powerpcle`
+- `elf64-powerpc`
+- `elf64-powerpcle`
+- `elf32-bigmips`
+- `elf32-ntradbigmips`
+- `elf32-ntradlittlemips`
+- `elf32-tradbigmips`
+- `elf32-tradlittlemips`
+- `elf64-tradbigmips`
+- `elf64-tradlittlemips`
+- `elf32-sparc`
+- `elf32-sparcel`
+
+Additionally, all targets except `binary` and `ihex` can have `-freebsd` as a
+suffix.
+
+BINARY INPUT AND OUTPUT
+-----------------------
+
+If `binary` is used as the value for :option:`--input-target`, the input file
+will be embedded as a data section in an ELF relocatable object, with symbols
+``_binary_<file_name>_start``, ``_binary_<file_name>_end``, and
+``_binary_<file_name>_size`` representing the start, end and size of the data,
+where ``<file_name>`` is the path of the input file as specified on the command
+line with non-alphanumeric characters converted to ``_``.
+
+If `binary` is used as the value for :option:`--output-target`, the output file
+will be a raw binary file, containing the memory image of the input file.
+Symbols and relocation information will be discarded. The image will start at
+the address of the first loadable section in the output.
+
+EXIT STATUS
+-----------
+
+:program:`llvm-objcopy` exits with a non-zero exit code if there is an error.
+Otherwise, it exits with code 0.
+
+BUGS
+----
+
+To report bugs, please visit <http://llvm.org/bugs/>.
+
+There is a known issue with :option:`--input-target` and :option:`--target`
+causing only ``binary`` and ``ihex`` formats to have any effect. Other values
+will be ignored and :program:`llvm-objcopy` will attempt to guess the input
+format.
+
+SEE ALSO
+--------
+
+:manpage:`llvm-strip(1)`

Added: www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-objdump.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-objdump.rst.txt?rev=368037&view=auto
==============================================================================
--- www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-objdump.rst.txt (added)
+++ www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-objdump.rst.txt Tue Aug  6 06:51:02 2019
@@ -0,0 +1,123 @@
+llvm-objdump - LLVM's object file dumper
+========================================
+
+SYNOPSIS
+--------
+
+:program:`llvm-objdump` [*commands*] [*options*] [*filenames...*]
+
+DESCRIPTION
+-----------
+The :program:`llvm-objdump` utility prints the contents of object files and
+final linked images named on the command line. If no file name is specified,
+:program:`llvm-objdump` will attempt to read from *a.out*. If *-* is used as a
+file name, :program:`llvm-objdump` will process a file on its standard input
+stream.
+
+COMMANDS
+--------
+At least one of the following commands are required, and some commands can be
+combined with other commands:
+
+.. option:: -d, -disassemble
+
+  Display assembler mnemonics for the machine instructions. Disassembles all
+  text sections found in the input file(s).
+
+.. option:: -D, -disassemble-all
+
+  Display assembler mnemonics for the machine instructions. Disassembles all
+  sections found in the input file(s).
+
+.. option:: -help
+
+  Display usage information and exit. Does not stack with other commands.
+
+.. option:: -r
+
+  Display the relocation entries in the file.
+
+.. option:: -s
+
+  Display the content of each section.
+
+.. option:: -section-headers
+
+  Display summaries of the headers for each section.
+
+.. option:: -t
+
+  Display the symbol table.
+
+.. option:: -version
+
+  Display the version of this program. Does not stack with other commands.
+
+OPTIONS
+-------
+:program:`llvm-objdump` supports the following options:
+
+.. option:: -arch=<architecture>
+
+  Specify the architecture to disassemble. see ``-version`` for available
+  architectures.
+
+.. option:: -cfg
+
+  Create a CFG for every symbol in the object file and write it to a graphviz
+  file (Mach-O-only).
+
+.. option:: -dsym=<string>
+
+  Use .dSYM file for debug info.
+
+.. option:: -g
+
+  Print line information from debug info if available.
+
+.. option:: -m, -macho
+
+  Use Mach-O specific object file parser. Commands and other options may behave
+  differently when used with ``-macho``.
+
+.. option:: -mattr=<a1,+a2,-a3,...>
+
+  Target specific attributes.
+
+.. option:: -mc-x86-disable-arith-relaxation
+
+  Disable relaxation of arithmetic instruction for X86.
+
+.. option:: -stats
+
+  Enable statistics output from program.
+
+.. option:: -triple=<string>
+
+  Target triple to disassemble for, see ``-version`` for available targets.
+
+.. option:: -x86-asm-syntax=<style>
+
+  When used with the ``-disassemble`` option, choose style of code to emit from
+  X86 backend. Supported values are:
+
+   .. option:: att
+
+    AT&T-style assembly
+
+   .. option:: intel
+
+    Intel-style assembly
+
+
+  The default disassembly style is **att**.
+
+BUGS
+----
+
+To report bugs, please visit <http://llvm.org/bugs/>.
+
+SEE ALSO
+--------
+
+:manpage:`llvm-nm(1)`

Added: www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-pdbutil.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-pdbutil.rst.txt?rev=368037&view=auto
==============================================================================
--- www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-pdbutil.rst.txt (added)
+++ www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-pdbutil.rst.txt Tue Aug  6 06:51:02 2019
@@ -0,0 +1,585 @@
+llvm-pdbutil - PDB File forensics and diagnostics
+=================================================
+
+.. contents::
+   :local:
+
+Synopsis
+--------
+
+:program:`llvm-pdbutil` [*subcommand*] [*options*]
+
+Description
+-----------
+
+Display types, symbols, CodeView records, and other information from a
+PDB file, as well as manipulate and create PDB files.  :program:`llvm-pdbutil`
+is normally used by FileCheck-based tests to test LLVM's PDB reading and
+writing functionality, but can also be used for general PDB file investigation
+and forensics, or as a replacement for cvdump.
+
+Subcommands
+-----------
+
+:program:`llvm-pdbutil` is separated into several subcommands each tailored to
+a different purpose.  A brief summary of each command follows, with more detail
+in the sections that follow.
+
+  * :ref:`pretty_subcommand` - Dump symbol and type information in a format that
+    tries to look as much like the original source code as possible.
+  * :ref:`dump_subcommand` - Dump low level types and structures from the PDB
+    file, including CodeView records, hash tables, PDB streams, etc.
+  * :ref:`bytes_subcommand` - Dump data from the PDB file's streams, records,
+    types, symbols, etc as raw bytes.
+  * :ref:`yaml2pdb_subcommand` - Given a yaml description of a PDB file, produce
+    a valid PDB file that matches that description.
+  * :ref:`pdb2yaml_subcommand` - For a given PDB file, produce a YAML
+    description of some or all of the file in a way that the PDB can be
+    reconstructed.
+  * :ref:`merge_subcommand` - Given two PDBs, produce a third PDB that is the
+    result of merging the two input PDBs.
+
+.. _pretty_subcommand:
+
+pretty
+~~~~~~
+
+.. program:: llvm-pdbutil pretty
+
+.. important::
+   The **pretty** subcommand is built on the Windows DIA SDK, and as such is not
+   supported on non-Windows platforms.
+
+USAGE: :program:`llvm-pdbutil` pretty [*options*] <input PDB file>
+
+Summary
+^^^^^^^^^^^
+
+The *pretty* subcommand displays a very high level representation of your
+program's debug info.  Since it is built on the Windows DIA SDK which is the
+standard API that Windows tools and debuggers query debug information, it
+presents a more authoritative view of how a debugger is going to interpret your
+debug information than a mode which displays low-level CodeView records.
+
+Options
+^^^^^^^
+
+Filtering and Sorting Options
++++++++++++++++++++++++++++++
+
+.. note::
+   *exclude* filters take priority over *include* filters.  So if a filter
+   matches both an include and an exclude rule, then it is excluded.
+
+.. option:: -exclude-compilands=<string>
+
+ When dumping compilands, compiland source-file contributions, or per-compiland
+ symbols, this option instructs **llvm-pdbutil** to omit any compilands that
+ match the specified regular expression.
+
+.. option:: -exclude-symbols=<string>
+
+ When dumping global, public, or per-compiland symbols, this option instructs
+ **llvm-pdbutil** to omit any symbols that match the specified regular
+ expression.
+
+.. option:: -exclude-types=<string>
+
+ When dumping types, this option instructs **llvm-pdbutil** to omit any types
+ that match the specified regular expression.
+
+.. option:: -include-compilands=<string>
+
+ When dumping compilands, compiland source-file contributions, or per-compiland
+ symbols, limit the initial search to only those compilands that match the
+ specified regular expression.
+
+.. option:: -include-symbols=<string>
+
+ When dumping global, public, or per-compiland symbols, limit the initial
+ search to only those symbols that match the specified regular expression.
+
+.. option:: -include-types=<string>
+
+ When dumping types, limit the initial search to only those types that match
+ the specified regular expression.
+
+.. option:: -min-class-padding=<uint>
+
+ Only display types that have at least the specified amount of alignment
+ padding, accounting for padding in base classes and aggregate field members.
+
+.. option:: -min-class-padding-imm=<uint>
+
+ Only display types that have at least the specified amount of alignment
+ padding, ignoring padding in base classes and aggregate field members.
+
+.. option:: -min-type-size=<uint>
+
+ Only display types T where sizeof(T) is greater than or equal to the specified
+ amount.
+
+.. option:: -no-compiler-generated
+
+ Don't show compiler generated types and symbols
+
+.. option:: -no-enum-definitions
+
+ When dumping an enum, don't show the full enum (e.g. the individual enumerator
+ values).
+
+.. option:: -no-system-libs
+
+ Don't show symbols from system libraries
+
+Symbol Type Options
++++++++++++++++++++
+.. option:: -all
+
+ Implies all other options in this category.
+
+.. option:: -class-definitions=<format>
+
+ Displays class definitions in the specified format.
+
+ .. code-block:: text
+
+    =all      - Display all class members including data, constants, typedefs, functions, etc (default)
+    =layout   - Only display members that contribute to class size.
+    =none     - Don't display class definitions (e.g. only display the name and base list)
+
+.. option:: -class-order
+
+ Displays classes in the specified order.
+
+ .. code-block:: text
+
+    =none            - Undefined / no particular sort order (default)
+    =name            - Sort classes by name
+    =size            - Sort classes by size
+    =padding         - Sort classes by amount of padding
+    =padding-pct     - Sort classes by percentage of space consumed by padding
+    =padding-imm     - Sort classes by amount of immediate padding
+    =padding-pct-imm - Sort classes by percentage of space consumed by immediate padding
+
+.. option::  -class-recurse-depth=<uint>
+
+ When dumping class definitions, stop after recursing the specified number of times.  The
+ default is 0, which is no limit.
+
+.. option::  -classes
+
+ Display classes
+
+.. option::  -compilands
+
+ Display compilands (e.g. object files)
+
+.. option::  -enums
+
+ Display enums
+
+.. option::  -externals
+
+ Dump external (e.g. exported) symbols
+
+.. option::  -globals
+
+ Dump global symbols
+
+.. option::  -lines
+
+ Dump the mappings between source lines and code addresses.
+
+.. option::  -module-syms
+
+ Display symbols (variables, functions, etc) for each compiland
+
+.. option::  -sym-types=<types>
+
+ Type of symbols to dump when -globals, -externals, or -module-syms is
+ specified. (default all)
+
+ .. code-block:: text
+
+    =thunks - Display thunk symbols
+    =data   - Display data symbols
+    =funcs  - Display function symbols
+    =all    - Display all symbols (default)
+
+.. option::  -symbol-order=<order>
+
+ For symbols dumped via the -module-syms, -globals, or -externals options, sort
+ the results in specified order.
+
+ .. code-block:: text
+
+    =none - Undefined / no particular sort order
+    =name - Sort symbols by name
+    =size - Sort symbols by size
+
+.. option::  -typedefs
+
+ Display typedef types
+
+.. option::  -types
+
+ Display all types (implies -classes, -enums, -typedefs)
+
+Other Options
++++++++++++++
+
+.. option:: -color-output
+
+ Force color output on or off.  By default, color if used if outputting to a
+ terminal.
+
+.. option:: -load-address=<uint>
+
+ When displaying relative virtual addresses, assume the process is loaded at the
+ given address and display what would be the absolute address.
+
+.. _dump_subcommand:
+
+dump
+~~~~
+
+USAGE: :program:`llvm-pdbutil` dump [*options*] <input PDB file>
+
+.. program:: llvm-pdbutil dump
+
+Summary
+^^^^^^^^^^^
+
+The **dump** subcommand displays low level information about the structure of a
+PDB file.  It is used heavily by LLVM's testing infrastructure, but can also be
+used for PDB forensics.  It serves a role similar to that of Microsoft's
+`cvdump` tool.
+
+.. note::
+   The **dump** subcommand exposes internal details of the file format.  As
+   such, the reader should be familiar with :doc:`/PDB/index` before using this
+   command.
+
+Options
+^^^^^^^
+
+MSF Container Options
++++++++++++++++++++++
+
+.. option:: -streams
+
+ dump a summary of all of the streams in the PDB file.
+
+.. option:: -stream-blocks
+
+ In conjunction with :option:`-streams`, add information to the output about
+ what blocks the specified stream occupies.
+
+.. option:: -summary
+
+ Dump MSF and PDB header information.
+
+Module & File Options
++++++++++++++++++++++
+
+.. option:: -modi=<uint>
+
+ For all options that dump information from each module/compiland, limit to
+ the specified module.
+
+.. option:: -files
+
+ Dump the source files that contribute to each displayed module.
+
+.. option:: -il
+
+ Dump inlinee line information (DEBUG_S_INLINEELINES CodeView subsection)
+
+.. option:: -l
+
+ Dump line information (DEBUG_S_LINES CodeView subsection)
+
+.. option:: -modules
+
+ Dump compiland information
+
+.. option:: -xme
+
+ Dump cross module exports (DEBUG_S_CROSSSCOPEEXPORTS CodeView subsection)
+
+.. option:: -xmi
+
+ Dump cross module imports (DEBUG_S_CROSSSCOPEIMPORTS CodeView subsection)
+
+Symbol Options
+++++++++++++++
+
+.. option:: -globals
+
+ dump global symbol records
+
+.. option:: -global-extras
+
+ dump additional information about the globals, such as hash buckets and hash
+ values.
+
+.. option:: -publics
+
+ dump public symbol records
+
+.. option:: -public-extras
+
+ dump additional information about the publics, such as hash buckets and hash
+ values.
+
+.. option:: -symbols
+
+ dump symbols (functions, variables, etc) for each module dumped.
+
+.. option:: -sym-data
+
+ For each symbol record dumped as a result of the :option:`-symbols` option,
+ display the full bytes of the record in binary as well.
+
+Type Record Options
++++++++++++++++++++
+
+.. option:: -types
+
+ Dump CodeView type records from TPI stream
+
+.. option:: -type-extras
+
+ Dump additional information from the TPI stream, such as hashes and the type
+ index offsets array.
+
+.. option:: -type-data
+
+ For each type record dumped, display the full bytes of the record in binary as
+ well.
+
+.. option:: -type-index=<uint>
+
+ Only dump types with the specified type index.
+
+.. option:: -ids
+
+ Dump CodeView type records from IPI stream.
+
+.. option:: -id-extras
+
+ Dump additional information from the IPI stream, such as hashes and the type
+ index offsets array.
+
+.. option:: -id-data
+
+ For each ID record dumped, display the full bytes of the record in binary as
+ well.
+
+.. option:: -id-index=<uint>
+
+ only dump ID records with the specified hexadecimal type index.
+
+.. option:: -dependents
+
+ When used in conjunction with :option:`-type-index` or :option:`-id-index`,
+ dumps the entire dependency graph for the specified index instead of just the
+ single record with the specified index.  For example, if type index 0x4000 is
+ a function whose return type has index 0x3000, and you specify
+ `-dependents=0x4000`, then this would dump both records (as well as any other
+ dependents in the tree).
+
+Miscellaneous Options
++++++++++++++++++++++
+
+.. option:: -all
+
+ Implies most other options.
+
+.. option:: -section-contribs
+
+ Dump section contributions.
+
+.. option:: -section-headers
+
+ Dump image section headers.
+
+.. option:: -section-map
+
+ Dump section map.
+
+.. option:: -string-table
+
+ Dump PDB string table.
+
+.. _bytes_subcommand:
+
+bytes
+~~~~~
+
+USAGE: :program:`llvm-pdbutil` bytes [*options*] <input PDB file>
+
+.. program:: llvm-pdbutil bytes
+
+Summary
+^^^^^^^
+
+Like the **dump** subcommand, the **bytes** subcommand displays low level
+information about the structure of a PDB file, but it is used for even deeper
+forensics.  The **bytes** subcommand finds various structures in a PDB file
+based on the command line options specified, and dumps them in hex.  Someone
+working on support for emitting PDBs would use this heavily, for example, to
+compare one PDB against another PDB to ensure byte-for-byte compatibility.  It
+is not enough to simply compare the bytes of an entire file, or an entire stream
+because it's perfectly fine for the same structure to exist at different
+locations in two different PDBs, and "finding" the structure is half the battle.
+
+Options
+^^^^^^^
+
+MSF File Options
+++++++++++++++++
+
+.. option:: -block-range=<start[-end]>
+
+ Dump binary data from specified range of MSF file blocks.
+
+.. option:: -byte-range=<start[-end]>
+
+ Dump binary data from specified range of bytes in the file.
+
+.. option:: -fpm
+
+ Dump the MSF free page map.
+
+.. option:: -stream-data=<string>
+
+ Dump binary data from the specified streams.  Format is SN[:Start][@Size].
+ For example, `-stream-data=7:3 at 12` dumps 12 bytes from stream 7, starting
+ at offset 3 in the stream.
+
+PDB Stream Options
+++++++++++++++++++
+
+.. option:: -name-map
+
+ Dump bytes of PDB Name Map
+
+DBI Stream Options
+++++++++++++++++++
+
+.. option:: -ec
+
+ Dump the edit and continue map substream of the DBI stream.
+
+.. option:: -files
+
+ Dump the file info substream of the DBI stream.
+
+.. option:: -modi
+
+ Dump the modi substream of the DBI stream.
+
+.. option:: -sc
+
+ Dump section contributions substream of the DBI stream.
+
+.. option:: -sm
+
+ Dump the section map from the DBI stream.
+
+.. option:: -type-server
+
+ Dump the type server map from the DBI stream.
+
+Module Options
+++++++++++++++
+
+.. option:: -mod=<uint>
+
+ Limit all options in this category to the specified module index.  By default,
+ options in this category will dump bytes from all modules.
+
+.. option:: -chunks
+
+ Dump the bytes of each module's C13 debug subsection.
+
+.. option:: -split-chunks
+
+ When specified with :option:`-chunks`, split the C13 debug subsection into a
+ separate chunk for each subsection type, and dump them separately.
+
+.. option:: -syms
+
+ Dump the symbol record substream from each module.
+
+Type Record Options
++++++++++++++++++++
+
+.. option:: -id=<uint>
+
+ Dump the record from the IPI stream with the given type index.
+
+.. option:: -type=<uint>
+
+ Dump the record from the TPI stream with the given type index.
+
+.. _pdb2yaml_subcommand:
+
+pdb2yaml
+~~~~~~~~
+
+USAGE: :program:`llvm-pdbutil` pdb2yaml [*options*] <input PDB file>
+
+.. program:: llvm-pdbutil pdb2yaml
+
+Summary
+^^^^^^^
+
+Options
+^^^^^^^
+
+.. _yaml2pdb_subcommand:
+
+yaml2pdb
+~~~~~~~~
+
+USAGE: :program:`llvm-pdbutil` yaml2pdb [*options*] <input YAML file>
+
+.. program:: llvm-pdbutil yaml2pdb
+
+Summary
+^^^^^^^
+
+Generate a PDB file from a YAML description.  The YAML syntax is not described
+here.  Instead, use :ref:`llvm-pdbutil pdb2yaml <pdb2yaml_subcommand>` and
+examine the output for an example starting point.
+
+Options
+^^^^^^^
+
+.. option:: -pdb=<file-name>
+
+Write the resulting PDB to the specified file.
+
+.. _merge_subcommand:
+
+merge
+~~~~~
+
+USAGE: :program:`llvm-pdbutil` merge [*options*] <input PDB file 1> <input PDB file 2>
+
+.. program:: llvm-pdbutil merge
+
+Summary
+^^^^^^^
+
+Merge two PDB files into a single file.
+
+Options
+^^^^^^^
+
+.. option:: -pdb=<file-name>
+
+Write the resulting PDB to the specified file.

Added: www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-profdata.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-profdata.rst.txt?rev=368037&view=auto
==============================================================================
--- www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-profdata.rst.txt (added)
+++ www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-profdata.rst.txt Tue Aug  6 06:51:02 2019
@@ -0,0 +1,233 @@
+llvm-profdata - Profile data tool
+=================================
+
+SYNOPSIS
+--------
+
+:program:`llvm-profdata` *command* [*args...*]
+
+DESCRIPTION
+-----------
+
+The :program:`llvm-profdata` tool is a small utility for working with profile
+data files.
+
+COMMANDS
+--------
+
+* :ref:`merge <profdata-merge>`
+* :ref:`show <profdata-show>`
+
+.. program:: llvm-profdata merge
+
+.. _profdata-merge:
+
+MERGE
+-----
+
+SYNOPSIS
+^^^^^^^^
+
+:program:`llvm-profdata merge` [*options*] [*filename...*]
+
+DESCRIPTION
+^^^^^^^^^^^
+
+:program:`llvm-profdata merge` takes several profile data files
+generated by PGO instrumentation and merges them together into a single
+indexed profile data file.
+
+By default profile data is merged without modification. This means that the
+relative importance of each input file is proportional to the number of samples
+or counts it contains. In general, the input from a longer training run will be
+interpreted as relatively more important than a shorter run. Depending on the
+nature of the training runs it may be useful to adjust the weight given to each
+input file by using the ``-weighted-input`` option.
+
+Profiles passed in via ``-weighted-input``, ``-input-files``, or via positional
+arguments are processed once for each time they are seen.
+
+
+OPTIONS
+^^^^^^^
+
+.. option:: -help
+
+ Print a summary of command line options.
+
+.. option:: -output=output, -o=output
+
+ Specify the output file name.  *Output* cannot be ``-`` as the resulting
+ indexed profile data can't be written to standard output.
+
+.. option:: -weighted-input=weight,filename
+
+ Specify an input file name along with a weight. The profile counts of the
+ supplied ``filename`` will be scaled (multiplied) by the supplied
+ ``weight``, where where ``weight`` is a decimal integer >= 1.
+ Input files specified without using this option are assigned a default
+ weight of 1. Examples are shown below.
+
+.. option:: -input-files=path, -f=path
+
+  Specify a file which contains a list of files to merge. The entries in this
+  file are newline-separated. Lines starting with '#' are skipped. Entries may
+  be of the form <filename> or <weight>,<filename>.
+
+.. option:: -remapping-file=path, -r=path
+
+  Specify a file which contains a remapping from symbol names in the input
+  profile to the symbol names that should be used in the output profile. The
+  file should consist of lines of the form ``<input-symbol> <output-symbol>``.
+  Blank lines and lines starting with ``#`` are skipped.
+
+  The :doc:`llvm-cxxmap <llvm-cxxmap>` tool can be used to generate the symbol
+  remapping file.
+
+.. option:: -instr (default)
+
+ Specify that the input profile is an instrumentation-based profile.
+
+.. option:: -sample
+
+ Specify that the input profile is a sample-based profile.
+ 
+ The format of the generated file can be generated in one of three ways:
+
+ .. option:: -binary (default)
+
+ Emit the profile using a binary encoding. For instrumentation-based profile
+ the output format is the indexed binary format. 
+
+ .. option:: -text
+
+ Emit the profile in text mode. This option can also be used with both
+ sample-based and instrumentation-based profile. When this option is used
+ the profile will be dumped in the text format that is parsable by the profile
+ reader.
+
+ .. option:: -gcc
+
+ Emit the profile using GCC's gcov format (Not yet supported).
+
+.. option:: -sparse[=true|false]
+
+ Do not emit function records with 0 execution count. Can only be used in
+ conjunction with -instr. Defaults to false, since it can inhibit compiler
+ optimization during PGO.
+
+.. option:: -num-threads=N, -j=N
+
+ Use N threads to perform profile merging. When N=0, llvm-profdata auto-detects
+ an appropriate number of threads to use. This is the default.
+
+EXAMPLES
+^^^^^^^^
+Basic Usage
++++++++++++
+Merge three profiles:
+
+::
+
+    llvm-profdata merge foo.profdata bar.profdata baz.profdata -output merged.profdata
+
+Weighted Input
+++++++++++++++
+The input file `foo.profdata` is especially important, multiply its counts by 10:
+
+::
+
+    llvm-profdata merge -weighted-input=10,foo.profdata bar.profdata baz.profdata -output merged.profdata
+
+Exactly equivalent to the previous invocation (explicit form; useful for programmatic invocation):
+
+::
+
+    llvm-profdata merge -weighted-input=10,foo.profdata -weighted-input=1,bar.profdata -weighted-input=1,baz.profdata -output merged.profdata
+
+.. program:: llvm-profdata show
+
+.. _profdata-show:
+
+SHOW
+----
+
+SYNOPSIS
+^^^^^^^^
+
+:program:`llvm-profdata show` [*options*] [*filename*]
+
+DESCRIPTION
+^^^^^^^^^^^
+
+:program:`llvm-profdata show` takes a profile data file and displays the
+information about the profile counters for this file and
+for any of the specified function(s).
+
+If *filename* is omitted or is ``-``, then **llvm-profdata show** reads its
+input from standard input.
+
+OPTIONS
+^^^^^^^
+
+.. option:: -all-functions
+
+ Print details for every function.
+
+.. option:: -counts
+
+ Print the counter values for the displayed functions.
+
+.. option:: -function=string
+
+ Print details for a function if the function's name contains the given string.
+
+.. option:: -help
+
+ Print a summary of command line options.
+
+.. option:: -output=output, -o=output
+
+ Specify the output file name.  If *output* is ``-`` or it isn't specified,
+ then the output is sent to standard output.
+
+.. option:: -instr (default)
+
+ Specify that the input profile is an instrumentation-based profile.
+
+.. option:: -text
+
+ Instruct the profile dumper to show profile counts in the text format of the
+ instrumentation-based profile data representation. By default, the profile
+ information is dumped in a more human readable form (also in text) with
+ annotations.
+
+.. option:: -topn=n
+
+ Instruct the profile dumper to show the top ``n`` functions with the
+ hottest basic blocks in the summary section. By default, the topn functions
+ are not dumped.
+
+.. option:: -sample
+
+ Specify that the input profile is a sample-based profile.
+
+.. option:: -memop-sizes
+
+ Show the profiled sizes of the memory intrinsic calls for shown functions.
+
+.. option:: -value-cutoff=n
+
+ Show only those functions whose max count values are greater or equal to ``n``.
+ By default, the value-cutoff is set to 0.
+
+.. option:: -list-below-cutoff
+
+ Only output names of functions whose max count value are below the cutoff
+ value.
+
+EXIT STATUS
+-----------
+
+:program:`llvm-profdata` returns 1 if the command is omitted or is invalid,
+if it cannot read input files, or if there is a mismatch between their data.

Added: www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-ranlib.md.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-ranlib.md.txt?rev=368037&view=auto
==============================================================================
--- www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-ranlib.md.txt (added)
+++ www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-ranlib.md.txt Tue Aug  6 06:51:02 2019
@@ -0,0 +1,17 @@
+# llvm-ranlib - generates an archive index
+
+## SYNOPSIS
+
+**llvm-ranlib** [*options*]
+
+## DESCRIPTION
+
+**llvm-ranlib** is an alias for the [llvm-ar](llvm-ar.html) tool that generates
+an index for an archive. It can be used as a replacement for GNU's **ranlib**
+tool.
+
+Running **llvm-ranlib** is equivalent to running **llvm-ar s**.
+
+## SEE ALSO
+
+Refer to [llvm-ar](llvm-ar.html) for additional information.

Added: www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-readelf.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-readelf.rst.txt?rev=368037&view=auto
==============================================================================
--- www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-readelf.rst.txt (added)
+++ www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-readelf.rst.txt Tue Aug  6 06:51:02 2019
@@ -0,0 +1,197 @@
+llvm-readelf - GNU-style LLVM Object Reader
+===========================================
+
+.. program:: llvm-readelf
+
+SYNOPSIS
+--------
+
+:program:`llvm-readelf` [*options*] [*input...*]
+
+DESCRIPTION
+-----------
+
+The :program:`llvm-readelf` tool displays low-level format-specific information
+about one or more object files.
+
+If ``input`` is "``-``" or omitted, :program:`llvm-readelf` reads from standard
+input. Otherwise, it will read from the specified ``filenames``.
+
+OPTIONS
+-------
+
+.. option:: --all
+
+ Equivalent to specifying all the main display options.
+
+.. option:: --addrsig
+
+ Display the address-significance table.
+
+.. option:: --arm-attributes
+
+ Display the ARM attributes section. Only applicable for ARM architectures.
+
+.. option:: --color
+
+ Use colors in the output for warnings and errors.
+
+.. option:: --demangle, -C
+
+ Display demangled symbol names in the output.
+
+.. option:: --dyn-relocations
+
+ Display the dynamic relocation entries.
+
+.. option:: --dyn-symbols, --dyn-syms
+
+ Display the dynamic symbol table.
+
+.. option:: --dynamic-table, --dynamic, -d
+
+ Display the dynamic table.
+
+.. option:: --elf-cg-profile
+
+ Display the callgraph profile section.
+
+.. option:: --elf-hash-histogram, --histogram, -I
+
+ Display a bucket list histogram for dynamic symbol hash tables.
+
+.. option:: --elf-linker-options
+
+ Display the linker options section.
+
+.. option:: --elf-output-style=<value>
+
+ Format ELF information in the specified style. Valid options are ``LLVM`` and
+ ``GNU``. ``LLVM`` output is an expanded and structured format, whilst ``GNU``
+ (the default) output mimics the equivalent GNU :program:`readelf` output.
+
+.. option:: --elf-section-groups, --section-groups, -g
+
+ Display section groups.
+
+.. option:: --expand-relocs
+
+ When used with :option:`--relocations`, display each relocation in an expanded
+ multi-line format.
+
+.. option:: --file-headers, -h
+
+ Display file headers.
+
+.. option:: --gnu-hash-table
+
+ Display the GNU hash table for dynamic symbols.
+
+.. option:: --hash-symbols
+
+ Display the expanded hash table with dynamic symbol data.
+
+.. option:: --hash-table
+
+ Display the hash table for dynamic symbols.
+
+.. option:: --headers, -e
+
+ Equivalent to setting: :option:`--file-headers`, :option:`--program-headers`,
+ and :option:`--sections`.
+
+.. option:: --help
+
+ Display a summary of command line options.
+
+.. option:: --help-list
+
+ Display an uncategorized summary of command line options.
+
+.. option:: --hex-dump=<section[,section,...]>, -x
+
+ Display the specified section(s) as hexadecimal bytes. ``section`` may be a
+ section index or section name.
+
+.. option:: --needed-libs
+
+ Display the needed libraries.
+
+.. option:: --notes, -n
+
+ Display all notes.
+
+.. option:: --program-headers, --segments, -l
+
+ Display the program headers.
+
+.. option:: --raw-relr
+
+ Do not decode relocations in RELR relocation sections when displaying them.
+
+.. option:: --relocations, --relocs, -r
+
+ Display the relocation entries in the file.
+
+.. option:: --sections, --section-headers, -S
+
+ Display all sections.
+
+.. option:: --section-data
+
+ When used with :option:`--sections`, display section data for each section
+ shown. This option has no effect for GNU style output.
+
+.. option:: --section-mapping
+
+ Display the section to segment mapping.
+
+.. option:: --section-relocations
+
+ When used with :option:`--sections`, display relocations for each section
+ shown. This option has no effect for GNU style output.
+
+.. option:: --section-symbols
+
+ When used with :option:`--sections`, display symbols for each section shown.
+ This option has no effect for GNU style output.
+
+.. option:: --stackmap
+
+ Display contents of the stackmap section.
+
+.. option:: --string-dump=<section[,section,...]>, -p
+
+ Display the specified section(s) as a list of strings. ``section`` may be a
+ section index or section name.
+
+.. option:: --symbols, --syms, -s
+
+ Display the symbol table.
+
+.. option:: --unwind, -u
+
+ Display unwind information.
+
+.. option:: --version
+
+ Display the version of this program.
+
+.. option:: --version-info, -V
+
+ Display version sections.
+
+.. option:: @<FILE>
+
+ Read command-line options from response file `<FILE>`.
+
+EXIT STATUS
+-----------
+
+:program:`llvm-readelf` returns 0 under normal operation. It returns a non-zero
+exit code if there were any errors.
+
+SEE ALSO
+--------
+
+:manpage:`llvm-nm(1)`, :manpage:`llvm-objdump(1)`, :manpage:`llvm-readobj(1)`

Added: www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-readobj.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-readobj.rst.txt?rev=368037&view=auto
==============================================================================
--- www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-readobj.rst.txt (added)
+++ www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-readobj.rst.txt Tue Aug  6 06:51:02 2019
@@ -0,0 +1,90 @@
+llvm-readobj - LLVM Object Reader
+=================================
+
+SYNOPSIS
+--------
+
+:program:`llvm-readobj` [*options*] [*input...*]
+
+DESCRIPTION
+-----------
+
+The :program:`llvm-readobj` tool displays low-level format-specific information
+about one or more object files. The tool and its output is primarily designed
+for use in FileCheck-based tests.
+
+OPTIONS
+-------
+
+If ``input`` is "``-``" or omitted, :program:`llvm-readobj` reads from standard
+input. Otherwise, it will read from the specified ``filenames``.
+
+.. option:: -help
+
+ Print a summary of command line options.
+
+.. option:: -version
+
+ Display the version of this program
+
+.. option:: -file-headers, -h
+
+ Display file headers.
+
+.. option:: -sections, -s
+
+ Display all sections.
+
+.. option:: -section-data, -sd
+
+ When used with ``-sections``, display section data for each section shown.
+
+.. option:: -section-relocations, -sr
+
+ When used with ``-sections``, display relocations for each section shown.
+
+.. option:: -section-symbols, -st
+
+ When used with ``-sections``, display symbols for each section shown.
+
+.. option:: -relocations, -r
+
+ Display the relocation entries in the file.
+
+.. option:: -symbols, -t
+
+ Display the symbol table.
+
+.. option:: -dyn-symbols
+
+ Display the dynamic symbol table (only for ELF object files).
+
+.. option:: -unwind, -u
+
+ Display unwind information.
+
+.. option:: -expand-relocs
+
+ When used with ``-relocations``, display each relocation in an expanded
+ multi-line format.
+
+.. option:: -dynamic-table
+
+ Display the ELF .dynamic section table (only for ELF object files).
+
+.. option:: -needed-libs
+
+ Display the needed libraries (only for ELF object files).
+
+.. option:: -program-headers
+
+ Display the ELF program headers (only for ELF object files).
+
+.. option:: -elf-section-groups, -g
+
+ Display section groups (only for ELF object files).
+
+EXIT STATUS
+-----------
+
+:program:`llvm-readobj` returns 0.

Added: www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-size.md.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-size.md.txt?rev=368037&view=auto
==============================================================================
--- www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-size.md.txt (added)
+++ www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-size.md.txt Tue Aug  6 06:51:02 2019
@@ -0,0 +1,10 @@
+# llvm-size - print segment sizes
+
+## SYNOPSIS
+
+**llvm-size** [*options*]
+
+## DESCRIPTION
+
+**llvm-size** is a tool that prints segment sizes in object files. The goal is
+to make it a drop-in replacement for GNU's **size**.

Added: www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-stress.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-stress.rst.txt?rev=368037&view=auto
==============================================================================
--- www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-stress.rst.txt (added)
+++ www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-stress.rst.txt Tue Aug  6 06:51:02 2019
@@ -0,0 +1,34 @@
+llvm-stress - generate random .ll files
+=======================================
+
+SYNOPSIS
+--------
+
+:program:`llvm-stress` [-size=filesize] [-seed=initialseed] [-o=outfile]
+
+DESCRIPTION
+-----------
+
+The :program:`llvm-stress` tool is used to generate random ``.ll`` files that
+can be used to test different components of LLVM.
+
+OPTIONS
+-------
+
+.. option:: -o filename
+
+ Specify the output filename.
+
+.. option:: -size size
+
+ Specify the size of the generated ``.ll`` file.
+
+.. option:: -seed seed
+
+ Specify the seed to be used for the randomly generated instructions.
+
+EXIT STATUS
+-----------
+
+:program:`llvm-stress` returns 0.
+

Added: www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-strings.md.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-strings.md.txt?rev=368037&view=auto
==============================================================================
--- www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-strings.md.txt (added)
+++ www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-strings.md.txt Tue Aug  6 06:51:02 2019
@@ -0,0 +1,10 @@
+# llvm-strings - print strings
+
+## SYNOPSIS
+
+**llvm-strings** [*options*]
+
+## DESCRIPTION
+
+**llvm-strings** is a tool that prints strings in object files. The goal is to
+make it a drop-in replacement for GNU's **size**.

Added: www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-strip.md.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-strip.md.txt?rev=368037&view=auto
==============================================================================
--- www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-strip.md.txt (added)
+++ www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-strip.md.txt Tue Aug  6 06:51:02 2019
@@ -0,0 +1,16 @@
+# llvm-strip - object stripping tool
+
+## SYNOPSIS
+
+**llvm-strip** [*options*]
+
+## DESCRIPTION
+
+**llvm-strip** is a tool to strip sections and symbols from object files.
+
+The tool is still in active development, but in most scenarios it works as a
+drop-in replacement for GNU's **strip**.
+
+## SEE ALSO
+
+[llvm-objcopy](llvm-objcopy.html)

Added: www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-symbolizer.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-symbolizer.rst.txt?rev=368037&view=auto
==============================================================================
--- www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-symbolizer.rst.txt (added)
+++ www-releases/trunk/8.0.1/docs/_sources/CommandGuide/llvm-symbolizer.rst.txt Tue Aug  6 06:51:02 2019
@@ -0,0 +1,121 @@
+llvm-symbolizer - convert addresses into source code locations
+==============================================================
+
+SYNOPSIS
+--------
+
+:program:`llvm-symbolizer` [options]
+
+DESCRIPTION
+-----------
+
+:program:`llvm-symbolizer` reads object file names and addresses from standard
+input and prints corresponding source code locations to standard output.
+If object file is specified in command line, :program:`llvm-symbolizer` 
+processes only addresses from standard input, the rest is output verbatim.
+This program uses debug info sections and symbol table in the object files.
+
+EXAMPLE
+--------
+
+.. code-block:: console
+
+  $ cat addr.txt
+  a.out 0x4004f4
+  /tmp/b.out 0x400528
+  /tmp/c.so 0x710
+  /tmp/mach_universal_binary:i386 0x1f84
+  /tmp/mach_universal_binary:x86_64 0x100000f24
+  $ llvm-symbolizer < addr.txt
+  main
+  /tmp/a.cc:4
+  
+  f(int, int)
+  /tmp/b.cc:11
+
+  h_inlined_into_g
+  /tmp/header.h:2
+  g_inlined_into_f
+  /tmp/header.h:7
+  f_inlined_into_main
+  /tmp/source.cc:3
+  main
+  /tmp/source.cc:8
+
+  _main
+  /tmp/source_i386.cc:8
+
+  _main
+  /tmp/source_x86_64.cc:8
+  $ cat addr2.txt
+  0x4004f4
+  0x401000
+  $ llvm-symbolizer -obj=a.out < addr2.txt
+  main
+  /tmp/a.cc:4
+
+  foo(int)
+  /tmp/a.cc:12
+  $cat addr.txt
+  0x40054d
+  $llvm-symbolizer -inlining -print-address -pretty-print -obj=addr.exe < addr.txt
+  0x40054d: inc at /tmp/x.c:3:3
+   (inlined by) main at /tmp/x.c:9:0
+  $llvm-symbolizer -inlining -pretty-print -obj=addr.exe < addr.txt
+  inc at /tmp/x.c:3:3
+   (inlined by) main at /tmp/x.c:9:0
+
+OPTIONS
+-------
+
+.. option:: -obj, -exe, -e
+
+  Path to object file to be symbolized.
+
+.. option:: -functions=[none|short|linkage]
+
+  Specify the way function names are printed (omit function name,
+  print short function name, or print full linkage name, respectively).
+  Defaults to ``linkage``.
+
+.. option:: -use-symbol-table
+
+ Prefer function names stored in symbol table to function names
+ in debug info sections. Defaults to true.
+
+.. option:: -demangle, -C
+
+ Print demangled function names. Defaults to true.
+
+.. option:: -inlining 
+
+ If a source code location is in an inlined function, prints all the
+ inlnied frames. Defaults to true.
+
+.. option:: -default-arch
+
+ If a binary contains object files for multiple architectures (e.g. it is a
+ Mach-O universal binary), symbolize the object file for a given architecture.
+ You can also specify architecture by writing ``binary_name:arch_name`` in the
+ input (see example above). If architecture is not specified in either way,
+ address will not be symbolized. Defaults to empty string.
+
+.. option:: -dsym-hint=<path/to/file.dSYM>
+
+ (Darwin-only flag). If the debug info for a binary isn't present in the default
+ location, look for the debug info at the .dSYM path provided via the
+ ``-dsym-hint`` flag. This flag can be used multiple times.
+
+.. option:: -print-address, -addresses, -a
+
+ Print address before the source code location. Defaults to false.
+
+.. option:: -pretty-print, -p
+
+ Print human readable output. If ``-inlining`` is specified, enclosing scope is
+ prefixed by (inlined by). Refer to listed examples.
+
+EXIT STATUS
+-----------
+
+:program:`llvm-symbolizer` returns 0. Other exit codes imply internal program error.

Added: www-releases/trunk/8.0.1/docs/_sources/CommandGuide/opt.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.1/docs/_sources/CommandGuide/opt.rst.txt?rev=368037&view=auto
==============================================================================
--- www-releases/trunk/8.0.1/docs/_sources/CommandGuide/opt.rst.txt (added)
+++ www-releases/trunk/8.0.1/docs/_sources/CommandGuide/opt.rst.txt Tue Aug  6 06:51:02 2019
@@ -0,0 +1,123 @@
+opt - LLVM optimizer
+====================
+
+SYNOPSIS
+--------
+
+:program:`opt` [*options*] [*filename*]
+
+DESCRIPTION
+-----------
+
+The :program:`opt` command is the modular LLVM optimizer and analyzer.  It
+takes LLVM source files as input, runs the specified optimizations or analyses
+on it, and then outputs the optimized file or the analysis results.  The
+function of :program:`opt` depends on whether the `-analyze` option is
+given.
+
+When `-analyze` is specified, :program:`opt` performs various analyses
+of the input source.  It will usually print the results on standard output, but
+in a few cases, it will print output to standard error or generate a file with
+the analysis output, which is usually done when the output is meant for another
+program.
+
+While `-analyze` is *not* given, :program:`opt` attempts to produce an
+optimized output file.  The optimizations available via :program:`opt` depend
+upon what libraries were linked into it as well as any additional libraries
+that have been loaded with the :option:`-load` option.  Use the :option:`-help`
+option to determine what optimizations you can use.
+
+If ``filename`` is omitted from the command line or is "``-``", :program:`opt`
+reads its input from standard input.  Inputs can be in either the LLVM assembly
+language format (``.ll``) or the LLVM bitcode format (``.bc``).
+
+If an output filename is not specified with the :option:`-o` option,
+:program:`opt` writes its output to the standard output.
+
+OPTIONS
+-------
+
+.. option:: -f
+
+ Enable binary output on terminals.  Normally, :program:`opt` will refuse to
+ write raw bitcode output if the output stream is a terminal.  With this option,
+ :program:`opt` will write raw bitcode regardless of the output device.
+
+.. option:: -help
+
+ Print a summary of command line options.
+
+.. option:: -o <filename>
+
+ Specify the output filename.
+
+.. option:: -S
+
+ Write output in LLVM intermediate language (instead of bitcode).
+
+.. option:: -{passname}
+
+ :program:`opt` provides the ability to run any of LLVM's optimization or
+ analysis passes in any order.  The :option:`-help` option lists all the passes
+ available.  The order in which the options occur on the command line are the
+ order in which they are executed (within pass constraints).
+
+.. option:: -disable-inlining
+
+ This option simply removes the inlining pass from the standard list.
+
+.. option:: -disable-opt
+
+ This option is only meaningful when `-std-link-opts` is given.  It
+ disables most passes.
+
+.. option:: -strip-debug
+
+ This option causes opt to strip debug information from the module before
+ applying other optimizations.  It is essentially the same as `-strip`
+ but it ensures that stripping of debug information is done first.
+
+.. option:: -verify-each
+
+ This option causes opt to add a verify pass after every pass otherwise
+ specified on the command line (including `-verify`).  This is useful
+ for cases where it is suspected that a pass is creating an invalid module but
+ it is not clear which pass is doing it.
+
+.. option:: -stats
+
+ Print statistics.
+
+.. option:: -time-passes
+
+ Record the amount of time needed for each pass and print it to standard
+ error.
+
+.. option:: -debug
+
+ If this is a debug build, this option will enable debug printouts from passes
+ which use the ``LLVM_DEBUG()`` macro.  See the `LLVM Programmer's Manual
+ <../ProgrammersManual.html>`_, section ``#DEBUG`` for more information.
+
+.. option:: -load=<plugin>
+
+ Load the dynamic object ``plugin``.  This object should register new
+ optimization or analysis passes.  Once loaded, the object will add new command
+ line options to enable various optimizations or analyses.  To see the new
+ complete list of optimizations, use the :option:`-help` and :option:`-load`
+ options together.  For example:
+
+ .. code-block:: sh
+
+     opt -load=plugin.so -help
+
+.. option:: -p
+
+ Print module after each transformation.
+
+EXIT STATUS
+-----------
+
+If :program:`opt` succeeds, it will exit with 0.  Otherwise, if an error
+occurs, it will exit with a non-zero value.
+

Added: www-releases/trunk/8.0.1/docs/_sources/CommandGuide/tblgen.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.1/docs/_sources/CommandGuide/tblgen.rst.txt?rev=368037&view=auto
==============================================================================
--- www-releases/trunk/8.0.1/docs/_sources/CommandGuide/tblgen.rst.txt (added)
+++ www-releases/trunk/8.0.1/docs/_sources/CommandGuide/tblgen.rst.txt Tue Aug  6 06:51:02 2019
@@ -0,0 +1,145 @@
+tblgen - Target Description To C++ Code Generator
+=================================================
+
+SYNOPSIS
+--------
+
+:program:`tblgen` [*options*] [*filename*]
+
+DESCRIPTION
+-----------
+
+:program:`tblgen` translates from target description (``.td``) files into C++
+code that can be included in the definition of an LLVM target library.  Most
+users of LLVM will not need to use this program.  It is only for assisting with
+writing an LLVM target backend.
+
+The input and output of :program:`tblgen` is beyond the scope of this short
+introduction; please see the :doc:`introduction to TableGen
+<../TableGen/index>`.
+
+The *filename* argument specifies the name of a Target Description (``.td``)
+file to read as input.
+
+OPTIONS
+-------
+
+.. program:: tblgen
+
+.. option:: -help
+
+ Print a summary of command line options.
+
+.. option:: -o filename
+
+ Specify the output file name.  If ``filename`` is ``-``, then
+ :program:`tblgen` sends its output to standard output.
+
+.. option:: -I directory
+
+ Specify where to find other target description files for inclusion.  The
+ ``directory`` value should be a full or partial path to a directory that
+ contains target description files.
+
+.. option:: -asmparsernum N
+
+ Make -gen-asm-parser emit assembly writer number ``N``.
+
+.. option:: -asmwriternum N
+
+ Make -gen-asm-writer emit assembly writer number ``N``.
+
+.. option:: -class className
+
+ Print the enumeration list for this class.
+
+.. option:: -print-records
+
+ Print all records to standard output (default).
+
+.. option:: -dump-json
+
+ Print a JSON representation of all records, suitable for further
+ automated processing.
+
+.. option:: -print-enums
+
+ Print enumeration values for a class.
+
+.. option:: -print-sets
+
+ Print expanded sets for testing DAG exprs.
+
+.. option:: -gen-emitter
+
+ Generate machine code emitter.
+
+.. option:: -gen-register-info
+
+ Generate registers and register classes info.
+
+.. option:: -gen-instr-info
+
+ Generate instruction descriptions.
+
+.. option:: -gen-asm-writer
+
+ Generate the assembly writer.
+
+.. option:: -gen-disassembler
+
+ Generate disassembler.
+
+.. option:: -gen-pseudo-lowering
+
+ Generate pseudo instruction lowering.
+
+.. option:: -gen-dag-isel
+
+ Generate a DAG (Directed Acycle Graph) instruction selector.
+
+.. option:: -gen-asm-matcher
+
+ Generate assembly instruction matcher.
+
+.. option:: -gen-dfa-packetizer
+
+ Generate DFA Packetizer for VLIW targets.
+
+.. option:: -gen-fast-isel
+
+ Generate a "fast" instruction selector.
+
+.. option:: -gen-subtarget
+
+ Generate subtarget enumerations.
+
+.. option:: -gen-intrinsic-enums
+
+ Generate intrinsic enums.
+
+.. option:: -gen-intrinsic-impl
+
+ Generate intrinsic implementation.
+
+.. option:: -gen-tgt-intrinsic
+
+ Generate target intrinsic information.
+
+.. option:: -gen-enhanced-disassembly-info
+
+ Generate enhanced disassembly info.
+
+.. option:: -gen-exegesis
+
+ Generate llvm-exegesis tables.
+
+.. option:: -version
+
+ Show the version number of this program.
+
+EXIT STATUS
+-----------
+
+If :program:`tblgen` succeeds, it will exit with 0.  Otherwise, if an error
+occurs, it will exit with a non-zero value.

Added: www-releases/trunk/8.0.1/docs/_sources/CommandLine.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.1/docs/_sources/CommandLine.rst.txt?rev=368037&view=auto
==============================================================================
--- www-releases/trunk/8.0.1/docs/_sources/CommandLine.rst.txt (added)
+++ www-releases/trunk/8.0.1/docs/_sources/CommandLine.rst.txt Tue Aug  6 06:51:02 2019
@@ -0,0 +1,1732 @@
+==============================
+CommandLine 2.0 Library Manual
+==============================
+
+.. contents::
+   :local:
+
+Introduction
+============
+
+This document describes the CommandLine argument processing library.  It will
+show you how to use it, and what it can do.  The CommandLine library uses a
+declarative approach to specifying the command line options that your program
+takes.  By default, these options declarations implicitly hold the value parsed
+for the option declared (of course this `can be changed`_).
+
+Although there are a **lot** of command line argument parsing libraries out
+there in many different languages, none of them fit well with what I needed.  By
+looking at the features and problems of other libraries, I designed the
+CommandLine library to have the following features:
+
+#. Speed: The CommandLine library is very quick and uses little resources.  The
+   parsing time of the library is directly proportional to the number of
+   arguments parsed, not the number of options recognized.  Additionally,
+   command line argument values are captured transparently into user defined
+   global variables, which can be accessed like any other variable (and with the
+   same performance).
+
+#. Type Safe: As a user of CommandLine, you don't have to worry about
+   remembering the type of arguments that you want (is it an int?  a string? a
+   bool? an enum?) and keep casting it around.  Not only does this help prevent
+   error prone constructs, it also leads to dramatically cleaner source code.
+
+#. No subclasses required: To use CommandLine, you instantiate variables that
+   correspond to the arguments that you would like to capture, you don't
+   subclass a parser.  This means that you don't have to write **any**
+   boilerplate code.
+
+#. Globally accessible: Libraries can specify command line arguments that are
+   automatically enabled in any tool that links to the library.  This is
+   possible because the application doesn't have to keep a list of arguments to
+   pass to the parser.  This also makes supporting `dynamically loaded options`_
+   trivial.
+
+#. Cleaner: CommandLine supports enum and other types directly, meaning that
+   there is less error and more security built into the library.  You don't have
+   to worry about whether your integral command line argument accidentally got
+   assigned a value that is not valid for your enum type.
+
+#. Powerful: The CommandLine library supports many different types of arguments,
+   from simple `boolean flags`_ to `scalars arguments`_ (`strings`_,
+   `integers`_, `enums`_, `doubles`_), to `lists of arguments`_.  This is
+   possible because CommandLine is...
+
+#. Extensible: It is very simple to add a new argument type to CommandLine.
+   Simply specify the parser that you want to use with the command line option
+   when you declare it. `Custom parsers`_ are no problem.
+
+#. Labor Saving: The CommandLine library cuts down on the amount of grunt work
+   that you, the user, have to do.  For example, it automatically provides a
+   ``-help`` option that shows the available command line options for your tool.
+   Additionally, it does most of the basic correctness checking for you.
+
+#. Capable: The CommandLine library can handle lots of different forms of
+   options often found in real programs.  For example, `positional`_ arguments,
+   ``ls`` style `grouping`_ options (to allow processing '``ls -lad``'
+   naturally), ``ld`` style `prefix`_ options (to parse '``-lmalloc
+   -L/usr/lib``'), and interpreter style options.
+
+This document will hopefully let you jump in and start using CommandLine in your
+utility quickly and painlessly.  Additionally it should be a simple reference
+manual to figure out how stuff works.
+
+Quick Start Guide
+=================
+
+This section of the manual runs through a simple CommandLine'ification of a
+basic compiler tool.  This is intended to show you how to jump into using the
+CommandLine library in your own program, and show you some of the cool things it
+can do.
+
+To start out, you need to include the CommandLine header file into your program:
+
+.. code-block:: c++
+
+  #include "llvm/Support/CommandLine.h"
+
+Additionally, you need to add this as the first line of your main program:
+
+.. code-block:: c++
+
+  int main(int argc, char **argv) {
+    cl::ParseCommandLineOptions(argc, argv);
+    ...
+  }
+
+... which actually parses the arguments and fills in the variable declarations.
+
+Now that you are ready to support command line arguments, we need to tell the
+system which ones we want, and what type of arguments they are.  The CommandLine
+library uses a declarative syntax to model command line arguments with the
+global variable declarations that capture the parsed values.  This means that
+for every command line option that you would like to support, there should be a
+global variable declaration to capture the result.  For example, in a compiler,
+we would like to support the Unix-standard '``-o <filename>``' option to specify
+where to put the output.  With the CommandLine library, this is represented like
+this:
+
+.. _scalars arguments:
+.. _here:
+
+.. code-block:: c++
+
+  cl::opt<string> OutputFilename("o", cl::desc("Specify output filename"), cl::value_desc("filename"));
+
+This declares a global variable "``OutputFilename``" that is used to capture the
+result of the "``o``" argument (first parameter).  We specify that this is a
+simple scalar option by using the "``cl::opt``" template (as opposed to the
+"``cl::list``" template), and tell the CommandLine library that the data
+type that we are parsing is a string.
+
+The second and third parameters (which are optional) are used to specify what to
+output for the "``-help``" option.  In this case, we get a line that looks like
+this:
+
+::
+
+  USAGE: compiler [options]
+
+  OPTIONS:
+    -help             - display available options (-help-hidden for more)
+    -o <filename>     - Specify output filename
+
+Because we specified that the command line option should parse using the
+``string`` data type, the variable declared is automatically usable as a real
+string in all contexts that a normal C++ string object may be used.  For
+example:
+
+.. code-block:: c++
+
+  ...
+  std::ofstream Output(OutputFilename.c_str());
+  if (Output.good()) ...
+  ...
+
+There are many different options that you can use to customize the command line
+option handling library, but the above example shows the general interface to
+these options.  The options can be specified in any order, and are specified
+with helper functions like `cl::desc(...)`_, so there are no positional
+dependencies to remember.  The available options are discussed in detail in the
+`Reference Guide`_.
+
+Continuing the example, we would like to have our compiler take an input
+filename as well as an output filename, but we do not want the input filename to
+be specified with a hyphen (ie, not ``-filename.c``).  To support this style of
+argument, the CommandLine library allows for `positional`_ arguments to be
+specified for the program.  These positional arguments are filled with command
+line parameters that are not in option form.  We use this feature like this:
+
+.. code-block:: c++
+
+
+  cl::opt<string> InputFilename(cl::Positional, cl::desc("<input file>"), cl::init("-"));
+
+This declaration indicates that the first positional argument should be treated
+as the input filename.  Here we use the `cl::init`_ option to specify an initial
+value for the command line option, which is used if the option is not specified
+(if you do not specify a `cl::init`_ modifier for an option, then the default
+constructor for the data type is used to initialize the value).  Command line
+options default to being optional, so if we would like to require that the user
+always specify an input filename, we would add the `cl::Required`_ flag, and we
+could eliminate the `cl::init`_ modifier, like this:
+
+.. code-block:: c++
+
+  cl::opt<string> InputFilename(cl::Positional, cl::desc("<input file>"), cl::Required);
+
+Again, the CommandLine library does not require the options to be specified in
+any particular order, so the above declaration is equivalent to:
+
+.. code-block:: c++
+
+  cl::opt<string> InputFilename(cl::Positional, cl::Required, cl::desc("<input file>"));
+
+By simply adding the `cl::Required`_ flag, the CommandLine library will
+automatically issue an error if the argument is not specified, which shifts all
+of the command line option verification code out of your application into the
+library.  This is just one example of how using flags can alter the default
+behaviour of the library, on a per-option basis.  By adding one of the
+declarations above, the ``-help`` option synopsis is now extended to:
+
+::
+
+  USAGE: compiler [options] <input file>
+
+  OPTIONS:
+    -help             - display available options (-help-hidden for more)
+    -o <filename>     - Specify output filename
+
+... indicating that an input filename is expected.
+
+Boolean Arguments
+-----------------
+
+In addition to input and output filenames, we would like the compiler example to
+support three boolean flags: "``-f``" to force writing binary output to a
+terminal, "``--quiet``" to enable quiet mode, and "``-q``" for backwards
+compatibility with some of our users.  We can support these by declaring options
+of boolean type like this:
+
+.. code-block:: c++
+
+  cl::opt<bool> Force ("f", cl::desc("Enable binary output on terminals"));
+  cl::opt<bool> Quiet ("quiet", cl::desc("Don't print informational messages"));
+  cl::opt<bool> Quiet2("q", cl::desc("Don't print informational messages"), cl::Hidden);
+
+This does what you would expect: it declares three boolean variables
+("``Force``", "``Quiet``", and "``Quiet2``") to recognize these options.  Note
+that the "``-q``" option is specified with the "`cl::Hidden`_" flag.  This
+modifier prevents it from being shown by the standard "``-help``" output (note
+that it is still shown in the "``-help-hidden``" output).
+
+The CommandLine library uses a `different parser`_ for different data types.
+For example, in the string case, the argument passed to the option is copied
+literally into the content of the string variable... we obviously cannot do that
+in the boolean case, however, so we must use a smarter parser.  In the case of
+the boolean parser, it allows no options (in which case it assigns the value of
+true to the variable), or it allows the values "``true``" or "``false``" to be
+specified, allowing any of the following inputs:
+
+::
+
+  compiler -f          # No value, 'Force' == true
+  compiler -f=true     # Value specified, 'Force' == true
+  compiler -f=TRUE     # Value specified, 'Force' == true
+  compiler -f=FALSE    # Value specified, 'Force' == false
+
+... you get the idea.  The `bool parser`_ just turns the string values into
+boolean values, and rejects things like '``compiler -f=foo``'.  Similarly, the
+`float`_, `double`_, and `int`_ parsers work like you would expect, using the
+'``strtol``' and '``strtod``' C library calls to parse the string value into the
+specified data type.
+
+With the declarations above, "``compiler -help``" emits this:
+
+::
+
+  USAGE: compiler [options] <input file>
+
+  OPTIONS:
+    -f     - Enable binary output on terminals
+    -o     - Override output filename
+    -quiet - Don't print informational messages
+    -help  - display available options (-help-hidden for more)
+
+and "``compiler -help-hidden``" prints this:
+
+::
+
+  USAGE: compiler [options] <input file>
+
+  OPTIONS:
+    -f     - Enable binary output on terminals
+    -o     - Override output filename
+    -q     - Don't print informational messages
+    -quiet - Don't print informational messages
+    -help  - display available options (-help-hidden for more)
+
+This brief example has shown you how to use the '`cl::opt`_' class to parse
+simple scalar command line arguments.  In addition to simple scalar arguments,
+the CommandLine library also provides primitives to support CommandLine option
+`aliases`_, and `lists`_ of options.
+
+.. _aliases:
+
+Argument Aliases
+----------------
+
+So far, the example works well, except for the fact that we need to check the
+quiet condition like this now:
+
+.. code-block:: c++
+
+  ...
+    if (!Quiet && !Quiet2) printInformationalMessage(...);
+  ...
+
+... which is a real pain!  Instead of defining two values for the same
+condition, we can use the "`cl::alias`_" class to make the "``-q``" option an
+**alias** for the "``-quiet``" option, instead of providing a value itself:
+
+.. code-block:: c++
+
+  cl::opt<bool> Force ("f", cl::desc("Overwrite output files"));
+  cl::opt<bool> Quiet ("quiet", cl::desc("Don't print informational messages"));
+  cl::alias     QuietA("q", cl::desc("Alias for -quiet"), cl::aliasopt(Quiet));
+
+The third line (which is the only one we modified from above) defines a "``-q``"
+alias that updates the "``Quiet``" variable (as specified by the `cl::aliasopt`_
+modifier) whenever it is specified.  Because aliases do not hold state, the only
+thing the program has to query is the ``Quiet`` variable now.  Another nice
+feature of aliases is that they automatically hide themselves from the ``-help``
+output (although, again, they are still visible in the ``-help-hidden output``).
+
+Now the application code can simply use:
+
+.. code-block:: c++
+
+  ...
+    if (!Quiet) printInformationalMessage(...);
+  ...
+
+... which is much nicer!  The "`cl::alias`_" can be used to specify an
+alternative name for any variable type, and has many uses.
+
+.. _unnamed alternatives using the generic parser:
+
+Selecting an alternative from a set of possibilities
+----------------------------------------------------
+
+So far we have seen how the CommandLine library handles builtin types like
+``std::string``, ``bool`` and ``int``, but how does it handle things it doesn't
+know about, like enums or '``int*``'s?
+
+The answer is that it uses a table-driven generic parser (unless you specify
+your own parser, as described in the `Extension Guide`_).  This parser maps
+literal strings to whatever type is required, and requires you to tell it what
+this mapping should be.
+
+Let's say that we would like to add four optimization levels to our optimizer,
+using the standard flags "``-g``", "``-O0``", "``-O1``", and "``-O2``".  We
+could easily implement this with boolean options like above, but there are
+several problems with this strategy:
+
+#. A user could specify more than one of the options at a time, for example,
+   "``compiler -O3 -O2``".  The CommandLine library would not be able to catch
+   this erroneous input for us.
+
+#. We would have to test 4 different variables to see which ones are set.
+
+#. This doesn't map to the numeric levels that we want... so we cannot easily
+   see if some level >= "``-O1``" is enabled.
+
+To cope with these problems, we can use an enum value, and have the CommandLine
+library fill it in with the appropriate level directly, which is used like this:
+
+.. code-block:: c++
+
+  enum OptLevel {
+    g, O1, O2, O3
+  };
+
+  cl::opt<OptLevel> OptimizationLevel(cl::desc("Choose optimization level:"),
+    cl::values(
+      clEnumVal(g , "No optimizations, enable debugging"),
+      clEnumVal(O1, "Enable trivial optimizations"),
+      clEnumVal(O2, "Enable default optimizations"),
+      clEnumVal(O3, "Enable expensive optimizations")));
+
+  ...
+    if (OptimizationLevel >= O2) doPartialRedundancyElimination(...);
+  ...
+
+This declaration defines a variable "``OptimizationLevel``" of the
+"``OptLevel``" enum type.  This variable can be assigned any of the values that
+are listed in the declaration.  The CommandLine library enforces that
+the user can only specify one of the options, and it ensure that only valid enum
+values can be specified.  The "``clEnumVal``" macros ensure that the command
+line arguments matched the enum values.  With this option added, our help output
+now is:
+
+::
+
+  USAGE: compiler [options] <input file>
+
+  OPTIONS:
+    Choose optimization level:
+      -g          - No optimizations, enable debugging
+      -O1         - Enable trivial optimizations
+      -O2         - Enable default optimizations
+      -O3         - Enable expensive optimizations
+    -f            - Enable binary output on terminals
+    -help         - display available options (-help-hidden for more)
+    -o <filename> - Specify output filename
+    -quiet        - Don't print informational messages
+
+In this case, it is sort of awkward that flag names correspond directly to enum
+names, because we probably don't want a enum definition named "``g``" in our
+program.  Because of this, we can alternatively write this example like this:
+
+.. code-block:: c++
+
+  enum OptLevel {
+    Debug, O1, O2, O3
+  };
+
+  cl::opt<OptLevel> OptimizationLevel(cl::desc("Choose optimization level:"),
+    cl::values(
+     clEnumValN(Debug, "g", "No optimizations, enable debugging"),
+      clEnumVal(O1        , "Enable trivial optimizations"),
+      clEnumVal(O2        , "Enable default optimizations"),
+      clEnumVal(O3        , "Enable expensive optimizations")));
+
+  ...
+    if (OptimizationLevel == Debug) outputDebugInfo(...);
+  ...
+
+By using the "``clEnumValN``" macro instead of "``clEnumVal``", we can directly
+specify the name that the flag should get.  In general a direct mapping is nice,
+but sometimes you can't or don't want to preserve the mapping, which is when you
+would use it.
+
+Named Alternatives
+------------------
+
+Another useful argument form is a named alternative style.  We shall use this
+style in our compiler to specify different debug levels that can be used.
+Instead of each debug level being its own switch, we want to support the
+following options, of which only one can be specified at a time:
+"``--debug-level=none``", "``--debug-level=quick``",
+"``--debug-level=detailed``".  To do this, we use the exact same format as our
+optimization level flags, but we also specify an option name.  For this case,
+the code looks like this:
+
+.. code-block:: c++
+
+  enum DebugLev {
+    nodebuginfo, quick, detailed
+  };
+
+  // Enable Debug Options to be specified on the command line
+  cl::opt<DebugLev> DebugLevel("debug_level", cl::desc("Set the debugging level:"),
+    cl::values(
+      clEnumValN(nodebuginfo, "none", "disable debug information"),
+       clEnumVal(quick,               "enable quick debug information"),
+       clEnumVal(detailed,            "enable detailed debug information")));
+
+This definition defines an enumerated command line variable of type "``enum
+DebugLev``", which works exactly the same way as before.  The difference here is
+just the interface exposed to the user of your program and the help output by
+the "``-help``" option:
+
+::
+
+  USAGE: compiler [options] <input file>
+
+  OPTIONS:
+    Choose optimization level:
+      -g          - No optimizations, enable debugging
+      -O1         - Enable trivial optimizations
+      -O2         - Enable default optimizations
+      -O3         - Enable expensive optimizations
+    -debug_level  - Set the debugging level:
+      =none       - disable debug information
+      =quick      - enable quick debug information
+      =detailed   - enable detailed debug information
+    -f            - Enable binary output on terminals
+    -help         - display available options (-help-hidden for more)
+    -o <filename> - Specify output filename
+    -quiet        - Don't print informational messages
+
+Again, the only structural difference between the debug level declaration and
+the optimization level declaration is that the debug level declaration includes
+an option name (``"debug_level"``), which automatically changes how the library
+processes the argument.  The CommandLine library supports both forms so that you
+can choose the form most appropriate for your application.
+
+.. _lists:
+
+Parsing a list of options
+-------------------------
+
+Now that we have the standard run-of-the-mill argument types out of the way,
+lets get a little wild and crazy.  Lets say that we want our optimizer to accept
+a **list** of optimizations to perform, allowing duplicates.  For example, we
+might want to run: "``compiler -dce -constprop -inline -dce -strip``".  In this
+case, the order of the arguments and the number of appearances is very
+important.  This is what the "``cl::list``" template is for.  First, start by
+defining an enum of the optimizations that you would like to perform:
+
+.. code-block:: c++
+
+  enum Opts {
+    // 'inline' is a C++ keyword, so name it 'inlining'
+    dce, constprop, inlining, strip
+  };
+
+Then define your "``cl::list``" variable:
+
+.. code-block:: c++
+
+  cl::list<Opts> OptimizationList(cl::desc("Available Optimizations:"),
+    cl::values(
+      clEnumVal(dce               , "Dead Code Elimination"),
+      clEnumVal(constprop         , "Constant Propagation"),
+     clEnumValN(inlining, "inline", "Procedure Integration"),
+      clEnumVal(strip             , "Strip Symbols")));
+
+This defines a variable that is conceptually of the type
+"``std::vector<enum Opts>``".  Thus, you can access it with standard vector
+methods:
+
+.. code-block:: c++
+
+  for (unsigned i = 0; i != OptimizationList.size(); ++i)
+    switch (OptimizationList[i])
+       ...
+
+... to iterate through the list of options specified.
+
+Note that the "``cl::list``" template is completely general and may be used with
+any data types or other arguments that you can use with the "``cl::opt``"
+template.  One especially useful way to use a list is to capture all of the
+positional arguments together if there may be more than one specified.  In the
+case of a linker, for example, the linker takes several '``.o``' files, and
+needs to capture them into a list.  This is naturally specified as:
+
+.. code-block:: c++
+
+  ...
+  cl::list<std::string> InputFilenames(cl::Positional, cl::desc("<Input files>"), cl::OneOrMore);
+  ...
+
+This variable works just like a "``vector<string>``" object.  As such, accessing
+the list is simple, just like above.  In this example, we used the
+`cl::OneOrMore`_ modifier to inform the CommandLine library that it is an error
+if the user does not specify any ``.o`` files on our command line.  Again, this
+just reduces the amount of checking we have to do.
+
+Collecting options as a set of flags
+------------------------------------
+
+Instead of collecting sets of options in a list, it is also possible to gather
+information for enum values in a **bit vector**.  The representation used by the
+`cl::bits`_ class is an ``unsigned`` integer.  An enum value is represented by a
+0/1 in the enum's ordinal value bit position. 1 indicating that the enum was
+specified, 0 otherwise.  As each specified value is parsed, the resulting enum's
+bit is set in the option's bit vector:
+
+.. code-block:: c++
+
+  bits |= 1 << (unsigned)enum;
+
+Options that are specified multiple times are redundant.  Any instances after
+the first are discarded.
+
+Reworking the above list example, we could replace `cl::list`_ with `cl::bits`_:
+
+.. code-block:: c++
+
+  cl::bits<Opts> OptimizationBits(cl::desc("Available Optimizations:"),
+    cl::values(
+      clEnumVal(dce               , "Dead Code Elimination"),
+      clEnumVal(constprop         , "Constant Propagation"),
+     clEnumValN(inlining, "inline", "Procedure Integration"),
+      clEnumVal(strip             , "Strip Symbols")));
+
+To test to see if ``constprop`` was specified, we can use the ``cl:bits::isSet``
+function:
+
+.. code-block:: c++
+
+  if (OptimizationBits.isSet(constprop)) {
+    ...
+  }
+
+It's also possible to get the raw bit vector using the ``cl::bits::getBits``
+function:
+
+.. code-block:: c++
+
+  unsigned bits = OptimizationBits.getBits();
+
+Finally, if external storage is used, then the location specified must be of
+**type** ``unsigned``. In all other ways a `cl::bits`_ option is equivalent to a
+`cl::list`_ option.
+
+.. _additional extra text:
+
+Adding freeform text to help output
+-----------------------------------
+
+As our program grows and becomes more mature, we may decide to put summary
+information about what it does into the help output.  The help output is styled
+to look similar to a Unix ``man`` page, providing concise information about a
+program.  Unix ``man`` pages, however often have a description about what the
+program does.  To add this to your CommandLine program, simply pass a third
+argument to the `cl::ParseCommandLineOptions`_ call in main.  This additional
+argument is then printed as the overview information for your program, allowing
+you to include any additional information that you want.  For example:
+
+.. code-block:: c++
+
+  int main(int argc, char **argv) {
+    cl::ParseCommandLineOptions(argc, argv, " CommandLine compiler example\n\n"
+                                "  This program blah blah blah...\n");
+    ...
+  }
+
+would yield the help output:
+
+::
+
+  **OVERVIEW: CommandLine compiler example
+
+    This program blah blah blah...**
+
+  USAGE: compiler [options] <input file>
+
+  OPTIONS:
+    ...
+    -help             - display available options (-help-hidden for more)
+    -o <filename>     - Specify output filename
+
+.. _grouping options into categories:
+
+Grouping options into categories
+--------------------------------
+
+If our program has a large number of options it may become difficult for users
+of our tool to navigate the output of ``-help``. To alleviate this problem we
+can put our options into categories. This can be done by declaring option
+categories (`cl::OptionCategory`_ objects) and then placing our options into
+these categories using the `cl::cat`_ option attribute. For example:
+
+.. code-block:: c++
+
+  cl::OptionCategory StageSelectionCat("Stage Selection Options",
+                                       "These control which stages are run.");
+
+  cl::opt<bool> Preprocessor("E",cl::desc("Run preprocessor stage."),
+                             cl::cat(StageSelectionCat));
+
+  cl::opt<bool> NoLink("c",cl::desc("Run all stages except linking."),
+                       cl::cat(StageSelectionCat));
+
+The output of ``-help`` will become categorized if an option category is
+declared. The output looks something like ::
+
+  OVERVIEW: This is a small program to demo the LLVM CommandLine API
+  USAGE: Sample [options]
+
+  OPTIONS:
+
+    General options:
+
+      -help              - Display available options (-help-hidden for more)
+      -help-list         - Display list of available options (-help-list-hidden for more)
+
+
+    Stage Selection Options:
+    These control which stages are run.
+
+      -E                 - Run preprocessor stage.
+      -c                 - Run all stages except linking.
+
+In addition to the behaviour of ``-help`` changing when an option category is
+declared, the command line option ``-help-list`` becomes visible which will
+print the command line options as uncategorized list.
+
+Note that Options that are not explicitly categorized will be placed in the
+``cl::GeneralCategory`` category.
+
+.. _Reference Guide:
+
+Reference Guide
+===============
+
+Now that you know the basics of how to use the CommandLine library, this section
+will give you the detailed information you need to tune how command line options
+work, as well as information on more "advanced" command line option processing
+capabilities.
+
+.. _positional:
+.. _positional argument:
+.. _Positional Arguments:
+.. _Positional arguments section:
+.. _positional options:
+
+Positional Arguments
+--------------------
+
+Positional arguments are those arguments that are not named, and are not
+specified with a hyphen.  Positional arguments should be used when an option is
+specified by its position alone.  For example, the standard Unix ``grep`` tool
+takes a regular expression argument, and an optional filename to search through
+(which defaults to standard input if a filename is not specified).  Using the
+CommandLine library, this would be specified as:
+
+.. code-block:: c++
+
+  cl::opt<string> Regex   (cl::Positional, cl::desc("<regular expression>"), cl::Required);
+  cl::opt<string> Filename(cl::Positional, cl::desc("<input file>"), cl::init("-"));
+
+Given these two option declarations, the ``-help`` output for our grep
+replacement would look like this:
+
+::
+
+  USAGE: spiffygrep [options] <regular expression> <input file>
+
+  OPTIONS:
+    -help - display available options (-help-hidden for more)
+
+... and the resultant program could be used just like the standard ``grep``
+tool.
+
+Positional arguments are sorted by their order of construction.  This means that
+command line options will be ordered according to how they are listed in a .cpp
+file, but will not have an ordering defined if the positional arguments are
+defined in multiple .cpp files.  The fix for this problem is simply to define
+all of your positional arguments in one .cpp file.
+
+Specifying positional options with hyphens
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Sometimes you may want to specify a value to your positional argument that
+starts with a hyphen (for example, searching for '``-foo``' in a file).  At
+first, you will have trouble doing this, because it will try to find an argument
+named '``-foo``', and will fail (and single quotes will not save you).  Note
+that the system ``grep`` has the same problem:
+
+::
+
+  $ spiffygrep '-foo' test.txt
+  Unknown command line argument '-foo'.  Try: spiffygrep -help'
+
+  $ grep '-foo' test.txt
+  grep: illegal option -- f
+  grep: illegal option -- o
+  grep: illegal option -- o
+  Usage: grep -hblcnsviw pattern file . . .
+
+The solution for this problem is the same for both your tool and the system
+version: use the '``--``' marker.  When the user specifies '``--``' on the
+command line, it is telling the program that all options after the '``--``'
+should be treated as positional arguments, not options.  Thus, we can use it
+like this:
+
+::
+
+  $ spiffygrep -- -foo test.txt
+    ...output...
+
+Determining absolute position with getPosition()
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Sometimes an option can affect or modify the meaning of another option. For
+example, consider ``gcc``'s ``-x LANG`` option. This tells ``gcc`` to ignore the
+suffix of subsequent positional arguments and force the file to be interpreted
+as if it contained source code in language ``LANG``. In order to handle this
+properly, you need to know the absolute position of each argument, especially
+those in lists, so their interaction(s) can be applied correctly. This is also
+useful for options like ``-llibname`` which is actually a positional argument
+that starts with a dash.
+
+So, generally, the problem is that you have two ``cl::list`` variables that
+interact in some way. To ensure the correct interaction, you can use the
+``cl::list::getPosition(optnum)`` method. This method returns the absolute
+position (as found on the command line) of the ``optnum`` item in the
+``cl::list``.
+
+The idiom for usage is like this:
+
+.. code-block:: c++
+
+  static cl::list<std::string> Files(cl::Positional, cl::OneOrMore);
+  static cl::list<std::string> Libraries("l", cl::ZeroOrMore);
+
+  int main(int argc, char**argv) {
+    // ...
+    std::vector<std::string>::iterator fileIt = Files.begin();
+    std::vector<std::string>::iterator libIt  = Libraries.begin();
+    unsigned libPos = 0, filePos = 0;
+    while ( 1 ) {
+      if ( libIt != Libraries.end() )
+        libPos = Libraries.getPosition( libIt - Libraries.begin() );
+      else
+        libPos = 0;
+      if ( fileIt != Files.end() )
+        filePos = Files.getPosition( fileIt - Files.begin() );
+      else
+        filePos = 0;
+
+      if ( filePos != 0 && (libPos == 0 || filePos < libPos) ) {
+        // Source File Is next
+        ++fileIt;
+      }
+      else if ( libPos != 0 && (filePos == 0 || libPos < filePos) ) {
+        // Library is next
+        ++libIt;
+      }
+      else
+        break; // we're done with the list
+    }
+  }
+
+Note that, for compatibility reasons, the ``cl::opt`` also supports an
+``unsigned getPosition()`` option that will provide the absolute position of
+that option. You can apply the same approach as above with a ``cl::opt`` and a
+``cl::list`` option as you can with two lists.
+
+.. _interpreter style options:
+.. _cl::ConsumeAfter:
+.. _this section for more information:
+
+The ``cl::ConsumeAfter`` modifier
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``cl::ConsumeAfter`` `formatting option`_ is used to construct programs that
+use "interpreter style" option processing.  With this style of option
+processing, all arguments specified after the last positional argument are
+treated as special interpreter arguments that are not interpreted by the command
+line argument.
+
+As a concrete example, lets say we are developing a replacement for the standard
+Unix Bourne shell (``/bin/sh``).  To run ``/bin/sh``, first you specify options
+to the shell itself (like ``-x`` which turns on trace output), then you specify
+the name of the script to run, then you specify arguments to the script.  These
+arguments to the script are parsed by the Bourne shell command line option
+processor, but are not interpreted as options to the shell itself.  Using the
+CommandLine library, we would specify this as:
+
+.. code-block:: c++
+
+  cl::opt<string> Script(cl::Positional, cl::desc("<input script>"), cl::init("-"));
+  cl::list<string>  Argv(cl::ConsumeAfter, cl::desc("<program arguments>..."));
+  cl::opt<bool>    Trace("x", cl::desc("Enable trace output"));
+
+which automatically provides the help output:
+
+::
+
+  USAGE: spiffysh [options] <input script> <program arguments>...
+
+  OPTIONS:
+    -help - display available options (-help-hidden for more)
+    -x    - Enable trace output
+
+At runtime, if we run our new shell replacement as ```spiffysh -x test.sh -a -x
+-y bar``', the ``Trace`` variable will be set to true, the ``Script`` variable
+will be set to "``test.sh``", and the ``Argv`` list will contain ``["-a", "-x",
+"-y", "bar"]``, because they were specified after the last positional argument
+(which is the script name).
+
+There are several limitations to when ``cl::ConsumeAfter`` options can be
+specified.  For example, only one ``cl::ConsumeAfter`` can be specified per
+program, there must be at least one `positional argument`_ specified, there must
+not be any `cl::list`_ positional arguments, and the ``cl::ConsumeAfter`` option
+should be a `cl::list`_ option.
+
+.. _can be changed:
+.. _Internal vs External Storage:
+
+Internal vs External Storage
+----------------------------
+
+By default, all command line options automatically hold the value that they
+parse from the command line.  This is very convenient in the common case,
+especially when combined with the ability to define command line options in the
+files that use them.  This is called the internal storage model.
+
+Sometimes, however, it is nice to separate the command line option processing
+code from the storage of the value parsed.  For example, lets say that we have a
+'``-debug``' option that we would like to use to enable debug information across
+the entire body of our program.  In this case, the boolean value controlling the
+debug code should be globally accessible (in a header file, for example) yet the
+command line option processing code should not be exposed to all of these
+clients (requiring lots of .cpp files to ``#include CommandLine.h``).
+
+To do this, set up your .h file with your option, like this for example:
+
+.. code-block:: c++
+
+  // DebugFlag.h - Get access to the '-debug' command line option
+  //
+
+  // DebugFlag - This boolean is set to true if the '-debug' command line option
+  // is specified.  This should probably not be referenced directly, instead, use
+  // the DEBUG macro below.
+  //
+  extern bool DebugFlag;
+
+  // DEBUG macro - This macro should be used by code to emit debug information.
+  // In the '-debug' option is specified on the command line, and if this is a
+  // debug build, then the code specified as the option to the macro will be
+  // executed.  Otherwise it will not be.
+  #ifdef NDEBUG
+  #define LLVM_DEBUG(X)
+  #else
+  #define LLVM_DEBUG(X) do { if (DebugFlag) { X; } } while (0)
+  #endif
+
+This allows clients to blissfully use the ``LLVM_DEBUG()`` macro, or the
+``DebugFlag`` explicitly if they want to.  Now we just need to be able to set
+the ``DebugFlag`` boolean when the option is set.  To do this, we pass an
+additional argument to our command line argument processor, and we specify where
+to fill in with the `cl::location`_ attribute:
+
+.. code-block:: c++
+
+  bool DebugFlag;                  // the actual value
+  static cl::opt<bool, true>       // The parser
+  Debug("debug", cl::desc("Enable debug output"), cl::Hidden, cl::location(DebugFlag));
+
+In the above example, we specify "``true``" as the second argument to the
+`cl::opt`_ template, indicating that the template should not maintain a copy of
+the value itself.  In addition to this, we specify the `cl::location`_
+attribute, so that ``DebugFlag`` is automatically set.
+
+Option Attributes
+-----------------
+
+This section describes the basic attributes that you can specify on options.
+
+* The option name attribute (which is required for all options, except
+  `positional options`_) specifies what the option name is.  This option is
+  specified in simple double quotes:
+
+  .. code-block:: c++
+
+    cl::opt<bool> Quiet("quiet");
+
+.. _cl::desc(...):
+
+* The **cl::desc** attribute specifies a description for the option to be
+  shown in the ``-help`` output for the program. This attribute supports
+  multi-line descriptions with lines separated by '\n'.
+
+.. _cl::value_desc:
+
+* The **cl::value_desc** attribute specifies a string that can be used to
+  fine tune the ``-help`` output for a command line option.  Look `here`_ for an
+  example.
+
+.. _cl::init:
+
+* The **cl::init** attribute specifies an initial value for a `scalar`_
+  option.  If this attribute is not specified then the command line option value
+  defaults to the value created by the default constructor for the
+  type.
+
+  .. warning::
+
+    If you specify both **cl::init** and **cl::location** for an option, you
+    must specify **cl::location** first, so that when the command-line parser
+    sees **cl::init**, it knows where to put the initial value. (You will get an
+    error at runtime if you don't put them in the right order.)
+
+.. _cl::location:
+
+* The **cl::location** attribute where to store the value for a parsed command
+  line option if using external storage.  See the section on `Internal vs
+  External Storage`_ for more information.
+
+.. _cl::aliasopt:
+
+* The **cl::aliasopt** attribute specifies which option a `cl::alias`_ option is
+  an alias for.
+
+.. _cl::values:
+
+* The **cl::values** attribute specifies the string-to-value mapping to be used
+  by the generic parser.  It takes a list of (option, value, description)
+  triplets that specify the option name, the value mapped to, and the
+  description shown in the ``-help`` for the tool.  Because the generic parser
+  is used most frequently with enum values, two macros are often useful:
+
+  #. The **clEnumVal** macro is used as a nice simple way to specify a triplet
+     for an enum.  This macro automatically makes the option name be the same as
+     the enum name.  The first option to the macro is the enum, the second is
+     the description for the command line option.
+
+  #. The **clEnumValN** macro is used to specify macro options where the option
+     name doesn't equal the enum name.  For this macro, the first argument is
+     the enum value, the second is the flag name, and the second is the
+     description.
+
+  You will get a compile time error if you try to use cl::values with a parser
+  that does not support it.
+
+.. _cl::multi_val:
+
+* The **cl::multi_val** attribute specifies that this option takes has multiple
+  values (example: ``-sectalign segname sectname sectvalue``). This attribute
+  takes one unsigned argument - the number of values for the option. This
+  attribute is valid only on ``cl::list`` options (and will fail with compile
+  error if you try to use it with other option types). It is allowed to use all
+  of the usual modifiers on multi-valued options (besides
+  ``cl::ValueDisallowed``, obviously).
+
+.. _cl::cat:
+
+* The **cl::cat** attribute specifies the option category that the option
+  belongs to. The category should be a `cl::OptionCategory`_ object.
+
+Option Modifiers
+----------------
+
+Option modifiers are the flags and expressions that you pass into the
+constructors for `cl::opt`_ and `cl::list`_.  These modifiers give you the
+ability to tweak how options are parsed and how ``-help`` output is generated to
+fit your application well.
+
+These options fall into five main categories:
+
+#. Hiding an option from ``-help`` output
+
+#. Controlling the number of occurrences required and allowed
+
+#. Controlling whether or not a value must be specified
+
+#. Controlling other formatting options
+
+#. Miscellaneous option modifiers
+
+It is not possible to specify two options from the same category (you'll get a
+runtime error) to a single option, except for options in the miscellaneous
+category.  The CommandLine library specifies defaults for all of these settings
+that are the most useful in practice and the most common, which mean that you
+usually shouldn't have to worry about these.
+
+Hiding an option from ``-help`` output
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``cl::NotHidden``, ``cl::Hidden``, and ``cl::ReallyHidden`` modifiers are
+used to control whether or not an option appears in the ``-help`` and
+``-help-hidden`` output for the compiled program:
+
+.. _cl::NotHidden:
+
+* The **cl::NotHidden** modifier (which is the default for `cl::opt`_ and
+  `cl::list`_ options) indicates the option is to appear in both help
+  listings.
+
+.. _cl::Hidden:
+
+* The **cl::Hidden** modifier (which is the default for `cl::alias`_ options)
+  indicates that the option should not appear in the ``-help`` output, but
+  should appear in the ``-help-hidden`` output.
+
+.. _cl::ReallyHidden:
+
+* The **cl::ReallyHidden** modifier indicates that the option should not appear
+  in any help output.
+
+Controlling the number of occurrences required and allowed
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This group of options is used to control how many time an option is allowed (or
+required) to be specified on the command line of your program.  Specifying a
+value for this setting allows the CommandLine library to do error checking for
+you.
+
+The allowed values for this option group are:
+
+.. _cl::Optional:
+
+* The **cl::Optional** modifier (which is the default for the `cl::opt`_ and
+  `cl::alias`_ classes) indicates that your program will allow either zero or
+  one occurrence of the option to be specified.
+
+.. _cl::ZeroOrMore:
+
+* The **cl::ZeroOrMore** modifier (which is the default for the `cl::list`_
+  class) indicates that your program will allow the option to be specified zero
+  or more times.
+
+.. _cl::Required:
+
+* The **cl::Required** modifier indicates that the specified option must be
+  specified exactly one time.
+
+.. _cl::OneOrMore:
+
+* The **cl::OneOrMore** modifier indicates that the option must be specified at
+  least one time.
+
+* The **cl::ConsumeAfter** modifier is described in the `Positional arguments
+  section`_.
+
+If an option is not specified, then the value of the option is equal to the
+value specified by the `cl::init`_ attribute.  If the ``cl::init`` attribute is
+not specified, the option value is initialized with the default constructor for
+the data type.
+
+If an option is specified multiple times for an option of the `cl::opt`_ class,
+only the last value will be retained.
+
+Controlling whether or not a value must be specified
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This group of options is used to control whether or not the option allows a
+value to be present.  In the case of the CommandLine library, a value is either
+specified with an equal sign (e.g. '``-index-depth=17``') or as a trailing
+string (e.g. '``-o a.out``').
+
+The allowed values for this option group are:
+
+.. _cl::ValueOptional:
+
+* The **cl::ValueOptional** modifier (which is the default for ``bool`` typed
+  options) specifies that it is acceptable to have a value, or not.  A boolean
+  argument can be enabled just by appearing on the command line, or it can have
+  an explicit '``-foo=true``'.  If an option is specified with this mode, it is
+  illegal for the value to be provided without the equal sign.  Therefore
+  '``-foo true``' is illegal.  To get this behavior, you must use
+  the `cl::ValueRequired`_ modifier.
+
+.. _cl::ValueRequired:
+
+* The **cl::ValueRequired** modifier (which is the default for all other types
+  except for `unnamed alternatives using the generic parser`_) specifies that a
+  value must be provided.  This mode informs the command line library that if an
+  option is not provides with an equal sign, that the next argument provided
+  must be the value.  This allows things like '``-o a.out``' to work.
+
+.. _cl::ValueDisallowed:
+
+* The **cl::ValueDisallowed** modifier (which is the default for `unnamed
+  alternatives using the generic parser`_) indicates that it is a runtime error
+  for the user to specify a value.  This can be provided to disallow users from
+  providing options to boolean options (like '``-foo=true``').
+
+In general, the default values for this option group work just like you would
+want them to.  As mentioned above, you can specify the `cl::ValueDisallowed`_
+modifier to a boolean argument to restrict your command line parser.  These
+options are mostly useful when `extending the library`_.
+
+.. _formatting option:
+
+Controlling other formatting options
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The formatting option group is used to specify that the command line option has
+special abilities and is otherwise different from other command line arguments.
+As usual, you can only specify one of these arguments at most.
+
+.. _cl::NormalFormatting:
+
+* The **cl::NormalFormatting** modifier (which is the default all options)
+  specifies that this option is "normal".
+
+.. _cl::Positional:
+
+* The **cl::Positional** modifier specifies that this is a positional argument
+  that does not have a command line option associated with it.  See the
+  `Positional Arguments`_ section for more information.
+
+* The **cl::ConsumeAfter** modifier specifies that this option is used to
+  capture "interpreter style" arguments.  See `this section for more
+  information`_.
+
+.. _prefix:
+.. _cl::Prefix:
+
+* The **cl::Prefix** modifier specifies that this option prefixes its value.
+  With 'Prefix' options, the equal sign does not separate the value from the
+  option name specified. Instead, the value is everything after the prefix,
+  including any equal sign if present. This is useful for processing odd
+  arguments like ``-lmalloc`` and ``-L/usr/lib`` in a linker tool or
+  ``-DNAME=value`` in a compiler tool.  Here, the '``l``', '``D``' and '``L``'
+  options are normal string (or list) options, that have the **cl::Prefix**
+  modifier added to allow the CommandLine library to recognize them.  Note that
+  **cl::Prefix** options must not have the **cl::ValueDisallowed** modifier
+  specified.
+
+.. _grouping:
+.. _cl::Grouping:
+
+* The **cl::Grouping** modifier is used to implement Unix-style tools (like
+  ``ls``) that have lots of single letter arguments, but only require a single
+  dash.  For example, the '``ls -labF``' command actually enables four different
+  options, all of which are single letters.  Note that **cl::Grouping** options
+  cannot have values.
+
+The CommandLine library does not restrict how you use the **cl::Prefix** or
+**cl::Grouping** modifiers, but it is possible to specify ambiguous argument
+settings.  Thus, it is possible to have multiple letter options that are prefix
+or grouping options, and they will still work as designed.
+
+To do this, the CommandLine library uses a greedy algorithm to parse the input
+option into (potentially multiple) prefix and grouping options.  The strategy
+basically looks like this:
+
+::
+
+  parse(string OrigInput) {
+
+  1. string input = OrigInput;
+  2. if (isOption(input)) return getOption(input).parse();  // Normal option
+  3. while (!isOption(input) && !input.empty()) input.pop_back();  // Remove the last letter
+  4. if (input.empty()) return error();  // No matching option
+  5. if (getOption(input).isPrefix())
+       return getOption(input).parse(input);
+  6. while (!input.empty()) {  // Must be grouping options
+       getOption(input).parse();
+       OrigInput.erase(OrigInput.begin(), OrigInput.begin()+input.length());
+       input = OrigInput;
+       while (!isOption(input) && !input.empty()) input.pop_back();
+     }
+  7. if (!OrigInput.empty()) error();
+
+  }
+
+Miscellaneous option modifiers
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The miscellaneous option modifiers are the only flags where you can specify more
+than one flag from the set: they are not mutually exclusive.  These flags
+specify boolean properties that modify the option.
+
+.. _cl::CommaSeparated:
+
+* The **cl::CommaSeparated** modifier indicates that any commas specified for an
+  option's value should be used to split the value up into multiple values for
+  the option.  For example, these two options are equivalent when
+  ``cl::CommaSeparated`` is specified: "``-foo=a -foo=b -foo=c``" and
+  "``-foo=a,b,c``".  This option only makes sense to be used in a case where the
+  option is allowed to accept one or more values (i.e. it is a `cl::list`_
+  option).
+
+.. _cl::PositionalEatsArgs:
+
+* The **cl::PositionalEatsArgs** modifier (which only applies to positional
+  arguments, and only makes sense for lists) indicates that positional argument
+  should consume any strings after it (including strings that start with a "-")
+  up until another recognized positional argument.  For example, if you have two
+  "eating" positional arguments, "``pos1``" and "``pos2``", the string "``-pos1
+  -foo -bar baz -pos2 -bork``" would cause the "``-foo -bar -baz``" strings to
+  be applied to the "``-pos1``" option and the "``-bork``" string to be applied
+  to the "``-pos2``" option.
+
+.. _cl::Sink:
+
+* The **cl::Sink** modifier is used to handle unknown options. If there is at
+  least one option with ``cl::Sink`` modifier specified, the parser passes
+  unrecognized option strings to it as values instead of signaling an error. As
+  with ``cl::CommaSeparated``, this modifier only makes sense with a `cl::list`_
+  option.
+
+So far, these are the only three miscellaneous option modifiers.
+
+.. _response files:
+
+Response files
+^^^^^^^^^^^^^^
+
+Some systems, such as certain variants of Microsoft Windows and some older
+Unices have a relatively low limit on command-line length. It is therefore
+customary to use the so-called 'response files' to circumvent this
+restriction. These files are mentioned on the command-line (using the "@file")
+syntax. The program reads these files and inserts the contents into argv,
+thereby working around the command-line length limits.
+
+Top-Level Classes and Functions
+-------------------------------
+
+Despite all of the built-in flexibility, the CommandLine option library really
+only consists of one function `cl::ParseCommandLineOptions`_) and three main
+classes: `cl::opt`_, `cl::list`_, and `cl::alias`_.  This section describes
+these three classes in detail.
+
+.. _cl::getRegisteredOptions:
+
+The ``cl::getRegisteredOptions`` function
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``cl::getRegisteredOptions`` function is designed to give a programmer
+access to declared non-positional command line options so that how they appear
+in ``-help`` can be modified prior to calling `cl::ParseCommandLineOptions`_.
+Note this method should not be called during any static initialisation because
+it cannot be guaranteed that all options will have been initialised. Hence it
+should be called from ``main``.
+
+This function can be used to gain access to options declared in libraries that
+the tool writter may not have direct access to.
+
+The function retrieves a :ref:`StringMap <dss_stringmap>` that maps the option
+string (e.g. ``-help``) to an ``Option*``.
+
+Here is an example of how the function could be used:
+
+.. code-block:: c++
+
+  using namespace llvm;
+  int main(int argc, char **argv) {
+    cl::OptionCategory AnotherCategory("Some options");
+
+    StringMap<cl::Option*> &Map = cl::getRegisteredOptions();
+
+    //Unhide useful option and put it in a different category
+    assert(Map.count("print-all-options") > 0);
+    Map["print-all-options"]->setHiddenFlag(cl::NotHidden);
+    Map["print-all-options"]->setCategory(AnotherCategory);
+
+    //Hide an option we don't want to see
+    assert(Map.count("enable-no-infs-fp-math") > 0);
+    Map["enable-no-infs-fp-math"]->setHiddenFlag(cl::Hidden);
+
+    //Change --version to --show-version
+    assert(Map.count("version") > 0);
+    Map["version"]->setArgStr("show-version");
+
+    //Change --help description
+    assert(Map.count("help") > 0);
+    Map["help"]->setDescription("Shows help");
+
+    cl::ParseCommandLineOptions(argc, argv, "This is a small program to demo the LLVM CommandLine API");
+    ...
+  }
+
+
+.. _cl::ParseCommandLineOptions:
+
+The ``cl::ParseCommandLineOptions`` function
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``cl::ParseCommandLineOptions`` function is designed to be called directly
+from ``main``, and is used to fill in the values of all of the command line
+option variables once ``argc`` and ``argv`` are available.
+
+The ``cl::ParseCommandLineOptions`` function requires two parameters (``argc``
+and ``argv``), but may also take an optional third parameter which holds
+`additional extra text`_ to emit when the ``-help`` option is invoked.
+
+.. _cl::ParseEnvironmentOptions:
+
+The ``cl::ParseEnvironmentOptions`` function
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``cl::ParseEnvironmentOptions`` function has mostly the same effects as
+`cl::ParseCommandLineOptions`_, except that it is designed to take values for
+options from an environment variable, for those cases in which reading the
+command line is not convenient or desired. It fills in the values of all the
+command line option variables just like `cl::ParseCommandLineOptions`_ does.
+
+It takes four parameters: the name of the program (since ``argv`` may not be
+available, it can't just look in ``argv[0]``), the name of the environment
+variable to examine, and the optional `additional extra text`_ to emit when the
+``-help`` option is invoked.
+
+``cl::ParseEnvironmentOptions`` will break the environment variable's value up
+into words and then process them using `cl::ParseCommandLineOptions`_.
+**Note:** Currently ``cl::ParseEnvironmentOptions`` does not support quoting, so
+an environment variable containing ``-option "foo bar"`` will be parsed as three
+words, ``-option``, ``"foo``, and ``bar"``, which is different from what you
+would get from the shell with the same input.
+
+The ``cl::SetVersionPrinter`` function
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``cl::SetVersionPrinter`` function is designed to be called directly from
+``main`` and *before* ``cl::ParseCommandLineOptions``. Its use is optional. It
+simply arranges for a function to be called in response to the ``--version``
+option instead of having the ``CommandLine`` library print out the usual version
+string for LLVM. This is useful for programs that are not part of LLVM but wish
+to use the ``CommandLine`` facilities. Such programs should just define a small
+function that takes no arguments and returns ``void`` and that prints out
+whatever version information is appropriate for the program. Pass the address of
+that function to ``cl::SetVersionPrinter`` to arrange for it to be called when
+the ``--version`` option is given by the user.
+
+.. _cl::opt:
+.. _scalar:
+
+The ``cl::opt`` class
+^^^^^^^^^^^^^^^^^^^^^
+
+The ``cl::opt`` class is the class used to represent scalar command line
+options, and is the one used most of the time.  It is a templated class which
+can take up to three arguments (all except for the first have default values
+though):
+
+.. code-block:: c++
+
+  namespace cl {
+    template <class DataType, bool ExternalStorage = false,
+              class ParserClass = parser<DataType> >
+    class opt;
+  }
+
+The first template argument specifies what underlying data type the command line
+argument is, and is used to select a default parser implementation.  The second
+template argument is used to specify whether the option should contain the
+storage for the option (the default) or whether external storage should be used
+to contain the value parsed for the option (see `Internal vs External Storage`_
+for more information).
+
+The third template argument specifies which parser to use.  The default value
+selects an instantiation of the ``parser`` class based on the underlying data
+type of the option.  In general, this default works well for most applications,
+so this option is only used when using a `custom parser`_.
+
+.. _lists of arguments:
+.. _cl::list:
+
+The ``cl::list`` class
+^^^^^^^^^^^^^^^^^^^^^^
+
+The ``cl::list`` class is the class used to represent a list of command line
+options.  It too is a templated class which can take up to three arguments:
+
+.. code-block:: c++
+
+  namespace cl {
+    template <class DataType, class Storage = bool,
+              class ParserClass = parser<DataType> >
+    class list;
+  }
+
+This class works the exact same as the `cl::opt`_ class, except that the second
+argument is the **type** of the external storage, not a boolean value.  For this
+class, the marker type '``bool``' is used to indicate that internal storage
+should be used.
+
+.. _cl::bits:
+
+The ``cl::bits`` class
+^^^^^^^^^^^^^^^^^^^^^^
+
+The ``cl::bits`` class is the class used to represent a list of command line
+options in the form of a bit vector.  It is also a templated class which can
+take up to three arguments:
+
+.. code-block:: c++
+
+  namespace cl {
+    template <class DataType, class Storage = bool,
+              class ParserClass = parser<DataType> >
+    class bits;
+  }
+
+This class works the exact same as the `cl::list`_ class, except that the second
+argument must be of **type** ``unsigned`` if external storage is used.
+
+.. _cl::alias:
+
+The ``cl::alias`` class
+^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``cl::alias`` class is a nontemplated class that is used to form aliases for
+other arguments.
+
+.. code-block:: c++
+
+  namespace cl {
+    class alias;
+  }
+
+The `cl::aliasopt`_ attribute should be used to specify which option this is an
+alias for.  Alias arguments default to being `cl::Hidden`_, and use the aliased
+options parser to do the conversion from string to data.
+
+.. _cl::extrahelp:
+
+The ``cl::extrahelp`` class
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``cl::extrahelp`` class is a nontemplated class that allows extra help text
+to be printed out for the ``-help`` option.
+
+.. code-block:: c++
+
+  namespace cl {
+    struct extrahelp;
+  }
+
+To use the extrahelp, simply construct one with a ``const char*`` parameter to
+the constructor. The text passed to the constructor will be printed at the
+bottom of the help message, verbatim. Note that multiple ``cl::extrahelp``
+**can** be used, but this practice is discouraged. If your tool needs to print
+additional help information, put all that help into a single ``cl::extrahelp``
+instance.
+
+For example:
+
+.. code-block:: c++
+
+  cl::extrahelp("\nADDITIONAL HELP:\n\n  This is the extra help\n");
+
+.. _cl::OptionCategory:
+
+The ``cl::OptionCategory`` class
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``cl::OptionCategory`` class is a simple class for declaring
+option categories.
+
+.. code-block:: c++
+
+  namespace cl {
+    class OptionCategory;
+  }
+
+An option category must have a name and optionally a description which are
+passed to the constructor as ``const char*``.
+
+Note that declaring an option category and associating it with an option before
+parsing options (e.g. statically) will change the output of ``-help`` from
+uncategorized to categorized. If an option category is declared but not
+associated with an option then it will be hidden from the output of ``-help``
+but will be shown in the output of ``-help-hidden``.
+
+.. _different parser:
+.. _discussed previously:
+
+Builtin parsers
+---------------
+
+Parsers control how the string value taken from the command line is translated
+into a typed value, suitable for use in a C++ program.  By default, the
+CommandLine library uses an instance of ``parser<type>`` if the command line
+option specifies that it uses values of type '``type``'.  Because of this,
+custom option processing is specified with specializations of the '``parser``'
+class.
+
+The CommandLine library provides the following builtin parser specializations,
+which are sufficient for most applications. It can, however, also be extended to
+work with new data types and new ways of interpreting the same data.  See the
+`Writing a Custom Parser`_ for more details on this type of library extension.
+
+.. _enums:
+.. _cl::parser:
+
+* The generic ``parser<t>`` parser can be used to map strings values to any data
+  type, through the use of the `cl::values`_ property, which specifies the
+  mapping information.  The most common use of this parser is for parsing enum
+  values, which allows you to use the CommandLine library for all of the error
+  checking to make sure that only valid enum values are specified (as opposed to
+  accepting arbitrary strings).  Despite this, however, the generic parser class
+  can be used for any data type.
+
+.. _boolean flags:
+.. _bool parser:
+
+* The **parser<bool> specialization** is used to convert boolean strings to a
+  boolean value.  Currently accepted strings are "``true``", "``TRUE``",
+  "``True``", "``1``", "``false``", "``FALSE``", "``False``", and "``0``".
+
+* The **parser<boolOrDefault> specialization** is used for cases where the value
+  is boolean, but we also need to know whether the option was specified at all.
+  boolOrDefault is an enum with 3 values, BOU_UNSET, BOU_TRUE and BOU_FALSE.
+  This parser accepts the same strings as **``parser<bool>``**.
+
+.. _strings:
+
+* The **parser<string> specialization** simply stores the parsed string into the
+  string value specified.  No conversion or modification of the data is
+  performed.
+
+.. _integers:
+.. _int:
+
+* The **parser<int> specialization** uses the C ``strtol`` function to parse the
+  string input.  As such, it will accept a decimal number (with an optional '+'
+  or '-' prefix) which must start with a non-zero digit.  It accepts octal
+  numbers, which are identified with a '``0``' prefix digit, and hexadecimal
+  numbers with a prefix of '``0x``' or '``0X``'.
+
+.. _doubles:
+.. _float:
+.. _double:
+
+* The **parser<double>** and **parser<float> specializations** use the standard
+  C ``strtod`` function to convert floating point strings into floating point
+  values.  As such, a broad range of string formats is supported, including
+  exponential notation (ex: ``1.7e15``) and properly supports locales.
+
+.. _Extension Guide:
+.. _extending the library:
+
+Extension Guide
+===============
+
+Although the CommandLine library has a lot of functionality built into it
+already (as discussed previously), one of its true strengths lie in its
+extensibility.  This section discusses how the CommandLine library works under
+the covers and illustrates how to do some simple, common, extensions.
+
+.. _Custom parsers:
+.. _custom parser:
+.. _Writing a Custom Parser:
+
+Writing a custom parser
+-----------------------
+
+One of the simplest and most common extensions is the use of a custom parser.
+As `discussed previously`_, parsers are the portion of the CommandLine library
+that turns string input from the user into a particular parsed data type,
+validating the input in the process.
+
+There are two ways to use a new parser:
+
+#. Specialize the `cl::parser`_ template for your custom data type.
+
+   This approach has the advantage that users of your custom data type will
+   automatically use your custom parser whenever they define an option with a
+   value type of your data type.  The disadvantage of this approach is that it
+   doesn't work if your fundamental data type is something that is already
+   supported.
+
+#. Write an independent class, using it explicitly from options that need it.
+
+   This approach works well in situations where you would line to parse an
+   option using special syntax for a not-very-special data-type.  The drawback
+   of this approach is that users of your parser have to be aware that they are
+   using your parser instead of the builtin ones.
+
+To guide the discussion, we will discuss a custom parser that accepts file
+sizes, specified with an optional unit after the numeric size.  For example, we
+would like to parse "102kb", "41M", "1G" into the appropriate integer value.  In
+this case, the underlying data type we want to parse into is '``unsigned``'.  We
+choose approach #2 above because we don't want to make this the default for all
+``unsigned`` options.
+
+To start out, we declare our new ``FileSizeParser`` class:
+
+.. code-block:: c++
+
+  struct FileSizeParser : public cl::parser<unsigned> {
+    // parse - Return true on error.
+    bool parse(cl::Option &O, StringRef ArgName, const std::string &ArgValue,
+               unsigned &Val);
+  };
+
+Our new class inherits from the ``cl::parser`` template class to fill in
+the default, boiler plate code for us.  We give it the data type that we parse
+into, the last argument to the ``parse`` method, so that clients of our custom
+parser know what object type to pass in to the parse method.  (Here we declare
+that we parse into '``unsigned``' variables.)
+
+For most purposes, the only method that must be implemented in a custom parser
+is the ``parse`` method.  The ``parse`` method is called whenever the option is
+invoked, passing in the option itself, the option name, the string to parse, and
+a reference to a return value.  If the string to parse is not well-formed, the
+parser should output an error message and return true.  Otherwise it should
+return false and set '``Val``' to the parsed value.  In our example, we
+implement ``parse`` as:
+
+.. code-block:: c++
+
+  bool FileSizeParser::parse(cl::Option &O, StringRef ArgName,
+                             const std::string &Arg, unsigned &Val) {
+    const char *ArgStart = Arg.c_str();
+    char *End;
+
+    // Parse integer part, leaving 'End' pointing to the first non-integer char
+    Val = (unsigned)strtol(ArgStart, &End, 0);
+
+    while (1) {
+      switch (*End++) {
+      case 0: return false;   // No error
+      case 'i':               // Ignore the 'i' in KiB if people use that
+      case 'b': case 'B':     // Ignore B suffix
+        break;
+
+      case 'g': case 'G': Val *= 1024*1024*1024; break;
+      case 'm': case 'M': Val *= 1024*1024;      break;
+      case 'k': case 'K': Val *= 1024;           break;
+
+      default:
+        // Print an error message if unrecognized character!
+        return O.error("'" + Arg + "' value invalid for file size argument!");
+      }
+    }
+  }
+
+This function implements a very simple parser for the kinds of strings we are
+interested in.  Although it has some holes (it allows "``123KKK``" for example),
+it is good enough for this example.  Note that we use the option itself to print
+out the error message (the ``error`` method always returns true) in order to get
+a nice error message (shown below).  Now that we have our parser class, we can
+use it like this:
+
+.. code-block:: c++
+
+  static cl::opt<unsigned, false, FileSizeParser>
+  MFS("max-file-size", cl::desc("Maximum file size to accept"),
+      cl::value_desc("size"));
+
+Which adds this to the output of our program:
+
+::
+
+  OPTIONS:
+    -help                 - display available options (-help-hidden for more)
+    ...
+    -max-file-size=<size> - Maximum file size to accept
+
+And we can test that our parse works correctly now (the test program just prints
+out the max-file-size argument value):
+
+::
+
+  $ ./test
+  MFS: 0
+  $ ./test -max-file-size=123MB
+  MFS: 128974848
+  $ ./test -max-file-size=3G
+  MFS: 3221225472
+  $ ./test -max-file-size=dog
+  -max-file-size option: 'dog' value invalid for file size argument!
+
+It looks like it works.  The error message that we get is nice and helpful, and
+we seem to accept reasonable file sizes.  This wraps up the "custom parser"
+tutorial.
+
+Exploiting external storage
+---------------------------
+
+Several of the LLVM libraries define static ``cl::opt`` instances that will
+automatically be included in any program that links with that library.  This is
+a feature. However, sometimes it is necessary to know the value of the command
+line option outside of the library. In these cases the library does or should
+provide an external storage location that is accessible to users of the
+library. Examples of this include the ``llvm::DebugFlag`` exported by the
+``lib/Support/Debug.cpp`` file and the ``llvm::TimePassesIsEnabled`` flag
+exported by the ``lib/IR/PassManager.cpp`` file.
+
+.. todo::
+
+  TODO: complete this section
+
+.. _dynamically loaded options:
+
+Dynamically adding command line options
+---------------------------------------
+
+.. todo::
+
+  TODO: fill in this section

Added: www-releases/trunk/8.0.1/docs/_sources/CompileCudaWithLLVM.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.1/docs/_sources/CompileCudaWithLLVM.rst.txt?rev=368037&view=auto
==============================================================================
--- www-releases/trunk/8.0.1/docs/_sources/CompileCudaWithLLVM.rst.txt (added)
+++ www-releases/trunk/8.0.1/docs/_sources/CompileCudaWithLLVM.rst.txt Tue Aug  6 06:51:02 2019
@@ -0,0 +1,560 @@
+=========================
+Compiling CUDA with clang
+=========================
+
+.. contents::
+   :local:
+
+Introduction
+============
+
+This document describes how to compile CUDA code with clang, and gives some
+details about LLVM and clang's CUDA implementations.
+
+This document assumes a basic familiarity with CUDA. Information about CUDA
+programming can be found in the
+`CUDA programming guide
+<http://docs.nvidia.com/cuda/cuda-c-programming-guide/index.html>`_.
+
+Compiling CUDA Code
+===================
+
+Prerequisites
+-------------
+
+CUDA is supported since llvm 3.9. Current release of clang (7.0.0) supports CUDA
+7.0 through 9.2. If you need support for CUDA 10, you will need to use clang
+built from r342924 or newer.
+
+Before you build CUDA code, you'll need to have installed the appropriate driver
+for your nvidia GPU and the CUDA SDK.  See `NVIDIA's CUDA installation guide
+<https://docs.nvidia.com/cuda/cuda-installation-guide-linux/index.html>`_ for
+details.  Note that clang `does not support
+<https://llvm.org/bugs/show_bug.cgi?id=26966>`_ the CUDA toolkit as installed by
+many Linux package managers; you probably need to install CUDA in a single
+directory from NVIDIA's package.
+
+CUDA compilation is supported on Linux. Compilation on MacOS and Windows may or
+may not work and currently have no maintainers. Compilation with CUDA-9.x is
+`currently broken on Windows <https://bugs.llvm.org/show_bug.cgi?id=38811>`_.
+
+Invoking clang
+--------------
+
+Invoking clang for CUDA compilation works similarly to compiling regular C++.
+You just need to be aware of a few additional flags.
+
+You can use `this <https://gist.github.com/855e277884eb6b388cd2f00d956c2fd4>`_
+program as a toy example.  Save it as ``axpy.cu``.  (Clang detects that you're
+compiling CUDA code by noticing that your filename ends with ``.cu``.
+Alternatively, you can pass ``-x cuda``.)
+
+To build and run, run the following commands, filling in the parts in angle
+brackets as described below:
+
+.. code-block:: console
+
+  $ clang++ axpy.cu -o axpy --cuda-gpu-arch=<GPU arch> \
+      -L<CUDA install path>/<lib64 or lib>             \
+      -lcudart_static -ldl -lrt -pthread
+  $ ./axpy
+  y[0] = 2
+  y[1] = 4
+  y[2] = 6
+  y[3] = 8
+
+On MacOS, replace `-lcudart_static` with `-lcudart`; otherwise, you may get
+"CUDA driver version is insufficient for CUDA runtime version" errors when you
+run your program.
+
+* ``<CUDA install path>`` -- the directory where you installed CUDA SDK.
+  Typically, ``/usr/local/cuda``.
+
+  Pass e.g. ``-L/usr/local/cuda/lib64`` if compiling in 64-bit mode; otherwise,
+  pass e.g. ``-L/usr/local/cuda/lib``.  (In CUDA, the device code and host code
+  always have the same pointer widths, so if you're compiling 64-bit code for
+  the host, you're also compiling 64-bit code for the device.) Note that as of
+  v10.0 CUDA SDK `no longer supports compilation of 32-bit
+  applications <https://docs.nvidia.com/cuda/cuda-toolkit-release-notes/index.html#deprecated-features>`_.
+
+* ``<GPU arch>`` -- the `compute capability
+  <https://developer.nvidia.com/cuda-gpus>`_ of your GPU. For example, if you
+  want to run your program on a GPU with compute capability of 3.5, specify
+  ``--cuda-gpu-arch=sm_35``.
+
+  Note: You cannot pass ``compute_XX`` as an argument to ``--cuda-gpu-arch``;
+  only ``sm_XX`` is currently supported.  However, clang always includes PTX in
+  its binaries, so e.g. a binary compiled with ``--cuda-gpu-arch=sm_30`` would be
+  forwards-compatible with e.g. ``sm_35`` GPUs.
+
+  You can pass ``--cuda-gpu-arch`` multiple times to compile for multiple archs.
+
+The `-L` and `-l` flags only need to be passed when linking.  When compiling,
+you may also need to pass ``--cuda-path=/path/to/cuda`` if you didn't install
+the CUDA SDK into ``/usr/local/cuda`` or ``/usr/local/cuda-X.Y``.
+
+Flags that control numerical code
+---------------------------------
+
+If you're using GPUs, you probably care about making numerical code run fast.
+GPU hardware allows for more control over numerical operations than most CPUs,
+but this results in more compiler options for you to juggle.
+
+Flags you may wish to tweak include:
+
+* ``-ffp-contract={on,off,fast}`` (defaults to ``fast`` on host and device when
+  compiling CUDA) Controls whether the compiler emits fused multiply-add
+  operations.
+
+  * ``off``: never emit fma operations, and prevent ptxas from fusing multiply
+    and add instructions.
+  * ``on``: fuse multiplies and adds within a single statement, but never
+    across statements (C11 semantics).  Prevent ptxas from fusing other
+    multiplies and adds.
+  * ``fast``: fuse multiplies and adds wherever profitable, even across
+    statements.  Doesn't prevent ptxas from fusing additional multiplies and
+    adds.
+
+  Fused multiply-add instructions can be much faster than the unfused
+  equivalents, but because the intermediate result in an fma is not rounded,
+  this flag can affect numerical code.
+
+* ``-fcuda-flush-denormals-to-zero`` (default: off) When this is enabled,
+  floating point operations may flush `denormal
+  <https://en.wikipedia.org/wiki/Denormal_number>`_ inputs and/or outputs to 0.
+  Operations on denormal numbers are often much slower than the same operations
+  on normal numbers.
+
+* ``-fcuda-approx-transcendentals`` (default: off) When this is enabled, the
+  compiler may emit calls to faster, approximate versions of transcendental
+  functions, instead of using the slower, fully IEEE-compliant versions.  For
+  example, this flag allows clang to emit the ptx ``sin.approx.f32``
+  instruction.
+
+  This is implied by ``-ffast-math``.
+
+Standard library support
+========================
+
+In clang and nvcc, most of the C++ standard library is not supported on the
+device side.
+
+``<math.h>`` and ``<cmath>``
+----------------------------
+
+In clang, ``math.h`` and ``cmath`` are available and `pass
+<https://github.com/llvm-mirror/test-suite/blob/master/External/CUDA/math_h.cu>`_
+`tests
+<https://github.com/llvm-mirror/test-suite/blob/master/External/CUDA/cmath.cu>`_
+adapted from libc++'s test suite.
+
+In nvcc ``math.h`` and ``cmath`` are mostly available.  Versions of ``::foof``
+in namespace std (e.g. ``std::sinf``) are not available, and where the standard
+calls for overloads that take integral arguments, these are usually not
+available.
+
+.. code-block:: c++
+
+  #include <math.h>
+  #include <cmath.h>
+
+  // clang is OK with everything in this function.
+  __device__ void test() {
+    std::sin(0.); // nvcc - ok
+    std::sin(0);  // nvcc - error, because no std::sin(int) override is available.
+    sin(0);       // nvcc - same as above.
+
+    sinf(0.);       // nvcc - ok
+    std::sinf(0.);  // nvcc - no such function
+  }
+
+``<std::complex>``
+------------------
+
+nvcc does not officially support ``std::complex``.  It's an error to use
+``std::complex`` in ``__device__`` code, but it often works in ``__host__
+__device__`` code due to nvcc's interpretation of the "wrong-side rule" (see
+below).  However, we have heard from implementers that it's possible to get
+into situations where nvcc will omit a call to an ``std::complex`` function,
+especially when compiling without optimizations.
+
+As of 2016-11-16, clang supports ``std::complex`` without these caveats.  It is
+tested with libstdc++ 4.8.5 and newer, but is known to work only with libc++
+newer than 2016-11-16.
+
+``<algorithm>``
+---------------
+
+In C++14, many useful functions from ``<algorithm>`` (notably, ``std::min`` and
+``std::max``) become constexpr.  You can therefore use these in device code,
+when compiling with clang.
+
+Detecting clang vs NVCC from code
+=================================
+
+Although clang's CUDA implementation is largely compatible with NVCC's, you may
+still want to detect when you're compiling CUDA code specifically with clang.
+
+This is tricky, because NVCC may invoke clang as part of its own compilation
+process!  For example, NVCC uses the host compiler's preprocessor when
+compiling for device code, and that host compiler may in fact be clang.
+
+When clang is actually compiling CUDA code -- rather than being used as a
+subtool of NVCC's -- it defines the ``__CUDA__`` macro.  ``__CUDA_ARCH__`` is
+defined only in device mode (but will be defined if NVCC is using clang as a
+preprocessor).  So you can use the following incantations to detect clang CUDA
+compilation, in host and device modes:
+
+.. code-block:: c++
+
+  #if defined(__clang__) && defined(__CUDA__) && !defined(__CUDA_ARCH__)
+  // clang compiling CUDA code, host mode.
+  #endif
+
+  #if defined(__clang__) && defined(__CUDA__) && defined(__CUDA_ARCH__)
+  // clang compiling CUDA code, device mode.
+  #endif
+
+Both clang and nvcc define ``__CUDACC__`` during CUDA compilation.  You can
+detect NVCC specifically by looking for ``__NVCC__``.
+
+Dialect Differences Between clang and nvcc
+==========================================
+
+There is no formal CUDA spec, and clang and nvcc speak slightly different
+dialects of the language.  Below, we describe some of the differences.
+
+This section is painful; hopefully you can skip this section and live your life
+blissfully unaware.
+
+Compilation Models
+------------------
+
+Most of the differences between clang and nvcc stem from the different
+compilation models used by clang and nvcc.  nvcc uses *split compilation*,
+which works roughly as follows:
+
+ * Run a preprocessor over the input ``.cu`` file to split it into two source
+   files: ``H``, containing source code for the host, and ``D``, containing
+   source code for the device.
+
+ * For each GPU architecture ``arch`` that we're compiling for, do:
+
+   * Compile ``D`` using nvcc proper.  The result of this is a ``ptx`` file for
+     ``P_arch``.
+
+   * Optionally, invoke ``ptxas``, the PTX assembler, to generate a file,
+     ``S_arch``, containing GPU machine code (SASS) for ``arch``.
+
+ * Invoke ``fatbin`` to combine all ``P_arch`` and ``S_arch`` files into a
+   single "fat binary" file, ``F``.
+
+ * Compile ``H`` using an external host compiler (gcc, clang, or whatever you
+   like).  ``F`` is packaged up into a header file which is force-included into
+   ``H``; nvcc generates code that calls into this header to e.g. launch
+   kernels.
+
+clang uses *merged parsing*.  This is similar to split compilation, except all
+of the host and device code is present and must be semantically-correct in both
+compilation steps.
+
+  * For each GPU architecture ``arch`` that we're compiling for, do:
+
+    * Compile the input ``.cu`` file for device, using clang.  ``__host__`` code
+      is parsed and must be semantically correct, even though we're not
+      generating code for the host at this time.
+
+      The output of this step is a ``ptx`` file ``P_arch``.
+
+    * Invoke ``ptxas`` to generate a SASS file, ``S_arch``.  Note that, unlike
+      nvcc, clang always generates SASS code.
+
+  * Invoke ``fatbin`` to combine all ``P_arch`` and ``S_arch`` files into a
+    single fat binary file, ``F``.
+
+  * Compile ``H`` using clang.  ``__device__`` code is parsed and must be
+    semantically correct, even though we're not generating code for the device
+    at this time.
+
+    ``F`` is passed to this compilation, and clang includes it in a special ELF
+    section, where it can be found by tools like ``cuobjdump``.
+
+(You may ask at this point, why does clang need to parse the input file
+multiple times?  Why not parse it just once, and then use the AST to generate
+code for the host and each device architecture?
+
+Unfortunately this can't work because we have to define different macros during
+host compilation and during device compilation for each GPU architecture.)
+
+clang's approach allows it to be highly robust to C++ edge cases, as it doesn't
+need to decide at an early stage which declarations to keep and which to throw
+away.  But it has some consequences you should be aware of.
+
+Overloading Based on ``__host__`` and ``__device__`` Attributes
+---------------------------------------------------------------
+
+Let "H", "D", and "HD" stand for "``__host__`` functions", "``__device__``
+functions", and "``__host__ __device__`` functions", respectively.  Functions
+with no attributes behave the same as H.
+
+nvcc does not allow you to create H and D functions with the same signature:
+
+.. code-block:: c++
+
+  // nvcc: error - function "foo" has already been defined
+  __host__ void foo() {}
+  __device__ void foo() {}
+
+However, nvcc allows you to "overload" H and D functions with different
+signatures:
+
+.. code-block:: c++
+
+  // nvcc: no error
+  __host__ void foo(int) {}
+  __device__ void foo() {}
+
+In clang, the ``__host__`` and ``__device__`` attributes are part of a
+function's signature, and so it's legal to have H and D functions with
+(otherwise) the same signature:
+
+.. code-block:: c++
+
+  // clang: no error
+  __host__ void foo() {}
+  __device__ void foo() {}
+
+HD functions cannot be overloaded by H or D functions with the same signature:
+
+.. code-block:: c++
+
+  // nvcc: error - function "foo" has already been defined
+  // clang: error - redefinition of 'foo'
+  __host__ __device__ void foo() {}
+  __device__ void foo() {}
+
+  // nvcc: no error
+  // clang: no error
+  __host__ __device__ void bar(int) {}
+  __device__ void bar() {}
+
+When resolving an overloaded function, clang considers the host/device
+attributes of the caller and callee.  These are used as a tiebreaker during
+overload resolution.  See `IdentifyCUDAPreference
+<http://clang.llvm.org/doxygen/SemaCUDA_8cpp.html>`_ for the full set of rules,
+but at a high level they are:
+
+ * D functions prefer to call other Ds.  HDs are given lower priority.
+
+ * Similarly, H functions prefer to call other Hs, or ``__global__`` functions
+   (with equal priority).  HDs are given lower priority.
+
+ * HD functions prefer to call other HDs.
+
+   When compiling for device, HDs will call Ds with lower priority than HD, and
+   will call Hs with still lower priority.  If it's forced to call an H, the
+   program is malformed if we emit code for this HD function.  We call this the
+   "wrong-side rule", see example below.
+
+   The rules are symmetrical when compiling for host.
+
+Some examples:
+
+.. code-block:: c++
+
+   __host__ void foo();
+   __device__ void foo();
+
+   __host__ void bar();
+   __host__ __device__ void bar();
+
+   __host__ void test_host() {
+     foo();  // calls H overload
+     bar();  // calls H overload
+   }
+
+   __device__ void test_device() {
+     foo();  // calls D overload
+     bar();  // calls HD overload
+   }
+
+   __host__ __device__ void test_hd() {
+     foo();  // calls H overload when compiling for host, otherwise D overload
+     bar();  // always calls HD overload
+   }
+
+Wrong-side rule example:
+
+.. code-block:: c++
+
+  __host__ void host_only();
+
+  // We don't codegen inline functions unless they're referenced by a
+  // non-inline function.  inline_hd1() is called only from the host side, so
+  // does not generate an error.  inline_hd2() is called from the device side,
+  // so it generates an error.
+  inline __host__ __device__ void inline_hd1() { host_only(); }  // no error
+  inline __host__ __device__ void inline_hd2() { host_only(); }  // error
+
+  __host__ void host_fn() { inline_hd1(); }
+  __device__ void device_fn() { inline_hd2(); }
+
+  // This function is not inline, so it's always codegen'ed on both the host
+  // and the device.  Therefore, it generates an error.
+  __host__ __device__ void not_inline_hd() { host_only(); }
+
+For the purposes of the wrong-side rule, templated functions also behave like
+``inline`` functions: They aren't codegen'ed unless they're instantiated
+(usually as part of the process of invoking them).
+
+clang's behavior with respect to the wrong-side rule matches nvcc's, except
+nvcc only emits a warning for ``not_inline_hd``; device code is allowed to call
+``not_inline_hd``.  In its generated code, nvcc may omit ``not_inline_hd``'s
+call to ``host_only`` entirely, or it may try to generate code for
+``host_only`` on the device.  What you get seems to depend on whether or not
+the compiler chooses to inline ``host_only``.
+
+Member functions, including constructors, may be overloaded using H and D
+attributes.  However, destructors cannot be overloaded.
+
+Using a Different Class on Host/Device
+--------------------------------------
+
+Occasionally you may want to have a class with different host/device versions.
+
+If all of the class's members are the same on the host and device, you can just
+provide overloads for the class's member functions.
+
+However, if you want your class to have different members on host/device, you
+won't be able to provide working H and D overloads in both classes. In this
+case, clang is likely to be unhappy with you.
+
+.. code-block:: c++
+
+  #ifdef __CUDA_ARCH__
+  struct S {
+    __device__ void foo() { /* use device_only */ }
+    int device_only;
+  };
+  #else
+  struct S {
+    __host__ void foo() { /* use host_only */ }
+    double host_only;
+  };
+
+  __device__ void test() {
+    S s;
+    // clang generates an error here, because during host compilation, we
+    // have ifdef'ed away the __device__ overload of S::foo().  The __device__
+    // overload must be present *even during host compilation*.
+    S.foo();
+  }
+  #endif
+
+We posit that you don't really want to have classes with different members on H
+and D.  For example, if you were to pass one of these as a parameter to a
+kernel, it would have a different layout on H and D, so would not work
+properly.
+
+To make code like this compatible with clang, we recommend you separate it out
+into two classes.  If you need to write code that works on both host and
+device, consider writing an overloaded wrapper function that returns different
+types on host and device.
+
+.. code-block:: c++
+
+  struct HostS { ... };
+  struct DeviceS { ... };
+
+  __host__ HostS MakeStruct() { return HostS(); }
+  __device__ DeviceS MakeStruct() { return DeviceS(); }
+
+  // Now host and device code can call MakeStruct().
+
+Unfortunately, this idiom isn't compatible with nvcc, because it doesn't allow
+you to overload based on the H/D attributes.  Here's an idiom that works with
+both clang and nvcc:
+
+.. code-block:: c++
+
+  struct HostS { ... };
+  struct DeviceS { ... };
+
+  #ifdef __NVCC__
+    #ifndef __CUDA_ARCH__
+      __host__ HostS MakeStruct() { return HostS(); }
+    #else
+      __device__ DeviceS MakeStruct() { return DeviceS(); }
+    #endif
+  #else
+    __host__ HostS MakeStruct() { return HostS(); }
+    __device__ DeviceS MakeStruct() { return DeviceS(); }
+  #endif
+
+  // Now host and device code can call MakeStruct().
+
+Hopefully you don't have to do this sort of thing often.
+
+Optimizations
+=============
+
+Modern CPUs and GPUs are architecturally quite different, so code that's fast
+on a CPU isn't necessarily fast on a GPU.  We've made a number of changes to
+LLVM to make it generate good GPU code.  Among these changes are:
+
+* `Straight-line scalar optimizations <https://goo.gl/4Rb9As>`_ -- These
+  reduce redundancy within straight-line code.
+
+* `Aggressive speculative execution
+  <http://llvm.org/docs/doxygen/html/SpeculativeExecution_8cpp_source.html>`_
+  -- This is mainly for promoting straight-line scalar optimizations, which are
+  most effective on code along dominator paths.
+
+* `Memory space inference
+  <http://llvm.org/doxygen/NVPTXInferAddressSpaces_8cpp_source.html>`_ --
+  In PTX, we can operate on pointers that are in a paricular "address space"
+  (global, shared, constant, or local), or we can operate on pointers in the
+  "generic" address space, which can point to anything.  Operations in a
+  non-generic address space are faster, but pointers in CUDA are not explicitly
+  annotated with their address space, so it's up to LLVM to infer it where
+  possible.
+
+* `Bypassing 64-bit divides
+  <http://llvm.org/docs/doxygen/html/BypassSlowDivision_8cpp_source.html>`_ --
+  This was an existing optimization that we enabled for the PTX backend.
+
+  64-bit integer divides are much slower than 32-bit ones on NVIDIA GPUs.
+  Many of the 64-bit divides in our benchmarks have a divisor and dividend
+  which fit in 32-bits at runtime. This optimization provides a fast path for
+  this common case.
+
+* Aggressive loop unrooling and function inlining -- Loop unrolling and
+  function inlining need to be more aggressive for GPUs than for CPUs because
+  control flow transfer in GPU is more expensive. More aggressive unrolling and
+  inlining also promote other optimizations, such as constant propagation and
+  SROA, which sometimes speed up code by over 10x.
+
+  (Programmers can force unrolling and inline using clang's `loop unrolling pragmas
+  <http://clang.llvm.org/docs/AttributeReference.html#pragma-unroll-pragma-nounroll>`_
+  and ``__attribute__((always_inline))``.)
+
+Publication
+===========
+
+The team at Google published a paper in CGO 2016 detailing the optimizations
+they'd made to clang/LLVM.  Note that "gpucc" is no longer a meaningful name:
+The relevant tools are now just vanilla clang/LLVM.
+
+| `gpucc: An Open-Source GPGPU Compiler <http://dl.acm.org/citation.cfm?id=2854041>`_
+| Jingyue Wu, Artem Belevich, Eli Bendersky, Mark Heffernan, Chris Leary, Jacques Pienaar, Bjarke Roune, Rob Springer, Xuetian Weng, Robert Hundt
+| *Proceedings of the 2016 International Symposium on Code Generation and Optimization (CGO 2016)*
+|
+| `Slides from the CGO talk <http://wujingyue.github.io/docs/gpucc-talk.pdf>`_
+|
+| `Tutorial given at CGO <http://wujingyue.github.io/docs/gpucc-tutorial.pdf>`_
+
+Obtaining Help
+==============
+
+To obtain help on LLVM in general and its CUDA support, see `the LLVM
+community <http://llvm.org/docs/#mailing-lists>`_.

Added: www-releases/trunk/8.0.1/docs/_sources/CompilerWriterInfo.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.1/docs/_sources/CompilerWriterInfo.rst.txt?rev=368037&view=auto
==============================================================================
--- www-releases/trunk/8.0.1/docs/_sources/CompilerWriterInfo.rst.txt (added)
+++ www-releases/trunk/8.0.1/docs/_sources/CompilerWriterInfo.rst.txt Tue Aug  6 06:51:02 2019
@@ -0,0 +1,158 @@
+========================================================
+Architecture & Platform Information for Compiler Writers
+========================================================
+
+.. contents::
+   :local:
+
+.. note::
+
+  This document is a work-in-progress.  Additions and clarifications are
+  welcome.
+
+Hardware
+========
+
+AArch64 & ARM
+-------------
+
+* `ARMv8-A Architecture Reference Manual <http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.ddi0487a.h/index.html>`_ (authentication required, free sign-up). This document covers both AArch64 and ARM instructions
+
+* `ARMv7-M Architecture Reference Manual <http://infocenter.arm.com/help/topic/com.arm.doc.ddi0403e.b/index.html>`_ (authentication required, free sign-up). This covers the Thumb2-only microcontrollers
+
+* `ARMv6-M Architecture Reference Manual <http://infocenter.arm.com/help/topic/com.arm.doc.ddi0419c/index.html>`_ (authentication required, free sign-up). This covers the Thumb1-only microcontrollers
+
+* `ARM C Language Extensions <http://infocenter.arm.com/help/topic/com.arm.doc.ihi0053c/IHI0053C_acle_2_0.pdf>`_
+
+* AArch32 `ABI Addenda and Errata <http://infocenter.arm.com/help/topic/com.arm.doc.ihi0045d/IHI0045D_ABI_addenda.pdf>`_
+
+Itanium (ia64)
+--------------
+
+* `Itanium documentation <http://developer.intel.com/design/itanium2/documentation.htm>`_
+
+Lanai
+-----
+
+* `Lanai Instruction Set Architecture <http://g.co/lanai/isa>`_
+
+
+MIPS
+----
+
+* `MIPS Processor Architecture <https://www.mips.com/products/>`_
+
+* `MIPS 64-bit ELF Object File Specification <http://techpubs.sgi.com/library/manuals/4000/007-4658-001/pdf/007-4658-001.pdf>`_
+
+PowerPC
+-------
+
+IBM - Official manuals and docs
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* `Power Instruction Set Architecture, Versions 2.03 through 2.06 (authentication required, free sign-up) <https://www.power.org/technology-introduction/standards-specifications>`_
+
+* `PowerPC Compiler Writer's Guide <http://www.ibm.com/chips/techlib/techlib.nsf/techdocs/852569B20050FF7785256996007558C6>`_
+
+* `Intro to PowerPC Architecture <http://www.ibm.com/developerworks/linux/library/l-powarch/>`_
+
+* `PowerPC Processor Manuals (embedded) <http://www.ibm.com/chips/techlib/techlib.nsf/products/PowerPC>`_
+
+* `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>`_
+
+Other documents, collections, notes
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* `PowerPC ABI documents <http://penguinppc.org/dev/#library>`_
+* `PowerPC64 alignment of long doubles (from GCC) <http://gcc.gnu.org/ml/gcc-patches/2003-09/msg00997.html>`_
+* `Long branch stubs for powerpc64-linux (from binutils) <http://sources.redhat.com/ml/binutils/2002-04/msg00573.html>`_
+
+AMDGPU
+------
+
+Refer to :doc:`AMDGPUUsage` for additional documentation.
+
+RISC-V
+------
+* `RISC-V User-Level ISA Specification <https://riscv.org/specifications/>`_
+
+SPARC
+-----
+
+* `SPARC standards <http://sparc.org/standards>`_
+* `SPARC V9 ABI <http://sparc.org/standards/64.psabi.1.35.ps.Z>`_
+* `SPARC V8 ABI <http://sparc.org/standards/psABI3rd.pdf>`_
+
+SystemZ
+-------
+
+* `z/Architecture Principles of Operation (registration required, free sign-up) <http://www-01.ibm.com/support/docview.wss?uid=isg2b9de5f05a9d57819852571c500428f9a>`_
+
+X86
+---
+
+* `AMD processor manuals <http://developer.amd.com/resources/developer-guides-manuals/>`_
+* `Intel 64 and IA-32 manuals <http://www.intel.com/content/www/us/en/processors/architectures-software-developer-manuals.html>`_
+* `Intel Itanium documentation <http://www.intel.com/design/itanium/documentation.htm?iid=ipp_srvr_proc_itanium2+techdocs>`_
+* `X86 and X86-64 SysV psABI <https://github.com/hjl-tools/x86-psABI/wiki/X86-psABI>`_
+* `Calling conventions for different C++ compilers and operating systems  <http://www.agner.org/optimize/calling_conventions.pdf>`_
+
+XCore
+-----
+
+* `The XMOS XS1 Architecture (ISA) <https://www.xmos.com/en/download/public/The-XMOS-XS1-Architecture%28X7879A%29.pdf>`_
+* `Tools Development Guide (includes ABI) <https://www.xmos.com/download/public/Tools-Development-Guide%28X9114A%29.pdf>`_
+
+Hexagon
+-------
+
+* `Hexagon Programmer's Reference Manuals and Hexagon ABI Specification (registration required, free sign-up) <https://developer.qualcomm.com/software/hexagon-dsp-sdk/tools>`_
+
+Other relevant lists
+--------------------
+
+* `GCC reading list <http://gcc.gnu.org/readings.html>`_
+
+ABI
+===
+
+* `System V Application Binary Interface <http://www.sco.com/developers/gabi/latest/contents.html>`_
+* `Itanium C++ ABI <http://itanium-cxx-abi.github.io/cxx-abi/>`_
+
+Linux
+-----
+
+* `Linux extensions to gabi <https://github.com/hjl-tools/linux-abi/wiki/Linux-Extensions-to-gABI>`_
+* `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 Architecture <http://infocenter.arm.com/help/topic/com.arm.doc.ihi0044e/IHI0044E_aaelf.pdf>`_
+* `ELF for the ARM 64-bit Architecture (AArch64) <http://infocenter.arm.com/help/topic/com.arm.doc.ihi0056a/IHI0056A_aaelf64.pdf>`_
+* `System z ELF ABI Supplement <http://legacy.redhat.com/pub/redhat/linux/7.1/es/os/s390x/doc/lzsabi0.pdf>`_
+
+OS X
+----
+
+* `Mach-O Runtime Architecture <http://developer.apple.com/documentation/Darwin/RuntimeArchitecture-date.html>`_
+* `Notes on Mach-O ABI <http://www.unsanity.org/archives/000044.php>`_
+
+Windows
+-------
+
+* `Microsoft PE/COFF Specification <http://www.microsoft.com/whdc/system/platform/firmware/pecoff.mspx>`_
+
+NVPTX
+=====
+
+* `CUDA Documentation <http://docs.nvidia.com/cuda/index.html>`_ includes the PTX
+  ISA and Driver API documentation
+
+Miscellaneous Resources
+=======================
+
+* `Executable File Format library <http://www.nondot.org/sabre/os/articles/ExecutableFileFormats/>`_
+
+* `GCC prefetch project <http://gcc.gnu.org/projects/prefetch.html>`_ page has a
+  good survey of the prefetching capabilities of a variety of modern
+  processors.

Added: www-releases/trunk/8.0.1/docs/_sources/Contributing.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.1/docs/_sources/Contributing.rst.txt?rev=368037&view=auto
==============================================================================
--- www-releases/trunk/8.0.1/docs/_sources/Contributing.rst.txt (added)
+++ www-releases/trunk/8.0.1/docs/_sources/Contributing.rst.txt Tue Aug  6 06:51:02 2019
@@ -0,0 +1,127 @@
+==================================
+Contributing to LLVM
+==================================
+
+
+Thank you for your interest in contributing to LLVM! There are multiple ways to
+contribute, and we appreciate all contributions. In case you
+have questions, you can either use the `Developer's List (llvm-dev)`_
+or the #llvm channel on `irc.oftc.net`_.
+
+If you want to contribute code, please familiarize yourself with the :doc:`DeveloperPolicy`.
+
+.. contents::
+  :local:
+
+
+Ways to Contribute
+==================
+
+Bug Reports
+-----------
+If you are working with LLVM and run into a bug, we definitely want to know
+about it. Please let us know and follow the instructions in
+:doc:`HowToSubmitABug`  to create a bug report.
+
+Bug Fixes
+---------
+If you are interested in contributing code to LLVM, bugs labeled with the
+`beginner keyword`_ in the `bug tracker`_ are a good way to get familiar with
+the code base. If you are interested in fixing a bug, please create an account
+for the bug tracker and assign it to yourself, to let people know you are working on
+it.
+
+Then try to reproduce and fix the bug with upstream LLVM. Start by building
+LLVM from source as described in :doc:`GettingStarted` and
+and use the built binaries to reproduce the failure described in the bug. Use
+a debug build (`-DCMAKE_BUILD_TYPE=Debug`) or a build with assertions
+(`-DLLVM_ENABLE_ASSERTIONS=On`, enabled for Debug builds).
+
+Bigger Pieces of Work
+---------------------
+In case you are interested in taking on a bigger piece of work, a list of
+interesting projects is maintained at the `LLVM's Open Projects page`_. In case
+you are interested in working on any of these projects, please send a mail to
+the `LLVM Developer's mailing list`_, so that we know the project is being
+worked on.
+
+
+How to Submit a Patch
+=====================
+Once you have a patch ready, it is time to submit it. The patch should:
+
+* include a small unit test
+* conform to the :doc:`CodingStandards`. You can use the `clang-format-diff.py`_ or `git-clang-format`_ tools to automatically format your patch properly.
+* not contain any unrelated changes
+* be an isolated change. Independent changes should be submitted as separate patches as this makes reviewing easier.
+
+To get a patch accepted, it has to be reviewed by the LLVM community. This can
+be done using `LLVM's Phabricator`_ or the llvm-commits mailing list.
+Please  follow :ref:`Phabricator#requesting-a-review-via-the-web-interface <phabricator-request-review-web>`
+to request a review using Phabricator.
+
+To make sure the right people see your patch, please select suitable reviewers
+and add them to your patch when requesting a review. Suitable reviewers are the
+code owner (see CODE_OWNERS.txt) and other people doing work in the area your
+patch touches. If you are using Phabricator, add them to the `Reviewers` field
+when creating a review and if you are using `llvm-commits`, add them to the CC of
+your email.
+
+A reviewer may request changes or ask questions during the review. If you are
+uncertain on how to provide test cases, documentation, etc., feel free to ask
+for guidance during the review. Please address the feedback and re-post an
+updated version of your patch. This cycle continues until all requests and comments
+have been addressed and a reviewer accepts the patch with a `Looks good to me` or `LGTM`.
+Once that is done the change can be committed. If you do not have commit
+access, please let people know during the review and someone should commit it
+on your behalf.
+
+If you have received no comments on your patch for a week, you can request a
+review by 'ping'ing a patch by responding to the email thread containing the
+patch, or the Phabricator review with "Ping." The common courtesy 'ping' rate
+is once a week. Please remember that you are asking for valuable time from other
+professional developers.
+
+
+Helpful Information About LLVM
+==============================
+:doc:`LLVM's documentation <index>` provides a wealth of information about LLVM's internals as
+well as various user guides. The pages listed below should provide a good overview
+of LLVM's high-level design, as well as its internals:
+
+: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:`LangRef`
+  Defines the LLVM intermediate representation.
+
+:doc:`ProgrammersManual`
+  Introduction to the general layout of the LLVM sourcebase, important classes
+  and APIs, and some tips & tricks.
+
+:ref:`index-subsystem-docs`
+  A collection of pages documenting various subsystems of LLVM.
+
+`LLVM for Grad Students`__
+  This is an introduction to the LLVM infrastructure by Adrian Sampson. While it
+  has been written for grad students, it provides  a good, compact overview of
+  LLVM's architecture, LLVM's IR and how to write a new pass.
+
+  .. __: http://www.cs.cornell.edu/~asampson/blog/llvm.html
+
+`Intro to LLVM`__
+  Book chapter providing a compiler hacker's introduction to LLVM.
+
+  .. __: http://www.aosabook.org/en/llvm.html
+
+.. _Developer's List (llvm-dev): http://lists.llvm.org/mailman/listinfo/llvm-dev
+.. _irc.oftc.net: irc://irc.oftc.net/llvm
+.. _beginner keyword: https://bugs.llvm.org/buglist.cgi?bug_status=NEW&bug_status=REOPENED&keywords=beginner%2C%20&keywords_type=allwords&list_id=130748&query_format=advanced&resolution=---
+.. _bug tracker: https://bugs.llvm.org
+.. _clang-format-diff.py: https://reviews.llvm.org/source/clang/browse/cfe/trunk/tools/clang-format/clang-format-diff.py
+.. _git-clang-format: https://reviews.llvm.org/source/clang/browse/cfe/trunk/tools/clang-format/git-clang-format
+.. _LLVM's Phabricator: https://reviews.llvm.org/
+.. _LLVM's Open Projects page: https://llvm.org/OpenProjects.html#what
+.. _LLVM Developer's mailing list: http://lists.llvm.org/mailman/listinfo/llvm-dev

Added: www-releases/trunk/8.0.1/docs/_sources/Coroutines.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.1/docs/_sources/Coroutines.rst.txt?rev=368037&view=auto
==============================================================================
--- www-releases/trunk/8.0.1/docs/_sources/Coroutines.rst.txt (added)
+++ www-releases/trunk/8.0.1/docs/_sources/Coroutines.rst.txt Tue Aug  6 06:51:02 2019
@@ -0,0 +1,1319 @@
+=====================================
+Coroutines in LLVM
+=====================================
+
+.. contents::
+   :local:
+   :depth: 3
+
+.. warning::
+  This is a work in progress. Compatibility across LLVM releases is not 
+  guaranteed.
+
+Introduction
+============
+
+.. _coroutine handle:
+
+LLVM coroutines are functions that have one or more `suspend points`_. 
+When a suspend point is reached, the execution of a coroutine is suspended and
+control is returned back to its caller. A suspended coroutine can be resumed 
+to continue execution from the last suspend point or it can be destroyed. 
+
+In the following example, we call function `f` (which may or may not be a 
+coroutine itself) that returns a handle to a suspended coroutine 
+(**coroutine handle**) that is used by `main` to resume the coroutine twice and
+then destroy it:
+
+.. code-block:: llvm
+
+  define i32 @main() {
+  entry:
+    %hdl = call i8* @f(i32 4)
+    call void @llvm.coro.resume(i8* %hdl)
+    call void @llvm.coro.resume(i8* %hdl)
+    call void @llvm.coro.destroy(i8* %hdl)
+    ret i32 0
+  }
+
+.. _coroutine frame:
+
+In addition to the function stack frame which exists when a coroutine is 
+executing, there is an additional region of storage that contains objects that 
+keep the coroutine state when a coroutine is suspended. This region of storage
+is called **coroutine frame**. It is created when a coroutine is called and 
+destroyed when a coroutine runs to completion or destroyed by a call to 
+the `coro.destroy`_ intrinsic. 
+
+An LLVM coroutine is represented as an LLVM function that has calls to
+`coroutine intrinsics`_ defining the structure of the coroutine.
+After lowering, a coroutine is split into several
+functions that represent three different ways of how control can enter the 
+coroutine: 
+
+1. a ramp function, which represents an initial invocation of the coroutine that
+   creates the coroutine frame and executes the coroutine code until it 
+   encounters a suspend point or reaches the end of the function;
+
+2. a coroutine resume function that is invoked when the coroutine is resumed;
+
+3. a coroutine destroy function that is invoked when the coroutine is destroyed.
+
+.. note:: Splitting out resume and destroy functions are just one of the 
+   possible ways of lowering the coroutine. We chose it for initial 
+   implementation as it matches closely the mental model and results in 
+   reasonably nice code.
+
+Coroutines by Example
+=====================
+
+Coroutine Representation
+------------------------
+
+Let's look at an example of an LLVM coroutine with the behavior sketched
+by the following pseudo-code.
+
+.. code-block:: c++
+
+  void *f(int n) {
+     for(;;) {
+       print(n++);
+       <suspend> // returns a coroutine handle on first suspend
+     }     
+  } 
+
+This coroutine calls some function `print` with value `n` as an argument and
+suspends execution. Every time this coroutine resumes, it calls `print` again with an argument one bigger than the last time. This coroutine never completes by itself and must be destroyed explicitly. If we use this coroutine with 
+a `main` shown in the previous section. It will call `print` with values 4, 5 
+and 6 after which the coroutine will be destroyed.
+
+The LLVM IR for this coroutine looks like this:
+
+.. code-block:: llvm
+
+  define i8* @f(i32 %n) {
+  entry:
+    %id = call token @llvm.coro.id(i32 0, i8* null, i8* null, i8* null)
+    %size = call i32 @llvm.coro.size.i32()
+    %alloc = call i8* @malloc(i32 %size)
+    %hdl = call noalias i8* @llvm.coro.begin(token %id, i8* %alloc)
+    br label %loop
+  loop:
+    %n.val = phi i32 [ %n, %entry ], [ %inc, %loop ]
+    %inc = add nsw i32 %n.val, 1
+    call void @print(i32 %n.val)
+    %0 = call i8 @llvm.coro.suspend(token none, i1 false)
+    switch i8 %0, label %suspend [i8 0, label %loop
+                                  i8 1, label %cleanup]
+  cleanup:
+    %mem = call i8* @llvm.coro.free(token %id, i8* %hdl)
+    call void @free(i8* %mem)
+    br label %suspend
+  suspend:
+    %unused = call i1 @llvm.coro.end(i8* %hdl, i1 false)
+    ret i8* %hdl
+  }
+
+The `entry` block establishes the coroutine frame. The `coro.size`_ intrinsic is
+lowered to a constant representing the size required for the coroutine frame. 
+The `coro.begin`_ intrinsic initializes the coroutine frame and returns the 
+coroutine handle. The second parameter of `coro.begin` is given a block of memory 
+to be used if the coroutine frame needs to be allocated dynamically.
+The `coro.id`_ intrinsic serves as coroutine identity useful in cases when the
+`coro.begin`_ intrinsic get duplicated by optimization passes such as 
+jump-threading.
+
+The `cleanup` block destroys the coroutine frame. The `coro.free`_ intrinsic, 
+given the coroutine handle, returns a pointer of the memory block to be freed or
+`null` if the coroutine frame was not allocated dynamically. The `cleanup` 
+block is entered when coroutine runs to completion by itself or destroyed via
+call to the `coro.destroy`_ intrinsic.
+
+The `suspend` block contains code to be executed when coroutine runs to 
+completion or suspended. The `coro.end`_ intrinsic marks the point where 
+a coroutine needs to return control back to the caller if it is not an initial 
+invocation of the coroutine. 
+
+The `loop` blocks represents the body of the coroutine. The `coro.suspend`_ 
+intrinsic in combination with the following switch indicates what happens to 
+control flow when a coroutine is suspended (default case), resumed (case 0) or 
+destroyed (case 1).
+
+Coroutine Transformation
+------------------------
+
+One of the steps of coroutine lowering is building the coroutine frame. The
+def-use chains are analyzed to determine which objects need be kept alive across
+suspend points. In the coroutine shown in the previous section, use of virtual register 
+`%n.val` is separated from the definition by a suspend point, therefore, it 
+cannot reside on the stack frame since the latter goes away once the coroutine 
+is suspended and control is returned back to the caller. An i32 slot is 
+allocated in the coroutine frame and `%n.val` is spilled and reloaded from that
+slot as needed.
+
+We also store addresses of the resume and destroy functions so that the 
+`coro.resume` and `coro.destroy` intrinsics can resume and destroy the coroutine
+when its identity cannot be determined statically at compile time. For our 
+example, the coroutine frame will be:
+
+.. code-block:: llvm
+
+  %f.frame = type { void (%f.frame*)*, void (%f.frame*)*, i32 }
+
+After resume and destroy parts are outlined, function `f` will contain only the 
+code responsible for creation and initialization of the coroutine frame and 
+execution of the coroutine until a suspend point is reached:
+
+.. code-block:: llvm
+
+  define i8* @f(i32 %n) {
+  entry:
+    %id = call token @llvm.coro.id(i32 0, i8* null, i8* null, i8* null)
+    %alloc = call noalias i8* @malloc(i32 24)
+    %0 = call noalias i8* @llvm.coro.begin(token %id, i8* %alloc)
+    %frame = bitcast i8* %0 to %f.frame*
+    %1 = getelementptr %f.frame, %f.frame* %frame, i32 0, i32 0
+    store void (%f.frame*)* @f.resume, void (%f.frame*)** %1
+    %2 = getelementptr %f.frame, %f.frame* %frame, i32 0, i32 1
+    store void (%f.frame*)* @f.destroy, void (%f.frame*)** %2
+   
+    %inc = add nsw i32 %n, 1
+    %inc.spill.addr = getelementptr inbounds %f.Frame, %f.Frame* %FramePtr, i32 0, i32 2
+    store i32 %inc, i32* %inc.spill.addr
+    call void @print(i32 %n)
+   
+    ret i8* %frame
+  }
+
+Outlined resume part of the coroutine will reside in function `f.resume`:
+
+.. code-block:: llvm
+
+  define internal fastcc void @f.resume(%f.frame* %frame.ptr.resume) {
+  entry:
+    %inc.spill.addr = getelementptr %f.frame, %f.frame* %frame.ptr.resume, i64 0, i32 2
+    %inc.spill = load i32, i32* %inc.spill.addr, align 4
+    %inc = add i32 %n.val, 1
+    store i32 %inc, i32* %inc.spill.addr, align 4
+    tail call void @print(i32 %inc)
+    ret void
+  }
+
+Whereas function `f.destroy` will contain the cleanup code for the coroutine:
+
+.. code-block:: llvm
+
+  define internal fastcc void @f.destroy(%f.frame* %frame.ptr.destroy) {
+  entry:
+    %0 = bitcast %f.frame* %frame.ptr.destroy to i8*
+    tail call void @free(i8* %0)
+    ret void
+  }
+
+Avoiding Heap Allocations
+-------------------------
+ 
+A particular coroutine usage pattern, which is illustrated by the `main` 
+function in the overview section, where a coroutine is created, manipulated and 
+destroyed by the same calling function, is common for coroutines implementing
+RAII idiom and is suitable for allocation elision optimization which avoid 
+dynamic allocation by storing the coroutine frame as a static `alloca` in its 
+caller.
+
+In the entry block, we will call `coro.alloc`_ intrinsic that will return `true`
+when dynamic allocation is required, and `false` if dynamic allocation is 
+elided.
+
+.. code-block:: llvm
+
+  entry:
+    %id = call token @llvm.coro.id(i32 0, i8* null, i8* null, i8* null)
+    %need.dyn.alloc = call i1 @llvm.coro.alloc(token %id)
+    br i1 %need.dyn.alloc, label %dyn.alloc, label %coro.begin
+  dyn.alloc:
+    %size = call i32 @llvm.coro.size.i32()
+    %alloc = call i8* @CustomAlloc(i32 %size)
+    br label %coro.begin
+  coro.begin:
+    %phi = phi i8* [ null, %entry ], [ %alloc, %dyn.alloc ]
+    %hdl = call noalias i8* @llvm.coro.begin(token %id, i8* %phi)
+
+In the cleanup block, we will make freeing the coroutine frame conditional on
+`coro.free`_ intrinsic. If allocation is elided, `coro.free`_ returns `null`
+thus skipping the deallocation code:
+
+.. code-block:: llvm
+
+  cleanup:
+    %mem = call i8* @llvm.coro.free(token %id, i8* %hdl)
+    %need.dyn.free = icmp ne i8* %mem, null
+    br i1 %need.dyn.free, label %dyn.free, label %if.end
+  dyn.free:
+    call void @CustomFree(i8* %mem)
+    br label %if.end
+  if.end:
+    ...
+
+With allocations and deallocations represented as described as above, after
+coroutine heap allocation elision optimization, the resulting main will be:
+
+.. code-block:: llvm
+
+  define i32 @main() {
+  entry:
+    call void @print(i32 4)
+    call void @print(i32 5)
+    call void @print(i32 6)
+    ret i32 0
+  }
+
+Multiple Suspend Points
+-----------------------
+
+Let's consider the coroutine that has more than one suspend point:
+
+.. code-block:: c++
+
+  void *f(int n) {
+     for(;;) {
+       print(n++);
+       <suspend>
+       print(-n);
+       <suspend>
+     }
+  }
+
+Matching LLVM code would look like (with the rest of the code remaining the same
+as the code in the previous section):
+
+.. code-block:: llvm
+
+  loop:
+    %n.addr = phi i32 [ %n, %entry ], [ %inc, %loop.resume ]
+    call void @print(i32 %n.addr) #4
+    %2 = call i8 @llvm.coro.suspend(token none, i1 false)
+    switch i8 %2, label %suspend [i8 0, label %loop.resume
+                                  i8 1, label %cleanup]
+  loop.resume:
+    %inc = add nsw i32 %n.addr, 1
+    %sub = xor i32 %n.addr, -1
+    call void @print(i32 %sub)
+    %3 = call i8 @llvm.coro.suspend(token none, i1 false)
+    switch i8 %3, label %suspend [i8 0, label %loop
+                                  i8 1, label %cleanup]
+
+In this case, the coroutine frame would include a suspend index that will 
+indicate at which suspend point the coroutine needs to resume. The resume 
+function will use an index to jump to an appropriate basic block and will look 
+as follows:
+
+.. code-block:: llvm
+
+  define internal fastcc void @f.Resume(%f.Frame* %FramePtr) {
+  entry.Resume:
+    %index.addr = getelementptr inbounds %f.Frame, %f.Frame* %FramePtr, i64 0, i32 2
+    %index = load i8, i8* %index.addr, align 1
+    %switch = icmp eq i8 %index, 0
+    %n.addr = getelementptr inbounds %f.Frame, %f.Frame* %FramePtr, i64 0, i32 3
+    %n = load i32, i32* %n.addr, align 4
+    br i1 %switch, label %loop.resume, label %loop
+
+  loop.resume:
+    %sub = xor i32 %n, -1
+    call void @print(i32 %sub)
+    br label %suspend
+  loop:
+    %inc = add nsw i32 %n, 1
+    store i32 %inc, i32* %n.addr, align 4
+    tail call void @print(i32 %inc)
+    br label %suspend
+
+  suspend:
+    %storemerge = phi i8 [ 0, %loop ], [ 1, %loop.resume ]
+    store i8 %storemerge, i8* %index.addr, align 1
+    ret void
+  }
+
+If different cleanup code needs to get executed for different suspend points, 
+a similar switch will be in the `f.destroy` function.
+
+.. note ::
+
+  Using suspend index in a coroutine state and having a switch in `f.resume` and
+  `f.destroy` is one of the possible implementation strategies. We explored 
+  another option where a distinct `f.resume1`, `f.resume2`, etc. are created for
+  every suspend point, and instead of storing an index, the resume and destroy 
+  function pointers are updated at every suspend. Early testing showed that the
+  current approach is easier on the optimizer than the latter so it is a 
+  lowering strategy implemented at the moment.
+
+Distinct Save and Suspend
+-------------------------
+
+In the previous example, setting a resume index (or some other state change that 
+needs to happen to prepare a coroutine for resumption) happens at the same time as
+a suspension of a coroutine. However, in certain cases, it is necessary to control 
+when coroutine is prepared for resumption and when it is suspended.
+
+In the following example, a coroutine represents some activity that is driven
+by completions of asynchronous operations `async_op1` and `async_op2` which get
+a coroutine handle as a parameter and resume the coroutine once async
+operation is finished.
+
+.. code-block:: text
+
+  void g() {
+     for (;;)
+       if (cond()) {
+          async_op1(<coroutine-handle>); // will resume once async_op1 completes
+          <suspend>
+          do_one();
+       }
+       else {
+          async_op2(<coroutine-handle>); // will resume once async_op2 completes
+          <suspend>
+          do_two();
+       }
+     }
+  }
+
+In this case, coroutine should be ready for resumption prior to a call to 
+`async_op1` and `async_op2`. The `coro.save`_ intrinsic is used to indicate a
+point when coroutine should be ready for resumption (namely, when a resume index
+should be stored in the coroutine frame, so that it can be resumed at the 
+correct resume point):
+
+.. code-block:: llvm
+
+  if.true:
+    %save1 = call token @llvm.coro.save(i8* %hdl)
+    call void @async_op1(i8* %hdl)
+    %suspend1 = call i1 @llvm.coro.suspend(token %save1, i1 false)
+    switch i8 %suspend1, label %suspend [i8 0, label %resume1
+                                         i8 1, label %cleanup]
+  if.false:
+    %save2 = call token @llvm.coro.save(i8* %hdl)
+    call void @async_op2(i8* %hdl)
+    %suspend2 = call i1 @llvm.coro.suspend(token %save2, i1 false)
+    switch i8 %suspend1, label %suspend [i8 0, label %resume2
+                                         i8 1, label %cleanup]
+
+.. _coroutine promise:
+
+Coroutine Promise
+-----------------
+
+A coroutine author or a frontend may designate a distinguished `alloca` that can
+be used to communicate with the coroutine. This distinguished alloca is called
+**coroutine promise** and is provided as the second parameter to the 
+`coro.id`_ intrinsic.
+
+The following coroutine designates a 32 bit integer `promise` and uses it to
+store the current value produced by a coroutine.
+
+.. code-block:: llvm
+
+  define i8* @f(i32 %n) {
+  entry:
+    %promise = alloca i32
+    %pv = bitcast i32* %promise to i8*
+    %id = call token @llvm.coro.id(i32 0, i8* %pv, i8* null, i8* null)
+    %need.dyn.alloc = call i1 @llvm.coro.alloc(token %id)
+    br i1 %need.dyn.alloc, label %dyn.alloc, label %coro.begin
+  dyn.alloc:
+    %size = call i32 @llvm.coro.size.i32()
+    %alloc = call i8* @malloc(i32 %size)
+    br label %coro.begin
+  coro.begin:
+    %phi = phi i8* [ null, %entry ], [ %alloc, %dyn.alloc ]
+    %hdl = call noalias i8* @llvm.coro.begin(token %id, i8* %phi)
+    br label %loop
+  loop:
+    %n.val = phi i32 [ %n, %coro.begin ], [ %inc, %loop ]
+    %inc = add nsw i32 %n.val, 1
+    store i32 %n.val, i32* %promise
+    %0 = call i8 @llvm.coro.suspend(token none, i1 false)
+    switch i8 %0, label %suspend [i8 0, label %loop
+                                  i8 1, label %cleanup]
+  cleanup:
+    %mem = call i8* @llvm.coro.free(token %id, i8* %hdl)
+    call void @free(i8* %mem)
+    br label %suspend
+  suspend:
+    %unused = call i1 @llvm.coro.end(i8* %hdl, i1 false)
+    ret i8* %hdl
+  }
+
+A coroutine consumer can rely on the `coro.promise`_ intrinsic to access the
+coroutine promise.
+
+.. code-block:: llvm
+
+  define i32 @main() {
+  entry:
+    %hdl = call i8* @f(i32 4)
+    %promise.addr.raw = call i8* @llvm.coro.promise(i8* %hdl, i32 4, i1 false)
+    %promise.addr = bitcast i8* %promise.addr.raw to i32*
+    %val0 = load i32, i32* %promise.addr
+    call void @print(i32 %val0)
+    call void @llvm.coro.resume(i8* %hdl)
+    %val1 = load i32, i32* %promise.addr
+    call void @print(i32 %val1)
+    call void @llvm.coro.resume(i8* %hdl)
+    %val2 = load i32, i32* %promise.addr
+    call void @print(i32 %val2)
+    call void @llvm.coro.destroy(i8* %hdl)
+    ret i32 0
+  }
+
+After example in this section is compiled, result of the compilation will be:
+
+.. code-block:: llvm
+
+  define i32 @main() {
+  entry:
+    tail call void @print(i32 4)
+    tail call void @print(i32 5)
+    tail call void @print(i32 6)
+    ret i32 0
+  }
+
+.. _final:
+.. _final suspend:
+
+Final Suspend
+-------------
+
+A coroutine author or a frontend may designate a particular suspend to be final,
+by setting the second argument of the `coro.suspend`_ intrinsic to `true`.
+Such a suspend point has two properties:
+
+* it is possible to check whether a suspended coroutine is at the final suspend
+  point via `coro.done`_ intrinsic;
+
+* a resumption of a coroutine stopped at the final suspend point leads to 
+  undefined behavior. The only possible action for a coroutine at a final
+  suspend point is destroying it via `coro.destroy`_ intrinsic.
+
+From the user perspective, the final suspend point represents an idea of a 
+coroutine reaching the end. From the compiler perspective, it is an optimization
+opportunity for reducing number of resume points (and therefore switch cases) in
+the resume function.
+
+The following is an example of a function that keeps resuming the coroutine
+until the final suspend point is reached after which point the coroutine is 
+destroyed:
+
+.. code-block:: llvm
+
+  define i32 @main() {
+  entry:
+    %hdl = call i8* @f(i32 4)
+    br label %while
+  while:
+    call void @llvm.coro.resume(i8* %hdl)
+    %done = call i1 @llvm.coro.done(i8* %hdl)
+    br i1 %done, label %end, label %while
+  end:
+    call void @llvm.coro.destroy(i8* %hdl)
+    ret i32 0
+  }
+
+Usually, final suspend point is a frontend injected suspend point that does not
+correspond to any explicitly authored suspend point of the high level language.
+For example, for a Python generator that has only one suspend point:
+
+.. code-block:: python
+
+  def coroutine(n):
+    for i in range(n):
+      yield i
+
+Python frontend would inject two more suspend points, so that the actual code
+looks like this:
+
+.. code-block:: c
+
+  void* coroutine(int n) {
+    int current_value; 
+    <designate current_value to be coroutine promise>
+    <SUSPEND> // injected suspend point, so that the coroutine starts suspended
+    for (int i = 0; i < n; ++i) {
+      current_value = i; <SUSPEND>; // corresponds to "yield i"
+    }
+    <SUSPEND final=true> // injected final suspend point
+  }
+
+and python iterator `__next__` would look like:
+
+.. code-block:: c++
+
+  int __next__(void* hdl) {
+    coro.resume(hdl);
+    if (coro.done(hdl)) throw StopIteration();
+    return *(int*)coro.promise(hdl, 4, false);
+  }
+
+Intrinsics
+==========
+
+Coroutine Manipulation Intrinsics
+---------------------------------
+
+Intrinsics described in this section are used to manipulate an existing
+coroutine. They can be used in any function which happen to have a pointer
+to a `coroutine frame`_ or a pointer to a `coroutine promise`_.
+
+.. _coro.destroy:
+
+'llvm.coro.destroy' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+      declare void @llvm.coro.destroy(i8* <handle>)
+
+Overview:
+"""""""""
+
+The '``llvm.coro.destroy``' intrinsic destroys a suspended
+coroutine.
+
+Arguments:
+""""""""""
+
+The argument is a coroutine handle to a suspended coroutine.
+
+Semantics:
+""""""""""
+
+When possible, the `coro.destroy` intrinsic is replaced with a direct call to 
+the coroutine destroy function. Otherwise it is replaced with an indirect call 
+based on the function pointer for the destroy function stored in the coroutine
+frame. Destroying a coroutine that is not suspended leads to undefined behavior.
+
+.. _coro.resume:
+
+'llvm.coro.resume' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+::
+
+      declare void @llvm.coro.resume(i8* <handle>)
+
+Overview:
+"""""""""
+
+The '``llvm.coro.resume``' intrinsic resumes a suspended coroutine.
+
+Arguments:
+""""""""""
+
+The argument is a handle to a suspended coroutine.
+
+Semantics:
+""""""""""
+
+When possible, the `coro.resume` intrinsic is replaced with a direct call to the
+coroutine resume function. Otherwise it is replaced with an indirect call based 
+on the function pointer for the resume function stored in the coroutine frame. 
+Resuming a coroutine that is not suspended leads to undefined behavior.
+
+.. _coro.done:
+
+'llvm.coro.done' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+::
+
+      declare i1 @llvm.coro.done(i8* <handle>)
+
+Overview:
+"""""""""
+
+The '``llvm.coro.done``' intrinsic checks whether a suspended coroutine is at 
+the final suspend point or not.
+
+Arguments:
+""""""""""
+
+The argument is a handle to a suspended coroutine.
+
+Semantics:
+""""""""""
+
+Using this intrinsic on a coroutine that does not have a `final suspend`_ point 
+or on a coroutine that is not suspended leads to undefined behavior.
+
+.. _coro.promise:
+
+'llvm.coro.promise' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+::
+
+      declare i8* @llvm.coro.promise(i8* <ptr>, i32 <alignment>, i1 <from>)
+
+Overview:
+"""""""""
+
+The '``llvm.coro.promise``' intrinsic obtains a pointer to a 
+`coroutine promise`_ given a coroutine handle and vice versa.
+
+Arguments:
+""""""""""
+
+The first argument is a handle to a coroutine if `from` is false. Otherwise, 
+it is a pointer to a coroutine promise.
+
+The second argument is an alignment requirements of the promise. 
+If a frontend designated `%promise = alloca i32` as a promise, the alignment 
+argument to `coro.promise` should be the alignment of `i32` on the target 
+platform. If a frontend designated `%promise = alloca i32, align 16` as a 
+promise, the alignment argument should be 16.
+This argument only accepts constants.
+
+The third argument is a boolean indicating a direction of the transformation.
+If `from` is true, the intrinsic returns a coroutine handle given a pointer 
+to a promise. If `from` is false, the intrinsics return a pointer to a promise 
+from a coroutine handle. This argument only accepts constants.
+
+Semantics:
+""""""""""
+
+Using this intrinsic on a coroutine that does not have a coroutine promise
+leads to undefined behavior. It is possible to read and modify coroutine
+promise of the coroutine which is currently executing. The coroutine author and
+a coroutine user are responsible to makes sure there is no data races.
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+  define i8* @f(i32 %n) {
+  entry:
+    %promise = alloca i32
+    %pv = bitcast i32* %promise to i8*
+    ; the second argument to coro.id points to the coroutine promise.
+    %id = call token @llvm.coro.id(i32 0, i8* %pv, i8* null, i8* null)
+    ...
+    %hdl = call noalias i8* @llvm.coro.begin(token %id, i8* %alloc)
+    ...
+    store i32 42, i32* %promise ; store something into the promise
+    ...
+    ret i8* %hdl
+  }
+
+  define i32 @main() {
+  entry:
+    %hdl = call i8* @f(i32 4) ; starts the coroutine and returns its handle
+    %promise.addr.raw = call i8* @llvm.coro.promise(i8* %hdl, i32 4, i1 false)
+    %promise.addr = bitcast i8* %promise.addr.raw to i32*    
+    %val = load i32, i32* %promise.addr ; load a value from the promise
+    call void @print(i32 %val)
+    call void @llvm.coro.destroy(i8* %hdl)
+    ret i32 0
+  }
+
+.. _coroutine intrinsics:
+
+Coroutine Structure Intrinsics
+------------------------------
+Intrinsics described in this section are used within a coroutine to describe
+the coroutine structure. They should not be used outside of a coroutine.
+
+.. _coro.size:
+
+'llvm.coro.size' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+::
+
+    declare i32 @llvm.coro.size.i32()
+    declare i64 @llvm.coro.size.i64()
+
+Overview:
+"""""""""
+
+The '``llvm.coro.size``' intrinsic returns the number of bytes
+required to store a `coroutine frame`_.
+
+Arguments:
+""""""""""
+
+None
+
+Semantics:
+""""""""""
+
+The `coro.size` intrinsic is lowered to a constant representing the size of
+the coroutine frame. 
+
+.. _coro.begin:
+
+'llvm.coro.begin' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+::
+
+  declare i8* @llvm.coro.begin(token <id>, i8* <mem>)
+
+Overview:
+"""""""""
+
+The '``llvm.coro.begin``' intrinsic returns an address of the coroutine frame.
+
+Arguments:
+""""""""""
+
+The first argument is a token returned by a call to '``llvm.coro.id``' 
+identifying the coroutine.
+
+The second argument is a pointer to a block of memory where coroutine frame
+will be stored if it is allocated dynamically.
+
+Semantics:
+""""""""""
+
+Depending on the alignment requirements of the objects in the coroutine frame
+and/or on the codegen compactness reasons the pointer returned from `coro.begin` 
+may be at offset to the `%mem` argument. (This could be beneficial if 
+instructions that express relative access to data can be more compactly encoded 
+with small positive and negative offsets).
+
+A frontend should emit exactly one `coro.begin` intrinsic per coroutine.
+
+.. _coro.free:
+
+'llvm.coro.free' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+::
+
+  declare i8* @llvm.coro.free(token %id, i8* <frame>)
+
+Overview:
+"""""""""
+
+The '``llvm.coro.free``' intrinsic returns a pointer to a block of memory where 
+coroutine frame is stored or `null` if this instance of a coroutine did not use
+dynamically allocated memory for its coroutine frame.
+
+Arguments:
+""""""""""
+
+The first argument is a token returned by a call to '``llvm.coro.id``' 
+identifying the coroutine.
+
+The second argument is a pointer to the coroutine frame. This should be the same
+pointer that was returned by prior `coro.begin` call.
+
+Example (custom deallocation function):
+"""""""""""""""""""""""""""""""""""""""
+
+.. code-block:: llvm
+
+  cleanup:
+    %mem = call i8* @llvm.coro.free(token %id, i8* %frame)
+    %mem_not_null = icmp ne i8* %mem, null
+    br i1 %mem_not_null, label %if.then, label %if.end
+  if.then:
+    call void @CustomFree(i8* %mem)
+    br label %if.end
+  if.end:
+    ret void
+
+Example (standard deallocation functions):
+""""""""""""""""""""""""""""""""""""""""""
+
+.. code-block:: llvm
+
+  cleanup:
+    %mem = call i8* @llvm.coro.free(token %id, i8* %frame)
+    call void @free(i8* %mem)
+    ret void
+
+.. _coro.alloc:
+
+'llvm.coro.alloc' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+::
+
+  declare i1 @llvm.coro.alloc(token <id>)
+
+Overview:
+"""""""""
+
+The '``llvm.coro.alloc``' intrinsic returns `true` if dynamic allocation is
+required to obtain a memory for the coroutine frame and `false` otherwise.
+
+Arguments:
+""""""""""
+
+The first argument is a token returned by a call to '``llvm.coro.id``' 
+identifying the coroutine.
+
+Semantics:
+""""""""""
+
+A frontend should emit at most one `coro.alloc` intrinsic per coroutine.
+The intrinsic is used to suppress dynamic allocation of the coroutine frame
+when possible.
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+  entry:
+    %id = call token @llvm.coro.id(i32 0, i8* null, i8* null, i8* null)
+    %dyn.alloc.required = call i1 @llvm.coro.alloc(token %id)
+    br i1 %dyn.alloc.required, label %coro.alloc, label %coro.begin
+
+  coro.alloc:
+    %frame.size = call i32 @llvm.coro.size()
+    %alloc = call i8* @MyAlloc(i32 %frame.size)
+    br label %coro.begin
+
+  coro.begin:
+    %phi = phi i8* [ null, %entry ], [ %alloc, %coro.alloc ]
+    %frame = call i8* @llvm.coro.begin(token %id, i8* %phi)
+
+.. _coro.noop:
+
+'llvm.coro.noop' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+::
+
+  declare i8* @llvm.coro.noop()
+
+Overview:
+"""""""""
+
+The '``llvm.coro.noop``' intrinsic returns an address of the coroutine frame of
+a coroutine that does nothing when resumed or destroyed.
+
+Arguments:
+""""""""""
+
+None
+
+Semantics:
+""""""""""
+
+This intrinsic is lowered to refer to a private constant coroutine frame. The
+resume and destroy handlers for this frame are empty functions that do nothing.
+Note that in different translation units llvm.coro.noop may return different pointers.
+
+.. _coro.frame:
+
+'llvm.coro.frame' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+::
+
+  declare i8* @llvm.coro.frame()
+
+Overview:
+"""""""""
+
+The '``llvm.coro.frame``' intrinsic returns an address of the coroutine frame of
+the enclosing coroutine.
+
+Arguments:
+""""""""""
+
+None
+
+Semantics:
+""""""""""
+
+This intrinsic is lowered to refer to the `coro.begin`_ instruction. This is
+a frontend convenience intrinsic that makes it easier to refer to the
+coroutine frame.
+
+.. _coro.id:
+
+'llvm.coro.id' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+::
+
+  declare token @llvm.coro.id(i32 <align>, i8* <promise>, i8* <coroaddr>, 
+                                                          i8* <fnaddrs>)
+
+Overview:
+"""""""""
+
+The '``llvm.coro.id``' intrinsic returns a token identifying a coroutine.
+
+Arguments:
+""""""""""
+
+The first argument provides information on the alignment of the memory returned 
+by the allocation function and given to `coro.begin` by the first argument. If 
+this argument is 0, the memory is assumed to be aligned to 2 * sizeof(i8*).
+This argument only accepts constants.
+
+The second argument, if not `null`, designates a particular alloca instruction
+to be a `coroutine promise`_.
+
+The third argument is `null` coming out of the frontend. The CoroEarly pass sets
+this argument to point to the function this coro.id belongs to. 
+
+The fourth argument is `null` before coroutine is split, and later is replaced 
+to point to a private global constant array containing function pointers to 
+outlined resume and destroy parts of the coroutine.
+
+
+Semantics:
+""""""""""
+
+The purpose of this intrinsic is to tie together `coro.id`, `coro.alloc` and
+`coro.begin` belonging to the same coroutine to prevent optimization passes from
+duplicating any of these instructions unless entire body of the coroutine is
+duplicated.
+
+A frontend should emit exactly one `coro.id` intrinsic per coroutine.
+
+.. _coro.end:
+
+'llvm.coro.end' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+::
+
+  declare i1 @llvm.coro.end(i8* <handle>, i1 <unwind>)
+
+Overview:
+"""""""""
+
+The '``llvm.coro.end``' marks the point where execution of the resume part of 
+the coroutine should end and control should return to the caller.
+
+
+Arguments:
+""""""""""
+
+The first argument should refer to the coroutine handle of the enclosing
+coroutine. A frontend is allowed to supply null as the first parameter, in this
+case `coro-early` pass will replace the null with an appropriate coroutine 
+handle value.
+
+The second argument should be `true` if this coro.end is in the block that is 
+part of the unwind sequence leaving the coroutine body due to an exception and 
+`false` otherwise.
+
+Semantics:
+""""""""""
+The purpose of this intrinsic is to allow frontends to mark the cleanup and
+other code that is only relevant during the initial invocation of the coroutine
+and should not be present in resume and destroy parts. 
+
+This intrinsic is lowered when a coroutine is split into
+the start, resume and destroy parts. In the start part, it is a no-op,
+in resume and destroy parts, it is replaced with `ret void` instruction and
+the rest of the block containing `coro.end` instruction is discarded.
+In landing pads it is replaced with an appropriate instruction to unwind to 
+caller. The handling of coro.end differs depending on whether the target is 
+using landingpad or WinEH exception model.
+
+For landingpad based exception model, it is expected that frontend uses the 
+`coro.end`_ intrinsic as follows:
+
+.. code-block:: llvm
+
+    ehcleanup:
+      %InResumePart = call i1 @llvm.coro.end(i8* null, i1 true)
+      br i1 %InResumePart, label %eh.resume, label %cleanup.cont
+
+    cleanup.cont:
+      ; rest of the cleanup
+
+    eh.resume:
+      %exn = load i8*, i8** %exn.slot, align 8
+      %sel = load i32, i32* %ehselector.slot, align 4
+      %lpad.val = insertvalue { i8*, i32 } undef, i8* %exn, 0
+      %lpad.val29 = insertvalue { i8*, i32 } %lpad.val, i32 %sel, 1
+      resume { i8*, i32 } %lpad.val29
+
+The `CoroSpit` pass replaces `coro.end` with ``True`` in the resume functions,
+thus leading to immediate unwind to the caller, whereas in start function it
+is replaced with ``False``, thus allowing to proceed to the rest of the cleanup
+code that is only needed during initial invocation of the coroutine.
+
+For Windows Exception handling model, a frontend should attach a funclet bundle
+referring to an enclosing cleanuppad as follows:
+
+.. code-block:: llvm
+
+    ehcleanup: 
+      %tok = cleanuppad within none []
+      %unused = call i1 @llvm.coro.end(i8* null, i1 true) [ "funclet"(token %tok) ]
+      cleanupret from %tok unwind label %RestOfTheCleanup
+
+The `CoroSplit` pass, if the funclet bundle is present, will insert 
+``cleanupret from %tok unwind to caller`` before
+the `coro.end`_ intrinsic and will remove the rest of the block.
+
+The following table summarizes the handling of `coro.end`_ intrinsic.
+
++--------------------------+-------------------+-------------------------------+
+|                          | In Start Function | In Resume/Destroy Functions   |
++--------------------------+-------------------+-------------------------------+
+|unwind=false              | nothing           |``ret void``                   |
++------------+-------------+-------------------+-------------------------------+
+|            | WinEH       | nothing           |``cleanupret unwind to caller``|
+|unwind=true +-------------+-------------------+-------------------------------+
+|            | Landingpad  | nothing           | nothing                       |
++------------+-------------+-------------------+-------------------------------+
+
+.. _coro.suspend:
+.. _suspend points:
+
+'llvm.coro.suspend' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+::
+
+  declare i8 @llvm.coro.suspend(token <save>, i1 <final>)
+
+Overview:
+"""""""""
+
+The '``llvm.coro.suspend``' marks the point where execution of the coroutine 
+need to get suspended and control returned back to the caller.
+Conditional branches consuming the result of this intrinsic lead to basic blocks
+where coroutine should proceed when suspended (-1), resumed (0) or destroyed 
+(1).
+
+Arguments:
+""""""""""
+
+The first argument refers to a token of `coro.save` intrinsic that marks the 
+point when coroutine state is prepared for suspension. If `none` token is passed,
+the intrinsic behaves as if there were a `coro.save` immediately preceding
+the `coro.suspend` intrinsic.
+
+The second argument indicates whether this suspension point is `final`_.
+The second argument only accepts constants. If more than one suspend point is
+designated as final, the resume and destroy branches should lead to the same
+basic blocks.
+
+Example (normal suspend point):
+"""""""""""""""""""""""""""""""
+
+.. code-block:: llvm
+
+    %0 = call i8 @llvm.coro.suspend(token none, i1 false)
+    switch i8 %0, label %suspend [i8 0, label %resume
+                                  i8 1, label %cleanup]
+
+Example (final suspend point):
+""""""""""""""""""""""""""""""
+
+.. code-block:: llvm
+
+  while.end:
+    %s.final = call i8 @llvm.coro.suspend(token none, i1 true)
+    switch i8 %s.final, label %suspend [i8 0, label %trap
+                                        i8 1, label %cleanup]
+  trap: 
+    call void @llvm.trap()
+    unreachable
+
+Semantics:
+""""""""""
+
+If a coroutine that was suspended at the suspend point marked by this intrinsic
+is resumed via `coro.resume`_ the control will transfer to the basic block
+of the 0-case. If it is resumed via `coro.destroy`_, it will proceed to the
+basic block indicated by the 1-case. To suspend, coroutine proceed to the 
+default label.
+
+If suspend intrinsic is marked as final, it can consider the `true` branch
+unreachable and can perform optimizations that can take advantage of that fact.
+
+.. _coro.save:
+
+'llvm.coro.save' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+::
+
+  declare token @llvm.coro.save(i8* <handle>)
+
+Overview:
+"""""""""
+
+The '``llvm.coro.save``' marks the point where a coroutine need to update its 
+state to prepare for resumption to be considered suspended (and thus eligible 
+for resumption). 
+
+Arguments:
+""""""""""
+
+The first argument points to a coroutine handle of the enclosing coroutine.
+
+Semantics:
+""""""""""
+
+Whatever coroutine state changes are required to enable resumption of
+the coroutine from the corresponding suspend point should be done at the point 
+of `coro.save` intrinsic.
+
+Example:
+""""""""
+
+Separate save and suspend points are necessary when a coroutine is used to 
+represent an asynchronous control flow driven by callbacks representing
+completions of asynchronous operations.
+
+In such a case, a coroutine should be ready for resumption prior to a call to 
+`async_op` function that may trigger resumption of a coroutine from the same or
+a different thread possibly prior to `async_op` call returning control back
+to the coroutine:
+
+.. code-block:: llvm
+
+    %save1 = call token @llvm.coro.save(i8* %hdl)
+    call void @async_op1(i8* %hdl)
+    %suspend1 = call i1 @llvm.coro.suspend(token %save1, i1 false)
+    switch i8 %suspend1, label %suspend [i8 0, label %resume1
+                                         i8 1, label %cleanup]
+
+.. _coro.param:
+
+'llvm.coro.param' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+::
+
+  declare i1 @llvm.coro.param(i8* <original>, i8* <copy>)
+
+Overview:
+"""""""""
+
+The '``llvm.coro.param``' is used by a frontend to mark up the code used to
+construct and destruct copies of the parameters. If the optimizer discovers that
+a particular parameter copy is not used after any suspends, it can remove the
+construction and destruction of the copy by replacing corresponding coro.param
+with `i1 false` and replacing any use of the `copy` with the `original`.
+
+Arguments:
+""""""""""
+
+The first argument points to an `alloca` storing the value of a parameter to a 
+coroutine. 
+
+The second argument points to an `alloca` storing the value of the copy of that
+parameter.
+
+Semantics:
+""""""""""
+
+The optimizer is free to always replace this intrinsic with `i1 true`.
+
+The optimizer is also allowed to replace it with `i1 false` provided that the 
+parameter copy is only used prior to control flow reaching any of the suspend
+points. The code that would be DCE'd if the `coro.param` is replaced with 
+`i1 false` is not considered to be a use of the parameter copy.
+
+The frontend can emit this intrinsic if its language rules allow for this 
+optimization.
+
+Example:
+""""""""
+Consider the following example. A coroutine takes two parameters `a` and `b`
+that has a destructor and a move constructor.
+
+.. code-block:: c++
+
+  struct A { ~A(); A(A&&); bool foo(); void bar(); };
+
+  task<int> f(A a, A b) {
+    if (a.foo())
+      return 42;
+
+    a.bar();
+    co_await read_async(); // introduces suspend point
+    b.bar();
+  }
+
+Note that, uses of `b` is used after a suspend point and thus must be copied
+into a coroutine frame, whereas `a` does not have to, since it never used 
+after suspend.
+
+A frontend can create parameter copies for `a` and `b` as follows:
+
+.. code-block:: text
+
+  task<int> f(A a', A b') {
+    a = alloca A;
+    b = alloca A;
+    // move parameters to its copies
+    if (coro.param(a', a)) A::A(a, A&& a');
+    if (coro.param(b', b)) A::A(b, A&& b');
+    ...
+    // destroy parameters copies
+    if (coro.param(a', a)) A::~A(a);
+    if (coro.param(b', b)) A::~A(b);
+  }
+
+The optimizer can replace coro.param(a',a) with `i1 false` and replace all uses
+of `a` with `a'`, since it is not used after suspend.
+
+The optimizer must replace coro.param(b', b) with `i1 true`, since `b` is used
+after suspend and therefore, it has to reside in the coroutine frame.
+
+Coroutine Transformation Passes
+===============================
+CoroEarly
+---------
+The pass CoroEarly lowers coroutine intrinsics that hide the details of the
+structure of the coroutine frame, but, otherwise not needed to be preserved to
+help later coroutine passes. This pass lowers `coro.frame`_, `coro.done`_, 
+and `coro.promise`_ intrinsics.
+
+.. _CoroSplit:
+
+CoroSplit
+---------
+The pass CoroSplit buides coroutine frame and outlines resume and destroy parts 
+into separate functions.
+
+CoroElide
+---------
+The pass CoroElide examines if the inlined coroutine is eligible for heap 
+allocation elision optimization. If so, it replaces 
+`coro.begin` intrinsic with an address of a coroutine frame placed on its caller
+and replaces `coro.alloc` and `coro.free` intrinsics with `false` and `null`
+respectively to remove the deallocation code. 
+This pass also replaces `coro.resume` and `coro.destroy` intrinsics with direct 
+calls to resume and destroy functions for a particular coroutine where possible.
+
+CoroCleanup
+-----------
+This pass runs late to lower all coroutine related intrinsics not replaced by
+earlier passes.
+
+Areas Requiring Attention
+=========================
+#. A coroutine frame is bigger than it could be. Adding stack packing and stack 
+   coloring like optimization on the coroutine frame will result in tighter
+   coroutine frames.
+
+#. Take advantage of the lifetime intrinsics for the data that goes into the
+   coroutine frame. Leave lifetime intrinsics as is for the data that stays in
+   allocas.
+
+#. The CoroElide optimization pass relies on coroutine ramp function to be
+   inlined. It would be beneficial to split the ramp function further to 
+   increase the chance that it will get inlined into its caller.
+
+#. Design a convention that would make it possible to apply coroutine heap
+   elision optimization across ABI boundaries.
+
+#. Cannot handle coroutines with `inalloca` parameters (used in x86 on Windows).
+
+#. Alignment is ignored by coro.begin and coro.free intrinsics.
+
+#. Make required changes to make sure that coroutine optimizations work with
+   LTO.
+
+#. More tests, more tests, more tests

Added: www-releases/trunk/8.0.1/docs/_sources/CoverageMappingFormat.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.1/docs/_sources/CoverageMappingFormat.rst.txt?rev=368037&view=auto
==============================================================================
--- www-releases/trunk/8.0.1/docs/_sources/CoverageMappingFormat.rst.txt (added)
+++ www-releases/trunk/8.0.1/docs/_sources/CoverageMappingFormat.rst.txt Tue Aug  6 06:51:02 2019
@@ -0,0 +1,609 @@
+.. role:: raw-html(raw)
+   :format: html
+
+=================================
+LLVM Code Coverage Mapping Format
+=================================
+
+.. contents::
+   :local:
+
+Introduction
+============
+
+LLVM's code coverage mapping format is used to provide code coverage
+analysis using LLVM's and Clang's instrumenation based profiling
+(Clang's ``-fprofile-instr-generate`` option).
+
+This document is aimed at those who use LLVM's code coverage mapping to provide
+code coverage analysis for their own programs, and for those who would like
+to know how it works under the hood. A prior knowledge of how Clang's profile
+guided optimization works is useful, but not required.
+
+We start by showing how to use LLVM and Clang for code coverage analysis,
+then we briefly describe LLVM's code coverage mapping format and the
+way that Clang and LLVM's code coverage tool work with this format. After
+the basics are down, more advanced features of the coverage mapping format
+are discussed - such as the data structures, LLVM IR representation and
+the binary encoding.
+
+Quick Start
+===========
+
+Here's a short story that describes how to generate code coverage overview
+for a sample source file called *test.c*.
+
+* First, compile an instrumented version of your program using Clang's
+  ``-fprofile-instr-generate`` option with the additional ``-fcoverage-mapping``
+  option:
+
+  ``clang -o test -fprofile-instr-generate -fcoverage-mapping test.c``
+* Then, run the instrumented binary. The runtime will produce a file called
+  *default.profraw* containing the raw profile instrumentation data:
+
+  ``./test``
+* After that, merge the profile data using the *llvm-profdata* tool:
+
+  ``llvm-profdata merge -o test.profdata default.profraw``
+* Finally, run LLVM's code coverage tool (*llvm-cov*) to produce the code
+  coverage overview for the sample source file:
+
+  ``llvm-cov show ./test -instr-profile=test.profdata test.c``
+
+High Level Overview
+===================
+
+LLVM's code coverage mapping format is designed to be a self contained
+data format, that can be embedded into the LLVM IR and object files.
+It's described in this document as a **mapping** format because its goal is
+to store the data that is required for a code coverage tool to map between
+the specific source ranges in a file and the execution counts obtained
+after running the instrumented version of the program.
+
+The mapping data is used in two places in the code coverage process:
+
+1. When clang compiles a source file with ``-fcoverage-mapping``, it
+   generates the mapping information that describes the mapping between the
+   source ranges and the profiling instrumentation counters.
+   This information gets embedded into the LLVM IR and conveniently
+   ends up in the final executable file when the program is linked.
+
+2. It is also used by *llvm-cov* - the mapping information is extracted from an
+   object file and is used to associate the execution counts (the values of the
+   profile instrumentation counters), and the source ranges in a file.
+   After that, the tool is able to generate various code coverage reports
+   for the program.
+
+The coverage mapping format aims to be a "universal format" that would be
+suitable for usage by any frontend, and not just by Clang. It also aims to
+provide the frontend the possibility of generating the minimal coverage mapping
+data in order to reduce the size of the IR and object files - for example,
+instead of emitting mapping information for each statement in a function, the
+frontend is allowed to group the statements with the same execution count into
+regions of code, and emit the mapping information only for those regions.
+
+Advanced Concepts
+=================
+
+The remainder of this guide is meant to give you insight into the way the
+coverage mapping format works.
+
+The coverage mapping format operates on a per-function level as the
+profile instrumentation counters are associated with a specific function.
+For each function that requires code coverage, the frontend has to create
+coverage mapping data that can map between the source code ranges and
+the profile instrumentation counters for that function.
+
+Mapping Region
+--------------
+
+The function's coverage mapping data contains an array of mapping regions.
+A mapping region stores the `source code range`_ that is covered by this region,
+the `file id <coverage file id_>`_, the `coverage mapping counter`_ and
+the region's kind.
+There are several kinds of mapping regions:
+
+* Code regions associate portions of source code and `coverage mapping
+  counters`_. They make up the majority of the mapping regions. They are used
+  by the code coverage tool to compute the execution counts for lines,
+  highlight the regions of code that were never executed, and to obtain
+  the various code coverage statistics for a function.
+  For example:
+
+  :raw-html:`<pre class='highlight' style='line-height:initial;'><span>int main(int argc, const char *argv[]) </span><span style='background-color:#4A789C'>{    </span> <span class='c1'>// Code Region from 1:40 to 9:2</span>
+  <span style='background-color:#4A789C'>                                            </span>
+  <span style='background-color:#4A789C'>  if (argc > 1) </span><span style='background-color:#85C1F5'>{                         </span>   <span class='c1'>// Code Region from 3:17 to 5:4</span>
+  <span style='background-color:#85C1F5'>    printf("%s\n", argv[1]);              </span>
+  <span style='background-color:#85C1F5'>  }</span><span style='background-color:#4A789C'> else </span><span style='background-color:#F6D55D'>{                                </span>   <span class='c1'>// Code Region from 5:10 to 7:4</span>
+  <span style='background-color:#F6D55D'>    printf("\n");                         </span>
+  <span style='background-color:#F6D55D'>  }</span><span style='background-color:#4A789C'>                                         </span>
+  <span style='background-color:#4A789C'>  return 0;                                 </span>
+  <span style='background-color:#4A789C'>}</span>
+  </pre>`
+* Skipped regions are used to represent source ranges that were skipped
+  by Clang's preprocessor. They don't associate with
+  `coverage mapping counters`_, as the frontend knows that they are never
+  executed. They are used by the code coverage tool to mark the skipped lines
+  inside a function as non-code lines that don't have execution counts.
+  For example:
+
+  :raw-html:`<pre class='highlight' style='line-height:initial;'><span>int main() </span><span style='background-color:#4A789C'>{               </span> <span class='c1'>// Code Region from 1:12 to 6:2</span>
+  <span style='background-color:#85C1F5'>#ifdef DEBUG             </span>   <span class='c1'>// Skipped Region from 2:1 to 4:2</span>
+  <span style='background-color:#85C1F5'>  printf("Hello world"); </span>
+  <span style='background-color:#85C1F5'>#</span><span style='background-color:#4A789C'>endif                     </span>
+  <span style='background-color:#4A789C'>  return 0;                </span>
+  <span style='background-color:#4A789C'>}</span>
+  </pre>`
+* Expansion regions are used to represent Clang's macro expansions. They
+  have an additional property - *expanded file id*. This property can be
+  used by the code coverage tool to find the mapping regions that are created
+  as a result of this macro expansion, by checking if their file id matches the
+  expanded file id. They don't associate with `coverage mapping counters`_,
+  as the code coverage tool can determine the execution count for this region
+  by looking up the execution count of the first region with a corresponding
+  file id.
+  For example:
+
+  :raw-html:`<pre class='highlight' style='line-height:initial;'><span>int func(int x) </span><span style='background-color:#4A789C'>{                             </span>
+  <span style='background-color:#4A789C'>  #define MAX(x,y) </span><span style='background-color:#85C1F5'>((x) > (y)? </span><span style='background-color:#F6D55D'>(x)</span><span style='background-color:#85C1F5'> : </span><span style='background-color:#F4BA70'>(y)</span><span style='background-color:#85C1F5'>)</span><span style='background-color:#4A789C'>     </span>
+  <span style='background-color:#4A789C'>  return </span><span style='background-color:#7FCA9F'>MAX</span><span style='background-color:#4A789C'>(x, 42);                          </span> <span class='c1'>// Expansion Region from 3:10 to 3:13</span>
+  <span style='background-color:#4A789C'>}</span>
+  </pre>`
+
+.. _source code range:
+
+Source Range:
+^^^^^^^^^^^^^
+
+The source range record contains the starting and ending location of a certain
+mapping region. Both locations include the line and the column numbers.
+
+.. _coverage file id:
+
+File ID:
+^^^^^^^^
+
+The file id an integer value that tells us
+in which source file or macro expansion is this region located.
+It enables Clang to produce mapping information for the code
+defined inside macros, like this example demonstrates:
+
+:raw-html:`<pre class='highlight' style='line-height:initial;'><span>void func(const char *str) </span><span style='background-color:#4A789C'>{        </span> <span class='c1'>// Code Region from 1:28 to 6:2 with file id 0</span>
+<span style='background-color:#4A789C'>  #define PUT </span><span style='background-color:#85C1F5'>printf("%s\n", str)</span><span style='background-color:#4A789C'>   </span> <span class='c1'>// 2 Code Regions from 2:15 to 2:34 with file ids 1 and 2</span>
+<span style='background-color:#4A789C'>  if(*str)                          </span>
+<span style='background-color:#4A789C'>    </span><span style='background-color:#F6D55D'>PUT</span><span style='background-color:#4A789C'>;                            </span> <span class='c1'>// Expansion Region from 4:5 to 4:8 with file id 0 that expands a macro with file id 1</span>
+<span style='background-color:#4A789C'>  </span><span style='background-color:#F6D55D'>PUT</span><span style='background-color:#4A789C'>;                              </span> <span class='c1'>// Expansion Region from 5:3 to 5:6 with file id 0 that expands a macro with file id 2</span>
+<span style='background-color:#4A789C'>}</span>
+</pre>`
+
+.. _coverage mapping counter:
+.. _coverage mapping counters:
+
+Counter:
+^^^^^^^^
+
+A coverage mapping counter can represents a reference to the profile
+instrumentation counter. The execution count for a region with such counter
+is determined by looking up the value of the corresponding profile
+instrumentation counter.
+
+It can also represent a binary arithmetical expression that operates on
+coverage mapping counters or other expressions.
+The execution count for a region with an expression counter is determined by
+evaluating the expression's arguments and then adding them together or
+subtracting them from one another.
+In the example below, a subtraction expression is used to compute the execution
+count for the compound statement that follows the *else* keyword:
+
+:raw-html:`<pre class='highlight' style='line-height:initial;'><span>int main(int argc, const char *argv[]) </span><span style='background-color:#4A789C'>{   </span> <span class='c1'>// Region's counter is a reference to the profile counter #0</span>
+<span style='background-color:#4A789C'>                                           </span>
+<span style='background-color:#4A789C'>  if (argc > 1) </span><span style='background-color:#85C1F5'>{                        </span>   <span class='c1'>// Region's counter is a reference to the profile counter #1</span>
+<span style='background-color:#85C1F5'>    printf("%s\n", argv[1]);             </span><span>   </span>
+<span style='background-color:#85C1F5'>  }</span><span style='background-color:#4A789C'> else </span><span style='background-color:#F6D55D'>{                               </span>   <span class='c1'>// Region's counter is an expression (reference to the profile counter #0 - reference to the profile counter #1)</span>
+<span style='background-color:#F6D55D'>    printf("\n");                        </span>
+<span style='background-color:#F6D55D'>  }</span><span style='background-color:#4A789C'>                                        </span>
+<span style='background-color:#4A789C'>  return 0;                                </span>
+<span style='background-color:#4A789C'>}</span>
+</pre>`
+
+Finally, a coverage mapping counter can also represent an execution count of
+of zero. The zero counter is used to provide coverage mapping for
+unreachable statements and expressions, like in the example below:
+
+:raw-html:`<pre class='highlight' style='line-height:initial;'><span>int main() </span><span style='background-color:#4A789C'>{                  </span>
+<span style='background-color:#4A789C'>  return 0;                   </span>
+<span style='background-color:#4A789C'>  </span><span style='background-color:#85C1F5'>printf("Hello world!\n")</span><span style='background-color:#4A789C'>;   </span> <span class='c1'>// Unreachable region's counter is zero</span>
+<span style='background-color:#4A789C'>}</span>
+</pre>`
+
+The zero counters allow the code coverage tool to display proper line execution
+counts for the unreachable lines and highlight the unreachable code.
+Without them, the tool would think that those lines and regions were still
+executed, as it doesn't possess the frontend's knowledge.
+
+LLVM IR Representation
+======================
+
+The coverage mapping data is stored in the LLVM IR using a single global
+constant structure variable called *__llvm_coverage_mapping*
+with the *__llvm_covmap* section specifier.
+
+For example, let’s consider a C file and how it gets compiled to LLVM:
+
+.. _coverage mapping sample:
+
+.. code-block:: c
+
+  int foo() {
+    return 42;
+  }
+  int bar() {
+    return 13;
+  }
+
+The coverage mapping variable generated by Clang has 3 fields:
+
+* Coverage mapping header.
+
+* An array of function records.
+
+* Coverage mapping data which is an array of bytes. Zero paddings are added at the end to force 8 byte alignment.
+
+.. code-block:: llvm
+
+  @__llvm_coverage_mapping = internal constant { { i32, i32, i32, i32 }, [2 x { i64, i32, i64 }], [40 x i8] }
+  { 
+    { i32, i32, i32, i32 } ; Coverage map header
+    {
+      i32 2,  ; The number of function records
+      i32 20, ; The length of the string that contains the encoded translation unit filenames
+      i32 20, ; The length of the string that contains the encoded coverage mapping data
+      i32 2,  ; Coverage mapping format version
+    },
+    [2 x { i64, i32, i64 }] [ ; Function records
+     { i64, i32, i64 } {
+       i64 0x5cf8c24cdb18bdac, ; Function's name MD5
+       i32 9, ; Function's encoded coverage mapping data string length
+       i64 0  ; Function's structural hash
+     },
+     { i64, i32, i64 } { 
+       i64 0xe413754a191db537, ; Function's name MD5
+       i32 9, ; Function's encoded coverage mapping data string length
+       i64 0  ; Function's structural hash
+     }],
+   [40 x i8] c"..." ; Encoded data (dissected later)
+  }, section "__llvm_covmap", align 8
+
+The current version of the format is version 3. The only difference from version 2 is that a special encoding for column end locations was introduced to indicate gap regions.
+
+The function record layout has evolved since version 1. In version 1, the function record for *foo* is defined as follows:
+
+.. code-block:: llvm
+
+     { i8*, i32, i32, i64 } { i8* getelementptr inbounds ([3 x i8]* @__profn_foo, i32 0, i32 0), ; Function's name
+       i32 3, ; Function's name length
+       i32 9, ; Function's encoded coverage mapping data string length
+       i64 0  ; Function's structural hash
+     }
+
+
+Coverage Mapping Header:
+------------------------
+
+The coverage mapping header has the following fields:
+
+* The number of function records.
+
+* The length of the string in the third field of *__llvm_coverage_mapping* that contains the encoded translation unit filenames.
+
+* The length of the string in the third field of *__llvm_coverage_mapping* that contains the encoded coverage mapping data.
+
+* The format version. The current version is 3 (encoded as a 2).
+
+.. _function records:
+
+Function record:
+----------------
+
+A function record is a structure of the following type:
+
+.. code-block:: llvm
+
+  { i64, i32, i64 }
+
+It contains function name's MD5, the length of the encoded mapping data for that function, and function's 
+structural hash value.
+
+Encoded data:
+-------------
+
+The encoded data is stored in a single string that contains
+the encoded filenames used by this translation unit and the encoded coverage
+mapping data for each function in this translation unit.
+
+The encoded data has the following structure:
+
+``[filenames, coverageMappingDataForFunctionRecord0, coverageMappingDataForFunctionRecord1, ..., padding]``
+
+If necessary, the encoded data is padded with zeroes so that the size
+of the data string is rounded up to the nearest multiple of 8 bytes.
+
+Dissecting the sample:
+^^^^^^^^^^^^^^^^^^^^^^
+
+Here's an overview of the encoded data that was stored in the
+IR for the `coverage mapping sample`_ that was shown earlier:
+
+* The IR contains the following string constant that represents the encoded
+  coverage mapping data for the sample translation unit:
+
+  .. code-block:: llvm
+
+    c"\01\12/Users/alex/test.c\01\00\00\01\01\01\0C\02\02\01\00\00\01\01\04\0C\02\02\00\00"
+
+* The string contains values that are encoded in the LEB128 format, which is
+  used throughout for storing integers. It also contains a string value.
+
+* The length of the substring that contains the encoded translation unit
+  filenames is the value of the second field in the *__llvm_coverage_mapping*
+  structure, which is 20, thus the filenames are encoded in this string:
+
+  .. code-block:: llvm
+
+    c"\01\12/Users/alex/test.c"
+
+  This string contains the following data:
+
+  * Its first byte has a value of ``0x01``. It stores the number of filenames
+    contained in this string.
+  * Its second byte stores the length of the first filename in this string.
+  * The remaining 18 bytes are used to store the first filename.
+
+* The length of the substring that contains the encoded coverage mapping data
+  for the first function is the value of the third field in the first
+  structure in an array of `function records`_ stored in the
+  third field of the *__llvm_coverage_mapping* structure, which is the 9.
+  Therefore, the coverage mapping for the first function record is encoded
+  in this string:
+
+  .. code-block:: llvm
+
+    c"\01\00\00\01\01\01\0C\02\02"
+
+  This string consists of the following bytes:
+
+  +----------+-------------------------------------------------------------------------------------------------------------------------+
+  | ``0x01`` | The number of file ids used by this function. There is only one file id used by the mapping data in this function.      |
+  +----------+-------------------------------------------------------------------------------------------------------------------------+
+  | ``0x00`` | An index into the filenames array which corresponds to the file "/Users/alex/test.c".                                   |
+  +----------+-------------------------------------------------------------------------------------------------------------------------+
+  | ``0x00`` | The number of counter expressions used by this function. This function doesn't use any expressions.                     |
+  +----------+-------------------------------------------------------------------------------------------------------------------------+
+  | ``0x01`` | The number of mapping regions that are stored in an array for the function's file id #0.                                |
+  +----------+-------------------------------------------------------------------------------------------------------------------------+
+  | ``0x01`` | The coverage mapping counter for the first region in this function. The value of 1 tells us that it's a coverage        |
+  |          | mapping counter that is a reference to the profile instrumentation counter with an index of 0.                          |
+  +----------+-------------------------------------------------------------------------------------------------------------------------+
+  | ``0x01`` | The starting line of the first mapping region in this function.                                                         |
+  +----------+-------------------------------------------------------------------------------------------------------------------------+
+  | ``0x0C`` | The starting column of the first mapping region in this function.                                                       |
+  +----------+-------------------------------------------------------------------------------------------------------------------------+
+  | ``0x02`` | The ending line of the first mapping region in this function.                                                           |
+  +----------+-------------------------------------------------------------------------------------------------------------------------+
+  | ``0x02`` | The ending column of the first mapping region in this function.                                                         |
+  +----------+-------------------------------------------------------------------------------------------------------------------------+
+
+* The length of the substring that contains the encoded coverage mapping data
+  for the second function record is also 9. It's structured like the mapping data
+  for the first function record.
+
+* The two trailing bytes are zeroes and are used to pad the coverage mapping
+  data to give it the 8 byte alignment.
+
+Encoding
+========
+
+The per-function coverage mapping data is encoded as a stream of bytes,
+with a simple structure. The structure consists of the encoding
+`types <cvmtypes_>`_ like variable-length unsigned integers, that
+are used to encode `File ID Mapping`_, `Counter Expressions`_ and
+the `Mapping Regions`_.
+
+The format of the structure follows:
+
+  ``[file id mapping, counter expressions, mapping regions]``
+
+The translation unit filenames are encoded using the same encoding
+`types <cvmtypes_>`_ as the per-function coverage mapping data, with the
+following structure:
+
+  ``[numFilenames : LEB128, filename0 : string, filename1 : string, ...]``
+
+.. _cvmtypes:
+
+Types
+-----
+
+This section describes the basic types that are used by the encoding format
+and can appear after ``:`` in the ``[foo : type]`` description.
+
+.. _LEB128:
+
+LEB128
+^^^^^^
+
+LEB128 is an unsigned integer value that is encoded using DWARF's LEB128
+encoding, optimizing for the case where values are small
+(1 byte for values less than 128).
+
+.. _CoverageStrings:
+
+Strings
+^^^^^^^
+
+``[length : LEB128, characters...]``
+
+String values are encoded with a `LEB value <LEB128_>`_ for the length
+of the string and a sequence of bytes for its characters.
+
+.. _file id mapping:
+
+File ID Mapping
+---------------
+
+``[numIndices : LEB128, filenameIndex0 : LEB128, filenameIndex1 : LEB128, ...]``
+
+File id mapping in a function's coverage mapping stream
+contains the indices into the translation unit's filenames array.
+
+Counter
+-------
+
+``[value : LEB128]``
+
+A `coverage mapping counter`_ is stored in a single `LEB value <LEB128_>`_.
+It is composed of two things --- the `tag <counter-tag_>`_
+which is stored in the lowest 2 bits, and the `counter data`_ which is stored
+in the remaining bits.
+
+.. _counter-tag:
+
+Tag:
+^^^^
+
+The counter's tag encodes the counter's kind
+and, if the counter is an expression, the expression's kind.
+The possible tag values are:
+
+* 0 - The counter is zero.
+
+* 1 - The counter is a reference to the profile instrumentation counter.
+
+* 2 - The counter is a subtraction expression.
+
+* 3 - The counter is an addition expression.
+
+.. _counter data:
+
+Data:
+^^^^^
+
+The counter's data is interpreted in the following manner:
+
+* When the counter is a reference to the profile instrumentation counter,
+  then the counter's data is the id of the profile counter.
+* When the counter is an expression, then the counter's data
+  is the index into the array of counter expressions.
+
+.. _Counter Expressions:
+
+Counter Expressions
+-------------------
+
+``[numExpressions : LEB128, expr0LHS : LEB128, expr0RHS : LEB128, expr1LHS : LEB128, expr1RHS : LEB128, ...]``
+
+Counter expressions consist of two counters as they
+represent binary arithmetic operations.
+The expression's kind is determined from the `tag <counter-tag_>`_ of the
+counter that references this expression.
+
+.. _Mapping Regions:
+
+Mapping Regions
+---------------
+
+``[numRegionArrays : LEB128, regionsForFile0, regionsForFile1, ...]``
+
+The mapping regions are stored in an array of sub-arrays where every
+region in a particular sub-array has the same file id.
+
+The file id for a sub-array of regions is the index of that
+sub-array in the main array e.g. The first sub-array will have the file id
+of 0.
+
+Sub-Array of Regions
+^^^^^^^^^^^^^^^^^^^^
+
+``[numRegions : LEB128, region0, region1, ...]``
+
+The mapping regions for a specific file id are stored in an array that is
+sorted in an ascending order by the region's starting location.
+
+Mapping Region
+^^^^^^^^^^^^^^
+
+``[header, source range]``
+
+The mapping region record contains two sub-records ---
+the `header`_, which stores the counter and/or the region's kind,
+and the `source range`_ that contains the starting and ending
+location of this region.
+
+.. _header:
+
+Header
+^^^^^^
+
+``[counter]``
+
+or
+
+``[pseudo-counter]``
+
+The header encodes the region's counter and the region's kind.
+
+The value of the counter's tag distinguishes between the counters and
+pseudo-counters --- if the tag is zero, than this header contains a
+pseudo-counter, otherwise this header contains an ordinary counter.
+
+Counter:
+""""""""
+
+A mapping region whose header has a counter with a non-zero tag is
+a code region.
+
+Pseudo-Counter:
+"""""""""""""""
+
+``[value : LEB128]``
+
+A pseudo-counter is stored in a single `LEB value <LEB128_>`_, just like
+the ordinary counter. It has the following interpretation:
+
+* bits 0-1: tag, which is always 0.
+
+* bit 2: expansionRegionTag. If this bit is set, then this mapping region
+  is an expansion region.
+
+* remaining bits: data. If this region is an expansion region, then the data
+  contains the expanded file id of that region.
+
+  Otherwise, the data contains the region's kind. The possible region
+  kind values are:
+
+  * 0 - This mapping region is a code region with a counter of zero.
+  * 2 - This mapping region is a skipped region.
+
+.. _source range:
+
+Source Range
+^^^^^^^^^^^^
+
+``[deltaLineStart : LEB128, columnStart : LEB128, numLines : LEB128, columnEnd : LEB128]``
+
+The source range record contains the following fields:
+
+* *deltaLineStart*: The difference between the starting line of the
+  current mapping region and the starting line of the previous mapping region.
+
+  If the current mapping region is the first region in the current
+  sub-array, then it stores the starting line of that region.
+
+* *columnStart*: The starting column of the mapping region.
+
+* *numLines*: The difference between the ending line and the starting line
+  of the current mapping region.
+
+* *columnEnd*: The ending column of the mapping region. If the high bit is set,
+  the current mapping region is a gap area. A count for a gap area is only used
+  as the line execution count if there are no other regions on a line.

Added: www-releases/trunk/8.0.1/docs/_sources/DebuggingJITedCode.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.1/docs/_sources/DebuggingJITedCode.rst.txt?rev=368037&view=auto
==============================================================================
--- www-releases/trunk/8.0.1/docs/_sources/DebuggingJITedCode.rst.txt (added)
+++ www-releases/trunk/8.0.1/docs/_sources/DebuggingJITedCode.rst.txt Tue Aug  6 06:51:02 2019
@@ -0,0 +1,143 @@
+==============================
+Debugging JIT-ed Code With GDB
+==============================
+
+Background
+==========
+
+Without special runtime support, debugging dynamically generated code with
+GDB (as well as most debuggers) can be quite painful.  Debuggers generally
+read debug information from the object file of the code, but for JITed
+code, there is no such file to look for.
+
+In order to communicate the necessary debug info to GDB, an interface for
+registering JITed code with debuggers has been designed and implemented for
+GDB and LLVM MCJIT.  At a high level, whenever MCJIT generates new machine code,
+it does so in an in-memory object file that contains the debug information in
+DWARF format.  MCJIT then adds this in-memory object file to a global list of
+dynamically generated object files and calls a special function
+(``__jit_debug_register_code``) marked noinline that GDB knows about.  When
+GDB attaches to a process, it puts a breakpoint in this function and loads all
+of the object files in the global list.  When MCJIT calls the registration
+function, GDB catches the breakpoint signal, loads the new object file from
+the inferior's memory, and resumes the execution.  In this way, GDB can get the
+necessary debug information.
+
+GDB Version
+===========
+
+In order to debug code JIT-ed by LLVM, you need GDB 7.0 or newer, which is
+available on most modern distributions of Linux.  The version of GDB that
+Apple ships with Xcode has been frozen at 6.3 for a while.  LLDB may be a
+better option for debugging JIT-ed code on Mac OS X.
+
+
+Debugging MCJIT-ed code
+=======================
+
+The emerging MCJIT component of LLVM allows full debugging of JIT-ed code with
+GDB.  This is due to MCJIT's ability to use the MC emitter to provide full
+DWARF debugging information to GDB.
+
+Note that lli has to be passed the ``-use-mcjit`` flag to JIT the code with
+MCJIT instead of the old JIT.
+
+Example
+-------
+
+Consider the following C code (with line numbers added to make the example
+easier to follow):
+
+..
+   FIXME:
+   Sphinx has the ability to automatically number these lines by adding
+   :linenos: on the line immediately following the `.. code-block:: c`, but
+   it looks like garbage; the line numbers don't even line up with the
+   lines. Is this a Sphinx bug, or is it a CSS problem?
+
+.. code-block:: c
+
+   1   int compute_factorial(int n)
+   2   {
+   3       if (n <= 1)
+   4           return 1;
+   5
+   6       int f = n;
+   7       while (--n > 1)
+   8           f *= n;
+   9       return f;
+   10  }
+   11
+   12
+   13  int main(int argc, char** argv)
+   14  {
+   15      if (argc < 2)
+   16          return -1;
+   17      char firstletter = argv[1][0];
+   18      int result = compute_factorial(firstletter - '0');
+   19
+   20      // Returned result is clipped at 255...
+   21      return result;
+   22  }
+
+Here is a sample command line session that shows how to build and run this
+code via ``lli`` inside GDB:
+
+.. code-block:: bash
+
+   $ $BINPATH/clang -cc1 -O0 -g -emit-llvm showdebug.c
+   $ gdb --quiet --args $BINPATH/lli -use-mcjit showdebug.ll 5
+   Reading symbols from $BINPATH/lli...done.
+   (gdb) b showdebug.c:6
+   No source file named showdebug.c.
+   Make breakpoint pending on future shared library load? (y or [n]) y
+   Breakpoint 1 (showdebug.c:6) pending.
+   (gdb) r
+   Starting program: $BINPATH/lli -use-mcjit showdebug.ll 5
+   [Thread debugging using libthread_db enabled]
+
+   Breakpoint 1, compute_factorial (n=5) at showdebug.c:6
+   6	    int f = n;
+   (gdb) p n
+   $1 = 5
+   (gdb) p f
+   $2 = 0
+   (gdb) n
+   7	    while (--n > 1)
+   (gdb) p f
+   $3 = 5
+   (gdb) b showdebug.c:9
+   Breakpoint 2 at 0x7ffff7ed404c: file showdebug.c, line 9.
+   (gdb) c
+   Continuing.
+
+   Breakpoint 2, compute_factorial (n=1) at showdebug.c:9
+   9	    return f;
+   (gdb) p f
+   $4 = 120
+   (gdb) bt
+   #0  compute_factorial (n=1) at showdebug.c:9
+   #1  0x00007ffff7ed40a9 in main (argc=2, argv=0x16677e0) at showdebug.c:18
+   #2  0x3500000001652748 in ?? ()
+   #3  0x00000000016677e0 in ?? ()
+   #4  0x0000000000000002 in ?? ()
+   #5  0x0000000000d953b3 in llvm::MCJIT::runFunction (this=0x16151f0, F=0x1603020, ArgValues=...) at /home/ebenders_test/llvm_svn_rw/lib/ExecutionEngine/MCJIT/MCJIT.cpp:161
+   #6  0x0000000000dc8872 in llvm::ExecutionEngine::runFunctionAsMain (this=0x16151f0, Fn=0x1603020, argv=..., envp=0x7fffffffe040)
+       at /home/ebenders_test/llvm_svn_rw/lib/ExecutionEngine/ExecutionEngine.cpp:397
+   #7  0x000000000059c583 in main (argc=4, argv=0x7fffffffe018, envp=0x7fffffffe040) at /home/ebenders_test/llvm_svn_rw/tools/lli/lli.cpp:324
+   (gdb) finish
+   Run till exit from #0  compute_factorial (n=1) at showdebug.c:9
+   0x00007ffff7ed40a9 in main (argc=2, argv=0x16677e0) at showdebug.c:18
+   18	    int result = compute_factorial(firstletter - '0');
+   Value returned is $5 = 120
+   (gdb) p result
+   $6 = 23406408
+   (gdb) n
+   21	    return result;
+   (gdb) p result
+   $7 = 120
+   (gdb) c
+   Continuing.
+
+   Program exited with code 0170.
+   (gdb)

Added: www-releases/trunk/8.0.1/docs/_sources/DeveloperPolicy.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.1/docs/_sources/DeveloperPolicy.rst.txt?rev=368037&view=auto
==============================================================================
--- www-releases/trunk/8.0.1/docs/_sources/DeveloperPolicy.rst.txt (added)
+++ www-releases/trunk/8.0.1/docs/_sources/DeveloperPolicy.rst.txt Tue Aug  6 06:51:02 2019
@@ -0,0 +1,785 @@
+=====================
+LLVM Developer Policy
+=====================
+
+.. contents::
+   :local:
+
+Introduction
+============
+
+This document contains the LLVM Developer Policy which defines the project's
+policy towards developers and their contributions. The intent of this policy is
+to eliminate miscommunication, rework, and confusion that might arise from the
+distributed nature of LLVM's development.  By stating the policy in clear terms,
+we hope each developer can know ahead of time what to expect when making LLVM
+contributions.  This policy covers all llvm.org subprojects, including Clang,
+LLDB, libc++, etc.
+
+This policy is also designed to accomplish the following objectives:
+
+#. Attract both users and developers to the LLVM project.
+
+#. Make life as simple and easy for contributors as possible.
+
+#. Keep the top of tree as stable as possible.
+
+#. Establish awareness of the project's :ref:`copyright, license, and patent
+   policies <copyright-license-patents>` with contributors to the project.
+
+This policy is aimed at frequent contributors to LLVM. People interested in
+contributing one-off patches can do so in an informal way by sending them to the
+`llvm-commits mailing list
+<http://lists.llvm.org/mailman/listinfo/llvm-commits>`_ and engaging another
+developer to see it through the process.
+
+Developer Policies
+==================
+
+This section contains policies that pertain to frequent LLVM developers.  We
+always welcome `one-off patches`_ from people who do not routinely contribute to
+LLVM, but we expect more from frequent contributors to keep the system as
+efficient as possible for everyone.  Frequent LLVM contributors are expected to
+meet the following requirements in order for LLVM to maintain a high standard of
+quality.
+
+Stay Informed
+-------------
+
+Developers should stay informed by reading at least the "dev" mailing list for
+the projects you are interested in, such as `llvm-dev
+<http://lists.llvm.org/mailman/listinfo/llvm-dev>`_ for LLVM, `cfe-dev
+<http://lists.llvm.org/mailman/listinfo/cfe-dev>`_ for Clang, or `lldb-dev
+<http://lists.llvm.org/mailman/listinfo/lldb-dev>`_ for LLDB.  If you are
+doing anything more than just casual work on LLVM, it is suggested that you also
+subscribe to the "commits" mailing list for the subproject you're interested in,
+such as `llvm-commits
+<http://lists.llvm.org/mailman/listinfo/llvm-commits>`_, `cfe-commits
+<http://lists.llvm.org/mailman/listinfo/cfe-commits>`_, or `lldb-commits
+<http://lists.llvm.org/mailman/listinfo/lldb-commits>`_.  Reading the
+"commits" list and paying attention to changes being made by others is a good
+way to see what other people are interested in and watching the flow of the
+project as a whole.
+
+We recommend that active developers register an email account with `LLVM
+Bugzilla <https://bugs.llvm.org/>`_ and preferably subscribe to the `llvm-bugs
+<http://lists.llvm.org/mailman/listinfo/llvm-bugs>`_ email list to keep track
+of bugs and enhancements occurring in LLVM.  We really appreciate people who are
+proactive at catching incoming bugs in their components and dealing with them
+promptly.
+
+Please be aware that all public LLVM mailing lists are public and archived, and
+that notices of confidentiality or non-disclosure cannot be respected.
+
+.. _patch:
+.. _one-off patches:
+
+Making and Submitting a Patch
+-----------------------------
+
+When making a patch for review, the goal is to make it as easy for the reviewer
+to read it as possible.  As such, we recommend that you:
+
+#. Make your patch against git master, not a branch, and not an old version
+   of LLVM.  This makes it easy to apply the patch.  For information on how to
+   clone from git, please see the :ref:`Getting Started Guide
+   <checkout>`.
+
+#. Similarly, patches should be submitted soon after they are generated.  Old
+   patches may not apply correctly if the underlying code changes between the
+   time the patch was created and the time it is applied.
+
+#. Patches should be made with ``git format-patch``, or similar. If you use a
+   different tool, make sure it uses the ``diff -u`` format and that it
+   doesn't contain clutter which makes it hard to read.
+
+Once your patch is ready, submit it by emailing it to the appropriate project's
+commit mailing list (or commit it directly if applicable). Alternatively, some
+patches get sent to the project's development list or component of the LLVM bug
+tracker, but the commit list is the primary place for reviews and should
+generally be preferred.
+
+When sending a patch to a mailing list, it is a good idea to send it as an
+*attachment* to the message, not embedded into the text of the message.  This
+ensures that your mailer will not mangle the patch when it sends it (e.g. by
+making whitespace changes or by wrapping lines).
+
+*For Thunderbird users:* Before submitting a patch, please open *Preferences >
+Advanced > General > Config Editor*, find the key
+``mail.content_disposition_type``, and set its value to ``1``. Without this
+setting, Thunderbird sends your attachment using ``Content-Disposition: inline``
+rather than ``Content-Disposition: attachment``. Apple Mail gamely displays such
+a file inline, making it difficult to work with for reviewers using that
+program.
+
+When submitting patches, please do not add confidentiality or non-disclosure
+notices to the patches themselves.  These notices conflict with the `LLVM
+License`_ and may result in your contribution being excluded.
+
+.. _code review:
+
+Code Reviews
+------------
+
+LLVM has a code review policy. Code review is one way to increase the quality of
+software. We generally follow these policies:
+
+#. All developers are required to have significant changes reviewed before they
+   are committed to the repository.
+
+#. Code reviews are conducted by email on the relevant project's commit mailing
+   list, or alternatively on the project's development list or bug tracker.
+
+#. Code can be reviewed either before it is committed or after.  We expect major
+   changes to be reviewed before being committed, but smaller changes (or
+   changes where the developer owns the component) can be reviewed after commit.
+
+#. The developer responsible for a code change is also responsible for making
+   all necessary review-related changes.
+
+#. Code review can be an iterative process, which continues until the patch is
+   ready to be committed. Specifically, once a patch is sent out for review, it
+   needs an explicit "looks good" before it is submitted. Do not assume silent
+   approval, or request active objections to the patch with a deadline.
+
+Sometimes code reviews will take longer than you would hope for, especially for
+larger features. Accepted ways to speed up review times for your patches are:
+
+* Review other people's patches. If you help out, everybody will be more
+  willing to do the same for you; goodwill is our currency.
+* Ping the patch. If it is urgent, provide reasons why it is important to you to
+  get this patch landed and ping it every couple of days. If it is
+  not urgent, the common courtesy ping rate is one week. Remember that you're
+  asking for valuable time from other professional developers.
+* Ask for help on IRC. Developers on IRC will be able to either help you
+  directly, or tell you who might be a good reviewer.
+* Split your patch into multiple smaller patches that build on each other. The
+  smaller your patch, the higher the probability that somebody will take a quick
+  look at it.
+
+Developers should participate in code reviews as both reviewers and
+reviewees. If someone is kind enough to review your code, you should return the
+favor for someone else.  Note that anyone is welcome to review and give feedback
+on a patch, but only people with Subversion write access can approve it.
+
+There is a web based code review tool that can optionally be used
+for code reviews. See :doc:`Phabricator`.
+
+.. _code owners:
+
+Code Owners
+-----------
+
+The LLVM Project relies on two features of its process to maintain rapid
+development in addition to the high quality of its source base: the combination
+of code review plus post-commit review for trusted maintainers.  Having both is
+a great way for the project to take advantage of the fact that most people do
+the right thing most of the time, and only commit patches without pre-commit
+review when they are confident they are right.
+
+The trick to this is that the project has to guarantee that all patches that are
+committed are reviewed after they go in: you don't want everyone to assume
+someone else will review it, allowing the patch to go unreviewed.  To solve this
+problem, we have a notion of an 'owner' for a piece of the code.  The sole
+responsibility of a code owner is to ensure that a commit to their area of the
+code is appropriately reviewed, either by themself or by someone else.  The list
+of current code owners can be found in the file `CODE_OWNERS.TXT
+<https://github.com/llvm/llvm-project/blob/master/llvm/CODE_OWNERS.TXT>`_ in the
+root of the LLVM source tree.
+
+Note that code ownership is completely different than reviewers: anyone can
+review a piece of code, and we welcome code review from anyone who is
+interested.  Code owners are the "last line of defense" to guarantee that all
+patches that are committed are actually reviewed.
+
+Being a code owner is a somewhat unglamorous position, but it is incredibly
+important for the ongoing success of the project.  Because people get busy,
+interests change, and unexpected things happen, code ownership is purely opt-in,
+and anyone can choose to resign their "title" at any time. For now, we do not
+have an official policy on how one gets elected to be a code owner.
+
+.. _include a testcase:
+
+Test Cases
+----------
+
+Developers are required to create test cases for any bugs fixed and any new
+features added.  Some tips for getting your testcase approved:
+
+* All feature and regression test cases are added to the ``llvm/test``
+  directory. The appropriate sub-directory should be selected (see the
+  :doc:`Testing Guide <TestingGuide>` for details).
+
+* Test cases should be written in :doc:`LLVM assembly language <LangRef>`.
+
+* Test cases, especially for regressions, should be reduced as much as possible,
+  by :doc:`bugpoint <Bugpoint>` or manually. It is unacceptable to place an
+  entire failing program into ``llvm/test`` as this creates a *time-to-test*
+  burden on all developers. Please keep them short.
+
+Note that llvm/test and clang/test are designed for regression and small feature
+tests only. More extensive test cases (e.g., entire applications, benchmarks,
+etc) should be added to the ``llvm-test`` test suite.  The llvm-test suite is
+for coverage (correctness, performance, etc) testing, not feature or regression
+testing.
+
+Quality
+-------
+
+The minimum quality standards that any change must satisfy before being
+committed to the main development branch are:
+
+#. Code must adhere to the `LLVM Coding Standards <CodingStandards.html>`_.
+
+#. Code must compile cleanly (no errors, no warnings) on at least one platform.
+
+#. Bug fixes and new features should `include a testcase`_ so we know if the
+   fix/feature ever regresses in the future.
+
+#. Code must pass the ``llvm/test`` test suite.
+
+#. The code must not cause regressions on a reasonable subset of llvm-test,
+   where "reasonable" depends on the contributor's judgement and the scope of
+   the change (more invasive changes require more testing). A reasonable subset
+   might be something like "``llvm-test/MultiSource/Benchmarks``".
+
+Additionally, the committer is responsible for addressing any problems found in
+the future that the change is responsible for.  For example:
+
+* The code should compile cleanly on all supported platforms.
+
+* The changes should not cause any correctness regressions in the ``llvm-test``
+  suite and must not cause any major performance regressions.
+
+* The change set should not cause performance or correctness regressions for the
+  LLVM tools.
+
+* The changes should not cause performance or correctness regressions in code
+  compiled by LLVM on all applicable targets.
+
+* You are expected to address any `Bugzilla bugs <https://bugs.llvm.org/>`_ that
+  result from your change.
+
+We prefer for this to be handled before submission but understand that it isn't
+possible to test all of this for every submission.  Our build bots and nightly
+testing infrastructure normally finds these problems.  A good rule of thumb is
+to check the nightly testers for regressions the day after your change.  Build
+bots will directly email you if a group of commits that included yours caused a
+failure.  You are expected to check the build bot messages to see if they are
+your fault and, if so, fix the breakage.
+
+Commits that violate these quality standards (e.g. are very broken) may be
+reverted. This is necessary when the change blocks other developers from making
+progress. The developer is welcome to re-commit the change after the problem has
+been fixed.
+
+.. _commit messages:
+
+Commit messages
+---------------
+
+Although we don't enforce the format of commit messages, we prefer that
+you follow these guidelines to help review, search in logs, email formatting
+and so on. These guidelines are very similar to rules used by other open source
+projects.
+
+Most importantly, the contents of the message should be carefully written to
+convey the rationale of the change (without delving too much in detail). It
+also should avoid being vague or overly specific. For example, "bits were not
+set right" will leave the reviewer wondering about which bits, and why they
+weren't right, while "Correctly set overflow bits in TargetInfo" conveys almost
+all there is to the change.
+
+Below are some guidelines about the format of the message itself:
+
+* Separate the commit message into title, body and, if you're not the original
+  author, a "Patch by" attribution line (see below).
+
+* The title should be concise. Because all commits are emailed to the list with
+  the first line as the subject, long titles are frowned upon.  Short titles
+  also look better in `git log`.
+
+* When the changes are restricted to a specific part of the code (e.g. a
+  back-end or optimization pass), it is customary to add a tag to the
+  beginning of the line in square brackets.  For example, "[SCEV] ..."
+  or "[OpenMP] ...". This helps email filters and searches for post-commit
+  reviews.
+
+* The body, if it exists, should be separated from the title by an empty line.
+
+* The body should be concise, but explanatory, including a complete
+  reasoning.  Unless it is required to understand the change, examples,
+  code snippets and gory details should be left to bug comments, web
+  review or the mailing list.
+
+* If the patch fixes a bug in bugzilla, please include the PR# in the message.
+
+* `Attribution of Changes`_ should be in a separate line, after the end of
+  the body, as simple as "Patch by John Doe.". This is how we officially
+  handle attribution, and there are automated processes that rely on this
+  format.
+
+* Text formatting and spelling should follow the same rules as documentation
+  and in-code comments, ex. capitalization, full stop, etc.
+
+* If the commit is a bug fix on top of another recently committed patch, or a
+  revert or reapply of a patch, include the svn revision number of the prior
+  related commit. This could be as simple as "Revert rNNNN because it caused
+  PR#".
+
+For minor violations of these recommendations, the community normally favors
+reminding the contributor of this policy over reverting. Minor corrections and
+omissions can be handled by sending a reply to the commits mailing list.
+
+Obtaining Commit Access
+-----------------------
+
+We grant commit access to contributors with a track record of submitting high
+quality patches.  If you would like commit access, please send an email to
+`Chris <mailto:clattner at llvm.org>`_ with the following information:
+
+#. The user name you want to commit with, e.g. "hacker".
+
+#. The full name and email address you want message to llvm-commits to come
+   from, e.g. "J. Random Hacker <hacker at yoyodyne.com>".
+
+#. A "password hash" of the password you want to use, e.g. "``2ACR96qjUqsyM``".
+   Note that you don't ever tell us what your password is; you just give it to
+   us in an encrypted form.  To get this, run "``htpasswd``" (a utility that
+   comes with apache) in *crypt* mode (often enabled with "``-d``"), or find a web
+   page that will do it for you.  Note that our system does not work with MD5
+   hashes.  These are significantly longer than a crypt hash - e.g.
+   "``$apr1$vea6bBV2$Z8IFx.AfeD8LhqlZFqJer0``", we only accept the shorter crypt hash.
+
+Once you've been granted commit access, you should be able to check out an LLVM
+tree with an SVN URL of "https://username@llvm.org/..." instead of the normal
+anonymous URL of "http://llvm.org/...".  The first time you commit you'll have
+to type in your password.  Note that you may get a warning from SVN about an
+untrusted key; you can ignore this.  To verify that your commit access works,
+please do a test commit (e.g. change a comment or add a blank line).  Your first
+commit to a repository may require the autogenerated email to be approved by a
+moderator of the mailing list.
+This is normal and will be done when the mailing list owner has time.
+
+If you have recently been granted commit access, these policies apply:
+
+#. You are granted *commit-after-approval* to all parts of LLVM.  To get
+   approval, submit a `patch`_ to `llvm-commits
+   <http://lists.llvm.org/mailman/listinfo/llvm-commits>`_. When approved,
+   you may commit it yourself.
+
+#. You are allowed to commit patches without approval which you think are
+   obvious. This is clearly a subjective decision --- we simply expect you to
+   use good judgement.  Examples include: fixing build breakage, reverting
+   obviously broken patches, documentation/comment changes, any other minor
+   changes. Avoid committing formatting- or whitespace-only changes outside of
+   code you plan to make subsequent changes to. Also, try to separate
+   formatting or whitespace changes from functional changes, either by
+   correcting the format first (ideally) or afterward. Such changes should be
+   highly localized and the commit message should clearly state that the commit
+   is not intended to change functionality, usually by stating it is
+   :ref:`NFC <nfc>`.
+
+#. You are allowed to commit patches without approval to those portions of LLVM
+   that you have contributed or maintain (i.e., have been assigned
+   responsibility for), with the proviso that such commits must not break the
+   build.  This is a "trust but verify" policy, and commits of this nature are
+   reviewed after they are committed.
+
+#. Multiple violations of these policies or a single egregious violation may
+   cause commit access to be revoked.
+
+In any case, your changes are still subject to `code review`_ (either before or
+after they are committed, depending on the nature of the change).  You are
+encouraged to review other peoples' patches as well, but you aren't required
+to do so.
+
+.. _discuss the change/gather consensus:
+
+Making a Major Change
+---------------------
+
+When a developer begins a major new project with the aim of contributing it back
+to LLVM, they should inform the community with an email to the `llvm-dev
+<http://lists.llvm.org/mailman/listinfo/llvm-dev>`_ email list, to the extent
+possible. The reason for this is to:
+
+#. keep the community informed about future changes to LLVM,
+
+#. avoid duplication of effort by preventing multiple parties working on the
+   same thing and not knowing about it, and
+
+#. ensure that any technical issues around the proposed work are discussed and
+   resolved before any significant work is done.
+
+The design of LLVM is carefully controlled to ensure that all the pieces fit
+together well and are as consistent as possible. If you plan to make a major
+change to the way LLVM works or want to add a major new extension, it is a good
+idea to get consensus with the development community before you start working on
+it.
+
+Once the design of the new feature is finalized, the work itself should be done
+as a series of `incremental changes`_, not as a long-term development branch.
+
+.. _incremental changes:
+
+Incremental Development
+-----------------------
+
+In the LLVM project, we do all significant changes as a series of incremental
+patches.  We have a strong dislike for huge changes or long-term development
+branches.  Long-term development branches have a number of drawbacks:
+
+#. Branches must have mainline merged into them periodically.  If the branch
+   development and mainline development occur in the same pieces of code,
+   resolving merge conflicts can take a lot of time.
+
+#. Other people in the community tend to ignore work on branches.
+
+#. Huge changes (produced when a branch is merged back onto mainline) are
+   extremely difficult to `code review`_.
+
+#. Branches are not routinely tested by our nightly tester infrastructure.
+
+#. Changes developed as monolithic large changes often don't work until the
+   entire set of changes is done.  Breaking it down into a set of smaller
+   changes increases the odds that any of the work will be committed to the main
+   repository.
+
+To address these problems, LLVM uses an incremental development style and we
+require contributors to follow this practice when making a large/invasive
+change.  Some tips:
+
+* Large/invasive changes usually have a number of secondary changes that are
+  required before the big change can be made (e.g. API cleanup, etc).  These
+  sorts of changes can often be done before the major change is done,
+  independently of that work.
+
+* The remaining inter-related work should be decomposed into unrelated sets of
+  changes if possible.  Once this is done, define the first increment and get
+  consensus on what the end goal of the change is.
+
+* Each change in the set can be stand alone (e.g. to fix a bug), or part of a
+  planned series of changes that works towards the development goal.
+
+* Each change should be kept as small as possible. This simplifies your work
+  (into a logical progression), simplifies code review and reduces the chance
+  that you will get negative feedback on the change. Small increments also
+  facilitate the maintenance of a high quality code base.
+
+* Often, an independent precursor to a big change is to add a new API and slowly
+  migrate clients to use the new API.  Each change to use the new API is often
+  "obvious" and can be committed without review.  Once the new API is in place
+  and used, it is much easier to replace the underlying implementation of the
+  API.  This implementation change is logically separate from the API
+  change.
+
+If you are interested in making a large change, and this scares you, please make
+sure to first `discuss the change/gather consensus`_ then ask about the best way
+to go about making the change.
+
+Attribution of Changes
+----------------------
+
+When contributors submit a patch to an LLVM project, other developers with
+commit access may commit it for the author once appropriate (based on the
+progression of code review, etc.). When doing so, it is important to retain
+correct attribution of contributions to their contributors. However, we do not
+want the source code to be littered with random attributions "this code written
+by J. Random Hacker" (this is noisy and distracting). In practice, the revision
+control system keeps a perfect history of who changed what, and the CREDITS.txt
+file describes higher-level contributions. If you commit a patch for someone
+else, please follow the attribution of changes in the simple manner as outlined
+by the `commit messages`_ section. Overall, please do not add contributor names
+to the source code.
+
+Also, don't commit patches authored by others unless they have submitted the
+patch to the project or you have been authorized to submit them on their behalf
+(you work together and your company authorized you to contribute the patches,
+etc.). The author should first submit them to the relevant project's commit
+list, development list, or LLVM bug tracker component. If someone sends you
+a patch privately, encourage them to submit it to the appropriate list first.
+
+
+.. _IR backwards compatibility:
+
+IR Backwards Compatibility
+--------------------------
+
+When the IR format has to be changed, keep in mind that we try to maintain some
+backwards compatibility. The rules are intended as a balance between convenience
+for llvm users and not imposing a big burden on llvm developers:
+
+* The textual format is not backwards compatible. We don't change it too often,
+  but there are no specific promises.
+
+* Additions and changes to the IR should be reflected in
+  ``test/Bitcode/compatibility.ll``.
+
+* The current LLVM version supports loading any bitcode since version 3.0.
+
+* After each X.Y release, ``compatibility.ll`` must be copied to
+  ``compatibility-X.Y.ll``. The corresponding bitcode file should be assembled
+  using the X.Y build and committed as ``compatibility-X.Y.ll.bc``.
+
+* Newer releases can ignore features from older releases, but they cannot
+  miscompile them. For example, if nsw is ever replaced with something else,
+  dropping it would be a valid way to upgrade the IR.
+
+* Debug metadata is special in that it is currently dropped during upgrades.
+
+* Non-debug metadata is defined to be safe to drop, so a valid way to upgrade
+  it is to drop it. That is not very user friendly and a bit more effort is
+  expected, but no promises are made.
+
+C API Changes
+----------------
+
+* Stability Guarantees: The C API is, in general, a "best effort" for stability.
+  This means that we make every attempt to keep the C API stable, but that
+  stability will be limited by the abstractness of the interface and the
+  stability of the C++ API that it wraps. In practice, this means that things
+  like "create debug info" or "create this type of instruction" are likely to be
+  less stable than "take this IR file and JIT it for my current machine".
+
+* Release stability: We won't break the C API on the release branch with patches
+  that go on that branch, with the exception that we will fix an unintentional
+  C API break that will keep the release consistent with both the previous and
+  next release.
+
+* Testing: Patches to the C API are expected to come with tests just like any
+  other patch.
+
+* Including new things into the API: If an LLVM subcomponent has a C API already
+  included, then expanding that C API is acceptable. Adding C API for
+  subcomponents that don't currently have one needs to be discussed on the
+  mailing list for design and maintainability feedback prior to implementation.
+
+* Documentation: Any changes to the C API are required to be documented in the
+  release notes so that it's clear to external users who do not follow the
+  project how the C API is changing and evolving.
+
+New Targets
+-----------
+
+LLVM is very receptive to new targets, even experimental ones, but a number of
+problems can appear when adding new large portions of code, and back-ends are
+normally added in bulk.  We have found that landing large pieces of new code 
+and then trying to fix emergent problems in-tree is problematic for a variety 
+of reasons.
+
+For these reasons, new targets are *always* added as *experimental* until
+they can be proven stable, and later moved to non-experimental. The difference
+between both classes is that experimental targets are not built by default
+(need to be added to -DLLVM_TARGETS_TO_BUILD at CMake time).
+
+The basic rules for a back-end to be upstreamed in **experimental** mode are:
+
+* Every target must have a :ref:`code owner<code owners>`. The `CODE_OWNERS.TXT`
+  file has to be updated as part of the first merge. The code owner makes sure
+  that changes to the target get reviewed and steers the overall effort.
+
+* There must be an active community behind the target. This community
+  will help maintain the target by providing buildbots, fixing
+  bugs, answering the LLVM community's questions and making sure the new
+  target doesn't break any of the other targets, or generic code. This
+  behavior is expected to continue throughout the lifetime of the
+  target's code.
+
+* The code must be free of contentious issues, for example, large
+  changes in how the IR behaves or should be formed by the front-ends,
+  unless agreed by the majority of the community via refactoring of the
+  (:doc:`IR standard<LangRef>`) **before** the merge of the new target changes,
+  following the :ref:`IR backwards compatibility`.
+
+* The code conforms to all of the policies laid out in this developer policy
+  document, including license, patent, and coding standards.
+
+* The target should have either reasonable documentation on how it
+  works (ISA, ABI, etc.) or a publicly available simulator/hardware
+  (either free or cheap enough) - preferably both.  This allows
+  developers to validate assumptions, understand constraints and review code 
+  that can affect the target. 
+
+In addition, the rules for a back-end to be promoted to **official** are:
+
+* The target must have addressed every other minimum requirement and
+  have been stable in tree for at least 3 months. This cool down
+  period is to make sure that the back-end and the target community can
+  endure continuous upstream development for the foreseeable future.
+
+* The target's code must have been completely adapted to this policy
+  as well as the :doc:`coding standards<CodingStandards>`. Any exceptions that
+  were made to move into experimental mode must have been fixed **before**
+  becoming official.
+
+* The test coverage needs to be broad and well written (small tests,
+  well documented). The build target ``check-all`` must pass with the
+  new target built, and where applicable, the ``test-suite`` must also
+  pass without errors, in at least one configuration (publicly
+  demonstrated, for example, via buildbots).
+
+* Public buildbots need to be created and actively maintained, unless
+  the target requires no additional buildbots (ex. ``check-all`` covers
+  all tests). The more relevant and public the new target's CI infrastructure
+  is, the more the LLVM community will embrace it.
+
+To **continue** as a supported and official target:
+
+* The maintainer(s) must continue following these rules throughout the lifetime
+  of the target. Continuous violations of aforementioned rules and policies
+  could lead to complete removal of the target from the code base.
+
+* Degradation in support, documentation or test coverage will make the target as
+  nuisance to other targets and be considered a candidate for deprecation and
+  ultimately removed.
+
+In essences, these rules are necessary for targets to gain and retain their
+status, but also markers to define bit-rot, and will be used to clean up the
+tree from unmaintained targets.
+
+.. _toolchain:
+
+Updating Toolchain Requirements
+-------------------------------
+
+We intend to require newer toolchains as time goes by. This means LLVM's
+codebase can use newer versions of C++ as they get standardized. Requiring newer
+toolchains to build LLVM can be painful for those building LLVM; therefore, it
+will only be done through the following process:
+
+  * Generally, try to support LLVM and GCC versions from the last 3 years at a
+    minimum. This time-based guideline is not strict: we may support much older
+    compilers, or decide to support fewer versions.
+
+  * An RFC is sent to the `llvm-dev mailing list <http://lists.llvm.org/mailman/listinfo/llvm-dev>`_
+
+    - Detail upsides of the version increase (e.g. which newer C++ language or
+      library features LLVM should use; avoid miscompiles in particular compiler
+      versions, etc).
+    - Detail downsides on important platforms (e.g. Ubuntu LTS status).
+
+  * Once the RFC reaches consensus, update the CMake toolchain version checks as
+    well as the :doc:`getting started<GettingStarted>` guide. We want to
+    soft-error when developers compile LLVM. We say "soft-error" because the
+    error can be turned into a warning using a CMake flag. This is an important
+    step: LLVM still doesn't have code which requires the new toolchains, but it
+    soon will. If you compile LLVM but don't read the mailing list, we should
+    tell you!
+
+  * Ensure that at least one LLVM release has had this soft-error. Not all
+    developers compile LLVM top-of-tree. These release-bound developers should
+    also be told about upcoming changes.
+
+  * Turn the soft-error into a hard-error after said LLVM release has branched.
+
+  * Update the :doc:`coding standards<CodingStandards>` to allow the new
+    features we've explicitly approved in the RFC.
+
+  * Start using the new features in LLVM's codebase.
+
+
+.. _copyright-license-patents:
+
+Copyright, License, and Patents
+===============================
+
+.. note::
+
+   This section deals with legal matters but does not provide legal advice.  We
+   are not lawyers --- please seek legal counsel from an attorney.
+
+This section addresses the issues of copyright, license and patents for the LLVM
+project.  The copyright for the code is held by the individual contributors of
+the code and the terms of its license to LLVM users and developers is the
+`University of Illinois/NCSA Open Source License
+<http://www.opensource.org/licenses/UoI-NCSA.php>`_ (with portions dual licensed
+under the `MIT License <http://www.opensource.org/licenses/mit-license.php>`_,
+see below).  As contributor to the LLVM project, you agree to allow any
+contributions to the project to licensed under these terms.
+
+Copyright
+---------
+
+The LLVM project does not require copyright assignments, which means that the
+copyright for the code in the project is held by its respective contributors who
+have each agreed to release their contributed code under the terms of the `LLVM
+License`_.
+
+An implication of this is that the LLVM license is unlikely to ever change:
+changing it would require tracking down all the contributors to LLVM and getting
+them to agree that a license change is acceptable for their contribution.  Since
+there are no plans to change the license, this is not a cause for concern.
+
+As a contributor to the project, this means that you (or your company) retain
+ownership of the code you contribute, that it cannot be used in a way that
+contradicts the license (which is a liberal BSD-style license), and that the
+license for your contributions won't change without your approval in the
+future.
+
+.. _LLVM License:
+
+License
+-------
+
+We intend to keep LLVM perpetually open source and to use a liberal open source
+license. **As a contributor to the project, you agree that any contributions be
+licensed under the terms of the corresponding subproject.** All of the code in
+LLVM is available under the `University of Illinois/NCSA Open Source License
+<http://www.opensource.org/licenses/UoI-NCSA.php>`_, which boils down to
+this:
+
+* You can freely distribute LLVM.
+* You must retain the copyright notice if you redistribute LLVM.
+* Binaries derived from LLVM must reproduce the copyright notice (e.g. in an
+  included readme file).
+* You can't use our names to promote your LLVM derived products.
+* There's no warranty on LLVM at all.
+
+We believe this fosters the widest adoption of LLVM because it **allows
+commercial products to be derived from LLVM** with few restrictions and without
+a requirement for making any derived works also open source (i.e.  LLVM's
+license is not a "copyleft" license like the GPL). We suggest that you read the
+`License <http://www.opensource.org/licenses/UoI-NCSA.php>`_ if further
+clarification is needed.
+
+In addition to the UIUC license, the runtime library components of LLVM
+(**compiler_rt, libc++, and libclc**) are also licensed under the `MIT License
+<http://www.opensource.org/licenses/mit-license.php>`_, which does not contain
+the binary redistribution clause.  As a user of these runtime libraries, it
+means that you can choose to use the code under either license (and thus don't
+need the binary redistribution clause), and as a contributor to the code that
+you agree that any contributions to these libraries be licensed under both
+licenses.  We feel that this is important for runtime libraries, because they
+are implicitly linked into applications and therefore should not subject those
+applications to the binary redistribution clause. This also means that it is ok
+to move code from (e.g.)  libc++ to the LLVM core without concern, but that code
+cannot be moved from the LLVM core to libc++ without the copyright owner's
+permission.
+
+Note that the LLVM Project does distribute dragonegg, **which is
+GPL.** This means that anything "linked" into dragonegg must itself be compatible
+with the GPL, and must be releasable under the terms of the GPL.  This implies
+that **any code linked into dragonegg and distributed to others may be subject to
+the viral aspects of the GPL** (for example, a proprietary code generator linked
+into dragonegg must be made available under the GPL).  This is not a problem for
+code already distributed under a more liberal license (like the UIUC license),
+and GPL-containing subprojects are kept in separate SVN repositories whose
+LICENSE.txt files specifically indicate that they contain GPL code.
+
+Patents
+-------
+
+To the best of our knowledge, LLVM does not infringe on any patents (we have
+actually removed code from LLVM in the past that was found to infringe).  Having
+code in LLVM that infringes on patents would violate an important goal of the
+project by making it hard or impossible to reuse the code for arbitrary purposes
+(including commercial use).
+
+When contributing code, we expect contributors to notify us of any potential for
+patent-related trouble with their changes (including from third parties).  If
+you or your employer own the rights to a patent and would like to contribute
+code to LLVM that relies on it, we require that the copyright owner sign an
+agreement that allows any other user of LLVM to freely use your patent.  Please
+contact the `LLVM Foundation Board of Directors <mailto:board at llvm.org>`_ for more
+details.

Added: www-releases/trunk/8.0.1/docs/_sources/Docker.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.1/docs/_sources/Docker.rst.txt?rev=368037&view=auto
==============================================================================
--- www-releases/trunk/8.0.1/docs/_sources/Docker.rst.txt (added)
+++ www-releases/trunk/8.0.1/docs/_sources/Docker.rst.txt Tue Aug  6 06:51:02 2019
@@ -0,0 +1,185 @@
+=========================================
+A guide to Dockerfiles for building LLVM
+=========================================
+
+Introduction
+============
+You can find a number of sources to build docker images with LLVM components in
+``llvm/utils/docker``. They can be used by anyone who wants to build the docker
+images for their own use, or as a starting point for someone who wants to write
+their own Dockerfiles.
+
+We currently provide Dockerfiles with ``debian8`` and ``nvidia-cuda`` base images.
+We also provide an ``example`` image, which contains placeholders that one would need
+to fill out in order to produce Dockerfiles for a new docker image.
+
+Why?
+----
+Docker images provide a way to produce binary distributions of
+software inside a controlled environment. Having Dockerfiles to builds docker images
+inside LLVM repo makes them much more discoverable than putting them into any other
+place.
+
+Docker basics
+-------------
+If you've never heard about Docker before, you might find this section helpful
+to get a very basic explanation of it.
+`Docker <https://www.docker.com/>`_ is a popular solution for running programs in
+an isolated and reproducible environment, especially to maintain releases for
+software deployed to large distributed fleets.
+It uses linux kernel namespaces and cgroups to provide a lightweight isolation
+inside currently running linux kernel.
+A single active instance of dockerized environment is called a *docker
+container*.
+A snapshot of a docker container filesystem is called a *docker image*.
+One can start a container from a prebuilt docker image.
+
+Docker images are built from a so-called *Dockerfile*, a source file written in
+a specialized language that defines instructions to be used when build
+the docker image (see `official
+documentation <https://docs.docker.com/engine/reference/builder/>`_ for more
+details). A minimal Dockerfile typically contains a base image and a number
+of RUN commands that have to be executed to build the image. When building a new
+image, docker will first download your base image, mount its filesystem as
+read-only and then add a writable overlay on top of it to keep track of all
+filesystem modifications, performed while building your image. When the build
+process is finished, a diff between your image's final filesystem state and the
+base image's filesystem is stored in the resulting image.
+
+Overview
+========
+The ``llvm/utils/docker`` folder contains Dockerfiles and simple bash scripts to
+serve as a basis for anyone who wants to create their own Docker image with
+LLVM components, compiled from sources. The sources are checked out from the
+upstream svn repository when building the image.
+
+The resulting image contains only the requested LLVM components and a few extra
+packages to make the image minimally useful for C++ development, e.g. libstdc++
+and binutils.
+
+The interface to run the build is ``build_docker_image.sh`` script. It accepts a
+list of LLVM repositories to checkout and arguments for CMake invocation.
+
+If you want to write your own docker image, start with an ``example/`` subfolder.
+It provides an incomplete Dockerfile with (very few) FIXMEs explaining the steps
+you need to take in order to make your Dockerfiles functional.
+
+Usage
+=====
+The ``llvm/utils/build_docker_image.sh`` script provides a rather high degree of
+control on how to run the build. It allows you to specify the projects to
+checkout from svn and provide a list of CMake arguments to use during when
+building LLVM inside docker container.
+
+Here's a very simple example of getting a docker image with clang binary,
+compiled by the system compiler in the debian8 image:
+
+.. code-block:: bash
+
+    ./llvm/utils/docker/build_docker_image.sh \
+	--source debian8 \
+	--docker-repository clang-debian8 --docker-tag "staging" \
+	-p clang -i install-clang -i install-clang-headers \
+	-- \
+	-DCMAKE_BUILD_TYPE=Release
+
+Note that a build like that doesn't use a 2-stage build process that
+you probably want for clang. Running a 2-stage build is a little more intricate,
+this command will do that:
+
+.. code-block:: bash
+
+    # Run a 2-stage build.
+    #   LLVM_TARGETS_TO_BUILD=Native is to reduce stage1 compile time.
+    #   Options, starting with BOOTSTRAP_* are passed to stage2 cmake invocation.
+    ./build_docker_image.sh \
+	--source debian8 \
+	--docker-repository clang-debian8 --docker-tag "staging" \
+	-p clang -i stage2-install-clang -i stage2-install-clang-headers \
+	-- \
+	-DLLVM_TARGETS_TO_BUILD=Native -DCMAKE_BUILD_TYPE=Release \
+	-DBOOTSTRAP_CMAKE_BUILD_TYPE=Release \
+	-DCLANG_ENABLE_BOOTSTRAP=ON -DCLANG_BOOTSTRAP_TARGETS="install-clang;install-clang-headers"
+	
+This will produce a new image ``clang-debian8:staging`` from the latest
+upstream revision.
+After the image is built you can run bash inside a container based on your image
+like this:
+
+.. code-block:: bash
+
+    docker run -ti clang-debian8:staging bash
+
+Now you can run bash commands as you normally would:
+
+.. code-block:: bash
+
+    root at 80f351b51825:/# clang -v
+    clang version 5.0.0 (trunk 305064)
+    Target: x86_64-unknown-linux-gnu
+    Thread model: posix
+    InstalledDir: /bin
+    Found candidate GCC installation: /usr/lib/gcc/x86_64-linux-gnu/4.8
+    Found candidate GCC installation: /usr/lib/gcc/x86_64-linux-gnu/4.8.4
+    Found candidate GCC installation: /usr/lib/gcc/x86_64-linux-gnu/4.9
+    Found candidate GCC installation: /usr/lib/gcc/x86_64-linux-gnu/4.9.2
+    Selected GCC installation: /usr/lib/gcc/x86_64-linux-gnu/4.9
+    Candidate multilib: .;@m64
+    Selected multilib: .;@m64
+
+
+Which image should I choose?
+============================
+We currently provide two images: debian8-based and nvidia-cuda-based. They
+differ in the base image that they use, i.e. they have a different set of
+preinstalled binaries. Debian8 is very minimal, nvidia-cuda is larger, but has
+preinstalled CUDA libraries and allows to access a GPU, installed on your
+machine.
+
+If you need a minimal linux distribution with only clang and libstdc++ included,
+you should try debian8-based image.
+
+If you want to use CUDA libraries and have access to a GPU on your machine,
+you should choose nvidia-cuda-based image and use `nvidia-docker
+<https://github.com/NVIDIA/nvidia-docker>`_ to run your docker containers. Note
+that you don't need nvidia-docker to build the images, but you need it in order
+to have an access to GPU from a docker container that is running the built
+image.
+
+If you have a different use-case, you could create your own image based on
+``example/`` folder.
+
+Any docker image can be built and run using only the docker binary, i.e. you can
+run debian8 build on Fedora or any other Linux distribution. You don't need to
+install CMake, compilers or any other clang dependencies. It is all handled
+during the build process inside Docker's isolated environment.
+
+Stable build
+============
+If you want a somewhat recent and somewhat stable build, use the
+``branches/google/stable`` branch, i.e. the following command will produce a
+debian8-based image using the latest ``google/stable`` sources for you:
+
+.. code-block:: bash
+
+    ./llvm/utils/docker/build_docker_image.sh \
+	-s debian8 --d clang-debian8 -t "staging" \
+	--branch branches/google/stable \
+	-p clang -i install-clang -i install-clang-headers \
+	-- \
+	-DCMAKE_BUILD_TYPE=Release
+
+
+Minimizing docker image size
+============================
+Due to how Docker's filesystem works, all intermediate writes are persisted in
+the resulting image, even if they are removed in the following commands.
+To minimize the resulting image size we use `multi-stage Docker builds
+<https://docs.docker.com/develop/develop-images/multistage-build/>`_.
+Internally Docker builds two images. The first image does all the work: installs
+build dependencies, checks out LLVM source code, compiles LLVM, etc.
+The first image is only used during build and does not have a descriptive name,
+i.e. it is only accessible via the hash value after the build is finished.
+The second image is our resulting image. It contains only the built binaries
+and not any build dependencies. It is also accessible via a descriptive name
+(specified by -d and -t flags).

Added: www-releases/trunk/8.0.1/docs/_sources/ExceptionHandling.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.1/docs/_sources/ExceptionHandling.rst.txt?rev=368037&view=auto
==============================================================================
--- www-releases/trunk/8.0.1/docs/_sources/ExceptionHandling.rst.txt (added)
+++ www-releases/trunk/8.0.1/docs/_sources/ExceptionHandling.rst.txt Tue Aug  6 06:51:02 2019
@@ -0,0 +1,904 @@
+==========================
+Exception Handling in LLVM
+==========================
+
+.. contents::
+   :local:
+
+Introduction
+============
+
+This document is the central repository for all information pertaining to
+exception handling in LLVM.  It describes the format that LLVM exception
+handling information takes, which is useful for those interested in creating
+front-ends or dealing directly with the information.  Further, this document
+provides specific examples of what exception handling information is used for in
+C and C++.
+
+Itanium ABI Zero-cost Exception Handling
+----------------------------------------
+
+Exception handling for most programming languages is designed to recover from
+conditions that rarely occur during general use of an application.  To that end,
+exception handling should not interfere with the main flow of an application's
+algorithm by performing checkpointing tasks, such as saving the current pc or
+register state.
+
+The Itanium ABI Exception Handling Specification defines a methodology for
+providing outlying data in the form of exception tables without inlining
+speculative exception handling code in the flow of an application's main
+algorithm.  Thus, the specification is said to add "zero-cost" to the normal
+execution of an application.
+
+A more complete description of the Itanium ABI exception handling runtime
+support of can be found at `Itanium C++ ABI: Exception Handling
+<http://itanium-cxx-abi.github.io/cxx-abi/abi-eh.html>`_. A description of the
+exception frame format can be found at `Exception Frames
+<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://itanium-cxx-abi.github.io/cxx-abi/exceptions.pdf>`_.
+
+Setjmp/Longjmp Exception Handling
+---------------------------------
+
+Setjmp/Longjmp (SJLJ) based exception handling uses LLVM intrinsics
+`llvm.eh.sjlj.setjmp`_ and `llvm.eh.sjlj.longjmp`_ to handle control flow for
+exception handling.
+
+For each function which does exception processing --- be it ``try``/``catch``
+blocks or cleanups --- that function registers itself on a global frame
+list. When exceptions are unwinding, the runtime uses this list to identify
+which functions need processing.
+
+Landing pad selection is encoded in the call site entry of the function
+context. The runtime returns to the function via `llvm.eh.sjlj.longjmp`_, where
+a switch table transfers control to the appropriate landing pad based on the
+index stored in the function context.
+
+In contrast to DWARF exception handling, which encodes exception regions and
+frame information in out-of-line tables, SJLJ exception handling builds and
+removes the unwind frame context at runtime. This results in faster exception
+handling at the expense of slower execution when no exceptions are thrown. As
+exceptions are, by their nature, intended for uncommon code paths, DWARF
+exception handling is generally preferred to SJLJ.
+
+Windows Runtime Exception Handling
+-----------------------------------
+
+LLVM supports handling exceptions produced by the Windows runtime, but it
+requires a very different intermediate representation. It is not based on the
+":ref:`landingpad <i_landingpad>`" instruction like the other two models, and is
+described later in this document under :ref:`wineh`.
+
+Overview
+--------
+
+When an exception is thrown in LLVM code, the runtime does its best to find a
+handler suited to processing the circumstance.
+
+The runtime first attempts to find an *exception frame* corresponding to the
+function where the exception was thrown.  If the programming language supports
+exception handling (e.g. C++), the exception frame contains a reference to an
+exception table describing how to process the exception.  If the language does
+not support exception handling (e.g. C), or if the exception needs to be
+forwarded to a prior activation, the exception frame contains information about
+how to unwind the current activation and restore the state of the prior
+activation.  This process is repeated until the exception is handled. If the
+exception is not handled and no activations remain, then the application is
+terminated with an appropriate error message.
+
+Because different programming languages have different behaviors when handling
+exceptions, the exception handling ABI provides a mechanism for
+supplying *personalities*. An exception handling personality is defined by
+way of a *personality function* (e.g. ``__gxx_personality_v0`` in C++),
+which receives the context of the exception, an *exception structure*
+containing the exception object type and value, and a reference to the exception
+table for the current function.  The personality function for the current
+compile unit is specified in a *common exception frame*.
+
+The organization of an exception table is language dependent. For C++, an
+exception table is organized as a series of code ranges defining what to do if
+an exception occurs in that range. Typically, the information associated with a
+range defines which types of exception objects (using C++ *type info*) that are
+handled in that range, and an associated action that should take place. Actions
+typically pass control to a *landing pad*.
+
+A landing pad corresponds roughly to the code found in the ``catch`` portion of
+a ``try``/``catch`` sequence. When execution resumes at a landing pad, it
+receives an *exception structure* and a *selector value* corresponding to the
+*type* of exception thrown. The selector is then used to determine which *catch*
+should actually process the exception.
+
+LLVM Code Generation
+====================
+
+From a C++ developer's perspective, exceptions are defined in terms of the
+``throw`` and ``try``/``catch`` statements. In this section we will describe the
+implementation of LLVM exception handling in terms of C++ examples.
+
+Throw
+-----
+
+Languages that support exception handling typically provide a ``throw``
+operation to initiate the exception process. Internally, a ``throw`` operation
+breaks down into two steps.
+
+#. A request is made to allocate exception space for an exception structure.
+   This structure needs to survive beyond the current activation. This structure
+   will contain the type and value of the object being thrown.
+
+#. A call is made to the runtime to raise the exception, passing the exception
+   structure as an argument.
+
+In C++, the allocation of the exception structure is done by the
+``__cxa_allocate_exception`` runtime function. The exception raising is handled
+by ``__cxa_throw``. The type of the exception is represented using a C++ RTTI
+structure.
+
+Try/Catch
+---------
+
+A call within the scope of a *try* statement can potentially raise an
+exception. In those circumstances, the LLVM C++ front-end replaces the call with
+an ``invoke`` instruction. Unlike a call, the ``invoke`` has two potential
+continuation points:
+
+#. where to continue when the call succeeds as per normal, and
+
+#. where to continue if the call raises an exception, either by a throw or the
+   unwinding of a throw
+
+The term used to define the place where an ``invoke`` continues after an
+exception is called a *landing pad*. LLVM landing pads are conceptually
+alternative function entry points where an exception structure reference and a
+type info index are passed in as arguments. The landing pad saves the exception
+structure reference and then proceeds to select the catch block that corresponds
+to the type info of the exception object.
+
+The LLVM :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 looks for a reference to the personality
+function to be used for this ``try``/``catch`` sequence in the parent
+function's attribute list. The instruction contains a list of *cleanup*,
+*catch*, and *filter* clauses. The exception is tested against the clauses
+sequentially from first to last. The clauses have the following meanings:
+
+-  ``catch <type> @ExcType``
+
+   - This clause means that the landingpad block should be entered if the
+     exception being thrown is of type ``@ExcType`` or a subtype of
+     ``@ExcType``. For C++, ``@ExcType`` is a pointer to the ``std::type_info``
+     object (an RTTI object) representing the C++ exception type.
+
+   - If ``@ExcType`` is ``null``, any exception matches, so the landingpad
+     should always be entered. This is used for C++ catch-all blocks ("``catch
+     (...)``").
+
+   - When this clause is matched, the selector value will be equal to the value
+     returned by "``@llvm.eh.typeid.for(i8* @ExcType)``". This will always be a
+     positive value.
+
+-  ``filter <type> [<type> @ExcType1, ..., <type> @ExcTypeN]``
+
+   - This clause means that the landingpad should be entered if the exception
+     being thrown does *not* match any of the types in the list (which, for C++,
+     are again specified as ``std::type_info`` pointers).
+
+   - C++ front-ends use this to implement C++ exception specifications, such as
+     "``void foo() throw (ExcType1, ..., ExcTypeN) { ... }``".
+
+   - When this clause is matched, the selector value will be negative.
+
+   - The array argument to ``filter`` may be empty; for example, "``[0 x i8**]
+     undef``". This means that the landingpad should always be entered. (Note
+     that such a ``filter`` would not be equivalent to "``catch i8* null``",
+     because ``filter`` and ``catch`` produce negative and positive selector
+     values respectively.)
+
+-  ``cleanup``
+
+   - This clause means that the landingpad should always be entered.
+
+   - C++ front-ends use this for calling objects' destructors.
+
+   - When this clause is matched, the selector value will be zero.
+
+   - The runtime may treat "``cleanup``" differently from "``catch <type>
+     null``".
+
+     In C++, if an unhandled exception occurs, the language runtime will call
+     ``std::terminate()``, but it is implementation-defined whether the runtime
+     unwinds the stack and calls object destructors first. For example, the GNU
+     C++ unwinder does not call object destructors when an unhandled exception
+     occurs. The reason for this is to improve debuggability: it ensures that
+     ``std::terminate()`` is called from the context of the ``throw``, so that
+     this context is not lost by unwinding the stack. A runtime will typically
+     implement this by searching for a matching non-``cleanup`` clause, and
+     aborting if it does not find one, before entering any landingpad blocks.
+
+Once the landing pad has the type info selector, the code branches to the code
+for the first catch. The catch then checks the value of the type info selector
+against the index of type info for that catch.  Since the type info index is not
+known until all the type infos have been gathered in the backend, the catch code
+must call the `llvm.eh.typeid.for`_ intrinsic to determine the index for a given
+type info. If the catch fails to match the selector then control is passed on to
+the next catch.
+
+Finally, the entry and exit of catch code is bracketed with calls to
+``__cxa_begin_catch`` and ``__cxa_end_catch``.
+
+* ``__cxa_begin_catch`` takes an exception structure reference as an argument
+  and returns the value of the exception object.
+
+* ``__cxa_end_catch`` takes no arguments. This function:
+
+  #. Locates the most recently caught exception and decrements its handler
+     count,
+
+  #. Removes the exception from the *caught* stack if the handler count goes to
+     zero, and
+
+  #. Destroys the exception if the handler count goes to zero and the exception
+     was not re-thrown by throw.
+
+  .. note::
+
+    a rethrow from within the catch may replace this call with a
+    ``__cxa_rethrow``.
+
+Cleanups
+--------
+
+A cleanup is extra code which needs to be run as part of unwinding a scope.  C++
+destructors are a typical example, but other languages and language extensions
+provide a variety of different kinds of cleanups. In general, a landing pad may
+need to run arbitrary amounts of cleanup code before actually entering a catch
+block. To indicate the presence of cleanups, a :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::
+
+  Do not allow a new exception to propagate out of the execution of a
+  cleanup. This can corrupt the internal state of the unwinder.  Different
+  languages describe different high-level semantics for these situations: for
+  example, C++ requires that the process be terminated, whereas Ada cancels both
+  exceptions and throws a third.
+
+When all cleanups are finished, if the exception is not handled by the current
+function, resume unwinding by calling the :ref:`resume instruction <i_resume>`,
+passing in the result of the ``landingpad`` instruction for the original
+landing pad.
+
+Throw Filters
+-------------
+
+C++ allows the specification of which exception types may be thrown from a
+function. To represent this, a top level landing pad may exist to filter out
+invalid types. To express this in LLVM code the :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
+exception structure.  Note that the most general form of a ``landingpad``
+instruction can have any number of catch, cleanup, and filter clauses (though
+having more than one cleanup is pointless). The LLVM C++ front-end can generate
+such ``landingpad`` instructions due to inlining creating nested exception
+handling scopes.
+
+.. _undefined:
+
+Restrictions
+------------
+
+The unwinder delegates the decision of whether to stop in a call frame to that
+call frame's language-specific personality function. Not all unwinders guarantee
+that they will stop to perform cleanups. For example, the GNU C++ unwinder
+doesn't do so unless the exception is actually caught somewhere further up the
+stack.
+
+In order for inlining to behave correctly, landing pads must be prepared to
+handle selector results that they did not originally advertise. Suppose that a
+function catches exceptions of type ``A``, and it's inlined into a function that
+catches exceptions of type ``B``. The inliner will update the ``landingpad``
+instruction for the inlined landing pad to include the fact that ``B`` is also
+caught. If that landing pad assumes that it will only be entered to catch an
+``A``, it's in for a rude awakening.  Consequently, landing pads must test for
+the selector results they understand and then resume exception propagation with
+the `resume instruction <LangRef.html#i_resume>`_ if none of the conditions
+match.
+
+Exception Handling Intrinsics
+=============================
+
+In addition to the ``landingpad`` and ``resume`` instructions, LLVM uses several
+intrinsic functions (name prefixed with ``llvm.eh``) to provide exception
+handling information at various points in generated code.
+
+.. _llvm.eh.typeid.for:
+
+``llvm.eh.typeid.for``
+----------------------
+
+.. code-block:: llvm
+
+  i32 @llvm.eh.typeid.for(i8* %type_info)
+
+
+This intrinsic returns the type info index in the exception table of the current
+function.  This value can be used to compare against the result of
+``landingpad`` instruction.  The single argument is a reference to a type info.
+
+Uses of this intrinsic are generated by the C++ front-end.
+
+.. _llvm.eh.begincatch:
+
+``llvm.eh.begincatch``
+----------------------
+
+.. code-block:: llvm
+
+  void @llvm.eh.begincatch(i8* %ehptr, i8* %ehobj)
+
+
+This intrinsic marks the beginning of catch handling code within the blocks
+following a ``landingpad`` instruction.  The exact behavior of this function
+depends on the compilation target and the personality function associated
+with the ``landingpad`` instruction.
+
+The first argument to this intrinsic is a pointer that was previously extracted
+from the aggregate return value of the ``landingpad`` instruction.  The second
+argument to the intrinsic is a pointer to stack space where the exception object
+should be stored. The runtime handles the details of copying the exception
+object into the slot. If the second parameter is null, no copy occurs.
+
+Uses of this intrinsic are generated by the C++ front-end.  Many targets will
+use implementation-specific functions (such as ``__cxa_begin_catch``) instead
+of this intrinsic.  The intrinsic is provided for targets that require a more
+abstract interface.
+
+When used in the native Windows C++ exception handling implementation, this
+intrinsic serves as a placeholder to delimit code before a catch handler is
+outlined.  When the handler is outlined, this intrinsic will be replaced
+by instructions that retrieve the exception object pointer from the frame
+allocation block.
+
+
+.. _llvm.eh.endcatch:
+
+``llvm.eh.endcatch``
+----------------------
+
+.. code-block:: llvm
+
+  void @llvm.eh.endcatch()
+
+
+This intrinsic marks the end of catch handling code within the current block,
+which will be a successor of a block which called ``llvm.eh.begincatch''.
+The exact behavior of this function depends on the compilation target and the
+personality function associated with the corresponding ``landingpad``
+instruction.
+
+There may be more than one call to ``llvm.eh.endcatch`` for any given call to
+``llvm.eh.begincatch`` with each ``llvm.eh.endcatch`` call corresponding to the
+end of a different control path.  All control paths following a call to
+``llvm.eh.begincatch`` must reach a call to ``llvm.eh.endcatch``.
+
+Uses of this intrinsic are generated by the C++ front-end.  Many targets will
+use implementation-specific functions (such as ``__cxa_begin_catch``) instead
+of this intrinsic.  The intrinsic is provided for targets that require a more
+abstract interface.
+
+When used in the native Windows C++ exception handling implementation, this
+intrinsic serves as a placeholder to delimit code before a catch handler is
+outlined.  After the handler is outlined, this intrinsic is simply removed.
+
+
+.. _llvm.eh.exceptionpointer:
+
+``llvm.eh.exceptionpointer``
+----------------------------
+
+.. code-block:: text
+
+  i8 addrspace(N)* @llvm.eh.padparam.pNi8(token %catchpad)
+
+
+This intrinsic retrieves a pointer to the exception caught by the given
+``catchpad``.
+
+
+SJLJ Intrinsics
+---------------
+
+The ``llvm.eh.sjlj`` intrinsics are used internally within LLVM's
+backend.  Uses of them are generated by the backend's
+``SjLjEHPrepare`` pass.
+
+.. _llvm.eh.sjlj.setjmp:
+
+``llvm.eh.sjlj.setjmp``
+~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: text
+
+  i32 @llvm.eh.sjlj.setjmp(i8* %setjmp_buf)
+
+For SJLJ based exception handling, this intrinsic forces register saving for the
+current function and stores the address of the following instruction for use as
+a destination address by `llvm.eh.sjlj.longjmp`_. The buffer format and the
+overall functioning of this intrinsic is compatible with the GCC
+``__builtin_setjmp`` implementation allowing code built with the clang and GCC
+to interoperate.
+
+The single parameter is a pointer to a five word buffer in which the calling
+context is saved. The front end places the frame pointer in the first word, and
+the target implementation of this intrinsic should place the destination address
+for a `llvm.eh.sjlj.longjmp`_ in the second word. The following three words are
+available for use in a target-specific manner.
+
+.. _llvm.eh.sjlj.longjmp:
+
+``llvm.eh.sjlj.longjmp``
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: llvm
+
+  void @llvm.eh.sjlj.longjmp(i8* %setjmp_buf)
+
+For SJLJ based exception handling, the ``llvm.eh.sjlj.longjmp`` intrinsic is
+used to implement ``__builtin_longjmp()``. The single parameter is a pointer to
+a buffer populated by `llvm.eh.sjlj.setjmp`_. The frame pointer and stack
+pointer are restored from the buffer, then control is transferred to the
+destination address.
+
+``llvm.eh.sjlj.lsda``
+~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: llvm
+
+  i8* @llvm.eh.sjlj.lsda()
+
+For SJLJ based exception handling, the ``llvm.eh.sjlj.lsda`` intrinsic returns
+the address of the Language Specific Data Area (LSDA) for the current
+function. The SJLJ front-end code stores this address in the exception handling
+function context for use by the runtime.
+
+``llvm.eh.sjlj.callsite``
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: llvm
+
+  void @llvm.eh.sjlj.callsite(i32 %call_site_num)
+
+For SJLJ based exception handling, the ``llvm.eh.sjlj.callsite`` intrinsic
+identifies the callsite value associated with the following ``invoke``
+instruction. This is used to ensure that landing pad entries in the LSDA are
+generated in matching order.
+
+Asm Table Formats
+=================
+
+There are two tables that are used by the exception handling runtime to
+determine which actions should be taken when an exception is thrown.
+
+Exception Handling Frame
+------------------------
+
+An exception handling frame ``eh_frame`` is very similar to the unwind frame
+used by DWARF debug info. The frame contains all the information necessary to
+tear down the current frame and restore the state of the prior frame. There is
+an exception handling frame for each function in a compile unit, plus a common
+exception handling frame that defines information common to all functions in the
+unit.
+
+The format of this call frame information (CFI) is often platform-dependent,
+however. ARM, for example, defines their own format. Apple has their own compact
+unwind info format.  On Windows, another format is used for all architectures
+since 32-bit x86.  LLVM will emit whatever information is required by the
+target.
+
+Exception Tables
+----------------
+
+An exception table contains information about what actions to take when an
+exception is thrown in a particular part of a function's code. This is typically
+referred to as the language-specific data area (LSDA). The format of the LSDA
+table is specific to the personality function, but the majority of personalities
+out there use a variation of the tables consumed by ``__gxx_personality_v0``.
+There is one exception table per function, except leaf functions and functions
+that have calls only to non-throwing functions. They do not need an exception
+table.
+
+.. _wineh:
+
+Exception Handling using the Windows Runtime
+=================================================
+
+Background on Windows exceptions
+---------------------------------
+
+Interacting with exceptions on Windows is significantly more complicated than
+on Itanium C++ ABI platforms. The fundamental difference between the two models
+is that Itanium EH is designed around the idea of "successive unwinding," while
+Windows EH is not.
+
+Under Itanium, throwing an exception typically involes allocating thread local
+memory to hold the exception, and calling into the EH runtime. The runtime
+identifies frames with appropriate exception handling actions, and successively
+resets the register context of the current thread to the most recently active
+frame with actions to run. In LLVM, execution resumes at a ``landingpad``
+instruction, which produces register values provided by the runtime. If a
+function is only cleaning up allocated resources, the function is responsible
+for calling ``_Unwind_Resume`` to transition to the next most recently active
+frame after it is finished cleaning up. Eventually, the frame responsible for
+handling the exception calls ``__cxa_end_catch`` to destroy the exception,
+release its memory, and resume normal control flow.
+
+The Windows EH model does not use these successive register context resets.
+Instead, the active exception is typically described by a frame on the stack.
+In the case of C++ exceptions, the exception object is allocated in stack memory
+and its address is passed to ``__CxxThrowException``. General purpose structured
+exceptions (SEH) are more analogous to Linux signals, and they are dispatched by
+userspace DLLs provided with Windows. Each frame on the stack has an assigned EH
+personality routine, which decides what actions to take to handle the exception.
+There are a few major personalities for C and C++ code: the C++ personality
+(``__CxxFrameHandler3``) and the SEH personalities (``_except_handler3``,
+``_except_handler4``, and ``__C_specific_handler``). All of them implement
+cleanups by calling back into a "funclet" contained in the parent function.
+
+Funclets, in this context, are regions of the parent function that can be called
+as though they were a function pointer with a very special calling convention.
+The frame pointer of the parent frame is passed into the funclet either using
+the standard EBP register or as the first parameter register, depending on the
+architecture. The funclet implements the EH action by accessing local variables
+in memory through the frame pointer, and returning some appropriate value,
+continuing the EH process.  No variables live in to or out of the funclet can be
+allocated in registers.
+
+The C++ personality also uses funclets to contain the code for catch blocks
+(i.e. all user code between the braces in ``catch (Type obj) { ... }``). The
+runtime must use funclets for catch bodies because the C++ exception object is
+allocated in a child stack frame of the function handling the exception. If the
+runtime rewound the stack back to frame of the catch, the memory holding the
+exception would be overwritten quickly by subsequent function calls.  The use of
+funclets also allows ``__CxxFrameHandler3`` to implement rethrow without
+resorting to TLS. Instead, the runtime throws a special exception, and then uses
+SEH (``__try / __except``) to resume execution with new information in the child
+frame.
+
+In other words, the successive unwinding approach is incompatible with Visual
+C++ exceptions and general purpose Windows exception handling. Because the C++
+exception object lives in stack memory, LLVM cannot provide a custom personality
+function that uses landingpads.  Similarly, SEH does not provide any mechanism
+to rethrow an exception or continue unwinding.  Therefore, LLVM must use the IR
+constructs described later in this document to implement compatible exception
+handling.
+
+SEH filter expressions
+-----------------------
+
+The SEH personality functions also use funclets to implement filter expressions,
+which allow executing arbitrary user code to decide which exceptions to catch.
+Filter expressions should not be confused with the ``filter`` clause of the LLVM
+``landingpad`` instruction.  Typically filter expressions are used to determine
+if the exception came from a particular DLL or code region, or if code faulted
+while accessing a particular memory address range. LLVM does not currently have
+IR to represent filter expressions because it is difficult to represent their
+control dependencies.  Filter expressions run during the first phase of EH,
+before cleanups run, making it very difficult to build a faithful control flow
+graph.  For now, the new EH instructions cannot represent SEH filter
+expressions, and frontends must outline them ahead of time. Local variables of
+the parent function can be escaped and accessed using the ``llvm.localescape``
+and ``llvm.localrecover`` intrinsics.
+
+New exception handling instructions
+------------------------------------
+
+The primary design goal of the new EH instructions is to support funclet
+generation while preserving information about the CFG so that SSA formation
+still works.  As a secondary goal, they are designed to be generic across MSVC
+and Itanium C++ exceptions. They make very few assumptions about the data
+required by the personality, so long as it uses the familiar core EH actions:
+catch, cleanup, and terminate.  However, the new instructions are hard to modify
+without knowing details of the EH personality. While they can be used to
+represent Itanium EH, the landingpad model is strictly better for optimization
+purposes.
+
+The following new instructions are considered "exception handling pads", in that
+they must be the first non-phi instruction of a basic block that may be the
+unwind destination of an EH flow edge:
+``catchswitch``, ``catchpad``, and ``cleanuppad``.
+As with landingpads, when entering a try scope, if the
+frontend encounters a call site that may throw an exception, it should emit an
+invoke that unwinds to a ``catchswitch`` block. Similarly, inside the scope of a
+C++ object with a destructor, invokes should unwind to a ``cleanuppad``.
+
+New instructions are also used to mark the points where control is transferred
+out of a catch/cleanup handler (which will correspond to exits from the
+generated funclet).  A catch handler which reaches its end by normal execution
+executes a ``catchret`` instruction, which is a terminator indicating where in
+the function control is returned to.  A cleanup handler which reaches its end
+by normal execution executes a ``cleanupret`` instruction, which is a terminator
+indicating where the active exception will unwind to next.
+
+Each of these new EH pad instructions has a way to identify which action should
+be considered after this action. The ``catchswitch`` instruction is a terminator
+and has an unwind destination operand analogous to the unwind destination of an
+invoke.  The ``cleanuppad`` instruction is not
+a terminator, so the unwind destination is stored on the ``cleanupret``
+instruction instead. Successfully executing a catch handler should resume
+normal control flow, so neither ``catchpad`` nor ``catchret`` instructions can
+unwind. All of these "unwind edges" may refer to a basic block that contains an
+EH pad instruction, or they may unwind to the caller.  Unwinding to the caller
+has roughly the same semantics as the ``resume`` instruction in the landingpad
+model. When inlining through an invoke, instructions that unwind to the caller
+are hooked up to unwind to the unwind destination of the call site.
+
+Putting things together, here is a hypothetical lowering of some C++ that uses
+all of the new IR instructions:
+
+.. code-block:: c
+
+  struct Cleanup {
+    Cleanup();
+    ~Cleanup();
+    int m;
+  };
+  void may_throw();
+  int f() noexcept {
+    try {
+      Cleanup obj;
+      may_throw();
+    } catch (int e) {
+      may_throw();
+      return e;
+    }
+    return 0;
+  }
+
+.. code-block:: text
+
+  define i32 @f() nounwind personality i32 (...)* @__CxxFrameHandler3 {
+  entry:
+    %obj = alloca %struct.Cleanup, align 4
+    %e = alloca i32, align 4
+    %call = invoke %struct.Cleanup* @"\01??0Cleanup@@QEAA at XZ"(%struct.Cleanup* nonnull %obj)
+            to label %invoke.cont unwind label %lpad.catch
+
+  invoke.cont:                                      ; preds = %entry
+    invoke void @"\01?may_throw@@YAXXZ"()
+            to label %invoke.cont.2 unwind label %lpad.cleanup
+
+  invoke.cont.2:                                    ; preds = %invoke.cont
+    call void @"\01??_DCleanup@@QEAA at XZ"(%struct.Cleanup* nonnull %obj) nounwind
+    br label %return
+
+  return:                                           ; preds = %invoke.cont.3, %invoke.cont.2
+    %retval.0 = phi i32 [ 0, %invoke.cont.2 ], [ %3, %invoke.cont.3 ]
+    ret i32 %retval.0
+
+  lpad.cleanup:                                     ; preds = %invoke.cont.2
+    %0 = cleanuppad within none []
+    call void @"\01??1Cleanup@@QEAA at XZ"(%struct.Cleanup* nonnull %obj) nounwind
+    cleanupret %0 unwind label %lpad.catch
+
+  lpad.catch:                                       ; preds = %lpad.cleanup, %entry
+    %1 = catchswitch within none [label %catch.body] unwind label %lpad.terminate
+
+  catch.body:                                       ; preds = %lpad.catch
+    %catch = catchpad within %1 [%rtti.TypeDescriptor2* @"\01??_R0H at 8", i32 0, i32* %e]
+    invoke void @"\01?may_throw@@YAXXZ"()
+            to label %invoke.cont.3 unwind label %lpad.terminate
+
+  invoke.cont.3:                                    ; preds = %catch.body
+    %3 = load i32, i32* %e, align 4
+    catchret from %catch to label %return
+
+  lpad.terminate:                                   ; preds = %catch.body, %lpad.catch
+    cleanuppad within none []
+    call void @"\01?terminate@@YAXXZ"
+    unreachable
+  }
+
+Funclet parent tokens
+-----------------------
+
+In order to produce tables for EH personalities that use funclets, it is
+necessary to recover the nesting that was present in the source. This funclet
+parent relationship is encoded in the IR using tokens produced by the new "pad"
+instructions. The token operand of a "pad" or "ret" instruction indicates which
+funclet it is in, or "none" if it is not nested within another funclet.
+
+The ``catchpad`` and ``cleanuppad`` instructions establish new funclets, and
+their tokens are consumed by other "pad" instructions to establish membership.
+The ``catchswitch`` instruction does not create a funclet, but it produces a
+token that is always consumed by its immediate successor ``catchpad``
+instructions. This ensures that every catch handler modelled by a ``catchpad``
+belongs to exactly one ``catchswitch``, which models the dispatch point after a
+C++ try.
+
+Here is an example of what this nesting looks like using some hypothetical
+C++ code:
+
+.. code-block:: c
+
+  void f() {
+    try {
+      throw;
+    } catch (...) {
+      try {
+        throw;
+      } catch (...) {
+      }
+    }
+  }
+
+.. code-block:: text
+
+  define void @f() #0 personality i8* bitcast (i32 (...)* @__CxxFrameHandler3 to i8*) {
+  entry:
+    invoke void @_CxxThrowException(i8* null, %eh.ThrowInfo* null) #1
+            to label %unreachable unwind label %catch.dispatch
+
+  catch.dispatch:                                   ; preds = %entry
+    %0 = catchswitch within none [label %catch] unwind to caller
+
+  catch:                                            ; preds = %catch.dispatch
+    %1 = catchpad within %0 [i8* null, i32 64, i8* null]
+    invoke void @_CxxThrowException(i8* null, %eh.ThrowInfo* null) #1
+            to label %unreachable unwind label %catch.dispatch2
+
+  catch.dispatch2:                                  ; preds = %catch
+    %2 = catchswitch within %1 [label %catch3] unwind to caller
+
+  catch3:                                           ; preds = %catch.dispatch2
+    %3 = catchpad within %2 [i8* null, i32 64, i8* null]
+    catchret from %3 to label %try.cont
+
+  try.cont:                                         ; preds = %catch3
+    catchret from %1 to label %try.cont6
+
+  try.cont6:                                        ; preds = %try.cont
+    ret void
+
+  unreachable:                                      ; preds = %catch, %entry
+    unreachable
+  }
+
+The "inner" ``catchswitch`` consumes ``%1`` which is produced by the outer
+catchswitch.
+
+.. _wineh-constraints:
+
+Funclet transitions
+-----------------------
+
+The EH tables for personalities that use funclets make implicit use of the
+funclet nesting relationship to encode unwind destinations, and so are
+constrained in the set of funclet transitions they can represent.  The related
+LLVM IR instructions accordingly have constraints that ensure encodability of
+the EH edges in the flow graph.
+
+A ``catchswitch``, ``catchpad``, or ``cleanuppad`` is said to be "entered"
+when it executes.  It may subsequently be "exited" by any of the following
+means:
+
+* A ``catchswitch`` is immediately exited when none of its constituent
+  ``catchpad``\ s are appropriate for the in-flight exception and it unwinds
+  to its unwind destination or the caller.
+* A ``catchpad`` and its parent ``catchswitch`` are both exited when a
+  ``catchret`` from the ``catchpad`` is executed.
+* A ``cleanuppad`` is exited when a ``cleanupret`` from it is executed.
+* Any of these pads is exited when control unwinds to the function's caller,
+  either by a ``call`` which unwinds all the way to the function's caller,
+  a nested ``catchswitch`` marked "``unwinds to caller``", or a nested
+  ``cleanuppad``\ 's ``cleanupret`` marked "``unwinds to caller"``.
+* Any of these pads is exited when an unwind edge (from an ``invoke``,
+  nested ``catchswitch``, or nested ``cleanuppad``\ 's ``cleanupret``)
+  unwinds to a destination pad that is not a descendant of the given pad.
+
+Note that the ``ret`` instruction is *not* a valid way to exit a funclet pad;
+it is undefined behavior to execute a ``ret`` when a pad has been entered but
+not exited.
+
+A single unwind edge may exit any number of pads (with the restrictions that
+the edge from a ``catchswitch`` must exit at least itself, and the edge from
+a ``cleanupret`` must exit at least its ``cleanuppad``), and then must enter
+exactly one pad, which must be distinct from all the exited pads.  The parent
+of the pad that an unwind edge enters must be the most-recently-entered
+not-yet-exited pad (after exiting from any pads that the unwind edge exits),
+or "none" if there is no such pad.  This ensures that the stack of executing
+funclets at run-time always corresponds to some path in the funclet pad tree
+that the parent tokens encode.
+
+All unwind edges which exit any given funclet pad (including ``cleanupret``
+edges exiting their ``cleanuppad`` and ``catchswitch`` edges exiting their
+``catchswitch``) must share the same unwind destination.  Similarly, any
+funclet pad which may be exited by unwind to caller must not be exited by
+any exception edges which unwind anywhere other than the caller.  This
+ensures that each funclet as a whole has only one unwind destination, which
+EH tables for funclet personalities may require.  Note that any unwind edge
+which exits a ``catchpad`` also exits its parent ``catchswitch``, so this
+implies that for any given ``catchswitch``, its unwind destination must also
+be the unwind destination of any unwind edge that exits any of its constituent
+``catchpad``\s.  Because ``catchswitch`` has no ``nounwind`` variant, and
+because IR producers are not *required* to annotate calls which will not
+unwind as ``nounwind``, it is legal to nest a ``call`` or an "``unwind to
+caller``\ " ``catchswitch`` within a funclet pad that has an unwind
+destination other than caller; it is undefined behavior for such a ``call``
+or ``catchswitch`` to unwind.
+
+Finally, the funclet pads' unwind destinations cannot form a cycle.  This
+ensures that EH lowering can construct "try regions" with a tree-like
+structure, which funclet-based personalities may require.
+
+Exception Handling support on the target
+=================================================
+
+In order to support exception handling on particular target, there are a few
+items need to be implemented.
+
+* CFI directives
+
+  First, you have to assign each target register with a unique DWARF number.
+  Then in ``TargetFrameLowering``'s ``emitPrologue``, you have to emit `CFI
+  directives <https://sourceware.org/binutils/docs/as/CFI-directives.html>`_
+  to specify how to calculate the CFA (Canonical Frame Address) and how register
+  is restored from the address pointed by the CFA with an offset. The assembler
+  is instructed by CFI directives to build ``.eh_frame`` section, which is used
+  by th unwinder to unwind stack during exception handling.
+
+* ``getExceptionPointerRegister`` and ``getExceptionSelectorRegister``
+
+  ``TargetLowering`` must implement both functions. The *personality function*
+  passes the *exception structure* (a pointer) and *selector value* (an integer)
+  to the landing pad through the registers specified by ``getExceptionPointerRegister``
+  and ``getExceptionSelectorRegister`` respectively. On most platforms, they
+  will be GPRs and will be the same as the ones specified in the calling convention.
+
+* ``EH_RETURN``
+
+  The ISD node represents the undocumented GCC extension ``__builtin_eh_return (offset, handler)``,
+  which adjusts the stack by offset and then jumps to the handler. ``__builtin_eh_return``
+  is used in GCC unwinder (`libgcc <https://gcc.gnu.org/onlinedocs/gccint/Libgcc.html>`_),
+  but not in LLVM unwinder (`libunwind <https://clang.llvm.org/docs/Toolchain.html#unwind-library>`_).
+  If you are on the top of ``libgcc`` and have particular requirement on your target,
+  you have to handle ``EH_RETURN`` in ``TargetLowering``.
+
+If you don't leverage the existing runtime (``libstdc++`` and ``libgcc``),
+you have to take a look on `libc++ <https://libcxx.llvm.org/>`_ and
+`libunwind <https://clang.llvm.org/docs/Toolchain.html#unwind-library>`_
+to see what have to be done there. For ``libunwind``, you have to do the following
+
+* ``__libunwind_config.h``
+
+  Define macros for your target.
+
+* ``include/libunwind.h``
+
+  Define enum for the target registers.
+
+* ``src/Registers.hpp``
+
+  Define ``Registers`` class for your target, implement setter and getter functions.
+
+* ``src/UnwindCursor.hpp``
+
+  Define ``dwarfEncoding`` and ``stepWithCompactEncoding`` for your ``Registers``
+  class.
+
+* ``src/UnwindRegistersRestore.S``
+
+  Write an assembly function to restore all your target registers from the memory.
+
+* ``src/UnwindRegistersSave.S``
+
+  Write an assembly function to save all your target registers on the memory.

Added: www-releases/trunk/8.0.1/docs/_sources/ExtendingLLVM.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.1/docs/_sources/ExtendingLLVM.rst.txt?rev=368037&view=auto
==============================================================================
--- www-releases/trunk/8.0.1/docs/_sources/ExtendingLLVM.rst.txt (added)
+++ www-releases/trunk/8.0.1/docs/_sources/ExtendingLLVM.rst.txt Tue Aug  6 06:51:02 2019
@@ -0,0 +1,319 @@
+============================================================
+Extending LLVM: Adding instructions, intrinsics, types, etc.
+============================================================
+
+Introduction and Warning
+========================
+
+
+During the course of using LLVM, you may wish to customize it for your research
+project or for experimentation. At this point, you may realize that you need to
+add something to LLVM, whether it be a new fundamental type, a new intrinsic
+function, or a whole new instruction.
+
+When you come to this realization, stop and think. Do you really need to extend
+LLVM? Is it a new fundamental capability that LLVM does not support at its
+current incarnation or can it be synthesized from already pre-existing LLVM
+elements? If you are not sure, ask on the `LLVM-dev
+<http://lists.llvm.org/mailman/listinfo/llvm-dev>`_ list. The reason is that
+extending LLVM will get involved as you need to update all the different passes
+that you intend to use with your extension, and there are ``many`` LLVM analyses
+and transformations, so it may be quite a bit of work.
+
+Adding an `intrinsic function`_ is far easier than adding an
+instruction, and is transparent to optimization passes.  If your added
+functionality can be expressed as a function call, an intrinsic function is the
+method of choice for LLVM extension.
+
+Before you invest a significant amount of effort into a non-trivial extension,
+**ask on the list** if what you are looking to do can be done with
+already-existing infrastructure, or if maybe someone else is already working on
+it. You will save yourself a lot of time and effort by doing so.
+
+.. _intrinsic function:
+
+Adding a new intrinsic function
+===============================
+
+Adding a new intrinsic function to LLVM is much easier than adding a new
+instruction.  Almost all extensions to LLVM should start as an intrinsic
+function and then be turned into an instruction if warranted.
+
+#. ``llvm/docs/LangRef.html``:
+
+   Document the intrinsic.  Decide whether it is code generator specific and
+   what the restrictions are.  Talk to other people about it so that you are
+   sure it's a good idea.
+
+#. ``llvm/include/llvm/IR/Intrinsics*.td``:
+
+   Add an entry for your intrinsic.  Describe its memory access characteristics
+   for optimization (this controls whether it will be DCE'd, CSE'd, etc). Note
+   that any intrinsic using one of the ``llvm_any*_ty`` types for an argument or
+   return type will be deemed by ``tblgen`` as overloaded and the corresponding
+   suffix will be required on the intrinsic's name.
+
+#. ``llvm/lib/Analysis/ConstantFolding.cpp``:
+
+   If it is possible to constant fold your intrinsic, add support to it in the
+   ``canConstantFoldCallTo`` and ``ConstantFoldCall`` functions.
+
+#. ``llvm/test/*``:
+
+   Add test cases for your test cases to the test suite
+
+Once the intrinsic has been added to the system, you must add code generator
+support for it.  Generally you must do the following steps:
+
+Add support to the .td file for the target(s) of your choice in
+``lib/Target/*/*.td``.
+
+  This is usually a matter of adding a pattern to the .td file that matches the
+  intrinsic, though it may obviously require adding the instructions you want to
+  generate as well.  There are lots of examples in the PowerPC and X86 backend
+  to follow.
+
+Adding a new SelectionDAG node
+==============================
+
+As with intrinsics, adding a new SelectionDAG node to LLVM is much easier than
+adding a new instruction.  New nodes are often added to help represent
+instructions common to many targets.  These nodes often map to an LLVM
+instruction (add, sub) or intrinsic (byteswap, population count).  In other
+cases, new nodes have been added to allow many targets to perform a common task
+(converting between floating point and integer representation) or capture more
+complicated behavior in a single node (rotate).
+
+#. ``include/llvm/CodeGen/ISDOpcodes.h``:
+
+   Add an enum value for the new SelectionDAG node.
+
+#. ``lib/CodeGen/SelectionDAG/SelectionDAG.cpp``:
+
+   Add code to print the node to ``getOperationName``.  If your new node can be
+    evaluated at compile time when given constant arguments (such as an add of a
+    constant with another constant), find the ``getNode`` method that takes the
+    appropriate number of arguments, and add a case for your node to the switch
+    statement that performs constant folding for nodes that take the same number
+    of arguments as your new node.
+
+#. ``lib/CodeGen/SelectionDAG/LegalizeDAG.cpp``:
+
+   Add code to `legalize, promote, and expand
+   <CodeGenerator.html#selectiondag_legalize>`_ the node as necessary.  At a
+   minimum, you will need to add a case statement for your node in
+   ``LegalizeOp`` which calls LegalizeOp on the node's operands, and returns a
+   new node if any of the operands changed as a result of being legalized.  It
+   is likely that not all targets supported by the SelectionDAG framework will
+   natively support the new node.  In this case, you must also add code in your
+   node's case statement in ``LegalizeOp`` to Expand your node into simpler,
+   legal operations.  The case for ``ISD::UREM`` for expanding a remainder into
+   a divide, multiply, and a subtract is a good example.
+
+#. ``lib/CodeGen/SelectionDAG/LegalizeDAG.cpp``:
+
+   If targets may support the new node being added only at certain sizes, you
+    will also need to add code to your node's case statement in ``LegalizeOp``
+    to Promote your node's operands to a larger size, and perform the correct
+    operation.  You will also need to add code to ``PromoteOp`` to do this as
+    well.  For a good example, see ``ISD::BSWAP``, which promotes its operand to
+    a wider size, performs the byteswap, and then shifts the correct bytes right
+    to emulate the narrower byteswap in the wider type.
+
+#. ``lib/CodeGen/SelectionDAG/LegalizeDAG.cpp``:
+
+   Add a case for your node in ``ExpandOp`` to teach the legalizer how to
+   perform the action represented by the new node on a value that has been split
+   into high and low halves.  This case will be used to support your node with a
+   64 bit operand on a 32 bit target.
+
+#. ``lib/CodeGen/SelectionDAG/DAGCombiner.cpp``:
+
+   If your node can be combined with itself, or other existing nodes in a
+   peephole-like fashion, add a visit function for it, and call that function
+   from. There are several good examples for simple combines you can do;
+   ``visitFABS`` and ``visitSRL`` are good starting places.
+
+#. ``lib/Target/PowerPC/PPCISelLowering.cpp``:
+
+   Each target has an implementation of the ``TargetLowering`` class, usually in
+   its own file (although some targets include it in the same file as the
+   DAGToDAGISel).  The default behavior for a target is to assume that your new
+   node is legal for all types that are legal for that target.  If this target
+   does not natively support your node, then tell the target to either Promote
+   it (if it is supported at a larger type) or Expand it.  This will cause the
+   code you wrote in ``LegalizeOp`` above to decompose your new node into other
+   legal nodes for this target.
+
+#. ``lib/Target/TargetSelectionDAG.td``:
+
+   Most current targets supported by LLVM generate code using the DAGToDAG
+   method, where SelectionDAG nodes are pattern matched to target-specific
+   nodes, which represent individual instructions.  In order for the targets to
+   match an instruction to your new node, you must add a def for that node to
+   the list in this file, with the appropriate type constraints. Look at
+   ``add``, ``bswap``, and ``fadd`` for examples.
+
+#. ``lib/Target/PowerPC/PPCInstrInfo.td``:
+
+   Each target has a tablegen file that describes the target's instruction set.
+   For targets that use the DAGToDAG instruction selection framework, add a
+   pattern for your new node that uses one or more target nodes.  Documentation
+   for this is a bit sparse right now, but there are several decent examples.
+   See the patterns for ``rotl`` in ``PPCInstrInfo.td``.
+
+#. TODO: document complex patterns.
+
+#. ``llvm/test/CodeGen/*``:
+
+   Add test cases for your new node to the test suite.
+   ``llvm/test/CodeGen/X86/bswap.ll`` is a good example.
+
+Adding a new instruction
+========================
+
+.. warning::
+
+  Adding instructions changes the bitcode format, and it will take some effort
+  to maintain compatibility with the previous version. Only add an instruction
+  if it is absolutely necessary.
+
+#. ``llvm/include/llvm/IR/Instruction.def``:
+
+   add a number for your instruction and an enum name
+
+#. ``llvm/include/llvm/IR/Instructions.h``:
+
+   add a definition for the class that will represent your instruction
+
+#. ``llvm/include/llvm/IR/InstVisitor.h``:
+
+   add a prototype for a visitor to your new instruction type
+
+#. ``llvm/lib/AsmParser/LLLexer.cpp``:
+
+   add a new token to parse your instruction from assembly text file
+
+#. ``llvm/lib/AsmParser/LLParser.cpp``:
+
+   add the grammar on how your instruction can be read and what it will
+   construct as a result
+
+#. ``llvm/lib/Bitcode/Reader/BitcodeReader.cpp``:
+
+   add a case for your instruction and how it will be parsed from bitcode
+
+#. ``llvm/lib/Bitcode/Writer/BitcodeWriter.cpp``:
+
+   add a case for your instruction and how it will be parsed from bitcode
+
+#. ``llvm/lib/IR/Instruction.cpp``:
+
+   add a case for how your instruction will be printed out to assembly
+
+#. ``llvm/lib/IR/Instructions.cpp``:
+
+   implement the class you defined in ``llvm/include/llvm/Instructions.h``
+
+#. Test your instruction
+
+#. ``llvm/lib/Target/*``:
+
+   add support for your instruction to code generators, or add a lowering pass.
+
+#. ``llvm/test/*``:
+
+   add your test cases to the test suite.
+
+Also, you need to implement (or modify) any analyses or passes that you want to
+understand this new instruction.
+
+Adding a new type
+=================
+
+.. warning::
+
+  Adding new types changes the bitcode format, and will break compatibility with
+  currently-existing LLVM installations. Only add new types if it is absolutely
+  necessary.
+
+Adding a fundamental type
+-------------------------
+
+#. ``llvm/include/llvm/IR/Type.h``:
+
+   add enum for the new type; add static ``Type*`` for this type
+
+#. ``llvm/lib/IR/Type.cpp`` and ``llvm/lib/IR/ValueTypes.cpp``:
+
+   add mapping from ``TypeID`` => ``Type*``; initialize the static ``Type*``
+
+#. ``llvm/llvm/llvm-c/Core.cpp``:
+
+   add enum ``LLVMTypeKind`` and modify
+   ``LLVMTypeKind LLVMGetTypeKind(LLVMTypeRef Ty)`` for the new type
+
+#. ``llvm/lib/AsmParser/LLLexer.cpp``:
+
+   add ability to parse in the type from text assembly
+
+#. ``llvm/lib/AsmParser/LLParser.cpp``:
+
+   add a token for that type
+
+#. ``llvm/lib/Bitcode/Writer/BitcodeWriter.cpp``:
+
+   modify ``static void WriteTypeTable(const ValueEnumerator &VE,
+   BitstreamWriter &Stream)`` to serialize your type
+
+#. ``llvm/lib/Bitcode/Reader/BitcodeReader.cpp``:
+
+   modify ``bool BitcodeReader::ParseTypeType()`` to read your data type
+
+#. ``include/llvm/Bitcode/LLVMBitCodes.h``:
+
+   add enum ``TypeCodes`` for the new type
+
+Adding a derived type
+---------------------
+
+#. ``llvm/include/llvm/IR/Type.h``:
+
+   add enum for the new type; add a forward declaration of the type also
+
+#. ``llvm/include/llvm/IR/DerivedTypes.h``:
+
+   add new class to represent new class in the hierarchy; add forward
+   declaration to the TypeMap value type
+
+#. ``llvm/lib/IR/Type.cpp`` and ``llvm/lib/IR/ValueTypes.cpp``:
+
+   add support for derived type, notably `enum TypeID` and `is`, `get` methods.
+
+#. ``llvm/llvm/llvm-c/Core.cpp``:
+
+   add enum ``LLVMTypeKind`` and modify
+   `LLVMTypeKind LLVMGetTypeKind(LLVMTypeRef Ty)` for the new type
+
+#. ``llvm/lib/AsmParser/LLLexer.cpp``:
+
+   modify ``lltok::Kind LLLexer::LexIdentifier()`` to add ability to
+   parse in the type from text assembly
+
+#. ``llvm/lib/Bitcode/Writer/BitcodeWriter.cpp``:
+
+   modify ``static void WriteTypeTable(const ValueEnumerator &VE,
+   BitstreamWriter &Stream)`` to serialize your type
+
+#. ``llvm/lib/Bitcode/Reader/BitcodeReader.cpp``:
+
+   modify ``bool BitcodeReader::ParseTypeType()`` to read your data type
+
+#. ``include/llvm/Bitcode/LLVMBitCodes.h``:
+
+   add enum ``TypeCodes`` for the new type
+
+#. ``llvm/lib/IR/AsmWriter.cpp``:
+
+   modify ``void TypePrinting::print(Type *Ty, raw_ostream &OS)``
+   to output the new derived type

Added: www-releases/trunk/8.0.1/docs/_sources/Extensions.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.1/docs/_sources/Extensions.rst.txt?rev=368037&view=auto
==============================================================================
--- www-releases/trunk/8.0.1/docs/_sources/Extensions.rst.txt (added)
+++ www-releases/trunk/8.0.1/docs/_sources/Extensions.rst.txt Tue Aug  6 06:51:02 2019
@@ -0,0 +1,522 @@
+===============
+LLVM Extensions
+===============
+
+.. contents::
+   :local:
+
+.. toctree::
+   :hidden:
+
+Introduction
+============
+
+This document describes extensions to tools and formats LLVM seeks compatibility
+with.
+
+General Assembly Syntax
+===========================
+
+C99-style Hexadecimal Floating-point Constants
+----------------------------------------------
+
+LLVM's assemblers allow floating-point constants to be written in C99's
+hexadecimal format instead of decimal if desired.
+
+.. code-block:: gas
+
+  .section .data
+  .float 0x1c2.2ap3
+
+Machine-specific Assembly Syntax
+================================
+
+X86/COFF-Dependent
+------------------
+
+Relocations
+^^^^^^^^^^^
+
+The following additional relocation types are supported:
+
+**@IMGREL** (AT&T syntax only) generates an image-relative relocation that
+corresponds to the COFF relocation types ``IMAGE_REL_I386_DIR32NB`` (32-bit) or
+``IMAGE_REL_AMD64_ADDR32NB`` (64-bit).
+
+.. code-block:: text
+
+  .text
+  fun:
+    mov foo at IMGREL(%ebx, %ecx, 4), %eax
+
+  .section .pdata
+    .long fun at IMGREL
+    .long (fun at imgrel + 0x3F)
+    .long $unwind$fun at imgrel
+
+**.secrel32** generates a relocation that corresponds to the COFF relocation
+types ``IMAGE_REL_I386_SECREL`` (32-bit) or ``IMAGE_REL_AMD64_SECREL`` (64-bit).
+
+**.secidx** relocation generates an index of the section that contains
+the target.  It corresponds to the COFF relocation types
+``IMAGE_REL_I386_SECTION`` (32-bit) or ``IMAGE_REL_AMD64_SECTION`` (64-bit).
+
+.. code-block:: none
+
+  .section .debug$S,"rn"
+    .long 4
+    .long 242
+    .long 40
+    .secrel32 _function_name + 0
+    .secidx   _function_name
+    ...
+
+``.linkonce`` Directive
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+
+   ``.linkonce [ comdat type ]``
+
+Supported COMDAT types:
+
+``discard``
+   Discards duplicate sections with the same COMDAT symbol. This is the default
+   if no type is specified.
+
+``one_only``
+   If the symbol is defined multiple times, the linker issues an error.
+
+``same_size``
+   Duplicates are discarded, but the linker issues an error if any have
+   different sizes.
+
+``same_contents``
+   Duplicates are discarded, but the linker issues an error if any duplicates
+   do not have exactly the same content.
+
+``largest``
+   Links the largest section from among the duplicates.
+
+``newest``
+   Links the newest section from among the duplicates.
+
+
+.. code-block:: gas
+
+  .section .text$foo
+  .linkonce
+    ...
+
+``.section`` Directive
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+MC supports passing the information in ``.linkonce`` at the end of
+``.section``. For example,  these two codes are equivalent
+
+.. code-block:: gas
+
+  .section secName, "dr", discard, "Symbol1"
+  .globl Symbol1
+  Symbol1:
+  .long 1
+
+.. code-block:: gas
+
+  .section secName, "dr"
+  .linkonce discard
+  .globl Symbol1
+  Symbol1:
+  .long 1
+
+Note that in the combined form the COMDAT symbol is explicit. This
+extension exists to support multiple sections with the same name in
+different COMDATs:
+
+
+.. code-block:: gas
+
+  .section secName, "dr", discard, "Symbol1"
+  .globl Symbol1
+  Symbol1:
+  .long 1
+
+  .section secName, "dr", discard, "Symbol2"
+  .globl Symbol2
+  Symbol2:
+  .long 1
+
+In addition to the types allowed with ``.linkonce``, ``.section`` also accepts
+``associative``. The meaning is that the section is linked  if a certain other
+COMDAT section is linked. This other section is indicated by the comdat symbol
+in this directive. It can be any symbol defined in the associated section, but
+is usually the associated section's comdat.
+
+   The following restrictions apply to the associated section:
+
+   1. It must be a COMDAT section.
+   2. It cannot be another associative COMDAT section.
+
+In the following example the symobl ``sym`` is the comdat symbol of ``.foo``
+and ``.bar`` is associated to ``.foo``.
+
+.. code-block:: gas
+
+	.section	.foo,"bw",discard, "sym"
+	.section	.bar,"rd",associative, "sym"
+
+MC supports these flags in the COFF ``.section`` directive:
+
+  - ``b``: BSS section (``IMAGE_SCN_CNT_INITIALIZED_DATA``)
+  - ``d``: Data section (``IMAGE_SCN_CNT_UNINITIALIZED_DATA``)
+  - ``n``: Section is not loaded (``IMAGE_SCN_LNK_REMOVE``)
+  - ``r``: Read-only
+  - ``s``: Shared section
+  - ``w``: Writable
+  - ``x``: Executable section
+  - ``y``: Not readable
+  - ``D``: Discardable (``IMAGE_SCN_MEM_DISCARDABLE``)
+
+These flags are all compatible with gas, with the exception of the ``D`` flag,
+which gnu as does not support. For gas compatibility, sections with a name
+starting with ".debug" are implicitly discardable.
+
+
+ARM64/COFF-Dependent
+--------------------
+
+Relocations
+^^^^^^^^^^^
+
+The following additional symbol variants are supported:
+
+**:secrel_lo12:** generates a relocation that corresponds to the COFF relocation
+types ``IMAGE_REL_ARM64_SECREL_LOW12A`` or ``IMAGE_REL_ARM64_SECREL_LOW12L``.
+
+**:secrel_hi12:** generates a relocation that corresponds to the COFF relocation
+type ``IMAGE_REL_ARM64_SECREL_HIGH12A``.
+
+.. code-block:: gas
+
+    add x0, x0, :secrel_hi12:symbol
+    ldr x0, [x0, :secrel_lo12:symbol]
+
+    add x1, x1, :secrel_hi12:symbol
+    add x1, x1, :secrel_lo12:symbol
+    ...
+
+
+ELF-Dependent
+-------------
+
+``.section`` Directive
+^^^^^^^^^^^^^^^^^^^^^^
+
+In order to support creating multiple sections with the same name and comdat,
+it is possible to add an unique number at the end of the ``.seciton`` directive.
+For example, the following code creates two sections named ``.text``.
+
+.. code-block:: gas
+
+	.section	.text,"ax", at progbits,unique,1
+        nop
+
+	.section	.text,"ax", at progbits,unique,2
+        nop
+
+
+The unique number is not present in the resulting object at all. It is just used
+in the assembler to differentiate the sections.
+
+The 'o' flag is mapped to SHF_LINK_ORDER. If it is present, a symbol
+must be given that identifies the section to be placed is the
+.sh_link.
+
+.. code-block:: gas
+
+        .section .foo,"a", at progbits
+        .Ltmp:
+        .section .bar,"ao", at progbits,.Ltmp
+
+which is equivalent to just
+
+.. code-block:: gas
+
+        .section .foo,"a", at progbits
+        .section .bar,"ao", at progbits,.foo
+
+``.linker-options`` Section (linker options)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In order to support passing linker options from the frontend to the linker, a
+special section of type ``SHT_LLVM_LINKER_OPTIONS`` (usually named
+``.linker-options`` though the name is not significant as it is identified by
+the type).  The contents of this section is a simple pair-wise encoding of
+directives for consideration by the linker.  The strings are encoded as standard
+null-terminated UTF-8 strings.  They are emitted inline to avoid having the
+linker traverse the object file for retrieving the value.  The linker is
+permitted to not honour the option and instead provide a warning/error to the
+user that the requested option was not honoured.
+
+The section has type ``SHT_LLVM_LINKER_OPTIONS`` and has the ``SHF_EXCLUDE``
+flag to ensure that the section is treated as opaque by linkers which do not
+support the feature and will not be emitted into the final linked binary.
+
+This would be equivalent to the follow raw assembly:
+
+.. code-block:: gas
+
+  .section ".linker-options","e", at llvm_linker_options
+  .asciz "option 1"
+  .asciz "value 1"
+  .asciz "option 2"
+  .asciz "value 2"
+
+The following directives are specified:
+
+  - lib
+
+    The parameter identifies a library to be linked against.  The library will
+    be looked up in the default and any specified library search paths
+    (specified to this point).
+
+  - libpath
+
+    The paramter identifies an additional library search path to be considered
+    when looking up libraries after the inclusion of this option.
+
+``SHT_LLVM_CALL_GRAPH_PROFILE`` Section (Call Graph Profile)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This section is used to pass a call graph profile to the linker which can be
+used to optimize the placement of sections.  It contains a sequence of
+(from symbol, to symbol, weight) tuples.
+
+It shall have a type of ``SHT_LLVM_CALL_GRAPH_PROFILE`` (0x6fff4c02), shall
+have the ``SHF_EXCLUDE`` flag set, the ``sh_link`` member shall hold the section
+header index of the associated symbol table, and shall have a ``sh_entsize`` of
+16.  It should be named ``.llvm.call-graph-profile``.
+
+The contents of the section shall be a sequence of ``Elf_CGProfile`` entries.
+
+.. code-block:: c
+
+  typedef struct {
+    Elf_Word cgp_from;
+    Elf_Word cgp_to;
+    Elf_Xword cgp_weight;
+  } Elf_CGProfile;
+
+cgp_from
+  The symbol index of the source of the edge.
+
+cgp_to
+  The symbol index of the destination of the edge.
+
+cgp_weight
+  The weight of the edge.
+
+This is represented in assembly as:
+
+.. code-block:: gas
+
+  .cg_profile from, to, 42
+
+``.cg_profile`` directives are processed at the end of the file.  It is an error
+if either ``from`` or ``to`` are undefined temporary symbols.  If either symbol
+is a temporary symbol, then the section symbol is used instead.  If either
+symbol is undefined, then that symbol is defined as if ``.weak symbol`` has been
+written at the end of the file.  This forces the symbol to show up in the symbol
+table.
+
+``SHT_LLVM_ADDRSIG`` Section (address-significance table)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This section is used to mark symbols as address-significant, i.e. the address
+of the symbol is used in a comparison or leaks outside the translation unit. It
+has the same meaning as the absence of the LLVM attributes ``unnamed_addr``
+and ``local_unnamed_addr``.
+
+Any sections referred to by symbols that are not marked as address-significant
+in any object file may be safely merged by a linker without breaking the
+address uniqueness guarantee provided by the C and C++ language standards.
+
+The contents of the section are a sequence of ULEB128-encoded integers
+referring to the symbol table indexes of the address-significant symbols.
+
+There are two associated assembly directives:
+
+.. code-block:: gas
+
+  .addrsig
+
+This instructs the assembler to emit an address-significance table. Without
+this directive, all symbols are considered address-significant.
+
+.. code-block:: gas
+
+  .addrsig_sym sym
+
+This marks ``sym`` as address-significant.
+
+CodeView-Dependent
+------------------
+
+``.cv_file`` Directive
+^^^^^^^^^^^^^^^^^^^^^^
+Syntax:
+  ``.cv_file`` *FileNumber FileName* [ *checksum* ] [ *checksumkind* ]
+
+``.cv_func_id`` Directive
+^^^^^^^^^^^^^^^^^^^^^^^^^
+Introduces a function ID that can be used with ``.cv_loc``.
+
+Syntax:
+  ``.cv_func_id`` *FunctionId*
+
+``.cv_inline_site_id`` Directive
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Introduces a function ID that can be used with ``.cv_loc``. Includes
+``inlined at`` source location information for use in the line table of the
+caller, whether the caller is a real function or another inlined call site.
+
+Syntax:
+  ``.cv_inline_site_id`` *FunctionId* ``within`` *Function* ``inlined_at`` *FileNumber Line* [ *Colomn* ]
+
+``.cv_loc`` Directive
+^^^^^^^^^^^^^^^^^^^^^
+The first number is a file number, must have been previously assigned with a
+``.file`` directive, the second number is the line number and optionally the
+third number is a column position (zero if not specified).  The remaining
+optional items are ``.loc`` sub-directives.
+
+Syntax:
+  ``.cv_loc`` *FunctionId FileNumber* [ *Line* ] [ *Column* ] [ *prologue_end* ] [ ``is_stmt`` *value* ]
+
+``.cv_linetable`` Directive
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Syntax:
+  ``.cv_linetable`` *FunctionId* ``,`` *FunctionStart* ``,`` *FunctionEnd*
+
+``.cv_inline_linetable`` Directive
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Syntax:
+  ``.cv_inline_linetable`` *PrimaryFunctionId* ``,`` *FileNumber Line FunctionStart FunctionEnd*
+
+``.cv_def_range`` Directive
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The *GapStart* and *GapEnd* options may be repeated as needed.
+
+Syntax:
+  ``.cv_def_range`` *RangeStart RangeEnd* [ *GapStart GapEnd* ] ``,`` *bytes*
+
+``.cv_stringtable`` Directive
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``.cv_filechecksums`` Directive
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``.cv_filechecksumoffset`` Directive
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Syntax:
+  ``.cv_filechecksumoffset`` *FileNumber*
+
+``.cv_fpo_data`` Directive
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+Syntax:
+  ``.cv_fpo_data`` *procsym*
+
+Target Specific Behaviour
+=========================
+
+X86
+---
+
+Relocations
+^^^^^^^^^^^
+
+``@ABS8`` can be applied to symbols which appear as immediate operands to
+instructions that have an 8-bit immediate form for that operand. It causes
+the assembler to use the 8-bit form and an 8-bit relocation (e.g. ``R_386_8``
+or ``R_X86_64_8``) for the symbol.
+
+For example:
+
+.. code-block:: gas
+
+  cmpq $foo at ABS8, %rdi
+
+This causes the assembler to select the form of the 64-bit ``cmpq`` instruction
+that takes an 8-bit immediate operand that is sign extended to 64 bits, as
+opposed to ``cmpq $foo, %rdi`` which takes a 32-bit immediate operand. This
+is also not the same as ``cmpb $foo, %dil``, which is an 8-bit comparison.
+
+Windows on ARM
+--------------
+
+Stack Probe Emission
+^^^^^^^^^^^^^^^^^^^^
+
+The reference implementation (Microsoft Visual Studio 2012) emits stack probes
+in the following fashion:
+
+.. code-block:: gas
+
+  movw r4, #constant
+  bl __chkstk
+  sub.w sp, sp, r4
+
+However, this has the limitation of 32 MiB (±16MiB).  In order to accommodate
+larger binaries, LLVM supports the use of ``-mcode-model=large`` to allow a 4GiB
+range via a slight deviation.  It will generate an indirect jump as follows:
+
+.. code-block:: gas
+
+  movw r4, #constant
+  movw r12, :lower16:__chkstk
+  movt r12, :upper16:__chkstk
+  blx r12
+  sub.w sp, sp, r4
+
+Variable Length Arrays
+^^^^^^^^^^^^^^^^^^^^^^
+
+The reference implementation (Microsoft Visual Studio 2012) does not permit the
+emission of Variable Length Arrays (VLAs).
+
+The Windows ARM Itanium ABI extends the base ABI by adding support for emitting
+a dynamic stack allocation.  When emitting a variable stack allocation, a call
+to ``__chkstk`` is emitted unconditionally to ensure that guard pages are setup
+properly.  The emission of this stack probe emission is handled similar to the
+standard stack probe emission.
+
+The MSVC environment does not emit code for VLAs currently.
+
+Windows on ARM64
+----------------
+
+Stack Probe Emission
+^^^^^^^^^^^^^^^^^^^^
+
+The reference implementation (Microsoft Visual Studio 2017) emits stack probes
+in the following fashion:
+
+.. code-block:: gas
+
+  mov x15, #constant
+  bl __chkstk
+  sub sp, sp, x15, lsl #4
+
+However, this has the limitation of 256 MiB (±128MiB).  In order to accommodate
+larger binaries, LLVM supports the use of ``-mcode-model=large`` to allow a 8GiB
+(±4GiB) range via a slight deviation.  It will generate an indirect jump as
+follows:
+
+.. code-block:: gas
+
+  mov x15, #constant
+  adrp x16, __chkstk
+  add x16, x16, :lo12:__chkstk
+  blr x16
+  sub sp, sp, x15, lsl #4
+

Added: www-releases/trunk/8.0.1/docs/_sources/FAQ.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.1/docs/_sources/FAQ.rst.txt?rev=368037&view=auto
==============================================================================
--- www-releases/trunk/8.0.1/docs/_sources/FAQ.rst.txt (added)
+++ www-releases/trunk/8.0.1/docs/_sources/FAQ.rst.txt Tue Aug  6 06:51:02 2019
@@ -0,0 +1,345 @@
+================================
+Frequently Asked Questions (FAQ)
+================================
+
+.. contents::
+   :local:
+
+
+License
+=======
+
+Does the University of Illinois Open Source License really qualify as an "open source" license?
+-----------------------------------------------------------------------------------------------
+Yes, the license is `certified
+<http://www.opensource.org/licenses/UoI-NCSA.php>`_ by the Open Source
+Initiative (OSI).
+
+
+Can I modify LLVM source code and redistribute the modified source?
+-------------------------------------------------------------------
+Yes.  The modified source distribution must retain the copyright notice and
+follow the three bulleted conditions listed in the `LLVM license
+<http://llvm.org/svn/llvm-project/llvm/trunk/LICENSE.TXT>`_.
+
+
+Can I modify the LLVM source code and redistribute binaries or other tools based on it, without redistributing the source?
+--------------------------------------------------------------------------------------------------------------------------
+Yes. This is why we distribute LLVM under a less restrictive license than GPL,
+as explained in the first question above.
+
+
+Source Code
+===========
+
+In what language is LLVM written?
+---------------------------------
+All of the LLVM tools and libraries are written in C++ with extensive use of
+the STL.
+
+
+How portable is the LLVM source code?
+-------------------------------------
+The LLVM source code should be portable to most modern Unix-like operating
+systems.  Most of the code is written in standard C++ with operating system
+services abstracted to a support library.  The tools required to build and
+test LLVM have been ported to a plethora of platforms.
+
+Some porting problems may exist in the following areas:
+
+* The autoconf/makefile build system relies heavily on UNIX shell tools,
+  like the Bourne Shell and sed.  Porting to systems without these tools
+  (MacOS 9, Plan 9) will require more effort.
+
+What API do I use to store a value to one of the virtual registers in LLVM IR's SSA representation?
+---------------------------------------------------------------------------------------------------
+
+In short: you can't. It's actually kind of a silly question once you grok
+what's going on. Basically, in code like:
+
+.. code-block:: llvm
+
+    %result = add i32 %foo, %bar
+
+, ``%result`` is just a name given to the ``Value`` of the ``add``
+instruction. In other words, ``%result`` *is* the add instruction. The
+"assignment" doesn't explicitly "store" anything to any "virtual register";
+the "``=``" is more like the mathematical sense of equality.
+
+Longer explanation: In order to generate a textual representation of the
+IR, some kind of name has to be given to each instruction so that other
+instructions can textually reference it. However, the isomorphic in-memory
+representation that you manipulate from C++ has no such restriction since
+instructions can simply keep pointers to any other ``Value``'s that they
+reference. In fact, the names of dummy numbered temporaries like ``%1`` are
+not explicitly represented in the in-memory representation at all (see
+``Value::getName()``).
+
+
+Source Languages
+================
+
+What source languages are supported?
+------------------------------------
+
+LLVM currently has full support for C and C++ source languages through
+`Clang <http://clang.llvm.org/>`_. Many other language frontends have
+been written using LLVM, and an incomplete list is available at
+`projects with LLVM <http://llvm.org/ProjectsWithLLVM/>`_.
+
+
+I'd like to write a self-hosting LLVM compiler. How should I interface with the LLVM middle-end optimizers and back-end code generators?
+----------------------------------------------------------------------------------------------------------------------------------------
+Your compiler front-end will communicate with LLVM by creating a module in the
+LLVM intermediate representation (IR) format. Assuming you want to write your
+language's compiler in the language itself (rather than C++), there are 3
+major ways to tackle generating LLVM IR from a front-end:
+
+1. **Call into the LLVM libraries code using your language's FFI (foreign
+   function interface).**
+
+  * *for:* best tracks changes to the LLVM IR, .ll syntax, and .bc format
+
+  * *for:* enables running LLVM optimization passes without a emit/parse
+    overhead
+
+  * *for:* adapts well to a JIT context
+
+  * *against:* lots of ugly glue code to write
+
+2. **Emit LLVM assembly from your compiler's native language.**
+
+  * *for:* very straightforward to get started
+
+  * *against:* the .ll parser is slower than the bitcode reader when
+    interfacing to the middle end
+
+  * *against:* it may be harder to track changes to the IR
+
+3. **Emit LLVM bitcode from your compiler's native language.**
+
+  * *for:* can use the more-efficient bitcode reader when interfacing to the
+    middle end
+
+  * *against:* you'll have to re-engineer the LLVM IR object model and bitcode
+    writer in your language
+
+  * *against:* it may be harder to track changes to the IR
+
+If you go with the first option, the C bindings in include/llvm-c should help
+a lot, since most languages have strong support for interfacing with C. The
+most common hurdle with calling C from managed code is interfacing with the
+garbage collector. The C interface was designed to require very little memory
+management, and so is straightforward in this regard.
+
+What support is there for a higher level source language constructs for building a compiler?
+--------------------------------------------------------------------------------------------
+Currently, there isn't much. LLVM supports an intermediate representation
+which is useful for code representation but will not support the high level
+(abstract syntax tree) representation needed by most compilers. There are no
+facilities for lexical nor semantic analysis.
+
+
+I don't understand the ``GetElementPtr`` instruction. Help!
+-----------------------------------------------------------
+See `The Often Misunderstood GEP Instruction <GetElementPtr.html>`_.
+
+
+Using the C and C++ Front Ends
+==============================
+
+Can I compile C or C++ code to platform-independent LLVM bitcode?
+-----------------------------------------------------------------
+No. C and C++ are inherently platform-dependent languages. The most obvious
+example of this is the preprocessor. A very common way that C code is made
+portable is by using the preprocessor to include platform-specific code. In
+practice, information about other platforms is lost after preprocessing, so
+the result is inherently dependent on the platform that the preprocessing was
+targeting.
+
+Another example is ``sizeof``. It's common for ``sizeof(long)`` to vary
+between platforms. In most C front-ends, ``sizeof`` is expanded to a
+constant immediately, thus hard-wiring a platform-specific detail.
+
+Also, since many platforms define their ABIs in terms of C, and since LLVM is
+lower-level than C, front-ends currently must emit platform-specific IR in
+order to have the result conform to the platform ABI.
+
+
+Questions about code generated by the demo page
+===============================================
+
+What is this ``llvm.global_ctors`` and ``_GLOBAL__I_a...`` stuff that happens when I ``#include <iostream>``?
+-------------------------------------------------------------------------------------------------------------
+If you ``#include`` the ``<iostream>`` header into a C++ translation unit,
+the file will probably use the ``std::cin``/``std::cout``/... global objects.
+However, C++ does not guarantee an order of initialization between static
+objects in different translation units, so if a static ctor/dtor in your .cpp
+file used ``std::cout``, for example, the object would not necessarily be
+automatically initialized before your use.
+
+To make ``std::cout`` and friends work correctly in these scenarios, the STL
+that we use declares a static object that gets created in every translation
+unit that includes ``<iostream>``.  This object has a static constructor
+and destructor that initializes and destroys the global iostream objects
+before they could possibly be used in the file.  The code that you see in the
+``.ll`` file corresponds to the constructor and destructor registration code.
+
+If you would like to make it easier to *understand* the LLVM code generated
+by the compiler in the demo page, consider using ``printf()`` instead of
+``iostream``\s to print values.
+
+
+Where did all of my code go??
+-----------------------------
+If you are using the LLVM demo page, you may often wonder what happened to
+all of the code that you typed in.  Remember that the demo script is running
+the code through the LLVM optimizers, so if your code doesn't actually do
+anything useful, it might all be deleted.
+
+To prevent this, make sure that the code is actually needed.  For example, if
+you are computing some expression, return the value from the function instead
+of leaving it in a local variable.  If you really want to constrain the
+optimizer, you can read from and assign to ``volatile`` global variables.
+
+
+What is this "``undef``" thing that shows up in my code?
+--------------------------------------------------------
+``undef`` is the LLVM way of representing a value that is not defined.  You
+can get these if you do not initialize a variable before you use it.  For
+example, the C function:
+
+.. code-block:: c
+
+   int X() { int i; return i; }
+
+Is compiled to "``ret i32 undef``" because "``i``" never has a value specified
+for it.
+
+
+Why does instcombine + simplifycfg turn a call to a function with a mismatched calling convention into "unreachable"? Why not make the verifier reject it?
+----------------------------------------------------------------------------------------------------------------------------------------------------------
+This is a common problem run into by authors of front-ends that are using
+custom calling conventions: you need to make sure to set the right calling
+convention on both the function and on each call to the function.  For
+example, this code:
+
+.. code-block:: llvm
+
+   define fastcc void @foo() {
+       ret void
+   }
+   define void @bar() {
+       call void @foo()
+       ret void
+   }
+
+Is optimized to:
+
+.. code-block:: llvm
+
+   define fastcc void @foo() {
+       ret void
+   }
+   define void @bar() {
+       unreachable
+   }
+
+... with "``opt -instcombine -simplifycfg``".  This often bites people because
+"all their code disappears".  Setting the calling convention on the caller and
+callee is required for indirect calls to work, so people often ask why not
+make the verifier reject this sort of thing.
+
+The answer is that this code has undefined behavior, but it is not illegal.
+If we made it illegal, then every transformation that could potentially create
+this would have to ensure that it doesn't, and there is valid code that can
+create this sort of construct (in dead code).  The sorts of things that can
+cause this to happen are fairly contrived, but we still need to accept them.
+Here's an example:
+
+.. code-block:: llvm
+
+   define fastcc void @foo() {
+       ret void
+   }
+   define internal void @bar(void()* %FP, i1 %cond) {
+       br i1 %cond, label %T, label %F
+   T:
+       call void %FP()
+       ret void
+   F:
+       call fastcc void %FP()
+       ret void
+   }
+   define void @test() {
+       %X = or i1 false, false
+       call void @bar(void()* @foo, i1 %X)
+       ret void
+   }
+
+In this example, "test" always passes ``@foo``/``false`` into ``bar``, which
+ensures that it is dynamically called with the right calling conv (thus, the
+code is perfectly well defined).  If you run this through the inliner, you
+get this (the explicit "or" is there so that the inliner doesn't dead code
+eliminate a bunch of stuff):
+
+.. code-block:: llvm
+
+   define fastcc void @foo() {
+       ret void
+   }
+   define void @test() {
+       %X = or i1 false, false
+       br i1 %X, label %T.i, label %F.i
+   T.i:
+       call void @foo()
+       br label %bar.exit
+   F.i:
+       call fastcc void @foo()
+       br label %bar.exit
+   bar.exit:
+       ret void
+   }
+
+Here you can see that the inlining pass made an undefined call to ``@foo``
+with the wrong calling convention.  We really don't want to make the inliner
+have to know about this sort of thing, so it needs to be valid code.  In this
+case, dead code elimination can trivially remove the undefined code.  However,
+if ``%X`` was an input argument to ``@test``, the inliner would produce this:
+
+.. code-block:: llvm
+
+   define fastcc void @foo() {
+       ret void
+   }
+
+   define void @test(i1 %X) {
+       br i1 %X, label %T.i, label %F.i
+   T.i:
+       call void @foo()
+       br label %bar.exit
+   F.i:
+       call fastcc void @foo()
+       br label %bar.exit
+   bar.exit:
+       ret void
+   }
+
+The interesting thing about this is that ``%X`` *must* be false for the
+code to be well-defined, but no amount of dead code elimination will be able
+to delete the broken call as unreachable.  However, since
+``instcombine``/``simplifycfg`` turns the undefined call into unreachable, we
+end up with a branch on a condition that goes to unreachable: a branch to
+unreachable can never happen, so "``-inline -instcombine -simplifycfg``" is
+able to produce:
+
+.. code-block:: llvm
+
+   define fastcc void @foo() {
+      ret void
+   }
+   define void @test(i1 %X) {
+   F.i:
+      call fastcc void @foo()
+      ret void
+   }

Added: www-releases/trunk/8.0.1/docs/_sources/FaultMaps.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.1/docs/_sources/FaultMaps.rst.txt?rev=368037&view=auto
==============================================================================
--- www-releases/trunk/8.0.1/docs/_sources/FaultMaps.rst.txt (added)
+++ www-releases/trunk/8.0.1/docs/_sources/FaultMaps.rst.txt Tue Aug  6 06:51:02 2019
@@ -0,0 +1,133 @@
+==============================
+FaultMaps and implicit checks
+==============================
+
+.. contents::
+   :local:
+   :depth: 2
+
+Motivation
+==========
+
+Code generated by managed language runtimes tend to have checks that
+are required for safety but never fail in practice.  In such cases, it
+is profitable to make the non-failing case cheaper even if it makes
+the failing case significantly more expensive.  This asymmetry can be
+exploited by folding such safety checks into operations that can be
+made to fault reliably if the check would have failed, and recovering
+from such a fault by using a signal handler.
+
+For example, Java requires null checks on objects before they are read
+from or written to.  If the object is ``null`` then a
+``NullPointerException`` has to be thrown, interrupting normal
+execution.  In practice, however, dereferencing a ``null`` pointer is
+extremely rare in well-behaved Java programs, and typically the null
+check can be folded into a nearby memory operation that operates on
+the same memory location.
+
+The Fault Map Section
+=====================
+
+Information about implicit checks generated by LLVM are put in a
+special "fault map" section.  On Darwin this section is named
+``__llvm_faultmaps``.
+
+The format of this section is
+
+.. code-block:: none
+
+  Header {
+    uint8  : Fault Map Version (current version is 1)
+    uint8  : Reserved (expected to be 0)
+    uint16 : Reserved (expected to be 0)
+  }
+  uint32 : NumFunctions
+  FunctionInfo[NumFunctions] {
+    uint64 : FunctionAddress
+    uint32 : NumFaultingPCs
+    uint32 : Reserved (expected to be 0)
+    FunctionFaultInfo[NumFaultingPCs] {
+      uint32  : FaultKind
+      uint32  : FaultingPCOffset
+      uint32  : HandlerPCOffset
+    }
+  }
+
+FailtKind describes the reason of expected fault. Currently three kind
+of faults are supported:
+
+  1. ``FaultMaps::FaultingLoad`` - fault due to load from memory.
+  2. ``FaultMaps::FaultingLoadStore`` - fault due to instruction load and store.
+  3. ``FaultMaps::FaultingStore`` - fault due to store to memory.
+
+The ``ImplicitNullChecks`` pass
+===============================
+
+The ``ImplicitNullChecks`` pass transforms explicit control flow for
+checking if a pointer is ``null``, like:
+
+.. code-block:: llvm
+
+    %ptr = call i32* @get_ptr()
+    %ptr_is_null = icmp i32* %ptr, null
+    br i1 %ptr_is_null, label %is_null, label %not_null, !make.implicit !0
+  
+  not_null:
+    %t = load i32, i32* %ptr
+    br label %do_something_with_t
+    
+  is_null:
+    call void @HFC()
+    unreachable
+  
+  !0 = !{}
+
+to control flow implicit in the instruction loading or storing through
+the pointer being null checked:
+
+.. code-block:: llvm
+
+    %ptr = call i32* @get_ptr()
+    %t = load i32, i32* %ptr  ;; handler-pc = label %is_null
+    br label %do_something_with_t
+    
+  is_null:
+    call void @HFC()
+    unreachable
+
+This transform happens at the ``MachineInstr`` level, not the LLVM IR
+level (so the above example is only representative, not literal).  The
+``ImplicitNullChecks`` pass runs during codegen, if
+``-enable-implicit-null-checks`` is passed to ``llc``.
+
+The ``ImplicitNullChecks`` pass adds entries to the
+``__llvm_faultmaps`` section described above as needed.
+
+``make.implicit`` metadata
+--------------------------
+
+Making null checks implicit is an aggressive optimization, and it can
+be a net performance pessimization if too many memory operations end
+up faulting because of it.  A language runtime typically needs to
+ensure that only a negligible number of implicit null checks actually
+fault once the application has reached a steady state.  A standard way
+of doing this is by healing failed implicit null checks into explicit
+null checks via code patching or recompilation.  It follows that there
+are two requirements an explicit null check needs to satisfy for it to
+be profitable to convert it to an implicit null check:
+
+  1. The case where the pointer is actually null (i.e. the "failing"
+     case) is extremely rare.
+
+  2. The failing path heals the implicit null check into an explicit
+     null check so that the application does not repeatedly page
+     fault.
+
+The frontend is expected to mark branches that satisfy (1) and (2)
+using a ``!make.implicit`` metadata node (the actual content of the
+metadata node is ignored).  Only branches that are marked with
+``!make.implicit`` metadata are considered as candidates for
+conversion into implicit null checks.
+
+(Note that while we could deal with (1) using profiling data, dealing
+with (2) requires some information not present in branch profiles.)

Added: www-releases/trunk/8.0.1/docs/_sources/Frontend/PerformanceTips.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.1/docs/_sources/Frontend/PerformanceTips.rst.txt?rev=368037&view=auto
==============================================================================
--- www-releases/trunk/8.0.1/docs/_sources/Frontend/PerformanceTips.rst.txt (added)
+++ www-releases/trunk/8.0.1/docs/_sources/Frontend/PerformanceTips.rst.txt Tue Aug  6 06:51:02 2019
@@ -0,0 +1,296 @@
+=====================================
+Performance Tips for Frontend Authors
+=====================================
+
+.. contents::
+   :local:
+   :depth: 2
+
+Abstract
+========
+
+The intended audience of this document is developers of language frontends 
+targeting LLVM IR. This document is home to a collection of tips on how to 
+generate IR that optimizes well.  
+
+IR Best Practices
+=================
+
+As with any optimizer, LLVM has its strengths and weaknesses.  In some cases, 
+surprisingly small changes in the source IR can have a large effect on the 
+generated code.  
+
+Beyond the specific items on the list below, it's worth noting that the most 
+mature frontend for LLVM is Clang.  As a result, the further your IR gets from what Clang might emit, the less likely it is to be effectively optimized.  It 
+can often be useful to write a quick C program with the semantics you're trying
+to model and see what decisions Clang's IRGen makes about what IR to emit.  
+Studying Clang's CodeGen directory can also be a good source of ideas.  Note 
+that Clang and LLVM are explicitly version locked so you'll need to make sure 
+you're using a Clang built from the same svn revision or release as the LLVM 
+library you're using.  As always, it's *strongly* recommended that you track 
+tip of tree development, particularly during bring up of a new project.
+
+The Basics
+^^^^^^^^^^^
+
+#. Make sure that your Modules contain both a data layout specification and 
+   target triple. Without these pieces, non of the target specific optimization
+   will be enabled.  This can have a major effect on the generated code quality.
+
+#. For each function or global emitted, use the most private linkage type
+   possible (private, internal or linkonce_odr preferably).  Doing so will 
+   make LLVM's inter-procedural optimizations much more effective.
+
+#. Avoid high in-degree basic blocks (e.g. basic blocks with dozens or hundreds
+   of predecessors).  Among other issues, the register allocator is known to 
+   perform badly with confronted with such structures.  The only exception to 
+   this guidance is that a unified return block with high in-degree is fine.
+
+Use of allocas
+^^^^^^^^^^^^^^
+
+An alloca instruction can be used to represent a function scoped stack slot, 
+but can also represent dynamic frame expansion.  When representing function 
+scoped variables or locations, placing alloca instructions at the beginning of 
+the entry block should be preferred.   In particular, place them before any 
+call instructions. Call instructions might get inlined and replaced with 
+multiple basic blocks. The end result is that a following alloca instruction 
+would no longer be in the entry basic block afterward.
+
+The SROA (Scalar Replacement Of Aggregates) and Mem2Reg passes only attempt
+to eliminate alloca instructions that are in the entry basic block.  Given 
+SSA is the canonical form expected by much of the optimizer; if allocas can 
+not be eliminated by Mem2Reg or SROA, the optimizer is likely to be less 
+effective than it could be.
+
+Avoid loads and stores of large aggregate type
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+LLVM currently does not optimize well loads and stores of large :ref:`aggregate
+types <t_aggregate>` (i.e. structs and arrays).  As an alternative, consider 
+loading individual fields from memory.
+
+Aggregates that are smaller than the largest (performant) load or store 
+instruction supported by the targeted hardware are well supported.  These can 
+be an effective way to represent collections of small packed fields.  
+
+Prefer zext over sext when legal
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+On some architectures (X86_64 is one), sign extension can involve an extra 
+instruction whereas zero extension can be folded into a load.  LLVM will try to
+replace a sext with a zext when it can be proven safe, but if you have 
+information in your source language about the range of a integer value, it can 
+be profitable to use a zext rather than a sext.  
+
+Alternatively, you can :ref:`specify the range of the value using metadata 
+<range-metadata>` and LLVM can do the sext to zext conversion for you.
+
+Zext GEP indices to machine register width
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Internally, LLVM often promotes the width of GEP indices to machine register
+width.  When it does so, it will default to using sign extension (sext) 
+operations for safety.  If your source language provides information about 
+the range of the index, you may wish to manually extend indices to machine 
+register width using a zext instruction.
+
+When to specify alignment
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+LLVM will always generate correct code if you don’t specify alignment, but may
+generate inefficient code.  For example, if you are targeting MIPS (or older 
+ARM ISAs) then the hardware does not handle unaligned loads and stores, and 
+so you will enter a trap-and-emulate path if you do a load or store with 
+lower-than-natural alignment.  To avoid this, LLVM will emit a slower 
+sequence of loads, shifts and masks (or load-right + load-left on MIPS) for 
+all cases where the load / store does not have a sufficiently high alignment 
+in the IR.
+
+The alignment is used to guarantee the alignment on allocas and globals, 
+though in most cases this is unnecessary (most targets have a sufficiently 
+high default alignment that they’ll be fine).  It is also used to provide a 
+contract to the back end saying ‘either this load/store has this alignment, or
+it is undefined behavior’.  This means that the back end is free to emit 
+instructions that rely on that alignment (and mid-level optimizers are free to 
+perform transforms that require that alignment).  For x86, it doesn’t make 
+much difference, as almost all instructions are alignment-independent.  For 
+MIPS, it can make a big difference.
+
+Note that if your loads and stores are atomic, the backend will be unable to 
+lower an under aligned access into a sequence of natively aligned accesses.  
+As a result, alignment is mandatory for atomic loads and stores.
+
+Other Things to Consider
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+#. Use ptrtoint/inttoptr sparingly (they interfere with pointer aliasing 
+   analysis), prefer GEPs
+
+#. Prefer globals over inttoptr of a constant address - this gives you 
+   dereferencability information.  In MCJIT, use getSymbolAddress to provide 
+   actual address.
+
+#. Be wary of ordered and atomic memory operations.  They are hard to optimize 
+   and may not be well optimized by the current optimizer.  Depending on your
+   source language, you may consider using fences instead.
+
+#. If calling a function which is known to throw an exception (unwind), use 
+   an invoke with a normal destination which contains an unreachable 
+   instruction.  This form conveys to the optimizer that the call returns 
+   abnormally.  For an invoke which neither returns normally or requires unwind
+   code in the current function, you can use a noreturn call instruction if 
+   desired.  This is generally not required because the optimizer will convert
+   an invoke with an unreachable unwind destination to a call instruction.
+
+#. Use profile metadata to indicate statically known cold paths, even if 
+   dynamic profiling information is not available.  This can make a large 
+   difference in code placement and thus the performance of tight loops.
+
+#. When generating code for loops, try to avoid terminating the header block of
+   the loop earlier than necessary.  If the terminator of the loop header 
+   block is a loop exiting conditional branch, the effectiveness of LICM will
+   be limited for loads not in the header.  (This is due to the fact that LLVM 
+   may not know such a load is safe to speculatively execute and thus can't 
+   lift an otherwise loop invariant load unless it can prove the exiting 
+   condition is not taken.)  It can be profitable, in some cases, to emit such 
+   instructions into the header even if they are not used along a rarely 
+   executed path that exits the loop.  This guidance specifically does not 
+   apply if the condition which terminates the loop header is itself invariant,
+   or can be easily discharged by inspecting the loop index variables.
+
+#. In hot loops, consider duplicating instructions from small basic blocks 
+   which end in highly predictable terminators into their successor blocks.  
+   If a hot successor block contains instructions which can be vectorized 
+   with the duplicated ones, this can provide a noticeable throughput
+   improvement.  Note that this is not always profitable and does involve a 
+   potentially large increase in code size.
+
+#. When checking a value against a constant, emit the check using a consistent
+   comparison type.  The GVN pass *will* optimize redundant equalities even if
+   the type of comparison is inverted, but GVN only runs late in the pipeline.
+   As a result, you may miss the opportunity to run other important 
+   optimizations.  Improvements to EarlyCSE to remove this issue are tracked in 
+   Bug 23333.
+
+#. Avoid using arithmetic intrinsics unless you are *required* by your source 
+   language specification to emit a particular code sequence.  The optimizer 
+   is quite good at reasoning about general control flow and arithmetic, it is
+   not anywhere near as strong at reasoning about the various intrinsics.  If 
+   profitable for code generation purposes, the optimizer will likely form the 
+   intrinsics itself late in the optimization pipeline.  It is *very* rarely 
+   profitable to emit these directly in the language frontend.  This item
+   explicitly includes the use of the :ref:`overflow intrinsics <int_overflow>`.
+
+#. Avoid using the :ref:`assume intrinsic <int_assume>` until you've 
+   established that a) there's no other way to express the given fact and b) 
+   that fact is critical for optimization purposes.  Assumes are a great 
+   prototyping mechanism, but they can have negative effects on both compile 
+   time and optimization effectiveness.  The former is fixable with enough 
+   effort, but the later is fairly fundamental to their designed purpose.
+
+
+Describing Language Specific Properties
+=======================================
+
+When translating a source language to LLVM, finding ways to express concepts 
+and guarantees available in your source language which are not natively 
+provided by LLVM IR will greatly improve LLVM's ability to optimize your code. 
+As an example, C/C++'s ability to mark every add as "no signed wrap (nsw)" goes
+a long way to assisting the optimizer in reasoning about loop induction 
+variables and thus generating more optimal code for loops.  
+
+The LLVM LangRef includes a number of mechanisms for annotating the IR with 
+additional semantic information.  It is *strongly* recommended that you become 
+highly familiar with this document.  The list below is intended to highlight a 
+couple of items of particular interest, but is by no means exhaustive.
+
+Restricted Operation Semantics
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+#. Add nsw/nuw flags as appropriate.  Reasoning about overflow is 
+   generally hard for an optimizer so providing these facts from the frontend 
+   can be very impactful.  
+
+#. Use fast-math flags on floating point operations if legal.  If you don't 
+   need strict IEEE floating point semantics, there are a number of additional 
+   optimizations that can be performed.  This can be highly impactful for 
+   floating point intensive computations.
+
+Describing Aliasing Properties
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+#. Add noalias/align/dereferenceable/nonnull to function arguments and return 
+   values as appropriate
+
+#. Use pointer aliasing metadata, especially tbaa metadata, to communicate 
+   otherwise-non-deducible pointer aliasing facts
+
+#. Use inbounds on geps.  This can help to disambiguate some aliasing queries.
+
+
+Modeling Memory Effects
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+#. Mark functions as readnone/readonly/argmemonly or noreturn/nounwind when
+   known.  The optimizer will try to infer these flags, but may not always be
+   able to.  Manual annotations are particularly important for external 
+   functions that the optimizer can not analyze.
+
+#. Use the lifetime.start/lifetime.end and invariant.start/invariant.end 
+   intrinsics where possible.  Common profitable uses are for stack like data 
+   structures (thus allowing dead store elimination) and for describing 
+   life times of allocas (thus allowing smaller stack sizes).  
+
+#. Mark invariant locations using !invariant.load and TBAA's constant flags
+
+Pass Ordering
+^^^^^^^^^^^^^
+
+One of the most common mistakes made by new language frontend projects is to 
+use the existing -O2 or -O3 pass pipelines as is.  These pass pipelines make a
+good starting point for an optimizing compiler for any language, but they have 
+been carefully tuned for C and C++, not your target language.  You will almost 
+certainly need to use a custom pass order to achieve optimal performance.  A 
+couple specific suggestions:
+
+#. For languages with numerous rarely executed guard conditions (e.g. null 
+   checks, type checks, range checks) consider adding an extra execution or 
+   two of LoopUnswith and LICM to your pass order.  The standard pass order, 
+   which is tuned for C and C++ applications, may not be sufficient to remove 
+   all dischargeable checks from loops.
+
+#. If you language uses range checks, consider using the IRCE pass.  It is not 
+   currently part of the standard pass order.
+
+#. A useful sanity check to run is to run your optimized IR back through the 
+   -O2 pipeline again.  If you see noticeable improvement in the resulting IR, 
+   you likely need to adjust your pass order.
+
+
+I Still Can't Find What I'm Looking For
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you didn't find what you were looking for above, consider proposing an piece
+of metadata which provides the optimization hint you need.  Such extensions are
+relatively common and are generally well received by the community.  You will 
+need to ensure that your proposal is sufficiently general so that it benefits 
+others if you wish to contribute it upstream.
+
+You should also consider describing the problem you're facing on `llvm-dev 
+<http://lists.llvm.org/mailman/listinfo/llvm-dev>`_ and asking for advice.  
+It's entirely possible someone has encountered your problem before and can 
+give good advice.  If there are multiple interested parties, that also 
+increases the chances that a metadata extension would be well received by the
+community as a whole.  
+
+Adding to this document
+=======================
+
+If you run across a case that you feel deserves to be covered here, please send
+a patch to `llvm-commits
+<http://lists.llvm.org/mailman/listinfo/llvm-commits>`_ for review.
+
+If you have questions on these items, please direct them to `llvm-dev 
+<http://lists.llvm.org/mailman/listinfo/llvm-dev>`_.  The more relevant 
+context you are able to give to your question, the more likely it is to be 
+answered.
+

Added: www-releases/trunk/8.0.1/docs/_sources/FuzzingLLVM.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.1/docs/_sources/FuzzingLLVM.rst.txt?rev=368037&view=auto
==============================================================================
--- www-releases/trunk/8.0.1/docs/_sources/FuzzingLLVM.rst.txt (added)
+++ www-releases/trunk/8.0.1/docs/_sources/FuzzingLLVM.rst.txt Tue Aug  6 06:51:02 2019
@@ -0,0 +1,280 @@
+================================
+Fuzzing LLVM libraries and tools
+================================
+
+.. contents::
+   :local:
+   :depth: 2
+
+Introduction
+============
+
+The LLVM tree includes a number of fuzzers for various components. These are
+built on top of :doc:`LibFuzzer <LibFuzzer>`. In order to build and run these
+fuzzers, see :ref:`building-fuzzers`.
+
+
+Available Fuzzers
+=================
+
+clang-fuzzer
+------------
+
+A |generic fuzzer| that tries to compile textual input as C++ code. Some of the
+bugs this fuzzer has reported are `on bugzilla`__ and `on OSS Fuzz's
+tracker`__.
+
+__ https://llvm.org/pr23057
+__ https://bugs.chromium.org/p/oss-fuzz/issues/list?q=proj-llvm+clang-fuzzer
+
+clang-proto-fuzzer
+------------------
+
+A |protobuf fuzzer| that compiles valid C++ programs generated from a protobuf
+class that describes a subset of the C++ language.
+
+This fuzzer accepts clang command line options after `ignore_remaining_args=1`.
+For example, the following command will fuzz clang with a higher optimization
+level:
+
+.. code-block:: shell
+
+   % bin/clang-proto-fuzzer <corpus-dir> -ignore_remaining_args=1 -O3
+
+clang-format-fuzzer
+-------------------
+
+A |generic fuzzer| that runs clang-format_ on C++ text fragments. Some of the
+bugs this fuzzer has reported are `on bugzilla`__
+and `on OSS Fuzz's tracker`__.
+
+.. _clang-format: https://clang.llvm.org/docs/ClangFormat.html
+__ https://llvm.org/pr23052
+__ https://bugs.chromium.org/p/oss-fuzz/issues/list?q=proj-llvm+clang-format-fuzzer
+
+llvm-as-fuzzer
+--------------
+
+A |generic fuzzer| that tries to parse text as :doc:`LLVM assembly <LangRef>`.
+Some of the bugs this fuzzer has reported are `on bugzilla`__.
+
+__ https://llvm.org/pr24639
+
+llvm-dwarfdump-fuzzer
+---------------------
+
+A |generic fuzzer| that interprets inputs as object files and runs
+:doc:`llvm-dwarfdump <CommandGuide/llvm-dwarfdump>` on them. Some of the bugs
+this fuzzer has reported are `on OSS Fuzz's tracker`__
+
+__ https://bugs.chromium.org/p/oss-fuzz/issues/list?q=proj-llvm+llvm-dwarfdump-fuzzer
+
+llvm-demangle-fuzzer
+---------------------
+
+A |generic fuzzer| for the Itanium demangler used in various LLVM tools. We've
+fuzzed __cxa_demangle to death, why not fuzz LLVM's implementation of the same
+function!
+
+llvm-isel-fuzzer
+----------------
+
+A |LLVM IR fuzzer| aimed at finding bugs in instruction selection.
+
+This fuzzer accepts flags after `ignore_remaining_args=1`. The flags match
+those of :doc:`llc <CommandGuide/llc>` and the triple is required. For example,
+the following command would fuzz AArch64 with :doc:`GlobalISel`:
+
+.. code-block:: shell
+
+   % bin/llvm-isel-fuzzer <corpus-dir> -ignore_remaining_args=1 -mtriple aarch64 -global-isel -O0
+
+Some flags can also be specified in the binary name itself in order to support
+OSS Fuzz, which has trouble with required arguments. To do this, you can copy
+or move ``llvm-isel-fuzzer`` to ``llvm-isel-fuzzer--x-y-z``, separating options
+from the binary name using "--". The valid options are architecture names
+(``aarch64``, ``x86_64``), optimization levels (``O0``, ``O2``), or specific
+keywords, like ``gisel`` for enabling global instruction selection. In this
+mode, the same example could be run like so:
+
+.. code-block:: shell
+
+   % bin/llvm-isel-fuzzer--aarch64-O0-gisel <corpus-dir>
+
+llvm-opt-fuzzer
+---------------
+
+A |LLVM IR fuzzer| aimed at finding bugs in optimization passes.
+
+It receives optimzation pipeline and runs it for each fuzzer input.
+
+Interface of this fuzzer almost directly mirrors ``llvm-isel-fuzzer``. Both
+``mtriple`` and ``passes`` arguments are required. Passes are specified in a
+format suitable for the new pass manager. You can find some documentation about
+this format in the doxygen for ``PassBuilder::parsePassPipeline``.
+
+.. code-block:: shell
+
+   % bin/llvm-opt-fuzzer <corpus-dir> -ignore_remaining_args=1 -mtriple x86_64 -passes instcombine
+
+Similarly to the ``llvm-isel-fuzzer`` arguments in some predefined configurations
+might be embedded directly into the binary file name:
+
+.. code-block:: shell
+
+   % bin/llvm-opt-fuzzer--x86_64-instcombine <corpus-dir>
+
+llvm-mc-assemble-fuzzer
+-----------------------
+
+A |generic fuzzer| that fuzzes the MC layer's assemblers by treating inputs as
+target specific assembly.
+
+Note that this fuzzer has an unusual command line interface which is not fully
+compatible with all of libFuzzer's features. Fuzzer arguments must be passed
+after ``--fuzzer-args``, and any ``llc`` flags must use two dashes. For
+example, to fuzz the AArch64 assembler you might use the following command:
+
+.. code-block:: console
+
+  llvm-mc-fuzzer --triple=aarch64-linux-gnu --fuzzer-args -max_len=4
+
+This scheme will likely change in the future.
+
+llvm-mc-disassemble-fuzzer
+--------------------------
+
+A |generic fuzzer| that fuzzes the MC layer's disassemblers by treating inputs
+as assembled binary data.
+
+Note that this fuzzer has an unusual command line interface which is not fully
+compatible with all of libFuzzer's features. See the notes above about
+``llvm-mc-assemble-fuzzer`` for details.
+
+
+.. |generic fuzzer| replace:: :ref:`generic fuzzer <fuzzing-llvm-generic>`
+.. |protobuf fuzzer|
+   replace:: :ref:`libprotobuf-mutator based fuzzer <fuzzing-llvm-protobuf>`
+.. |LLVM IR fuzzer|
+   replace:: :ref:`structured LLVM IR fuzzer <fuzzing-llvm-ir>`
+
+
+Mutators and Input Generators
+=============================
+
+The inputs for a fuzz target are generated via random mutations of a
+:ref:`corpus <libfuzzer-corpus>`. There are a few options for the kinds of
+mutations that a fuzzer in LLVM might want.
+
+.. _fuzzing-llvm-generic:
+
+Generic Random Fuzzing
+----------------------
+
+The most basic form of input mutation is to use the built in mutators of
+LibFuzzer. These simply treat the input corpus as a bag of bits and make random
+mutations. This type of fuzzer is good for stressing the surface layers of a
+program, and is good at testing things like lexers, parsers, or binary
+protocols.
+
+Some of the in-tree fuzzers that use this type of mutator are `clang-fuzzer`_,
+`clang-format-fuzzer`_, `llvm-as-fuzzer`_, `llvm-dwarfdump-fuzzer`_,
+`llvm-mc-assemble-fuzzer`_, and `llvm-mc-disassemble-fuzzer`_.
+
+.. _fuzzing-llvm-protobuf:
+
+Structured Fuzzing using ``libprotobuf-mutator``
+------------------------------------------------
+
+We can use libprotobuf-mutator_ in order to perform structured fuzzing and
+stress deeper layers of programs. This works by defining a protobuf class that
+translates arbitrary data into structurally interesting input. Specifically, we
+use this to work with a subset of the C++ language and perform mutations that
+produce valid C++ programs in order to exercise parts of clang that are more
+interesting than parser error handling.
+
+To build this kind of fuzzer you need `protobuf`_ and its dependencies
+installed, and you need to specify some extra flags when configuring the build
+with :doc:`CMake <CMake>`. For example, `clang-proto-fuzzer`_ can be enabled by
+adding ``-DCLANG_ENABLE_PROTO_FUZZER=ON`` to the flags described in
+:ref:`building-fuzzers`.
+
+The only in-tree fuzzer that uses ``libprotobuf-mutator`` today is
+`clang-proto-fuzzer`_.
+
+.. _libprotobuf-mutator: https://github.com/google/libprotobuf-mutator
+.. _protobuf: https://github.com/google/protobuf
+
+.. _fuzzing-llvm-ir:
+
+Structured Fuzzing of LLVM IR
+-----------------------------
+
+We also use a more direct form of structured fuzzing for fuzzers that take
+:doc:`LLVM IR <LangRef>` as input. This is achieved through the ``FuzzMutate``
+library, which was `discussed at EuroLLVM 2017`_.
+
+The ``FuzzMutate`` library is used to structurally fuzz backends in
+`llvm-isel-fuzzer`_.
+
+.. _discussed at EuroLLVM 2017: https://www.youtube.com/watch?v=UBbQ_s6hNgg
+
+
+Building and Running
+====================
+
+.. _building-fuzzers:
+
+Configuring LLVM to Build Fuzzers
+---------------------------------
+
+Fuzzers will be built and linked to libFuzzer by default as long as you build
+LLVM with sanitizer coverage enabled. You would typically also enable at least
+one sanitizer to find bugs faster. The most common way to build the fuzzers is
+by adding the following two flags to your CMake invocation:
+``-DLLVM_USE_SANITIZER=Address -DLLVM_USE_SANITIZE_COVERAGE=On``.
+
+.. note:: If you have ``compiler-rt`` checked out in an LLVM tree when building
+          with sanitizers, you'll want to specify ``-DLLVM_BUILD_RUNTIME=Off``
+          to avoid building the sanitizers themselves with sanitizers enabled.
+
+.. note:: You may run into issues if you build with BFD ld, which is the
+          default linker on many unix systems. These issues are being tracked
+          in https://llvm.org/PR34636.
+
+Continuously Running and Finding Bugs
+-------------------------------------
+
+There used to be a public buildbot running LLVM fuzzers continuously, and while
+this did find issues, it didn't have a very good way to report problems in an
+actionable way. Because of this, we're moving towards using `OSS Fuzz`_ more
+instead.
+
+You can browse the `LLVM project issue list`_ for the bugs found by
+`LLVM on OSS Fuzz`_. These are also mailed to the `llvm-bugs mailing
+list`_.
+
+.. _OSS Fuzz: https://github.com/google/oss-fuzz
+.. _LLVM project issue list:
+   https://bugs.chromium.org/p/oss-fuzz/issues/list?q=Proj-llvm
+.. _LLVM on OSS Fuzz:
+   https://github.com/google/oss-fuzz/blob/master/projects/llvm
+.. _llvm-bugs mailing list:
+   http://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-bugs
+
+
+Utilities for Writing Fuzzers
+=============================
+
+There are some utilities available for writing fuzzers in LLVM.
+
+Some helpers for handling the command line interface are available in
+``include/llvm/FuzzMutate/FuzzerCLI.h``, including functions to parse command
+line options in a consistent way and to implement standalone main functions so
+your fuzzer can be built and tested when not built against libFuzzer.
+
+There is also some handling of the CMake config for fuzzers, where you should
+use the ``add_llvm_fuzzer`` to set up fuzzer targets. This function works
+similarly to functions such as ``add_llvm_tool``, but they take care of linking
+to LibFuzzer when appropriate and can be passed the ``DUMMY_MAIN`` argument to
+enable standalone testing.

Added: www-releases/trunk/8.0.1/docs/_sources/GarbageCollection.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.1/docs/_sources/GarbageCollection.rst.txt?rev=368037&view=auto
==============================================================================
--- www-releases/trunk/8.0.1/docs/_sources/GarbageCollection.rst.txt (added)
+++ www-releases/trunk/8.0.1/docs/_sources/GarbageCollection.rst.txt Tue Aug  6 06:51:02 2019
@@ -0,0 +1,1028 @@
+=====================================
+Garbage Collection with LLVM
+=====================================
+
+.. contents::
+   :local:
+
+Abstract
+========
+
+This document covers how to integrate LLVM into a compiler for a language which
+supports garbage collection.  **Note that LLVM itself does not provide a 
+garbage collector.**  You must provide your own.  
+
+Quick Start
+============
+
+First, you should pick a collector strategy.  LLVM includes a number of built 
+in ones, but you can also implement a loadable plugin with a custom definition.
+Note that the collector strategy is a description of how LLVM should generate 
+code such that it interacts with your collector and runtime, not a description
+of the collector itself.
+
+Next, mark your generated functions as using your chosen collector strategy.  
+From c++, you can call: 
+
+.. code-block:: c++
+
+  F.setGC(<collector description name>);
+
+
+This will produce IR like the following fragment:
+
+.. code-block:: llvm
+
+  define void @foo() gc "<collector description name>" { ... }
+
+
+When generating LLVM IR for your functions, you will need to:
+
+* Use ``@llvm.gcread`` and/or ``@llvm.gcwrite`` in place of standard load and 
+  store instructions.  These intrinsics are used to represent load and store 
+  barriers.  If you collector does not require such barriers, you can skip 
+  this step.  
+
+* Use the memory allocation routines provided by your garbage collector's 
+  runtime library.
+
+* If your collector requires them, generate type maps according to your 
+  runtime's binary interface.  LLVM is not involved in the process.  In 
+  particular, the LLVM type system is not suitable for conveying such 
+  information though the compiler.
+
+* Insert any coordination code required for interacting with your collector.  
+  Many collectors require running application code to periodically check a
+  flag and conditionally call a runtime function.  This is often referred to 
+  as a safepoint poll.  
+
+You will need to identify roots (i.e. references to heap objects your collector 
+needs to know about) in your generated IR, so that LLVM can encode them into 
+your final stack maps.  Depending on the collector strategy chosen, this is 
+accomplished by using either the ``@llvm.gcroot`` intrinsics or an 
+``gc.statepoint`` relocation sequence. 
+
+Don't forget to create a root for each intermediate value that is generated when
+evaluating an expression.  In ``h(f(), g())``, the result of ``f()`` could 
+easily be collected if evaluating ``g()`` triggers a collection.
+
+Finally, you need to link your runtime library with the generated program 
+executable (for a static compiler) or ensure the appropriate symbols are 
+available for the runtime linker (for a JIT compiler).  
+
+
+Introduction
+============
+
+What is Garbage Collection?
+---------------------------
+
+Garbage collection is a widely used technique that frees the programmer from
+having to know the lifetimes of heap objects, making software easier to produce
+and maintain.  Many programming languages rely on garbage collection for
+automatic memory management.  There are two primary forms of garbage collection:
+conservative and accurate.
+
+Conservative garbage collection often does not require any special support from
+either the language or the compiler: it can handle non-type-safe programming
+languages (such as C/C++) and does not require any special information from the
+compiler.  The `Boehm collector
+<http://www.hpl.hp.com/personal/Hans_Boehm/gc/>`__ is an example of a
+state-of-the-art conservative collector.
+
+Accurate garbage collection requires the ability to identify all pointers in the
+program at run-time (which requires that the source-language be type-safe in
+most cases).  Identifying pointers at run-time requires compiler support to
+locate all places that hold live pointer variables at run-time, including the
+:ref:`processor stack and registers <gcroot>`.
+
+Conservative garbage collection is attractive because it does not require any
+special compiler support, but it does have problems.  In particular, because the
+conservative garbage collector cannot *know* that a particular word in the
+machine is a pointer, it cannot move live objects in the heap (preventing the
+use of compacting and generational GC algorithms) and it can occasionally suffer
+from memory leaks due to integer values that happen to point to objects in the
+program.  In addition, some aggressive compiler transformations can break
+conservative garbage collectors (though these seem rare in practice).
+
+Accurate garbage collectors do not suffer from any of these problems, but they
+can suffer from degraded scalar optimization of the program.  In particular,
+because the runtime must be able to identify and update all pointers active in
+the program, some optimizations are less effective.  In practice, however, the
+locality and performance benefits of using aggressive garbage collection
+techniques dominates any low-level losses.
+
+This document describes the mechanisms and interfaces provided by LLVM to
+support accurate garbage collection.
+
+Goals and non-goals
+-------------------
+
+LLVM's intermediate representation provides :ref:`garbage collection intrinsics
+<gc_intrinsics>` that offer support for a broad class of collector models.  For
+instance, the intrinsics permit:
+
+* semi-space collectors
+
+* mark-sweep collectors
+
+* generational collectors
+
+* incremental collectors
+
+* concurrent collectors
+
+* cooperative collectors
+
+* reference counting
+
+We hope that the support built into the LLVM IR is sufficient to support a 
+broad class of garbage collected languages including Scheme, ML, Java, C#, 
+Perl, Python, Lua, Ruby, other scripting languages, and more.
+
+Note that LLVM **does not itself provide a garbage collector** --- this should
+be part of your language's runtime library.  LLVM provides a framework for
+describing the garbage collectors requirements to the compiler.  In particular,
+LLVM provides support for generating stack maps at call sites, polling for a 
+safepoint, and emitting load and store barriers.  You can also extend LLVM - 
+possibly through a loadable :ref:`code generation plugins <plugin>` - to
+generate code and data structures which conforms to the *binary interface*
+specified by the *runtime library*.  This is similar to the relationship between
+LLVM and DWARF debugging info, for example.  The difference primarily lies in
+the lack of an established standard in the domain of garbage collection --- thus
+the need for a flexible extension mechanism.
+
+The aspects of the binary interface with which LLVM's GC support is
+concerned are:
+
+* Creation of GC safepoints within code where collection is allowed to execute
+  safely.
+
+* Computation of the stack map.  For each safe point in the code, object
+  references within the stack frame must be identified so that the collector may
+  traverse and perhaps update them.
+
+* Write barriers when storing object references to the heap.  These are commonly
+  used to optimize incremental scans in generational collectors.
+
+* Emission of read barriers when loading object references.  These are useful
+  for interoperating with concurrent collectors.
+
+There are additional areas that LLVM does not directly address:
+
+* Registration of global roots with the runtime.
+
+* Registration of stack map entries with the runtime.
+
+* The functions used by the program to allocate memory, trigger a collection,
+  etc.
+
+* Computation or compilation of type maps, or registration of them with the
+  runtime.  These are used to crawl the heap for object references.
+
+In general, LLVM's support for GC does not include features which can be
+adequately addressed with other features of the IR and does not specify a
+particular binary interface.  On the plus side, this means that you should be
+able to integrate LLVM with an existing runtime.  On the other hand, it can 
+have the effect of leaving a lot of work for the developer of a novel 
+language.  We try to mitigate this by providing built in collector strategy 
+descriptions that can work with many common collector designs and easy 
+extension points.  If you don't already have a specific binary interface 
+you need to support, we recommend trying to use one of these built in collector 
+strategies.
+
+.. _gc_intrinsics:
+
+LLVM IR Features
+================
+
+This section describes the garbage collection facilities provided by the
+:doc:`LLVM intermediate representation <LangRef>`.  The exact behavior of these
+IR features is specified by the selected :ref:`GC strategy description 
+<plugin>`. 
+
+Specifying GC code generation: ``gc "..."``
+-------------------------------------------
+
+.. code-block:: text
+
+  define <returntype> @name(...) gc "name" { ... }
+
+The ``gc`` function attribute is used to specify the desired GC strategy to the
+compiler.  Its programmatic equivalent is the ``setGC`` method of ``Function``.
+
+Setting ``gc "name"`` on a function triggers a search for a matching subclass
+of GCStrategy.  Some collector strategies are built in.  You can add others 
+using either the loadable plugin mechanism, or by patching your copy of LLVM.
+It is the selected GC strategy which defines the exact nature of the code 
+generated to support GC.  If none is found, the compiler will raise an error.
+
+Specifying the GC style on a per-function basis allows LLVM to link together
+programs that use different garbage collection algorithms (or none at all).
+
+.. _gcroot:
+
+Identifying GC roots on the stack
+----------------------------------
+
+LLVM currently supports two different mechanisms for describing references in
+compiled code at safepoints.  ``llvm.gcroot`` is the older mechanism; 
+``gc.statepoint`` has been added more recently.  At the moment, you can choose 
+either implementation (on a per :ref:`GC strategy <plugin>` basis).  Longer 
+term, we will probably either migrate away from ``llvm.gcroot`` entirely, or 
+substantially merge their implementations. Note that most new development 
+work is focused on ``gc.statepoint``.  
+
+Using ``gc.statepoint``
+^^^^^^^^^^^^^^^^^^^^^^^^
+:doc:`This page <Statepoints>` contains detailed documentation for 
+``gc.statepoint``. 
+
+Using ``llvm.gcwrite``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: llvm
+
+  void @llvm.gcroot(i8** %ptrloc, i8* %metadata)
+
+The ``llvm.gcroot`` intrinsic is used to inform LLVM that a stack variable
+references an object on the heap and is to be tracked for garbage collection.
+The exact impact on generated code is specified by the Function's selected 
+:ref:`GC strategy <plugin>`.  All calls to ``llvm.gcroot`` **must** reside 
+inside the first basic block.
+
+The first argument **must** be a value referring to an alloca instruction or a
+bitcast of an alloca.  The second contains a pointer to metadata that should be
+associated with the pointer, and **must** be a constant or global value
+address.  If your target collector uses tags, use a null pointer for metadata.
+
+A compiler which performs manual SSA construction **must** ensure that SSA 
+values representing GC references are stored in to the alloca passed to the
+respective ``gcroot`` before every call site and reloaded after every call.  
+A compiler which uses mem2reg to raise imperative code using ``alloca`` into 
+SSA form need only add a call to ``@llvm.gcroot`` for those variables which 
+are pointers into the GC heap.  
+
+It is also important to mark intermediate values with ``llvm.gcroot``.  For
+example, consider ``h(f(), g())``.  Beware leaking the result of ``f()`` in the
+case that ``g()`` triggers a collection.  Note, that stack variables must be
+initialized and marked with ``llvm.gcroot`` in function's prologue.
+
+The ``%metadata`` argument can be used to avoid requiring heap objects to have
+'isa' pointers or tag bits. [Appel89_, Goldberg91_, Tolmach94_] If specified,
+its value will be tracked along with the location of the pointer in the stack
+frame.
+
+Consider the following fragment of Java code:
+
+.. code-block:: java
+
+   {
+     Object X;   // A null-initialized reference to an object
+     ...
+   }
+
+This block (which may be located in the middle of a function or in a loop nest),
+could be compiled to this LLVM code:
+
+.. code-block:: llvm
+
+  Entry:
+     ;; In the entry block for the function, allocate the
+     ;; stack space for X, which is an LLVM pointer.
+     %X = alloca %Object*
+
+     ;; Tell LLVM that the stack space is a stack root.
+     ;; Java has type-tags on objects, so we pass null as metadata.
+     %tmp = bitcast %Object** %X to i8**
+     call void @llvm.gcroot(i8** %tmp, i8* null)
+     ...
+
+     ;; "CodeBlock" is the block corresponding to the start
+     ;;  of the scope above.
+  CodeBlock:
+     ;; Java null-initializes pointers.
+     store %Object* null, %Object** %X
+
+     ...
+
+     ;; As the pointer goes out of scope, store a null value into
+     ;; it, to indicate that the value is no longer live.
+     store %Object* null, %Object** %X
+     ...
+
+Reading and writing references in the heap
+------------------------------------------
+
+Some collectors need to be informed when the mutator (the program that needs
+garbage collection) either reads a pointer from or writes a pointer to a field
+of a heap object.  The code fragments inserted at these points are called *read
+barriers* and *write barriers*, respectively.  The amount of code that needs to
+be executed is usually quite small and not on the critical path of any
+computation, so the overall performance impact of the barrier is tolerable.
+
+Barriers often require access to the *object pointer* rather than the *derived
+pointer* (which is a pointer to the field within the object).  Accordingly,
+these intrinsics take both pointers as separate arguments for completeness.  In
+this snippet, ``%object`` is the object pointer, and ``%derived`` is the derived
+pointer:
+
+.. code-block:: llvm
+
+  ;; An array type.
+  %class.Array = type { %class.Object, i32, [0 x %class.Object*] }
+  ...
+
+  ;; Load the object pointer from a gcroot.
+  %object = load %class.Array** %object_addr
+
+  ;; Compute the derived pointer.
+  %derived = getelementptr %object, i32 0, i32 2, i32 %n
+
+LLVM does not enforce this relationship between the object and derived pointer
+(although a particular :ref:`collector strategy <plugin>` might).  However, it
+would be an unusual collector that violated it.
+
+The use of these intrinsics is naturally optional if the target GC does not 
+require the corresponding barrier.  The GC strategy used with such a collector 
+should replace the intrinsic calls with the corresponding ``load`` or 
+``store`` instruction if they are used.
+
+One known deficiency with the current design is that the barrier intrinsics do 
+not include the size or alignment of the underlying operation performed.  It is 
+currently assumed that the operation is of pointer size and the alignment is
+assumed to be the target machine's default alignment.
+
+Write barrier: ``llvm.gcwrite``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: llvm
+
+  void @llvm.gcwrite(i8* %value, i8* %object, i8** %derived)
+
+For write barriers, LLVM provides the ``llvm.gcwrite`` intrinsic function.  It
+has exactly the same semantics as a non-volatile ``store`` to the derived
+pointer (the third argument).  The exact code generated is specified by the
+Function's selected :ref:`GC strategy <plugin>`.
+
+Many important algorithms require write barriers, including generational and
+concurrent collectors.  Additionally, write barriers could be used to implement
+reference counting.
+
+Read barrier: ``llvm.gcread``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: llvm
+
+  i8* @llvm.gcread(i8* %object, i8** %derived)
+
+For read barriers, LLVM provides the ``llvm.gcread`` intrinsic function.  It has
+exactly the same semantics as a non-volatile ``load`` from the derived pointer
+(the second argument).  The exact code generated is specified by the Function's
+selected :ref:`GC strategy <plugin>`.
+
+Read barriers are needed by fewer algorithms than write barriers, and may have a
+greater performance impact since pointer reads are more frequent than writes.
+
+.. _plugin:
+
+.. _builtin-gc-strategies:
+
+Built In GC Strategies
+======================
+
+LLVM includes built in support for several varieties of garbage collectors.  
+
+The Shadow Stack GC
+----------------------
+
+To use this collector strategy, mark your functions with:
+
+.. code-block:: c++
+
+  F.setGC("shadow-stack");
+
+Unlike many GC algorithms which rely on a cooperative code generator to compile
+stack maps, this algorithm carefully maintains a linked list of stack roots
+[:ref:`Henderson2002 <henderson02>`].  This so-called "shadow stack" mirrors the
+machine stack.  Maintaining this data structure is slower than using a stack map
+compiled into the executable as constant data, but has a significant portability
+advantage because it requires no special support from the target code generator,
+and does not require tricky platform-specific code to crawl the machine stack.
+
+The tradeoff for this simplicity and portability is:
+
+* High overhead per function call.
+
+* Not thread-safe.
+
+Still, it's an easy way to get started.  After your compiler and runtime are up
+and running, writing a :ref:`plugin <plugin>` will allow you to take advantage
+of :ref:`more advanced GC features <collector-algos>` of LLVM in order to
+improve performance.
+
+
+The shadow stack doesn't imply a memory allocation algorithm.  A semispace
+collector or building atop ``malloc`` are great places to start, and can be
+implemented with very little code.
+
+When it comes time to collect, however, your runtime needs to traverse the stack
+roots, and for this it needs to integrate with the shadow stack.  Luckily, doing
+so is very simple. (This code is heavily commented to help you understand the
+data structure, but there are only 20 lines of meaningful code.)
+
+.. code-block:: c++
+
+  /// The map for a single function's stack frame.  One of these is
+  ///        compiled as constant data into the executable for each function.
+  ///
+  /// Storage of metadata values is elided if the %metadata parameter to
+  /// @llvm.gcroot is null.
+  struct FrameMap {
+    int32_t NumRoots;    //< Number of roots in stack frame.
+    int32_t NumMeta;     //< Number of metadata entries.  May be < NumRoots.
+    const void *Meta[0]; //< Metadata for each root.
+  };
+
+  /// A link in the dynamic shadow stack.  One of these is embedded in
+  ///        the stack frame of each function on the call stack.
+  struct StackEntry {
+    StackEntry *Next;    //< Link to next stack entry (the caller's).
+    const FrameMap *Map; //< Pointer to constant FrameMap.
+    void *Roots[0];      //< Stack roots (in-place array).
+  };
+
+  /// The head of the singly-linked list of StackEntries.  Functions push
+  ///        and pop onto this in their prologue and epilogue.
+  ///
+  /// Since there is only a global list, this technique is not threadsafe.
+  StackEntry *llvm_gc_root_chain;
+
+  /// Calls Visitor(root, meta) for each GC root on the stack.
+  ///        root and meta are exactly the values passed to
+  ///        @llvm.gcroot.
+  ///
+  /// Visitor could be a function to recursively mark live objects.  Or it
+  /// might copy them to another heap or generation.
+  ///
+  /// @param Visitor A function to invoke for every GC root on the stack.
+  void visitGCRoots(void (*Visitor)(void **Root, const void *Meta)) {
+    for (StackEntry *R = llvm_gc_root_chain; R; R = R->Next) {
+      unsigned i = 0;
+
+      // For roots [0, NumMeta), the metadata pointer is in the FrameMap.
+      for (unsigned e = R->Map->NumMeta; i != e; ++i)
+        Visitor(&R->Roots[i], R->Map->Meta[i]);
+
+      // For roots [NumMeta, NumRoots), the metadata pointer is null.
+      for (unsigned e = R->Map->NumRoots; i != e; ++i)
+        Visitor(&R->Roots[i], NULL);
+    }
+  }
+
+
+The 'Erlang' and 'Ocaml' GCs
+-----------------------------
+
+LLVM ships with two example collectors which leverage the ``gcroot`` 
+mechanisms.  To our knowledge, these are not actually used by any language 
+runtime, but they do provide a reasonable starting point for someone interested 
+in writing an ``gcroot`` compatible GC plugin.  In particular, these are the 
+only in tree examples of how to produce a custom binary stack map format using 
+a ``gcroot`` strategy.
+
+As there names imply, the binary format produced is intended to model that 
+used by the Erlang and OCaml compilers respectively.  
+
+.. _statepoint_example_gc:
+
+The Statepoint Example GC
+-------------------------
+
+.. code-block:: c++
+
+  F.setGC("statepoint-example");
+
+This GC provides an example of how one might use the infrastructure provided 
+by ``gc.statepoint``. This example GC is compatible with the 
+:ref:`PlaceSafepoints` and :ref:`RewriteStatepointsForGC` utility passes 
+which simplify ``gc.statepoint`` sequence insertion. If you need to build a 
+custom GC strategy around the ``gc.statepoints`` mechanisms, it is recommended
+that you use this one as a starting point.
+
+This GC strategy does not support read or write barriers.  As a result, these 
+intrinsics are lowered to normal loads and stores.
+
+The stack map format generated by this GC strategy can be found in the 
+:ref:`stackmap-section` using a format documented :ref:`here 
+<statepoint-stackmap-format>`. This format is intended to be the standard 
+format supported by LLVM going forward.
+
+The CoreCLR GC
+-------------------------
+
+.. code-block:: c++
+
+  F.setGC("coreclr");
+
+This GC leverages the ``gc.statepoint`` mechanism to support the 
+`CoreCLR <https://github.com/dotnet/coreclr>`__ runtime.
+
+Support for this GC strategy is a work in progress. This strategy will 
+differ from 
+:ref:`statepoint-example GC<statepoint_example_gc>` strategy in 
+certain aspects like:
+
+* Base-pointers of interior pointers are not explicitly 
+  tracked and reported.
+
+* A different format is used for encoding stack maps.
+
+* Safe-point polls are only needed before loop-back edges
+  and before tail-calls (not needed at function-entry).
+
+Custom GC Strategies
+====================
+
+If none of the built in GC strategy descriptions met your needs above, you will
+need to define a custom GCStrategy and possibly, a custom LLVM pass to perform 
+lowering.  Your best example of where to start defining a custom GCStrategy 
+would be to look at one of the built in strategies.
+
+You may be able to structure this additional code as a loadable plugin library.
+Loadable plugins are sufficient if all you need is to enable a different 
+combination of built in functionality, but if you need to provide a custom 
+lowering pass, you will need to build a patched version of LLVM.  If you think 
+you need a patched build, please ask for advice on llvm-dev.  There may be an 
+easy way we can extend the support to make it work for your use case without 
+requiring a custom build.  
+
+Collector Requirements
+----------------------
+
+You should be able to leverage any existing collector library that includes the following elements:
+
+#. A memory allocator which exposes an allocation function your compiled 
+   code can call.
+
+#. A binary format for the stack map.  A stack map describes the location
+   of references at a safepoint and is used by precise collectors to identify
+   references within a stack frame on the machine stack. Note that collectors
+   which conservatively scan the stack don't require such a structure.
+
+#. A stack crawler to discover functions on the call stack, and enumerate the
+   references listed in the stack map for each call site.  
+
+#. A mechanism for identifying references in global locations (e.g. global 
+   variables).
+
+#. If you collector requires them, an LLVM IR implementation of your collectors
+   load and store barriers.  Note that since many collectors don't require 
+   barriers at all, LLVM defaults to lowering such barriers to normal loads 
+   and stores unless you arrange otherwise.
+
+
+Implementing a collector plugin
+-------------------------------
+
+User code specifies which GC code generation to use with the ``gc`` function
+attribute or, equivalently, with the ``setGC`` method of ``Function``.
+
+To implement a GC plugin, it is necessary to subclass ``llvm::GCStrategy``,
+which can be accomplished in a few lines of boilerplate code.  LLVM's
+infrastructure provides access to several important algorithms.  For an
+uncontroversial collector, all that remains may be to compile LLVM's computed
+stack map to assembly code (using the binary representation expected by the
+runtime library).  This can be accomplished in about 100 lines of code.
+
+This is not the appropriate place to implement a garbage collected heap or a
+garbage collector itself.  That code should exist in the language's runtime
+library.  The compiler plugin is responsible for generating code which conforms
+to the binary interface defined by library, most essentially the :ref:`stack map
+<stack-map>`.
+
+To subclass ``llvm::GCStrategy`` and register it with the compiler:
+
+.. code-block:: c++
+
+  // lib/MyGC/MyGC.cpp - Example LLVM GC plugin
+
+  #include "llvm/CodeGen/GCStrategy.h"
+  #include "llvm/CodeGen/GCMetadata.h"
+  #include "llvm/Support/Compiler.h"
+
+  using namespace llvm;
+
+  namespace {
+    class LLVM_LIBRARY_VISIBILITY MyGC : public GCStrategy {
+    public:
+      MyGC() {}
+    };
+
+    GCRegistry::Add<MyGC>
+    X("mygc", "My bespoke garbage collector.");
+  }
+
+This boilerplate collector does nothing.  More specifically:
+
+* ``llvm.gcread`` calls are replaced with the corresponding ``load``
+  instruction.
+
+* ``llvm.gcwrite`` calls are replaced with the corresponding ``store``
+  instruction.
+
+* No safe points are added to the code.
+
+* The stack map is not compiled into the executable.
+
+Using the LLVM makefiles, this code
+can be compiled as a plugin using a simple makefile:
+
+.. code-block:: make
+
+  # lib/MyGC/Makefile
+
+  LEVEL := ../..
+  LIBRARYNAME = MyGC
+  LOADABLE_MODULE = 1
+
+  include $(LEVEL)/Makefile.common
+
+Once the plugin is compiled, code using it may be compiled using ``llc
+-load=MyGC.so`` (though MyGC.so may have some other platform-specific
+extension):
+
+::
+
+  $ cat sample.ll
+  define void @f() gc "mygc" {
+  entry:
+    ret void
+  }
+  $ llvm-as < sample.ll | llc -load=MyGC.so
+
+It is also possible to statically link the collector plugin into tools, such as
+a language-specific compiler front-end.
+
+.. _collector-algos:
+
+Overview of available features
+------------------------------
+
+``GCStrategy`` provides a range of features through which a plugin may do useful
+work.  Some of these are callbacks, some are algorithms that can be enabled,
+disabled, or customized.  This matrix summarizes the supported (and planned)
+features and correlates them with the collection techniques which typically
+require them.
+
+.. |v| unicode:: 0x2714
+   :trim:
+
+.. |x| unicode:: 0x2718
+   :trim:
+
++------------+------+--------+----------+-------+---------+-------------+----------+------------+
+| Algorithm  | Done | Shadow | refcount | mark- | copying | incremental | threaded | concurrent |
+|            |      | stack  |          | sweep |         |             |          |            |
++============+======+========+==========+=======+=========+=============+==========+============+
+| stack map  | |v|  |        |          | |x|   | |x|     | |x|         | |x|      | |x|        |
++------------+------+--------+----------+-------+---------+-------------+----------+------------+
+| initialize | |v|  | |x|    | |x|      | |x|   | |x|     | |x|         | |x|      | |x|        |
+| roots      |      |        |          |       |         |             |          |            |
++------------+------+--------+----------+-------+---------+-------------+----------+------------+
+| derived    | NO   |        |          |       |         |             | **N**\*  | **N**\*    |
+| pointers   |      |        |          |       |         |             |          |            |
++------------+------+--------+----------+-------+---------+-------------+----------+------------+
+| **custom   | |v|  |        |          |       |         |             |          |            |
+| lowering** |      |        |          |       |         |             |          |            |
++------------+------+--------+----------+-------+---------+-------------+----------+------------+
+| *gcroot*   | |v|  | |x|    | |x|      |       |         |             |          |            |
++------------+------+--------+----------+-------+---------+-------------+----------+------------+
+| *gcwrite*  | |v|  |        | |x|      |       |         | |x|         |          | |x|        |
++------------+------+--------+----------+-------+---------+-------------+----------+------------+
+| *gcread*   | |v|  |        |          |       |         |             |          | |x|        |
++------------+------+--------+----------+-------+---------+-------------+----------+------------+
+| **safe     |      |        |          |       |         |             |          |            |
+| points**   |      |        |          |       |         |             |          |            |
++------------+------+--------+----------+-------+---------+-------------+----------+------------+
+| *in        | |v|  |        |          | |x|   | |x|     | |x|         | |x|      | |x|        |
+| calls*     |      |        |          |       |         |             |          |            |
++------------+------+--------+----------+-------+---------+-------------+----------+------------+
+| *before    | |v|  |        |          |       |         |             | |x|      | |x|        |
+| calls*     |      |        |          |       |         |             |          |            |
++------------+------+--------+----------+-------+---------+-------------+----------+------------+
+| *for       | NO   |        |          |       |         |             | **N**    | **N**      |
+| loops*     |      |        |          |       |         |             |          |            |
++------------+------+--------+----------+-------+---------+-------------+----------+------------+
+| *before    | |v|  |        |          |       |         |             | |x|      | |x|        |
+| escape*    |      |        |          |       |         |             |          |            |
++------------+------+--------+----------+-------+---------+-------------+----------+------------+
+| emit code  | NO   |        |          |       |         |             | **N**    | **N**      |
+| at safe    |      |        |          |       |         |             |          |            |
+| points     |      |        |          |       |         |             |          |            |
++------------+------+--------+----------+-------+---------+-------------+----------+------------+
+| **output** |      |        |          |       |         |             |          |            |
++------------+------+--------+----------+-------+---------+-------------+----------+------------+
+| *assembly* | |v|  |        |          | |x|   | |x|     | |x|         | |x|      | |x|        |
++------------+------+--------+----------+-------+---------+-------------+----------+------------+
+| *JIT*      | NO   |        |          | **?** | **?**   | **?**       | **?**    | **?**      |
++------------+------+--------+----------+-------+---------+-------------+----------+------------+
+| *obj*      | NO   |        |          | **?** | **?**   | **?**       | **?**    | **?**      |
++------------+------+--------+----------+-------+---------+-------------+----------+------------+
+| live       | NO   |        |          | **?** | **?**   | **?**       | **?**    | **?**      |
+| analysis   |      |        |          |       |         |             |          |            |
++------------+------+--------+----------+-------+---------+-------------+----------+------------+
+| register   | NO   |        |          | **?** | **?**   | **?**       | **?**    | **?**      |
+| map        |      |        |          |       |         |             |          |            |
++------------+------+--------+----------+-------+---------+-------------+----------+------------+
+| \* Derived pointers only pose a hasard to copying collections.                                |
++------------+------+--------+----------+-------+---------+-------------+----------+------------+
+| **?** denotes a feature which could be utilized if available.                                 |
++------------+------+--------+----------+-------+---------+-------------+----------+------------+
+
+To be clear, the collection techniques above are defined as:
+
+Shadow Stack
+  The mutator carefully maintains a linked list of stack roots.
+
+Reference Counting
+  The mutator maintains a reference count for each object and frees an object
+  when its count falls to zero.
+
+Mark-Sweep
+  When the heap is exhausted, the collector marks reachable objects starting
+  from the roots, then deallocates unreachable objects in a sweep phase.
+
+Copying
+  As reachability analysis proceeds, the collector copies objects from one heap
+  area to another, compacting them in the process.  Copying collectors enable
+  highly efficient "bump pointer" allocation and can improve locality of
+  reference.
+
+Incremental
+  (Including generational collectors.) Incremental collectors generally have all
+  the properties of a copying collector (regardless of whether the mature heap
+  is compacting), but bring the added complexity of requiring write barriers.
+
+Threaded
+  Denotes a multithreaded mutator; the collector must still stop the mutator
+  ("stop the world") before beginning reachability analysis.  Stopping a
+  multithreaded mutator is a complicated problem.  It generally requires highly
+  platform-specific code in the runtime, and the production of carefully
+  designed machine code at safe points.
+
+Concurrent
+  In this technique, the mutator and the collector run concurrently, with the
+  goal of eliminating pause times.  In a *cooperative* collector, the mutator
+  further aids with collection should a pause occur, allowing collection to take
+  advantage of multiprocessor hosts.  The "stop the world" problem of threaded
+  collectors is generally still present to a limited extent.  Sophisticated
+  marking algorithms are necessary.  Read barriers may be necessary.
+
+As the matrix indicates, LLVM's garbage collection infrastructure is already
+suitable for a wide variety of collectors, but does not currently extend to
+multithreaded programs.  This will be added in the future as there is
+interest.
+
+.. _stack-map:
+
+Computing stack maps
+--------------------
+
+LLVM automatically computes a stack map.  One of the most important features
+of a ``GCStrategy`` is to compile this information into the executable in
+the binary representation expected by the runtime library.
+
+The stack map consists of the location and identity of each GC root in the
+each function in the module.  For each root:
+
+* ``RootNum``: The index of the root.
+
+* ``StackOffset``: The offset of the object relative to the frame pointer.
+
+* ``RootMetadata``: The value passed as the ``%metadata`` parameter to the
+  ``@llvm.gcroot`` intrinsic.
+
+Also, for the function as a whole:
+
+* ``getFrameSize()``: The overall size of the function's initial stack frame,
+   not accounting for any dynamic allocation.
+
+* ``roots_size()``: The count of roots in the function.
+
+To access the stack map, use ``GCFunctionMetadata::roots_begin()`` and
+-``end()`` from the :ref:`GCMetadataPrinter <assembly>`:
+
+.. code-block:: c++
+
+  for (iterator I = begin(), E = end(); I != E; ++I) {
+    GCFunctionInfo *FI = *I;
+    unsigned FrameSize = FI->getFrameSize();
+    size_t RootCount = FI->roots_size();
+
+    for (GCFunctionInfo::roots_iterator RI = FI->roots_begin(),
+                                        RE = FI->roots_end();
+                                        RI != RE; ++RI) {
+      int RootNum = RI->Num;
+      int RootStackOffset = RI->StackOffset;
+      Constant *RootMetadata = RI->Metadata;
+    }
+  }
+
+If the ``llvm.gcroot`` intrinsic is eliminated before code generation by a
+custom lowering pass, LLVM will compute an empty stack map.  This may be useful
+for collector plugins which implement reference counting or a shadow stack.
+
+.. _init-roots:
+
+Initializing roots to null
+---------------------------
+
+It is recommended that frontends initialize roots explicitly to avoid
+potentially confusing the optimizer.  This prevents the GC from visiting
+uninitialized pointers, which will almost certainly cause it to crash.
+
+As a fallback, LLVM will automatically initialize each root to ``null``
+upon entry to the function.  Support for this mode in code generation is
+largely a legacy detail to keep old collector implementations working.
+
+Custom lowering of intrinsics
+------------------------------
+
+For GCs which use barriers or unusual treatment of stack roots, the
+implementor is responsibly for providing a custom pass to lower the
+intrinsics with the desired semantics.  If you have opted in to custom
+lowering of a particular intrinsic your pass **must** eliminate all 
+instances of the corresponding intrinsic in functions which opt in to
+your GC.  The best example of such a pass is the ShadowStackGC and it's 
+ShadowStackGCLowering pass.  
+
+There is currently no way to register such a custom lowering pass 
+without building a custom copy of LLVM.
+
+.. _safe-points:
+
+Generating safe points
+-----------------------
+
+LLVM provides support for associating stackmaps with the return address of
+a call.  Any loop or return safepoints required by a given collector design
+can be modeled via calls to runtime routines, or potentially patchable call
+sequences.  Using gcroot, all call instructions are inferred to be possible
+safepoints and will thus have an associated stackmap.
+
+.. _assembly:
+
+Emitting assembly code: ``GCMetadataPrinter``
+---------------------------------------------
+
+LLVM allows a plugin to print arbitrary assembly code before and after the rest
+of a module's assembly code.  At the end of the module, the GC can compile the
+LLVM stack map into assembly code. (At the beginning, this information is not
+yet computed.)
+
+Since AsmWriter and CodeGen are separate components of LLVM, a separate abstract
+base class and registry is provided for printing assembly code, the
+``GCMetadaPrinter`` and ``GCMetadataPrinterRegistry``.  The AsmWriter will look
+for such a subclass if the ``GCStrategy`` sets ``UsesMetadata``:
+
+.. code-block:: c++
+
+  MyGC::MyGC() {
+    UsesMetadata = true;
+  }
+
+This separation allows JIT-only clients to be smaller.
+
+Note that LLVM does not currently have analogous APIs to support code generation
+in the JIT, nor using the object writers.
+
+.. code-block:: c++
+
+  // lib/MyGC/MyGCPrinter.cpp - Example LLVM GC printer
+
+  #include "llvm/CodeGen/GCMetadataPrinter.h"
+  #include "llvm/Support/Compiler.h"
+
+  using namespace llvm;
+
+  namespace {
+    class LLVM_LIBRARY_VISIBILITY MyGCPrinter : public GCMetadataPrinter {
+    public:
+      virtual void beginAssembly(AsmPrinter &AP);
+
+      virtual void finishAssembly(AsmPrinter &AP);
+    };
+
+    GCMetadataPrinterRegistry::Add<MyGCPrinter>
+    X("mygc", "My bespoke garbage collector.");
+  }
+
+The collector should use ``AsmPrinter`` to print portable assembly code.  The
+collector itself contains the stack map for the entire module, and may access
+the ``GCFunctionInfo`` using its own ``begin()`` and ``end()`` methods.  Here's
+a realistic example:
+
+.. code-block:: c++
+
+  #include "llvm/CodeGen/AsmPrinter.h"
+  #include "llvm/IR/Function.h"
+  #include "llvm/IR/DataLayout.h"
+  #include "llvm/Target/TargetAsmInfo.h"
+  #include "llvm/Target/TargetMachine.h"
+
+  void MyGCPrinter::beginAssembly(AsmPrinter &AP) {
+    // Nothing to do.
+  }
+
+  void MyGCPrinter::finishAssembly(AsmPrinter &AP) {
+    MCStreamer &OS = AP.OutStreamer;
+    unsigned IntPtrSize = AP.getPointerSize();
+
+    // Put this in the data section.
+    OS.SwitchSection(AP.getObjFileLowering().getDataSection());
+
+    // For each function...
+    for (iterator FI = begin(), FE = end(); FI != FE; ++FI) {
+      GCFunctionInfo &MD = **FI;
+
+      // A compact GC layout. Emit this data structure:
+      //
+      // struct {
+      //   int32_t PointCount;
+      //   void *SafePointAddress[PointCount];
+      //   int32_t StackFrameSize; // in words
+      //   int32_t StackArity;
+      //   int32_t LiveCount;
+      //   int32_t LiveOffsets[LiveCount];
+      // } __gcmap_<FUNCTIONNAME>;
+
+      // Align to address width.
+      AP.EmitAlignment(IntPtrSize == 4 ? 2 : 3);
+
+      // Emit PointCount.
+      OS.AddComment("safe point count");
+      AP.emitInt32(MD.size());
+
+      // And each safe point...
+      for (GCFunctionInfo::iterator PI = MD.begin(),
+                                    PE = MD.end(); PI != PE; ++PI) {
+        // Emit the address of the safe point.
+        OS.AddComment("safe point address");
+        MCSymbol *Label = PI->Label;
+        AP.EmitLabelPlusOffset(Label/*Hi*/, 0/*Offset*/, 4/*Size*/);
+      }
+
+      // Stack information never change in safe points! Only print info from the
+      // first call-site.
+      GCFunctionInfo::iterator PI = MD.begin();
+
+      // Emit the stack frame size.
+      OS.AddComment("stack frame size (in words)");
+      AP.emitInt32(MD.getFrameSize() / IntPtrSize);
+
+      // Emit stack arity, i.e. the number of stacked arguments.
+      unsigned RegisteredArgs = IntPtrSize == 4 ? 5 : 6;
+      unsigned StackArity = MD.getFunction().arg_size() > RegisteredArgs ?
+                            MD.getFunction().arg_size() - RegisteredArgs : 0;
+      OS.AddComment("stack arity");
+      AP.emitInt32(StackArity);
+
+      // Emit the number of live roots in the function.
+      OS.AddComment("live root count");
+      AP.emitInt32(MD.live_size(PI));
+
+      // And for each live root...
+      for (GCFunctionInfo::live_iterator LI = MD.live_begin(PI),
+                                         LE = MD.live_end(PI);
+                                         LI != LE; ++LI) {
+        // Emit live root's offset within the stack frame.
+        OS.AddComment("stack index (offset / wordsize)");
+        AP.emitInt32(LI->StackOffset);
+      }
+    }
+  }
+
+References
+==========
+
+.. _appel89:
+
+[Appel89] Runtime Tags Aren't Necessary. Andrew W. Appel. Lisp and Symbolic
+Computation 19(7):703-705, July 1989.
+
+.. _goldberg91:
+
+[Goldberg91] Tag-free garbage collection for strongly typed programming
+languages. Benjamin Goldberg. ACM SIGPLAN PLDI'91.
+
+.. _tolmach94:
+
+[Tolmach94] Tag-free garbage collection using explicit type parameters. Andrew
+Tolmach. Proceedings of the 1994 ACM conference on LISP and functional
+programming.
+
+.. _henderson02:
+
+[Henderson2002] `Accurate Garbage Collection in an Uncooperative Environment
+<http://citeseer.ist.psu.edu/henderson02accurate.html>`__

Added: www-releases/trunk/8.0.1/docs/_sources/GetElementPtr.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.1/docs/_sources/GetElementPtr.rst.txt?rev=368037&view=auto
==============================================================================
--- www-releases/trunk/8.0.1/docs/_sources/GetElementPtr.rst.txt (added)
+++ www-releases/trunk/8.0.1/docs/_sources/GetElementPtr.rst.txt Tue Aug  6 06:51:02 2019
@@ -0,0 +1,538 @@
+=======================================
+The Often Misunderstood GEP Instruction
+=======================================
+
+.. contents::
+   :local:
+
+Introduction
+============
+
+This document seeks to dispel the mystery and confusion surrounding LLVM's
+`GetElementPtr <LangRef.html#getelementptr-instruction>`_ (GEP) instruction.
+Questions about the wily GEP instruction are probably the most frequently
+occurring questions once a developer gets down to coding with LLVM. Here we lay
+out the sources of confusion and show that the GEP instruction is really quite
+simple.
+
+Address Computation
+===================
+
+When people are first confronted with the GEP instruction, they tend to relate
+it to known concepts from other programming paradigms, most notably C array
+indexing and field selection. GEP closely resembles C array indexing and field
+selection, however it is a little different and this leads to the following
+questions.
+
+What is the first index of the GEP instruction?
+-----------------------------------------------
+
+Quick answer: The index stepping through the second operand.
+
+The confusion with the first index usually arises from thinking about the
+GetElementPtr instruction as if it was a C index operator. They aren't the
+same. For example, when we write, in "C":
+
+.. code-block:: c++
+
+  AType *Foo;
+  ...
+  X = &Foo->F;
+
+it is natural to think that there is only one index, the selection of the field
+``F``.  However, in this example, ``Foo`` is a pointer. That pointer
+must be indexed explicitly in LLVM. C, on the other hand, indices through it
+transparently.  To arrive at the same address location as the C code, you would
+provide the GEP instruction with two index operands. The first operand indexes
+through the pointer; the second operand indexes the field ``F`` of the
+structure, just as if you wrote:
+
+.. code-block:: c++
+
+  X = &Foo[0].F;
+
+Sometimes this question gets rephrased as:
+
+.. _GEP index through first pointer:
+
+  *Why is it okay to index through the first pointer, but subsequent pointers
+  won't be dereferenced?*
+
+The answer is simply because memory does not have to be accessed to perform the
+computation. The second operand to the GEP instruction must be a value of a
+pointer type. The value of the pointer is provided directly to the GEP
+instruction as an operand without any need for accessing memory. It must,
+therefore be indexed and requires an index operand. Consider this example:
+
+.. code-block:: c++
+
+  struct munger_struct {
+    int f1;
+    int f2;
+  };
+  void munge(struct munger_struct *P) {
+    P[0].f1 = P[1].f1 + P[2].f2;
+  }
+  ...
+  munger_struct Array[3];
+  ...
+  munge(Array);
+
+In this "C" example, the front end compiler (Clang) will generate three GEP
+instructions for the three indices through "P" in the assignment statement.  The
+function argument ``P`` will be the second operand of each of these GEP
+instructions.  The third operand indexes through that pointer.  The fourth
+operand will be the field offset into the ``struct munger_struct`` type, for
+either the ``f1`` or ``f2`` field. So, in LLVM assembly the ``munge`` function
+looks like:
+
+.. code-block:: llvm
+
+  void %munge(%struct.munger_struct* %P) {
+  entry:
+    %tmp = getelementptr %struct.munger_struct, %struct.munger_struct* %P, i32 1, i32 0
+    %tmp = load i32* %tmp
+    %tmp6 = getelementptr %struct.munger_struct, %struct.munger_struct* %P, i32 2, i32 1
+    %tmp7 = load i32* %tmp6
+    %tmp8 = add i32 %tmp7, %tmp
+    %tmp9 = getelementptr %struct.munger_struct, %struct.munger_struct* %P, i32 0, i32 0
+    store i32 %tmp8, i32* %tmp9
+    ret void
+  }
+
+In each case the second operand is the pointer through which the GEP instruction
+starts. The same is true whether the second operand is an argument, allocated
+memory, or a global variable.
+
+To make this clear, let's consider a more obtuse example:
+
+.. code-block:: text
+
+  %MyVar = uninitialized global i32
+  ...
+  %idx1 = getelementptr i32, i32* %MyVar, i64 0
+  %idx2 = getelementptr i32, i32* %MyVar, i64 1
+  %idx3 = getelementptr i32, i32* %MyVar, i64 2
+
+These GEP instructions are simply making address computations from the base
+address of ``MyVar``.  They compute, as follows (using C syntax):
+
+.. code-block:: c++
+
+  idx1 = (char*) &MyVar + 0
+  idx2 = (char*) &MyVar + 4
+  idx3 = (char*) &MyVar + 8
+
+Since the type ``i32`` is known to be four bytes long, the indices 0, 1 and 2
+translate into memory offsets of 0, 4, and 8, respectively. No memory is
+accessed to make these computations because the address of ``%MyVar`` is passed
+directly to the GEP instructions.
+
+The obtuse part of this example is in the cases of ``%idx2`` and ``%idx3``. They
+result in the computation of addresses that point to memory past the end of the
+``%MyVar`` global, which is only one ``i32`` long, not three ``i32``\s long.
+While this is legal in LLVM, it is inadvisable because any load or store with
+the pointer that results from these GEP instructions would produce undefined
+results.
+
+Why is the extra 0 index required?
+----------------------------------
+
+Quick answer: there are no superfluous indices.
+
+This question arises most often when the GEP instruction is applied to a global
+variable which is always a pointer type. For example, consider this:
+
+.. code-block:: text
+
+  %MyStruct = uninitialized global { float*, i32 }
+  ...
+  %idx = getelementptr { float*, i32 }, { float*, i32 }* %MyStruct, i64 0, i32 1
+
+The GEP above yields an ``i32*`` by indexing the ``i32`` typed field of the
+structure ``%MyStruct``. When people first look at it, they wonder why the ``i64
+0`` index is needed. However, a closer inspection of how globals and GEPs work
+reveals the need. Becoming aware of the following facts will dispel the
+confusion:
+
+#. The type of ``%MyStruct`` is *not* ``{ float*, i32 }`` but rather ``{ float*,
+   i32 }*``. That is, ``%MyStruct`` is a pointer to a structure containing a
+   pointer to a ``float`` and an ``i32``.
+
+#. Point #1 is evidenced by noticing the type of the second operand of the GEP
+   instruction (``%MyStruct``) which is ``{ float*, i32 }*``.
+
+#. The first index, ``i64 0`` is required to step over the global variable
+   ``%MyStruct``.  Since the second argument to the GEP instruction must always
+   be a value of pointer type, the first index steps through that pointer. A
+   value of 0 means 0 elements offset from that pointer.
+
+#. The second index, ``i32 1`` selects the second field of the structure (the
+   ``i32``).
+
+What is dereferenced by GEP?
+----------------------------
+
+Quick answer: nothing.
+
+The GetElementPtr instruction dereferences nothing. That is, it doesn't access
+memory in any way. That's what the Load and Store instructions are for.  GEP is
+only involved in the computation of addresses. For example, consider this:
+
+.. code-block:: text
+
+  %MyVar = uninitialized global { [40 x i32 ]* }
+  ...
+  %idx = getelementptr { [40 x i32]* }, { [40 x i32]* }* %MyVar, i64 0, i32 0, i64 0, i64 17
+
+In this example, we have a global variable, ``%MyVar`` that is a pointer to a
+structure containing a pointer to an array of 40 ints. The GEP instruction seems
+to be accessing the 18th integer of the structure's array of ints. However, this
+is actually an illegal GEP instruction. It won't compile. The reason is that the
+pointer in the structure *must* be dereferenced in order to index into the
+array of 40 ints. Since the GEP instruction never accesses memory, it is
+illegal.
+
+In order to access the 18th integer in the array, you would need to do the
+following:
+
+.. code-block:: text
+
+  %idx = getelementptr { [40 x i32]* }, { [40 x i32]* }* %, i64 0, i32 0
+  %arr = load [40 x i32]** %idx
+  %idx = getelementptr [40 x i32], [40 x i32]* %arr, i64 0, i64 17
+
+In this case, we have to load the pointer in the structure with a load
+instruction before we can index into the array. If the example was changed to:
+
+.. code-block:: text
+
+  %MyVar = uninitialized global { [40 x i32 ] }
+  ...
+  %idx = getelementptr { [40 x i32] }, { [40 x i32] }*, i64 0, i32 0, i64 17
+
+then everything works fine. In this case, the structure does not contain a
+pointer and the GEP instruction can index through the global variable, into the
+first field of the structure and access the 18th ``i32`` in the array there.
+
+Why don't GEP x,0,0,1 and GEP x,1 alias?
+----------------------------------------
+
+Quick Answer: They compute different address locations.
+
+If you look at the first indices in these GEP instructions you find that they
+are different (0 and 1), therefore the address computation diverges with that
+index. Consider this example:
+
+.. code-block:: llvm
+
+  %MyVar = global { [10 x i32] }
+  %idx1 = getelementptr { [10 x i32] }, { [10 x i32] }* %MyVar, i64 0, i32 0, i64 1
+  %idx2 = getelementptr { [10 x i32] }, { [10 x i32] }* %MyVar, i64 1
+
+In this example, ``idx1`` computes the address of the second integer in the
+array that is in the structure in ``%MyVar``, that is ``MyVar+4``. The type of
+``idx1`` is ``i32*``. However, ``idx2`` computes the address of *the next*
+structure after ``%MyVar``. The type of ``idx2`` is ``{ [10 x i32] }*`` and its
+value is equivalent to ``MyVar + 40`` because it indexes past the ten 4-byte
+integers in ``MyVar``. Obviously, in such a situation, the pointers don't
+alias.
+
+Why do GEP x,1,0,0 and GEP x,1 alias?
+-------------------------------------
+
+Quick Answer: They compute the same address location.
+
+These two GEP instructions will compute the same address because indexing
+through the 0th element does not change the address. However, it does change the
+type. Consider this example:
+
+.. code-block:: llvm
+
+  %MyVar = global { [10 x i32] }
+  %idx1 = getelementptr { [10 x i32] }, { [10 x i32] }* %MyVar, i64 1, i32 0, i64 0
+  %idx2 = getelementptr { [10 x i32] }, { [10 x i32] }* %MyVar, i64 1
+
+In this example, the value of ``%idx1`` is ``%MyVar+40`` and its type is
+``i32*``. The value of ``%idx2`` is also ``MyVar+40`` but its type is ``{ [10 x
+i32] }*``.
+
+Can GEP index into vector elements?
+-----------------------------------
+
+This hasn't always been forcefully disallowed, though it's not recommended.  It
+leads to awkward special cases in the optimizers, and fundamental inconsistency
+in the IR. In the future, it will probably be outright disallowed.
+
+What effect do address spaces have on GEPs?
+-------------------------------------------
+
+None, except that the address space qualifier on the second operand pointer type
+always matches the address space qualifier on the result type.
+
+How is GEP different from ``ptrtoint``, arithmetic, and ``inttoptr``?
+---------------------------------------------------------------------
+
+It's very similar; there are only subtle differences.
+
+With ptrtoint, you have to pick an integer type. One approach is to pick i64;
+this is safe on everything LLVM supports (LLVM internally assumes pointers are
+never wider than 64 bits in many places), and the optimizer will actually narrow
+the i64 arithmetic down to the actual pointer size on targets which don't
+support 64-bit arithmetic in most cases. However, there are some cases where it
+doesn't do this. With GEP you can avoid this problem.
+
+Also, GEP carries additional pointer aliasing rules. It's invalid to take a GEP
+from one object, address into a different separately allocated object, and
+dereference it. IR producers (front-ends) must follow this rule, and consumers
+(optimizers, specifically alias analysis) benefit from being able to rely on
+it. See the `Rules`_ section for more information.
+
+And, GEP is more concise in common cases.
+
+However, for the underlying integer computation implied, there is no
+difference.
+
+
+I'm writing a backend for a target which needs custom lowering for GEP. How do I do this?
+-----------------------------------------------------------------------------------------
+
+You don't. The integer computation implied by a GEP is target-independent.
+Typically what you'll need to do is make your backend pattern-match expressions
+trees involving ADD, MUL, etc., which are what GEP is lowered into. This has the
+advantage of letting your code work correctly in more cases.
+
+GEP does use target-dependent parameters for the size and layout of data types,
+which targets can customize.
+
+If you require support for addressing units which are not 8 bits, you'll need to
+fix a lot of code in the backend, with GEP lowering being only a small piece of
+the overall picture.
+
+How does VLA addressing work with GEPs?
+---------------------------------------
+
+GEPs don't natively support VLAs. LLVM's type system is entirely static, and GEP
+address computations are guided by an LLVM type.
+
+VLA indices can be implemented as linearized indices. For example, an expression
+like ``X[a][b][c]``, must be effectively lowered into a form like
+``X[a*m+b*n+c]``, so that it appears to the GEP as a single-dimensional array
+reference.
+
+This means if you want to write an analysis which understands array indices and
+you want to support VLAs, your code will have to be prepared to reverse-engineer
+the linearization. One way to solve this problem is to use the ScalarEvolution
+library, which always presents VLA and non-VLA indexing in the same manner.
+
+.. _Rules:
+
+Rules
+=====
+
+What happens if an array index is out of bounds?
+------------------------------------------------
+
+There are two senses in which an array index can be out of bounds.
+
+First, there's the array type which comes from the (static) type of the first
+operand to the GEP. Indices greater than the number of elements in the
+corresponding static array type are valid. There is no problem with out of
+bounds indices in this sense. Indexing into an array only depends on the size of
+the array element, not the number of elements.
+
+A common example of how this is used is arrays where the size is not known.
+It's common to use array types with zero length to represent these. The fact
+that the static type says there are zero elements is irrelevant; it's perfectly
+valid to compute arbitrary element indices, as the computation only depends on
+the size of the array element, not the number of elements. Note that zero-sized
+arrays are not a special case here.
+
+This sense is unconnected with ``inbounds`` keyword. The ``inbounds`` keyword is
+designed to describe low-level pointer arithmetic overflow conditions, rather
+than high-level array indexing rules.
+
+Analysis passes which wish to understand array indexing should not assume that
+the static array type bounds are respected.
+
+The second sense of being out of bounds is computing an address that's beyond
+the actual underlying allocated object.
+
+With the ``inbounds`` keyword, the result value of the GEP is undefined if the
+address is outside the actual underlying allocated object and not the address
+one-past-the-end.
+
+Without the ``inbounds`` keyword, there are no restrictions on computing
+out-of-bounds addresses. Obviously, performing a load or a store requires an
+address of allocated and sufficiently aligned memory. But the GEP itself is only
+concerned with computing addresses.
+
+Can array indices be negative?
+------------------------------
+
+Yes. This is basically a special case of array indices being out of bounds.
+
+Can I compare two values computed with GEPs?
+--------------------------------------------
+
+Yes. If both addresses are within the same allocated object, or
+one-past-the-end, you'll get the comparison result you expect. If either is
+outside of it, integer arithmetic wrapping may occur, so the comparison may not
+be meaningful.
+
+Can I do GEP with a different pointer type than the type of the underlying object?
+----------------------------------------------------------------------------------
+
+Yes. There are no restrictions on bitcasting a pointer value to an arbitrary
+pointer type. The types in a GEP serve only to define the parameters for the
+underlying integer computation. They need not correspond with the actual type of
+the underlying object.
+
+Furthermore, loads and stores don't have to use the same types as the type of
+the underlying object. Types in this context serve only to specify memory size
+and alignment. Beyond that there are merely a hint to the optimizer indicating
+how the value will likely be used.
+
+Can I cast an object's address to integer and add it to null?
+-------------------------------------------------------------
+
+You can compute an address that way, but if you use GEP to do the add, you can't
+use that pointer to actually access the object, unless the object is managed
+outside of LLVM.
+
+The underlying integer computation is sufficiently defined; null has a defined
+value --- zero --- and you can add whatever value you want to it.
+
+However, it's invalid to access (load from or store to) an LLVM-aware object
+with such a pointer. This includes ``GlobalVariables``, ``Allocas``, and objects
+pointed to by noalias pointers.
+
+If you really need this functionality, you can do the arithmetic with explicit
+integer instructions, and use inttoptr to convert the result to an address. Most
+of GEP's special aliasing rules do not apply to pointers computed from ptrtoint,
+arithmetic, and inttoptr sequences.
+
+Can I compute the distance between two objects, and add that value to one address to compute the other address?
+---------------------------------------------------------------------------------------------------------------
+
+As with arithmetic on null, you can use GEP to compute an address that way, but
+you can't use that pointer to actually access the object if you do, unless the
+object is managed outside of LLVM.
+
+Also as above, ptrtoint and inttoptr provide an alternative way to do this which
+do not have this restriction.
+
+Can I do type-based alias analysis on LLVM IR?
+----------------------------------------------
+
+You can't do type-based alias analysis using LLVM's built-in type system,
+because LLVM has no restrictions on mixing types in addressing, loads or stores.
+
+LLVM's type-based alias analysis pass uses metadata to describe a different type
+system (such as the C type system), and performs type-based aliasing on top of
+that.  Further details are in the
+`language reference <LangRef.html#tbaa-metadata>`_.
+
+What happens if a GEP computation overflows?
+--------------------------------------------
+
+If the GEP lacks the ``inbounds`` keyword, the value is the result from
+evaluating the implied two's complement integer computation. However, since
+there's no guarantee of where an object will be allocated in the address space,
+such values have limited meaning.
+
+If the GEP has the ``inbounds`` keyword, the result value is undefined (a "trap
+value") if the GEP overflows (i.e. wraps around the end of the address space).
+
+As such, there are some ramifications of this for inbounds GEPs: scales implied
+by array/vector/pointer indices are always known to be "nsw" since they are
+signed values that are scaled by the element size.  These values are also
+allowed to be negative (e.g. "``gep i32 *%P, i32 -1``") but the pointer itself
+is logically treated as an unsigned value.  This means that GEPs have an
+asymmetric relation between the pointer base (which is treated as unsigned) and
+the offset applied to it (which is treated as signed). The result of the
+additions within the offset calculation cannot have signed overflow, but when
+applied to the base pointer, there can be signed overflow.
+
+How can I tell if my front-end is following the rules?
+------------------------------------------------------
+
+There is currently no checker for the getelementptr rules. Currently, the only
+way to do this is to manually check each place in your front-end where
+GetElementPtr operators are created.
+
+It's not possible to write a checker which could find all rule violations
+statically. It would be possible to write a checker which works by instrumenting
+the code with dynamic checks though. Alternatively, it would be possible to
+write a static checker which catches a subset of possible problems. However, no
+such checker exists today.
+
+Rationale
+=========
+
+Why is GEP designed this way?
+-----------------------------
+
+The design of GEP has the following goals, in rough unofficial order of
+priority:
+
+* Support C, C-like languages, and languages which can be conceptually lowered
+  into C (this covers a lot).
+
+* Support optimizations such as those that are common in C compilers. In
+  particular, GEP is a cornerstone of LLVM's `pointer aliasing
+  model <LangRef.html#pointeraliasing>`_.
+
+* Provide a consistent method for computing addresses so that address
+  computations don't need to be a part of load and store instructions in the IR.
+
+* Support non-C-like languages, to the extent that it doesn't interfere with
+  other goals.
+
+* Minimize target-specific information in the IR.
+
+Why do struct member indices always use ``i32``?
+------------------------------------------------
+
+The specific type i32 is probably just a historical artifact, however it's wide
+enough for all practical purposes, so there's been no need to change it.  It
+doesn't necessarily imply i32 address arithmetic; it's just an identifier which
+identifies a field in a struct. Requiring that all struct indices be the same
+reduces the range of possibilities for cases where two GEPs are effectively the
+same but have distinct operand types.
+
+What's an uglygep?
+------------------
+
+Some LLVM optimizers operate on GEPs by internally lowering them into more
+primitive integer expressions, which allows them to be combined with other
+integer expressions and/or split into multiple separate integer expressions. If
+they've made non-trivial changes, translating back into LLVM IR can involve
+reverse-engineering the structure of the addressing in order to fit it into the
+static type of the original first operand. It isn't always possibly to fully
+reconstruct this structure; sometimes the underlying addressing doesn't
+correspond with the static type at all. In such cases the optimizer instead will
+emit a GEP with the base pointer casted to a simple address-unit pointer, using
+the name "uglygep". This isn't pretty, but it's just as valid, and it's
+sufficient to preserve the pointer aliasing guarantees that GEP provides.
+
+Summary
+=======
+
+In summary, here's some things to always remember about the GetElementPtr
+instruction:
+
+
+#. The GEP instruction never accesses memory, it only provides pointer
+   computations.
+
+#. The second operand to the GEP instruction is always a pointer and it must be
+   indexed.
+
+#. There are no superfluous indices for the GEP instruction.
+
+#. Trailing zero indices are superfluous for pointer aliasing, but not for the
+   types of the pointers.
+
+#. Leading zero indices are not superfluous for pointer aliasing nor the types
+   of the pointers.

Added: www-releases/trunk/8.0.1/docs/_sources/GettingStarted.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.1/docs/_sources/GettingStarted.rst.txt?rev=368037&view=auto
==============================================================================
--- www-releases/trunk/8.0.1/docs/_sources/GettingStarted.rst.txt (added)
+++ www-releases/trunk/8.0.1/docs/_sources/GettingStarted.rst.txt Tue Aug  6 06:51:02 2019
@@ -0,0 +1,1116 @@
+====================================
+Getting Started with the LLVM System
+====================================
+
+.. contents::
+   :local:
+
+Overview
+========
+
+Welcome to the LLVM project! In order to get started, you first need to know
+some basic information.
+
+First, the LLVM project has multiple components. The core of the project is
+itself called "LLVM". This contains all of the tools, libraries, and header
+files needed to process an intermediate representation and convert it into
+object files.  It contains an assembler, disassembler, bitcode analyzer and
+bitcode optimizer.  It also contains basic regression tests.
+
+Another piece is the `Clang <http://clang.llvm.org/>`_ front end.  This
+component compiles C, C++, Objective C, and Objective C++ code into LLVM bitcode
+-- and from there into object files, using LLVM.
+
+There are other components as well:
+the `libc++ C++ standard library <https://libcxx.llvm.org>`_,
+the `LLD linker <https://lld.llvm.org>`_, and more.
+
+Getting Started Quickly (A Summary)
+===================================
+
+The LLVM Getting Started documentation may be out of date.  So, the `Clang
+Getting Started <http://clang.llvm.org/get_started.html>`_ page might also be a
+good place to start.
+
+Here's the short story for getting up and running quickly with LLVM:
+
+#. Read the documentation.
+#. Read the documentation.
+#. Remember that you were warned twice about reading the documentation.
+
+#. Checkout LLVM (including related subprojects like Clang):
+
+   * ``git clone https://github.com/llvm/llvm-project.git``
+   * Or, on windows, ``git clone --config core.autocrlf=false
+     https://github.com/llvm/llvm-project.git``
+
+#. Configure and build LLVM and Clang:.
+
+   * ``cd llvm-project``
+   * ``mkdir build``
+   * ``cd build``
+   * ``cmake -G <generator> [options] ../llvm``
+
+     Some common generators are:
+
+     * ``Ninja`` --- for generating `Ninja <https://ninja-build.org>`_
+       build files. Most llvm developers use Ninja.
+     * ``Unix Makefiles`` --- for generating make-compatible parallel makefiles.
+     * ``Visual Studio`` --- for generating Visual Studio projects and
+       solutions.
+     * ``Xcode`` --- for generating Xcode projects.
+
+     Some Common options:
+
+     * ``-DLLVM_ENABLE_PROJECTS='...'`` --- semicolon-separated list of the LLVM
+       subprojects you'd like to additionally build. Can include any of: clang,
+       libcxx, libcxxabi, libunwind, lldb, compiler-rt, lld, polly, or
+       debuginfo-tests.
+
+       For example, to build LLVM, Clang, libcxx, and libcxxabi, use
+       ``-DLLVM_ENABLE_PROJECTS="clang;libcxx;libcxxabi"``.
+
+     * ``-DCMAKE_INSTALL_PREFIX=directory`` --- Specify for *directory* the full
+       pathname of where you want the LLVM tools and libraries to be installed
+       (default ``/usr/local``).
+
+     * ``-DCMAKE_BUILD_TYPE=type`` --- Valid options for *type* are Debug,
+       Release, RelWithDebInfo, and MinSizeRel. Default is Debug.
+
+     * ``-DLLVM_ENABLE_ASSERTIONS=On`` --- Compile with assertion checks enabled
+       (default is Yes for Debug builds, No for all other build types).
+
+   * Run your build tool of choice!
+
+     * The default target (i.e. ``ninja`` or ``make``) will build all of LLVM.
+
+     * The ``check-all`` target (i.e. ``ninja check-all``) will run the
+       regression tests to ensure everything is in working order.
+
+     * CMake will generate build targets for each tool and library, and most
+       LLVM sub-projects generate their own ``check-<project>`` target.
+
+     * Running a serial build will be *slow*.  Make sure you run a parallel
+       build. That's already done by default in Ninja; for ``make``, use
+       ``make -j NNN`` (with an appropriate value of NNN, e.g. number of CPUs
+       you have.)
+
+   * For more information see `CMake <CMake.html>`_
+
+   * If you get an "internal compiler error (ICE)" or test failures, see
+     `below`_.
+
+Consult the `Getting Started with LLVM`_ section for detailed information on
+configuring and compiling LLVM.  Go to `Directory Layout`_ to learn about the
+layout of the source code tree.
+
+Requirements
+============
+
+Before you begin to use the LLVM system, review the requirements given below.
+This may save you some trouble by knowing ahead of time what hardware and
+software you will need.
+
+Hardware
+--------
+
+LLVM is known to work on the following host platforms:
+
+================== ===================== =============
+OS                 Arch                  Compilers
+================== ===================== =============
+Linux              x86\ :sup:`1`         GCC, Clang
+Linux              amd64                 GCC, Clang
+Linux              ARM                   GCC, Clang
+Linux              PowerPC               GCC, Clang
+Solaris            V9 (Ultrasparc)       GCC
+FreeBSD            x86\ :sup:`1`         GCC, Clang
+FreeBSD            amd64                 GCC, Clang
+NetBSD             x86\ :sup:`1`         GCC, Clang
+NetBSD             amd64                 GCC, Clang
+MacOS X\ :sup:`2`  PowerPC               GCC
+MacOS X            x86                   GCC, Clang
+Cygwin/Win32       x86\ :sup:`1, 3`      GCC
+Windows            x86\ :sup:`1`         Visual Studio
+Windows x64        x86-64                Visual Studio
+================== ===================== =============
+
+.. note::
+
+  #. Code generation supported for Pentium processors and up
+  #. Code generation supported for 32-bit ABI only
+  #. To use LLVM modules on Win32-based system, you may configure LLVM
+     with ``-DBUILD_SHARED_LIBS=On``.
+
+Note that Debug builds require a lot of time and disk space.  An LLVM-only build
+will need about 1-3 GB of space.  A full build of LLVM and Clang will need around
+15-20 GB of disk space.  The exact space requirements will vary by system.  (It
+is so large because of all the debugging information and the fact that the
+libraries are statically linked into multiple tools).
+
+If you are space-constrained, you can build only selected tools or only
+selected targets.  The Release build requires considerably less space.
+
+The LLVM suite *may* compile on other platforms, but it is not guaranteed to do
+so.  If compilation is successful, the LLVM utilities should be able to
+assemble, disassemble, analyze, and optimize LLVM bitcode.  Code generation
+should work as well, although the generated native code may not work on your
+platform.
+
+Software
+--------
+
+Compiling LLVM requires that you have several software packages installed. The
+table below lists those required packages. The Package column is the usual name
+for the software package that LLVM depends on. The Version column provides
+"known to work" versions of the package. The Notes column describes how LLVM
+uses the package and provides other details.
+
+=========================================================== ============ ==========================================
+Package                                                     Version      Notes
+=========================================================== ============ ==========================================
+`GNU Make <http://savannah.gnu.org/projects/make>`_         3.79, 3.79.1 Makefile/build processor
+`GCC <http://gcc.gnu.org/>`_                                >=5.1.0      C/C++ compiler\ :sup:`1`
+`python <http://www.python.org/>`_                          >=2.7        Automated test suite\ :sup:`2`
+`zlib <http://zlib.net>`_                                   >=1.2.3.4    Compression library\ :sup:`3`
+=========================================================== ============ ==========================================
+
+.. note::
+
+   #. Only the C and C++ languages are needed so there's no need to build the
+      other languages for LLVM's purposes. See `below` for specific version
+      info.
+   #. Only needed if you want to run the automated test suite in the
+      ``llvm/test`` directory.
+   #. Optional, adds compression / uncompression capabilities to selected LLVM
+      tools.
+
+Additionally, your compilation host is expected to have the usual plethora of
+Unix utilities. Specifically:
+
+* **ar** --- archive library builder
+* **bzip2** --- bzip2 command for distribution generation
+* **bunzip2** --- bunzip2 command for distribution checking
+* **chmod** --- change permissions on a file
+* **cat** --- output concatenation utility
+* **cp** --- copy files
+* **date** --- print the current date/time
+* **echo** --- print to standard output
+* **egrep** --- extended regular expression search utility
+* **find** --- find files/dirs in a file system
+* **grep** --- regular expression search utility
+* **gzip** --- gzip command for distribution generation
+* **gunzip** --- gunzip command for distribution checking
+* **install** --- install directories/files
+* **mkdir** --- create a directory
+* **mv** --- move (rename) files
+* **ranlib** --- symbol table builder for archive libraries
+* **rm** --- remove (delete) files and directories
+* **sed** --- stream editor for transforming output
+* **sh** --- Bourne shell for make build scripts
+* **tar** --- tape archive for distribution generation
+* **test** --- test things in file system
+* **unzip** --- unzip command for distribution checking
+* **zip** --- zip command for distribution generation
+
+.. _below:
+.. _check here:
+
+Host C++ Toolchain, both Compiler and Standard Library
+------------------------------------------------------
+
+LLVM is very demanding of the host C++ compiler, and as such tends to expose
+bugs in the compiler. We also attempt to follow improvements and developments in
+the C++ language and library reasonably closely. As such, we require a modern
+host C++ toolchain, both compiler and standard library, in order to build LLVM.
+
+LLVM is written using the subset of C++ documented in :doc:`coding
+standards<CodingStandards>`. To enforce this language version, we check the most
+popular host toolchains for specific minimum versions in our build systems:
+
+* Clang 3.5
+* Apple Clang 6.0
+* GCC 5.1
+* Visual Studio 2017
+
+The below versions currently soft-error as we transition to the new compiler
+versions listed above. The LLVM codebase is currently known to compile correctly
+with the following compilers, though this will change in the near future:
+
+* Clang 3.1
+* Apple Clang 3.1
+* GCC 4.8
+* Visual Studio 2015 (Update 3)
+
+Anything older than these toolchains *may* work, but will require forcing the
+build system with a special option and is not really a supported host platform.
+Also note that older versions of these compilers have often crashed or
+miscompiled LLVM.
+
+For less widely used host toolchains such as ICC or xlC, be aware that a very
+recent version may be required to support all of the C++ features used in LLVM.
+
+We track certain versions of software that are *known* to fail when used as
+part of the host toolchain. These even include linkers at times.
+
+**GNU ld 2.16.X**. Some 2.16.X versions of the ld linker will produce very long
+warning messages complaining that some "``.gnu.linkonce.t.*``" symbol was
+defined in a discarded section. You can safely ignore these messages as they are
+erroneous and the linkage is correct.  These messages disappear using ld 2.17.
+
+**GNU binutils 2.17**: Binutils 2.17 contains `a bug
+<http://sourceware.org/bugzilla/show_bug.cgi?id=3111>`__ which causes huge link
+times (minutes instead of seconds) when building LLVM.  We recommend upgrading
+to a newer version (2.17.50.0.4 or later).
+
+**GNU Binutils 2.19.1 Gold**: This version of Gold contained `a bug
+<http://sourceware.org/bugzilla/show_bug.cgi?id=9836>`__ which causes
+intermittent failures when building LLVM with position independent code.  The
+symptom is an error about cyclic dependencies.  We recommend upgrading to a
+newer version of Gold.
+
+Getting a Modern Host C++ Toolchain
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This section mostly applies to Linux and older BSDs. On Mac OS X, you should
+have a sufficiently modern Xcode, or you will likely need to upgrade until you
+do. Windows does not have a "system compiler", so you must install either Visual
+Studio 2015 or a recent version of mingw64. FreeBSD 10.0 and newer have a modern
+Clang as the system compiler.
+
+However, some Linux distributions and some other or older BSDs sometimes have
+extremely old versions of GCC. These steps attempt to help you upgrade you
+compiler even on such a system. However, if at all possible, we encourage you
+to use a recent version of a distribution with a modern system compiler that
+meets these requirements. Note that it is tempting to install a prior
+version of Clang and libc++ to be the host compiler, however libc++ was not
+well tested or set up to build on Linux until relatively recently. As
+a consequence, this guide suggests just using libstdc++ and a modern GCC as the
+initial host in a bootstrap, and then using Clang (and potentially libc++).
+
+The first step is to get a recent GCC toolchain installed. The most common
+distribution on which users have struggled with the version requirements is
+Ubuntu Precise, 12.04 LTS. For this distribution, one easy option is to install
+the `toolchain testing PPA`_ and use it to install a modern GCC. There is
+a really nice discussions of this on the `ask ubuntu stack exchange`_ and a
+`github gist`_ with updated commands. However, not all users can use PPAs and
+there are many other distributions, so it may be necessary (or just useful, if
+you're here you *are* doing compiler development after all) to build and install
+GCC from source. It is also quite easy to do these days.
+
+.. _toolchain testing PPA:
+  https://launchpad.net/~ubuntu-toolchain-r/+archive/test
+.. _ask ubuntu stack exchange:
+  https://askubuntu.com/questions/466651/how-do-i-use-the-latest-gcc-on-ubuntu/581497#58149
+.. _github gist:
+  https://gist.github.com/application2000/73fd6f4bf1be6600a2cf9f56315a2d91
+
+Easy steps for installing GCC 5.1.0:
+
+.. code-block:: console
+
+  % gcc_version=5.1.0
+  % wget https://ftp.gnu.org/gnu/gcc/gcc-${gcc_version}/gcc-${gcc_version}.tar.bz2
+  % wget https://ftp.gnu.org/gnu/gcc/gcc-${gcc_version}/gcc-${gcc_version}.tar.bz2.sig
+  % wget https://ftp.gnu.org/gnu/gnu-keyring.gpg
+  % signature_invalid=`gpg --verify --no-default-keyring --keyring ./gnu-keyring.gpg gcc-${gcc_version}.tar.bz2.sig`
+  % if [ $signature_invalid ]; then echo "Invalid signature" ; exit 1 ; fi
+  % tar -xvjf gcc-${gcc_version}.tar.bz2
+  % cd gcc-${gcc_version}
+  % ./contrib/download_prerequisites
+  % cd ..
+  % mkdir gcc-${gcc_version}-build
+  % cd gcc-${gcc_version}-build
+  % $PWD/../gcc-${gcc_version}/configure --prefix=$HOME/toolchains --enable-languages=c,c++
+  % make -j$(nproc)
+  % make install
+
+For more details, check out the excellent `GCC wiki entry`_, where I got most
+of this information from.
+
+.. _GCC wiki entry:
+  https://gcc.gnu.org/wiki/InstallingGCC
+
+Once you have a GCC toolchain, configure your build of LLVM to use the new
+toolchain for your host compiler and C++ standard library. Because the new
+version of libstdc++ is not on the system library search path, you need to pass
+extra linker flags so that it can be found at link time (``-L``) and at runtime
+(``-rpath``). If you are using CMake, this invocation should produce working
+binaries:
+
+.. code-block:: console
+
+  % mkdir build
+  % cd build
+  % CC=$HOME/toolchains/bin/gcc CXX=$HOME/toolchains/bin/g++ \
+    cmake .. -DCMAKE_CXX_LINK_FLAGS="-Wl,-rpath,$HOME/toolchains/lib64 -L$HOME/toolchains/lib64"
+
+If you fail to set rpath, most LLVM binaries will fail on startup with a message
+from the loader similar to ``libstdc++.so.6: version `GLIBCXX_3.4.20' not
+found``. This means you need to tweak the -rpath linker flag.
+
+When you build Clang, you will need to give *it* access to modern C++
+standard library in order to use it as your new host in part of a bootstrap.
+There are two easy ways to do this, either build (and install) libc++ along
+with Clang and then use it with the ``-stdlib=libc++`` compile and link flag,
+or install Clang into the same prefix (``$HOME/toolchains`` above) as GCC.
+Clang will look within its own prefix for libstdc++ and use it if found. You
+can also add an explicit prefix for Clang to look in for a GCC toolchain with
+the ``--gcc-toolchain=/opt/my/gcc/prefix`` flag, passing it to both compile and
+link commands when using your just-built-Clang to bootstrap.
+
+.. _Getting Started with LLVM:
+
+Getting Started with LLVM
+=========================
+
+The remainder of this guide is meant to get you up and running with LLVM and to
+give you some basic information about the LLVM environment.
+
+The later sections of this guide describe the `general layout`_ of the LLVM
+source tree, a `simple example`_ using the LLVM tool chain, and `links`_ to find
+more information about LLVM or to get help via e-mail.
+
+Terminology and Notation
+------------------------
+
+Throughout this manual, the following names are used to denote paths specific to
+the local system and working environment.  *These are not environment variables
+you need to set but just strings used in the rest of this document below*.  In
+any of the examples below, simply replace each of these names with the
+appropriate pathname on your local system.  All these paths are absolute:
+
+``SRC_ROOT``
+
+  This is the top level directory of the LLVM source tree.
+
+``OBJ_ROOT``
+
+  This is the top level directory of the LLVM object tree (i.e. the tree where
+  object files and compiled programs will be placed.  It can be the same as
+  SRC_ROOT).
+
+Unpacking the LLVM Archives
+---------------------------
+
+If you have the LLVM distribution, you will need to unpack it before you can
+begin to compile it.  LLVM is distributed as a number of different
+subprojects. Each one has its own download which is a TAR archive that is
+compressed with the gzip program.
+
+The files are as follows, with *x.y* marking the version number:
+
+``llvm-x.y.tar.gz``
+
+  Source release for the LLVM libraries and tools.
+
+``cfe-x.y.tar.gz``
+
+  Source release for the Clang frontend.
+
+.. _checkout:
+
+Checkout LLVM from Git
+----------------------
+
+You can also checkout the source code for LLVM from Git. While the LLVM
+project's official source-code repository is Subversion, we are in the process
+of migrating to git. We currently recommend that all developers use Git for
+day-to-day development.
+
+.. note::
+
+  Passing ``--config core.autocrlf=false`` should not be required in
+  the future after we adjust the .gitattribute settings correctly, but
+  is required for Windows users at the time of this writing.
+
+Simply run:
+
+.. code-block:: console
+
+  % git clone https://github.com/llvm/llvm-project.git`
+
+or on Windows,
+
+.. code-block:: console
+
+  % git clone --config core.autocrlf=false https://github.com/llvm/llvm-project.git
+
+This will create an '``llvm-project``' directory in the current directory and
+fully populate it with all of the source code, test directories, and local
+copies of documentation files for LLVM and all the related subprojects. Note
+that unlike the tarballs, which contain each subproject in a separate file, the
+git repository contains all of the projects together.
+
+If you want to get a specific release (as opposed to the most recent revision),
+you can check out a tag after cloning the repository. E.g., `git checkout
+llvmorg-6.0.1` inside the ``llvm-project`` directory created by the above
+command.  Use `git tag -l` to list all of them.
+
+Sending patches
+^^^^^^^^^^^^^^^
+
+Please read `Developer Policy <DeveloperPolicy.html#one-off-patches>`_, too.
+
+We don't currently accept github pull requests, so you'll need to send patches
+either via emailing to llvm-commits, or, preferably, via :ref:`Phabricator
+<phabricator-reviews>`.
+
+You'll generally want to make sure your branch has a single commit,
+corresponding to the review you wish to send, up-to-date with the upstream
+``origin/master`` branch, and doesn't contain merges. Once you have that, you
+can use ``git show`` or ``git format-patch`` to output the diff, and attach it
+to a Phabricator review (or to an email message).
+
+However, using the "Arcanist" tool is often easier. After `installing
+arcanist`_, you can upload the latest commit using:
+
+.. code-block:: console
+
+  % arc diff HEAD~1
+
+Additionally, before sending a patch for review, please also try to ensure it's
+formatted properly. We use ``clang-format`` for this, which has git integration
+through the ``git-clang-format`` script. On some systems, it may already be
+installed (or be installable via your package manager). If so, you can simply
+run it -- the following command will format only the code changed in the most
+recent commit:
+
+.. code-block:: console
+
+  % git clang-format HEAD~1
+
+Note that this modifies the files, but doesn't commit them -- you'll likely want
+to run
+
+.. code-block:: console
+
+  % git commit --amend -a
+
+in order to update the last commit with all pending changes.
+
+.. note::
+  If you don't already have ``clang-format`` or ``git clang-format`` installed
+  on your system, the ``clang-format`` binary will be built alongside clang, and
+  the git integration can be run from
+  ``clang/tools/clang-format/git-clang-format``.
+
+
+.. _commit_from_git:
+
+For developers to commit changes from Git
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A helper script is provided in ``llvm/utils/git-svn/git-llvm``. After you add it
+to your path, you can push committed changes upstream with ``git llvm
+push``. While this creates a Subversion checkout and patches it under the hood,
+it does not require you to have interaction with it.
+
+.. code-block:: console
+
+  % export PATH=$PATH:$TOP_LEVEL_DIR/llvm-project/llvm/utils/git-svn/
+  % git llvm push
+
+Within a couple minutes after pushing to subversion, the svn commit will have
+been converted back to a Git commit, and made its way into the official Git
+repository. At that point, ``git pull`` should get back the changes as they were
+committed.
+
+You'll likely want to ``git pull --rebase`` to get the official git commit
+downloaded back to your repository. The SVN revision numbers of each commit can
+be found at the end of the commit message, e.g. ``llvm-svn: 350914``.
+
+You may also find the ``-n`` flag useful, like ``git llvm push -n``. This runs
+through all the steps of committing _without_ actually doing the commit, and
+tell you what it would have done. That can be useful if you're unsure whether
+the right thing will happen.
+
+Checkout via SVN (deprecated)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Until we have fully migrated to Git, you may also get a fresh copy of
+the code from the official Subversion repository.
+
+* ``cd where-you-want-llvm-to-live``
+* Read-Only: ``svn co http://llvm.org/svn/llvm-project/llvm/trunk llvm``
+* Read-Write: ``svn co https://user@llvm.org/svn/llvm-project/llvm/trunk llvm``
+
+This will create an '``llvm``' directory in the current directory and fully
+populate it with the LLVM source code, Makefiles, test directories, and local
+copies of documentation files.
+
+If you want to get a specific release (as opposed to the most recent revision),
+you can check it out from the '``tags``' directory (instead of '``trunk``'). The
+following releases are located in the following subdirectories of the '``tags``'
+directory:
+
+* Release 3.5.0 and later: **RELEASE_350/final** and so on
+* Release 2.9 through 3.4: **RELEASE_29/final** and so on
+* Release 1.1 through 2.8: **RELEASE_11** and so on
+* Release 1.0: **RELEASE_1**
+
+Local LLVM Configuration
+------------------------
+
+Once checked out repository, the LLVM suite source code must be configured
+before being built. This process uses CMake.  Unlinke the normal ``configure``
+script, CMake generates the build files in whatever format you request as well
+as various ``*.inc`` files, and ``llvm/include/Config/config.h``.
+
+Variables are passed to ``cmake`` on the command line using the format
+``-D<variable name>=<value>``. The following variables are some common options
+used by people developing LLVM.
+
++-------------------------+----------------------------------------------------+
+| Variable                | Purpose                                            |
++=========================+====================================================+
+| CMAKE_C_COMPILER        | Tells ``cmake`` which C compiler to use. By        |
+|                         | default, this will be /usr/bin/cc.                 |
++-------------------------+----------------------------------------------------+
+| CMAKE_CXX_COMPILER      | Tells ``cmake`` which C++ compiler to use. By      |
+|                         | default, this will be /usr/bin/c++.                |
++-------------------------+----------------------------------------------------+
+| CMAKE_BUILD_TYPE        | Tells ``cmake`` what type of build you are trying  |
+|                         | to generate files for. Valid options are Debug,    |
+|                         | Release, RelWithDebInfo, and MinSizeRel. Default   |
+|                         | is Debug.                                          |
++-------------------------+----------------------------------------------------+
+| CMAKE_INSTALL_PREFIX    | Specifies the install directory to target when     |
+|                         | running the install action of the build files.     |
++-------------------------+----------------------------------------------------+
+| LLVM_TARGETS_TO_BUILD   | A semicolon delimited list controlling which       |
+|                         | targets will be built and linked into llvm.        |
+|                         | The default list is defined as                     |
+|                         | ``LLVM_ALL_TARGETS``, and can be set to include    |
+|                         | out-of-tree targets. The default value includes:   |
+|                         | ``AArch64, AMDGPU, ARM, BPF, Hexagon, Mips,        |
+|                         | MSP430, NVPTX, PowerPC, Sparc, SystemZ, X86,       |
+|                         | XCore``.                                           |
+|                         |                                                    |
++-------------------------+----------------------------------------------------+
+| LLVM_ENABLE_DOXYGEN     | Build doxygen-based documentation from the source  |
+|                         | code This is disabled by default because it is     |
+|                         | slow and generates a lot of output.                |
++-------------------------+----------------------------------------------------+
+| LLVM_ENABLE_PROJECTS    | A semicolon-delimited list selecting which of the  |
+|                         | other LLVM subprojects to additionally build. (Only|
+|                         | effective when using a side-by-side project layout |
+|                         | e.g. via git). The default list is empty. Can      |
+|                         | include: clang, libcxx, libcxxabi, libunwind, lldb,|
+|                         | compiler-rt, lld, polly, or debuginfo-tests.       |
++-------------------------+----------------------------------------------------+
+| LLVM_ENABLE_SPHINX      | Build sphinx-based documentation from the source   |
+|                         | code. This is disabled by default because it is    |
+|                         | slow and generates a lot of output. Sphinx version |
+|                         | 1.5 or later recommended.                          |
++-------------------------+----------------------------------------------------+
+| LLVM_BUILD_LLVM_DYLIB   | Generate libLLVM.so. This library contains a       |
+|                         | default set of LLVM components that can be         |
+|                         | overridden with ``LLVM_DYLIB_COMPONENTS``. The     |
+|                         | default contains most of LLVM and is defined in    |
+|                         | ``tools/llvm-shlib/CMakelists.txt``.               |
++-------------------------+----------------------------------------------------+
+| LLVM_OPTIMIZED_TABLEGEN | Builds a release tablegen that gets used during    |
+|                         | the LLVM build. This can dramatically speed up     |
+|                         | debug builds.                                      |
++-------------------------+----------------------------------------------------+
+
+To configure LLVM, follow these steps:
+
+#. Change directory into the object root directory:
+
+   .. code-block:: console
+
+     % cd OBJ_ROOT
+
+#. Run the ``cmake``:
+
+   .. code-block:: console
+
+     % cmake -G "Unix Makefiles" -DCMAKE_INSTALL_PREFIX=/install/path
+       [other options] SRC_ROOT
+
+Compiling the LLVM Suite Source Code
+------------------------------------
+
+Unlike with autotools, with CMake your build type is defined at configuration.
+If you want to change your build type, you can re-run cmake with the following
+invocation:
+
+   .. code-block:: console
+
+     % cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=type SRC_ROOT
+
+Between runs, CMake preserves the values set for all options. CMake has the
+following build types defined:
+
+Debug
+
+  These builds are the default. The build system will compile the tools and
+  libraries unoptimized, with debugging information, and asserts enabled.
+
+Release
+
+  For these builds, the build system will compile the tools and libraries
+  with optimizations enabled and not generate debug info. CMakes default
+  optimization level is -O3. This can be configured by setting the
+  ``CMAKE_CXX_FLAGS_RELEASE`` variable on the CMake command line.
+
+RelWithDebInfo
+
+  These builds are useful when debugging. They generate optimized binaries with
+  debug information. CMakes default optimization level is -O2. This can be
+  configured by setting the ``CMAKE_CXX_FLAGS_RELWITHDEBINFO`` variable on the
+  CMake command line.
+
+Once you have LLVM configured, you can build it by entering the *OBJ_ROOT*
+directory and issuing the following command:
+
+.. code-block:: console
+
+  % make
+
+If the build fails, please `check here`_ to see if you are using a version of
+GCC that is known not to compile LLVM.
+
+If you have multiple processors in your machine, you may wish to use some of the
+parallel build options provided by GNU Make.  For example, you could use the
+command:
+
+.. code-block:: console
+
+  % make -j2
+
+There are several special targets which are useful when working with the LLVM
+source code:
+
+``make clean``
+
+  Removes all files generated by the build.  This includes object files,
+  generated C/C++ files, libraries, and executables.
+
+``make install``
+
+  Installs LLVM header files, libraries, tools, and documentation in a hierarchy
+  under ``$PREFIX``, specified with ``CMAKE_INSTALL_PREFIX``, which
+  defaults to ``/usr/local``.
+
+``make docs-llvm-html``
+
+  If configured with ``-DLLVM_ENABLE_SPHINX=On``, this will generate a directory
+  at ``OBJ_ROOT/docs/html`` which contains the HTML formatted documentation.
+
+Cross-Compiling LLVM
+--------------------
+
+It is possible to cross-compile LLVM itself. That is, you can create LLVM
+executables and libraries to be hosted on a platform different from the platform
+where they are built (a Canadian Cross build). To generate build files for
+cross-compiling CMake provides a variable ``CMAKE_TOOLCHAIN_FILE`` which can
+define compiler flags and variables used during the CMake test operations.
+
+The result of such a build is executables that are not runnable on the build
+host but can be executed on the target. As an example the following CMake
+invocation can generate build files targeting iOS. This will work on Mac OS X
+with the latest Xcode:
+
+.. code-block:: console
+
+  % cmake -G "Ninja" -DCMAKE_OSX_ARCHITECTURES="armv7;armv7s;arm64"
+    -DCMAKE_TOOLCHAIN_FILE=<PATH_TO_LLVM>/cmake/platforms/iOS.cmake
+    -DCMAKE_BUILD_TYPE=Release -DLLVM_BUILD_RUNTIME=Off -DLLVM_INCLUDE_TESTS=Off
+    -DLLVM_INCLUDE_EXAMPLES=Off -DLLVM_ENABLE_BACKTRACES=Off [options]
+    <PATH_TO_LLVM>
+
+Note: There are some additional flags that need to be passed when building for
+iOS due to limitations in the iOS SDK.
+
+Check :doc:`HowToCrossCompileLLVM` and `Clang docs on how to cross-compile in general
+<http://clang.llvm.org/docs/CrossCompilation.html>`_ for more information
+about cross-compiling.
+
+The Location of LLVM Object Files
+---------------------------------
+
+The LLVM build system is capable of sharing a single LLVM source tree among
+several LLVM builds.  Hence, it is possible to build LLVM for several different
+platforms or configurations using the same source tree.
+
+* Change directory to where the LLVM object files should live:
+
+  .. code-block:: console
+
+    % cd OBJ_ROOT
+
+* Run ``cmake``:
+
+  .. code-block:: console
+
+    % cmake -G "Unix Makefiles" SRC_ROOT
+
+The LLVM build will create a structure underneath *OBJ_ROOT* that matches the
+LLVM source tree. At each level where source files are present in the source
+tree there will be a corresponding ``CMakeFiles`` directory in the *OBJ_ROOT*.
+Underneath that directory there is another directory with a name ending in
+``.dir`` under which you'll find object files for each source.
+
+For example:
+
+  .. code-block:: console
+
+    % cd llvm_build_dir
+    % find lib/Support/ -name APFloat*
+    lib/Support/CMakeFiles/LLVMSupport.dir/APFloat.cpp.o
+
+Optional Configuration Items
+----------------------------
+
+If you're running on a Linux system that supports the `binfmt_misc
+<http://en.wikipedia.org/wiki/binfmt_misc>`_
+module, and you have root access on the system, you can set your system up to
+execute LLVM bitcode files directly. To do this, use commands like this (the
+first command may not be required if you are already using the module):
+
+.. code-block:: console
+
+  % mount -t binfmt_misc none /proc/sys/fs/binfmt_misc
+  % echo ':llvm:M::BC::/path/to/lli:' > /proc/sys/fs/binfmt_misc/register
+  % chmod u+x hello.bc   (if needed)
+  % ./hello.bc
+
+This allows you to execute LLVM bitcode files directly.  On Debian, you can also
+use this command instead of the 'echo' command above:
+
+.. code-block:: console
+
+  % sudo update-binfmts --install llvm /path/to/lli --magic 'BC'
+
+.. _Program Layout:
+.. _general layout:
+
+Directory Layout
+================
+
+One useful source of information about the LLVM source base is the LLVM `doxygen
+<http://www.doxygen.org/>`_ documentation available at
+`<http://llvm.org/doxygen/>`_.  The following is a brief introduction to code
+layout:
+
+``llvm/examples``
+-----------------
+
+Simple examples using the LLVM IR and JIT.
+
+``llvm/include``
+----------------
+
+Public header files exported from the LLVM library. The three main subdirectories:
+
+``llvm/include/llvm``
+
+  All LLVM-specific header files, and  subdirectories for different portions of
+  LLVM: ``Analysis``, ``CodeGen``, ``Target``, ``Transforms``, etc...
+
+``llvm/include/llvm/Support``
+
+  Generic support libraries provided with LLVM but not necessarily specific to
+  LLVM. For example, some C++ STL utilities and a Command Line option processing
+  library store header files here.
+
+``llvm/include/llvm/Config``
+
+  Header files configured by ``cmake``.  They wrap "standard" UNIX and
+  C header files.  Source code can include these header files which
+  automatically take care of the conditional #includes that ``cmake``
+  generates.
+
+``llvm/lib``
+------------
+
+Most source files are here. By putting code in libraries, LLVM makes it easy to
+share code among the `tools`_.
+
+``llvm/lib/IR/``
+
+  Core LLVM source files that implement core classes like Instruction and
+  BasicBlock.
+
+``llvm/lib/AsmParser/``
+
+  Source code for the LLVM assembly language parser library.
+
+``llvm/lib/Bitcode/``
+
+  Code for reading and writing bitcode.
+
+``llvm/lib/Analysis/``
+
+  A variety of program analyses, such as Call Graphs, Induction Variables,
+  Natural Loop Identification, etc.
+
+``llvm/lib/Transforms/``
+
+  IR-to-IR program transformations, such as Aggressive Dead Code Elimination,
+  Sparse Conditional Constant Propagation, Inlining, Loop Invariant Code Motion,
+  Dead Global Elimination, and many others.
+
+``llvm/lib/Target/``
+
+  Files describing target architectures for code generation.  For example,
+  ``llvm/lib/Target/X86`` holds the X86 machine description.
+
+``llvm/lib/CodeGen/``
+
+  The major parts of the code generator: Instruction Selector, Instruction
+  Scheduling, and Register Allocation.
+
+``llvm/lib/MC/``
+
+  (FIXME: T.B.D.)  ....?
+
+``llvm/lib/ExecutionEngine/``
+
+  Libraries for directly executing bitcode at runtime in interpreted and
+  JIT-compiled scenarios.
+
+``llvm/lib/Support/``
+
+  Source code that corresponding to the header files in ``llvm/include/ADT/``
+  and ``llvm/include/Support/``.
+
+``llvm/projects``
+-----------------
+
+Projects not strictly part of LLVM but shipped with LLVM. This is also the
+directory for creating your own LLVM-based projects which leverage the LLVM
+build system.
+
+``llvm/test``
+-------------
+
+Feature and regression tests and other sanity checks on LLVM infrastructure. These
+are intended to run quickly and cover a lot of territory without being exhaustive.
+
+``test-suite``
+--------------
+
+A comprehensive correctness, performance, and benchmarking test suite
+for LLVM.  This comes in a ``separate git repository
+<https://github.com/llvm/llvm-test-suite>``, because it contains a
+large amount of third-party code under a variety of licenses. For
+details see the :doc:`Testing Guide <TestingGuide>` document.
+
+.. _tools:
+
+``llvm/tools``
+--------------
+
+Executables built out of the libraries
+above, which form the main part of the user interface.  You can always get help
+for a tool by typing ``tool_name -help``.  The following is a brief introduction
+to the most important tools.  More detailed information is in
+the `Command Guide <CommandGuide/index.html>`_.
+
+``bugpoint``
+
+  ``bugpoint`` is used to debug optimization passes or code generation backends
+  by narrowing down the given test case to the minimum number of passes and/or
+  instructions that still cause a problem, whether it is a crash or
+  miscompilation. See `<HowToSubmitABug.html>`_ for more information on using
+  ``bugpoint``.
+
+``llvm-ar``
+
+  The archiver produces an archive containing the given LLVM bitcode files,
+  optionally with an index for faster lookup.
+
+``llvm-as``
+
+  The assembler transforms the human readable LLVM assembly to LLVM bitcode.
+
+``llvm-dis``
+
+  The disassembler transforms the LLVM bitcode to human readable LLVM assembly.
+
+``llvm-link``
+
+  ``llvm-link``, not surprisingly, links multiple LLVM modules into a single
+  program.
+
+``lli``
+
+  ``lli`` is the LLVM interpreter, which can directly execute LLVM bitcode
+  (although very slowly...). For architectures that support it (currently x86,
+  Sparc, and PowerPC), by default, ``lli`` will function as a Just-In-Time
+  compiler (if the functionality was compiled in), and will execute the code
+  *much* faster than the interpreter.
+
+``llc``
+
+  ``llc`` is the LLVM backend compiler, which translates LLVM bitcode to a
+  native code assembly file.
+
+``opt``
+
+  ``opt`` reads LLVM bitcode, applies a series of LLVM to LLVM transformations
+  (which are specified on the command line), and outputs the resultant
+  bitcode.   '``opt -help``'  is a good way to get a list of the
+  program transformations available in LLVM.
+
+  ``opt`` can also  run a specific analysis on an input LLVM bitcode
+  file and print  the results.  Primarily useful for debugging
+  analyses, or familiarizing yourself with what an analysis does.
+
+``llvm/utils``
+--------------
+
+Utilities for working with LLVM source code; some are part of the build process
+because they are code generators for parts of the infrastructure.
+
+
+``codegen-diff``
+
+  ``codegen-diff`` finds differences between code that LLC
+  generates and code that LLI generates. This is useful if you are
+  debugging one of them, assuming that the other generates correct output. For
+  the full user manual, run ```perldoc codegen-diff'``.
+
+``emacs/``
+
+   Emacs and XEmacs syntax highlighting  for LLVM   assembly files and TableGen
+   description files.  See the ``README`` for information on using them.
+
+``getsrcs.sh``
+
+  Finds and outputs all non-generated source files,
+  useful if one wishes to do a lot of development across directories
+  and does not want to find each file. One way to use it is to run,
+  for example: ``xemacs `utils/getsources.sh``` from the top of the LLVM source
+  tree.
+
+``llvmgrep``
+
+  Performs an ``egrep -H -n`` on each source file in LLVM and
+  passes to it a regular expression provided on ``llvmgrep``'s command
+  line. This is an efficient way of searching the source base for a
+  particular regular expression.
+
+``TableGen/``
+
+  Contains the tool used to generate register
+  descriptions, instruction set descriptions, and even assemblers from common
+  TableGen description files.
+
+``vim/``
+
+  vim syntax-highlighting for LLVM assembly files
+  and TableGen description files. See the    ``README`` for how to use them.
+
+.. _simple example:
+
+An Example Using the LLVM Tool Chain
+====================================
+
+This section gives an example of using LLVM with the Clang front end.
+
+Example with clang
+------------------
+
+#. First, create a simple C file, name it 'hello.c':
+
+   .. code-block:: c
+
+     #include <stdio.h>
+
+     int main() {
+       printf("hello world\n");
+       return 0;
+     }
+
+#. Next, compile the C file into a native executable:
+
+   .. code-block:: console
+
+     % clang hello.c -o hello
+
+   .. note::
+
+     Clang works just like GCC by default.  The standard -S and -c arguments
+     work as usual (producing a native .s or .o file, respectively).
+
+#. Next, compile the C file into an LLVM bitcode file:
+
+   .. code-block:: console
+
+     % clang -O3 -emit-llvm hello.c -c -o hello.bc
+
+   The -emit-llvm option can be used with the -S or -c options to emit an LLVM
+   ``.ll`` or ``.bc`` file (respectively) for the code.  This allows you to use
+   the `standard LLVM tools <CommandGuide/index.html>`_ on the bitcode file.
+
+#. Run the program in both forms. To run the program, use:
+
+   .. code-block:: console
+
+      % ./hello
+
+   and
+
+   .. code-block:: console
+
+     % lli hello.bc
+
+   The second examples shows how to invoke the LLVM JIT, :doc:`lli
+   <CommandGuide/lli>`.
+
+#. Use the ``llvm-dis`` utility to take a look at the LLVM assembly code:
+
+   .. code-block:: console
+
+     % llvm-dis < hello.bc | less
+
+#. Compile the program to native assembly using the LLC code generator:
+
+   .. code-block:: console
+
+     % llc hello.bc -o hello.s
+
+#. Assemble the native assembly language file into a program:
+
+   .. code-block:: console
+
+     % /opt/SUNWspro/bin/cc -xarch=v9 hello.s -o hello.native   # On Solaris
+
+     % gcc hello.s -o hello.native                              # On others
+
+#. Execute the native code program:
+
+   .. code-block:: console
+
+     % ./hello.native
+
+   Note that using clang to compile directly to native code (i.e. when the
+   ``-emit-llvm`` option is not present) does steps 6/7/8 for you.
+
+Common Problems
+===============
+
+If you are having problems building or using LLVM, or if you have any other
+general questions about LLVM, please consult the `Frequently Asked
+Questions <FAQ.html>`_ page.
+
+.. _links:
+
+Links
+=====
+
+This document is just an **introduction** on how to use LLVM to do some simple
+things... there are many more interesting and complicated things that you can do
+that aren't documented here (but we'll gladly accept a patch if you want to
+write something up!).  For more information about LLVM, check out:
+
+* `LLVM Homepage <http://llvm.org/>`_
+* `LLVM Doxygen Tree <http://llvm.org/doxygen/>`_
+* `Starting a Project that Uses LLVM <http://llvm.org/docs/Projects.html>`_
+
+.. _installing arcanist: https://secure.phabricator.com/book/phabricator/article/arcanist_quick_start/

Added: www-releases/trunk/8.0.1/docs/_sources/GettingStartedVS.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.1/docs/_sources/GettingStartedVS.rst.txt?rev=368037&view=auto
==============================================================================
--- www-releases/trunk/8.0.1/docs/_sources/GettingStartedVS.rst.txt (added)
+++ www-releases/trunk/8.0.1/docs/_sources/GettingStartedVS.rst.txt Tue Aug  6 06:51:02 2019
@@ -0,0 +1,241 @@
+==================================================================
+Getting Started with the LLVM System using Microsoft Visual Studio
+==================================================================
+
+.. contents::
+   :local:
+
+
+Overview
+========
+Welcome to LLVM on Windows! This document only covers LLVM on Windows using
+Visual Studio, not mingw or cygwin. In order to get started, you first need to
+know some basic information.
+
+There are many different projects that compose LLVM. The first piece is the
+LLVM suite. This contains all of the tools, libraries, and header files needed
+to use LLVM. It contains an assembler, disassembler, bitcode analyzer and
+bitcode optimizer. It also contains basic regression tests that can be used to
+test the LLVM tools and the Clang front end.
+
+The second piece is the `Clang <http://clang.llvm.org/>`_ front end.  This
+component compiles C, C++, Objective C, and Objective C++ code into LLVM
+bitcode. Clang typically uses LLVM libraries to optimize the bitcode and emit
+machine code. LLVM fully supports the COFF object file format, which is
+compatible with all other existing Windows toolchains.
+
+The last major part of LLVM, the execution Test Suite, does not run on Windows,
+and this document does not discuss it.
+
+Additional information about the LLVM directory structure and tool chain
+can be found on the main :doc:`GettingStarted` page.
+
+
+Requirements
+============
+Before you begin to use the LLVM system, review the requirements given
+below.  This may save you some trouble by knowing ahead of time what hardware
+and software you will need.
+
+Hardware
+--------
+Any system that can adequately run Visual Studio 2015 is fine. The LLVM
+source tree and object files, libraries and executables will consume
+approximately 3GB.
+
+Software
+--------
+You will need Visual Studio 2015 or higher, with the latest Update installed.
+
+You will also need the `CMake <http://www.cmake.org/>`_ build system since it
+generates the project files you will use to build with.
+
+If you would like to run the LLVM tests you will need `Python
+<http://www.python.org/>`_. Version 2.7 and newer are known to work. You will
+need `GnuWin32 <http://gnuwin32.sourceforge.net/>`_ tools, too.
+
+Do not install the LLVM directory tree into a path containing spaces (e.g.
+``C:\Documents and Settings\...``) as the configure step will fail.
+
+
+Getting Started
+===============
+Here's the short story for getting up and running quickly with LLVM:
+
+1. Read the documentation.
+2. Seriously, read the documentation.
+3. Remember that you were warned twice about reading the documentation.
+4. Get the Source Code
+
+   * With the distributed files:
+
+      1. ``cd <where-you-want-llvm-to-live>``
+      2. ``gunzip --stdout llvm-VERSION.tar.gz | tar -xvf -``
+         (*or use WinZip*)
+      3. ``cd llvm``
+
+   * With anonymous Subversion access:
+
+     *Note:* some regression tests require Unix-style line ending (``\n``). To
+     pass all regression tests, please add two lines *enable-auto-props = yes*
+     and *\* = svn:mime-type=application/octet-stream* to
+     ``C:\Users\<username>\AppData\Roaming\Subversion\config``.
+
+      1. ``cd <where-you-want-llvm-to-live>``
+      2. ``svn co http://llvm.org/svn/llvm-project/llvm/trunk llvm``
+      3. ``cd llvm``
+
+5. Use `CMake <http://www.cmake.org/>`_ to generate up-to-date project files:
+
+   * Once CMake is installed then the simplest way is to just start the
+     CMake GUI, select the directory where you have LLVM extracted to, and
+     the default options should all be fine.  One option you may really
+     want to change, regardless of anything else, might be the
+     ``CMAKE_INSTALL_PREFIX`` setting to select a directory to INSTALL to
+     once compiling is complete, although installation is not mandatory for
+     using LLVM.  Another important option is ``LLVM_TARGETS_TO_BUILD``,
+     which controls the LLVM target architectures that are included on the
+     build.
+   * If CMake complains that it cannot find the compiler, make sure that
+     you have the Visual Studio C++ Tools installed, not just Visual Studio
+     itself (trying to create a C++ project in Visual Studio will generally
+     download the C++ tools if they haven't already been).
+   * See the :doc:`LLVM CMake guide <CMake>` for detailed information about
+     how to configure the LLVM build.
+   * CMake generates project files for all build types. To select a specific
+     build type, use the Configuration manager from the VS IDE or the 
+     ``/property:Configuration`` command line option when using MSBuild.
+   * By default, the Visual Studio project files generated by CMake use the
+     32-bit toolset. If you are developing on a 64-bit version of Windows and
+     want to use the 64-bit toolset, pass the ``-Thost=x64`` flag when
+     generating the Visual Studio solution. This requires CMake 3.8.0 or later.
+
+6. Start Visual Studio
+
+   * In the directory you created the project files will have an ``llvm.sln``
+     file, just double-click on that to open Visual Studio.
+
+7. Build the LLVM Suite:
+
+   * The projects may still be built individually, but to build them all do
+     not just select all of them in batch build (as some are meant as
+     configuration projects), but rather select and build just the
+     ``ALL_BUILD`` project to build everything, or the ``INSTALL`` project,
+     which first builds the ``ALL_BUILD`` project, then installs the LLVM
+     headers, libs, and other useful things to the directory set by the
+     ``CMAKE_INSTALL_PREFIX`` setting when you first configured CMake.
+   * The Fibonacci project is a sample program that uses the JIT. Modify the
+     project's debugging properties to provide a numeric command line argument
+     or run it from the command line.  The program will print the
+     corresponding fibonacci value.
+
+8. Test LLVM in Visual Studio:
+
+   * If ``%PATH%`` does not contain GnuWin32, you may specify
+     ``LLVM_LIT_TOOLS_DIR`` on CMake for the path to GnuWin32.
+   * You can run LLVM tests by merely building the project "check". The test
+     results will be shown in the VS output window.
+
+9. Test LLVM on the command line:
+
+   * The LLVM tests can be run by changing directory to the llvm source
+     directory and running:
+
+     .. code-block:: bat
+
+        C:\..\llvm> python ..\build\bin\llvm-lit --param build_config=Win32 --param build_mode=Debug --param llvm_site_config=../build/test/lit.site.cfg test
+
+     This example assumes that Python is in your PATH variable, you
+     have built a Win32 Debug version of llvm with a standard out of
+     line build. You should not see any unexpected failures, but will
+     see many unsupported tests and expected failures.
+
+     A specific test or test directory can be run with:
+
+     .. code-block:: bat
+
+        C:\..\llvm> python ..\build\bin\llvm-lit --param build_config=Win32 --param build_mode=Debug --param llvm_site_config=../build/test/lit.site.cfg test/path/to/test
+
+
+An Example Using the LLVM Tool Chain
+====================================
+
+1. First, create a simple C file, name it '``hello.c``':
+
+   .. code-block:: c
+
+      #include <stdio.h>
+      int main() {
+        printf("hello world\n");
+        return 0;
+      }
+
+2. Next, compile the C file into an LLVM bitcode file:
+
+   .. code-block:: bat
+
+      C:\..> clang -c hello.c -emit-llvm -o hello.bc
+
+   This will create the result file ``hello.bc`` which is the LLVM bitcode
+   that corresponds the compiled program and the library facilities that
+   it required.  You can execute this file directly using ``lli`` tool,
+   compile it to native assembly with the ``llc``, optimize or analyze it
+   further with the ``opt`` tool, etc.
+
+   Alternatively you can directly output an executable with clang with:
+
+   .. code-block:: bat
+
+      C:\..> clang hello.c -o hello.exe
+
+   The ``-o hello.exe`` is required because clang currently outputs ``a.out``
+   when neither ``-o`` nor ``-c`` are given.
+
+3. Run the program using the just-in-time compiler:
+
+   .. code-block:: bat
+
+      C:\..> lli hello.bc
+
+4. Use the ``llvm-dis`` utility to take a look at the LLVM assembly code:
+
+   .. code-block:: bat
+
+      C:\..> llvm-dis < hello.bc | more
+
+5. Compile the program to object code using the LLC code generator:
+
+   .. code-block:: bat
+
+      C:\..> llc -filetype=obj hello.bc
+
+6. Link to binary using Microsoft link:
+
+   .. code-block:: bat
+
+      C:\..> link hello.obj -defaultlib:libcmt
+
+7. Execute the native code program:
+
+   .. code-block:: bat
+
+      C:\..> hello.exe
+
+
+Common Problems
+===============
+If you are having problems building or using LLVM, or if you have any other
+general questions about LLVM, please consult the :doc:`Frequently Asked Questions
+<FAQ>` page.
+
+
+Links
+=====
+This document is just an **introduction** to how to use LLVM to do some simple
+things... there are many more interesting and complicated things that you can
+do that aren't documented here (but we'll gladly accept a patch if you want to
+write something up!).  For more information about LLVM, check out:
+
+* `LLVM homepage <http://llvm.org/>`_
+* `LLVM doxygen tree <http://llvm.org/doxygen/>`_
+

Added: www-releases/trunk/8.0.1/docs/_sources/GlobalISel.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.1/docs/_sources/GlobalISel.rst.txt?rev=368037&view=auto
==============================================================================
--- www-releases/trunk/8.0.1/docs/_sources/GlobalISel.rst.txt (added)
+++ www-releases/trunk/8.0.1/docs/_sources/GlobalISel.rst.txt Tue Aug  6 06:51:02 2019
@@ -0,0 +1,702 @@
+============================
+Global Instruction Selection
+============================
+
+.. contents::
+   :local:
+   :depth: 1
+
+.. warning::
+   This document is a work in progress.  It reflects the current state of the
+   implementation, as well as open design and implementation issues.
+
+Introduction
+============
+
+GlobalISel is a framework that provides a set of reusable passes and utilities
+for instruction selection --- translation from LLVM IR to target-specific
+Machine IR (MIR).
+
+GlobalISel is intended to be a replacement for SelectionDAG and FastISel, to
+solve three major problems:
+
+* **Performance** --- SelectionDAG introduces a dedicated intermediate
+  representation, which has a compile-time cost.
+
+  GlobalISel directly operates on the post-isel representation used by the
+  rest of the code generator, MIR.
+  It does require extensions to that representation to support arbitrary
+  incoming IR: :ref:`gmir`.
+
+* **Granularity** --- SelectionDAG and FastISel operate on individual basic
+  blocks, losing some global optimization opportunities.
+
+  GlobalISel operates on the whole function.
+
+* **Modularity** --- SelectionDAG and FastISel are radically different and share
+  very little code.
+
+  GlobalISel is built in a way that enables code reuse. For instance, both the
+  optimized and fast selectors share the :ref:`pipeline`, and targets can
+  configure that pipeline to better suit their needs.
+
+
+.. _gmir:
+
+Generic Machine IR
+==================
+
+Machine IR operates on physical registers, register classes, and (mostly)
+target-specific instructions.
+
+To bridge the gap with LLVM IR, GlobalISel introduces "generic" extensions to
+Machine IR:
+
+.. contents::
+   :local:
+
+``NOTE``:
+The generic MIR (GMIR) representation still contains references to IR
+constructs (such as ``GlobalValue``).  Removing those should let us write more
+accurate tests, or delete IR after building the initial MIR.  However, it is
+not part of the GlobalISel effort.
+
+.. _gmir-instructions:
+
+Generic Instructions
+--------------------
+
+The main addition is support for pre-isel generic machine instructions (e.g.,
+``G_ADD``).  Like other target-independent instructions (e.g., ``COPY`` or
+``PHI``), these are available on all targets.
+
+``TODO``:
+While we're progressively adding instructions, one kind in particular exposes
+interesting problems: compares and how to represent condition codes.
+Some targets (x86, ARM) have generic comparisons setting multiple flags,
+which are then used by predicated variants.
+Others (IR) specify the predicate in the comparison and users just get a single
+bit.  SelectionDAG uses SETCC/CONDBR vs BR_CC (and similar for select) to
+represent this.
+
+The ``MachineIRBuilder`` class wraps the ``MachineInstrBuilder`` and provides
+a convenient way to create these generic instructions.
+
+.. _gmir-gvregs:
+
+Generic Virtual Registers
+-------------------------
+
+Generic instructions operate on a new kind of register: "generic" virtual
+registers.  As opposed to non-generic vregs, they are not assigned a Register
+Class.  Instead, generic vregs have a :ref:`gmir-llt`, and can be assigned
+a :ref:`gmir-regbank`.
+
+``MachineRegisterInfo`` tracks the same information that it does for
+non-generic vregs (e.g., use-def chains).  Additionally, it also tracks the
+:ref:`gmir-llt` of the register, and, instead of the ``TargetRegisterClass``,
+its :ref:`gmir-regbank`, if any.
+
+For simplicity, most generic instructions only accept generic vregs:
+
+* instead of immediates, they use a gvreg defined by an instruction
+  materializing the immediate value (see :ref:`irtranslator-constants`).
+* instead of physical register, they use a gvreg defined by a ``COPY``.
+
+``NOTE``:
+We started with an alternative representation, where MRI tracks a size for
+each gvreg, and instructions have lists of types.
+That had two flaws: the type and size are redundant, and there was no generic
+way of getting a given operand's type (as there was no 1:1 mapping between
+instruction types and operands).
+We considered putting the type in some variant of MCInstrDesc instead:
+See `PR26576 <http://llvm.org/PR26576>`_: [GlobalISel] Generic MachineInstrs
+need a type but this increases the memory footprint of the related objects
+
+.. _gmir-regbank:
+
+Register Bank
+-------------
+
+A Register Bank is a set of register classes defined by the target.
+A bank has a size, which is the maximum store size of all covered classes.
+
+In general, cross-class copies inside a bank are expected to be cheaper than
+copies across banks.  They are also coalesceable by the register coalescer,
+whereas cross-bank copies are not.
+
+Also, equivalent operations can be performed on different banks using different
+instructions.
+
+For example, X86 can be seen as having 3 main banks: general-purpose, x87, and
+vector (which could be further split into a bank per domain for single vs
+double precision instructions).
+
+Register banks are described by a target-provided API,
+:ref:`RegisterBankInfo <api-registerbankinfo>`.
+
+.. _gmir-llt:
+
+Low Level Type
+--------------
+
+Additionally, every generic virtual register has a type, represented by an
+instance of the ``LLT`` class.
+
+Like ``EVT``/``MVT``/``Type``, it has no distinction between unsigned and signed
+integer types.  Furthermore, it also has no distinction between integer and
+floating-point types: it mainly conveys absolutely necessary information, such
+as size and number of vector lanes:
+
+* ``sN`` for scalars
+* ``pN`` for pointers
+* ``<N x sM>`` for vectors
+* ``unsized`` for labels, etc..
+
+``LLT`` is intended to replace the usage of ``EVT`` in SelectionDAG.
+
+Here are some LLT examples and their ``EVT`` and ``Type`` equivalents:
+
+   =============  =========  ======================================
+   LLT            EVT        IR Type
+   =============  =========  ======================================
+   ``s1``         ``i1``     ``i1``
+   ``s8``         ``i8``     ``i8``
+   ``s32``        ``i32``    ``i32``
+   ``s32``        ``f32``    ``float``
+   ``s17``        ``i17``    ``i17``
+   ``s16``        N/A        ``{i8, i8}``
+   ``s32``        N/A        ``[4 x i8]``
+   ``p0``         ``iPTR``   ``i8*``, ``i32*``, ``%opaque*``
+   ``p2``         ``iPTR``   ``i8 addrspace(2)*``
+   ``<4 x s32>``  ``v4f32``  ``<4 x float>``
+   ``s64``        ``v1f64``  ``<1 x double>``
+   ``<3 x s32>``  ``v3i32``  ``<3 x i32>``
+   ``unsized``    ``Other``  ``label``
+   =============  =========  ======================================
+
+
+Rationale: instructions already encode a specific interpretation of types
+(e.g., ``add`` vs. ``fadd``, or ``sdiv`` vs. ``udiv``).  Also encoding that
+information in the type system requires introducing bitcast with no real
+advantage for the selector.
+
+Pointer types are distinguished by address space.  This matches IR, as opposed
+to SelectionDAG where address space is an attribute on operations.
+This representation better supports pointers having different sizes depending
+on their addressspace.
+
+``NOTE``:
+Currently, LLT requires at least 2 elements in vectors, but some targets have
+the concept of a '1-element vector'.  Representing them as their underlying
+scalar type is a nice simplification.
+
+``TODO``:
+Currently, non-generic virtual registers, defined by non-pre-isel-generic
+instructions, cannot have a type, and thus cannot be used by a pre-isel generic
+instruction.  Instead, they are given a type using a COPY.  We could relax that
+and allow types on all vregs: this would reduce the number of MI required when
+emitting target-specific MIR early in the pipeline.  This should purely be
+a compile-time optimization.
+
+.. _pipeline:
+
+Core Pipeline
+=============
+
+There are four required passes, regardless of the optimization mode:
+
+.. contents::
+   :local:
+
+Additional passes can then be inserted at higher optimization levels or for
+specific targets. For example, to match the current SelectionDAG set of
+transformations: MachineCSE and a better MachineCombiner between every pass.
+
+``NOTE``:
+In theory, not all passes are always necessary.
+As an additional compile-time optimization, we could skip some of the passes by
+setting the relevant MachineFunction properties.  For instance, if the
+IRTranslator did not encounter any illegal instruction, it would set the
+``legalized`` property to avoid running the :ref:`milegalizer`.
+Similarly, we considered specializing the IRTranslator per-target to directly
+emit target-specific MI.
+However, we instead decided to keep the core pipeline simple, and focus on
+minimizing the overhead of the passes in the no-op cases.
+
+
+.. _irtranslator:
+
+IRTranslator
+------------
+
+This pass translates the input LLVM IR ``Function`` to a GMIR
+``MachineFunction``.
+
+``TODO``:
+This currently doesn't support the more complex instructions, in particular
+those involving control flow (``switch``, ``invoke``, ...).
+For ``switch`` in particular, we can initially use the ``LowerSwitch`` pass.
+
+.. _api-calllowering:
+
+API: CallLowering
+^^^^^^^^^^^^^^^^^
+
+The ``IRTranslator`` (using the ``CallLowering`` target-provided utility) also
+implements the ABI's calling convention by lowering calls, returns, and
+arguments to the appropriate physical register usage and instruction sequences.
+
+.. _irtranslator-aggregates:
+
+Aggregates
+^^^^^^^^^^
+
+Aggregates are lowered to a single scalar vreg.
+This differs from SelectionDAG's multiple vregs via ``GetValueVTs``.
+
+``TODO``:
+As some of the bits are undef (padding), we should consider augmenting the
+representation with additional metadata (in effect, caching computeKnownBits
+information on vregs).
+See `PR26161 <http://llvm.org/PR26161>`_: [GlobalISel] Value to vreg during
+IR to MachineInstr translation for aggregate type
+
+.. _irtranslator-constants:
+
+Constant Lowering
+^^^^^^^^^^^^^^^^^
+
+The ``IRTranslator`` lowers ``Constant`` operands into uses of gvregs defined
+by ``G_CONSTANT`` or ``G_FCONSTANT`` instructions.
+Currently, these instructions are always emitted in the entry basic block.
+In a ``MachineFunction``, each ``Constant`` is materialized by a single gvreg.
+
+This is beneficial as it allows us to fold constants into immediate operands
+during :ref:`instructionselect`, while still avoiding redundant materializations
+for expensive non-foldable constants.
+However, this can lead to unnecessary spills and reloads in an -O0 pipeline, as
+these vregs can have long live ranges.
+
+``TODO``:
+We're investigating better placement of these instructions, in fast and
+optimized modes.
+
+
+.. _milegalizer:
+
+Legalizer
+---------
+
+This pass transforms the generic machine instructions such that they are legal.
+
+A legal instruction is defined as:
+
+* **selectable** --- the target will later be able to select it to a
+  target-specific (non-generic) instruction.
+
+* operating on **vregs that can be loaded and stored** -- if necessary, the
+  target can select a ``G_LOAD``/``G_STORE`` of each gvreg operand.
+
+As opposed to SelectionDAG, there are no legalization phases.  In particular,
+'type' and 'operation' legalization are not separate.
+
+Legalization is iterative, and all state is contained in GMIR.  To maintain the
+validity of the intermediate code, instructions are introduced:
+
+* ``G_MERGE_VALUES`` --- concatenate multiple registers of the same
+  size into a single wider register.
+
+* ``G_UNMERGE_VALUES`` --- extract multiple registers of the same size
+  from a single wider register.
+
+* ``G_EXTRACT`` --- extract a simple register (as contiguous sequences of bits)
+  from a single wider register.
+
+As they are expected to be temporary byproducts of the legalization process,
+they are combined at the end of the :ref:`milegalizer` pass.
+If any remain, they are expected to always be selectable, using loads and stores
+if necessary.
+
+.. _api-legalizerinfo:
+
+API: LegalizerInfo
+^^^^^^^^^^^^^^^^^^
+
+Currently the API is broadly similar to SelectionDAG/TargetLowering, but
+extended in two ways:
+
+* The set of available actions is wider, avoiding the currently very
+  overloaded ``Expand`` (which can cover everything from libcalls to
+  scalarization depending on the node's opcode).
+
+* Since there's no separate type legalization, independently varying
+  types on an instruction can have independent actions. For example a
+  ``G_ICMP`` has 2 independent types: the result and the inputs; we need
+  to be able to say that comparing 2 s32s is OK, but the s1 result
+  must be dealt with in another way.
+
+As such, the primary key when deciding what to do is the ``InstrAspect``,
+essentially a tuple consisting of ``(Opcode, TypeIdx, Type)`` and mapping to a
+suggested course of action.
+
+An example use might be:
+
+  .. code-block:: c++
+
+    // The CPU can't deal with an s1 result, do something about it.
+    setAction({G_ICMP, 0, s1}, WidenScalar);
+    // An s32 input (the second type) is fine though.
+    setAction({G_ICMP, 1, s32}, Legal);
+
+
+``TODO``:
+An alternative worth investigating is to generalize the API to represent
+actions using ``std::function`` that implements the action, instead of explicit
+enum tokens (``Legal``, ``WidenScalar``, ...).
+
+``TODO``:
+Moreover, we could use TableGen to initially infer legality of operation from
+existing patterns (as any pattern we can select is by definition legal).
+Expanding that to describe legalization actions is a much larger but
+potentially useful project.
+
+.. _milegalizer-non-power-of-2:
+
+Non-power of 2 types
+^^^^^^^^^^^^^^^^^^^^
+
+``TODO``:
+Types which have a size that isn't a power of 2 aren't currently supported.
+The setAction API will probably require changes to support them.
+Even notionally explicitly specified operations only make suggestions
+like "Widen" or "Narrow". The eventual type is still unspecified and a
+search is performed by repeated doubling/halving of the type's
+size.
+This is incorrect for types that aren't a power of 2.  It's reasonable to
+expect we could construct an efficient set of side-tables for more general
+lookups though, encoding a map from the integers (i.e. the size of the current
+type) to types (the legal size).
+
+.. _milegalizer-vector:
+
+Vector types
+^^^^^^^^^^^^
+
+Vectors first get their element type legalized: ``<A x sB>`` becomes
+``<A x sC>`` such that at least one operation is legal with ``sC``.
+
+This is currently specified by the function ``setScalarInVectorAction``, called
+for example as:
+
+    setScalarInVectorAction(G_ICMP, s1, WidenScalar);
+
+Next the number of elements is chosen so that the entire operation is
+legal. This aspect is not controllable at the moment, but probably
+should be (you could imagine disagreements on whether a ``<2 x s8>``
+operation should be scalarized or extended to ``<8 x s8>``).
+
+
+.. _regbankselect:
+
+RegBankSelect
+-------------
+
+This pass constrains the :ref:`gmir-gvregs` operands of generic
+instructions to some :ref:`gmir-regbank`.
+
+It iteratively maps instructions to a set of per-operand bank assignment.
+The possible mappings are determined by the target-provided
+:ref:`RegisterBankInfo <api-registerbankinfo>`.
+The mapping is then applied, possibly introducing ``COPY`` instructions if
+necessary.
+
+It traverses the ``MachineFunction`` top down so that all operands are already
+mapped when analyzing an instruction.
+
+This pass could also remap target-specific instructions when beneficial.
+In the future, this could replace the ExeDepsFix pass, as we can directly
+select the best variant for an instruction that's available on multiple banks.
+
+.. _api-registerbankinfo:
+
+API: RegisterBankInfo
+^^^^^^^^^^^^^^^^^^^^^
+
+The ``RegisterBankInfo`` class describes multiple aspects of register banks.
+
+* **Banks**: ``addRegBankCoverage`` --- which register bank covers each
+  register class.
+
+* **Cross-Bank Copies**: ``copyCost`` --- the cost of a ``COPY`` from one bank
+  to another.
+
+* **Default Mapping**: ``getInstrMapping`` --- the default bank assignments for
+  a given instruction.
+
+* **Alternative Mapping**: ``getInstrAlternativeMapping`` --- the other
+  possible bank assignments for a given instruction.
+
+``TODO``:
+All this information should eventually be static and generated by TableGen,
+mostly using existing information augmented by bank descriptions.
+
+``TODO``:
+``getInstrMapping`` is currently separate from ``getInstrAlternativeMapping``
+because the latter is more expensive: as we move to static mapping info,
+both methods should be free, and we should merge them.
+
+.. _regbankselect-modes:
+
+RegBankSelect Modes
+^^^^^^^^^^^^^^^^^^^
+
+``RegBankSelect`` currently has two modes:
+
+* **Fast** --- For each instruction, pick a target-provided "default" bank
+  assignment.  This is the default at -O0.
+
+* **Greedy** --- For each instruction, pick the cheapest of several
+  target-provided bank assignment alternatives.
+
+We intend to eventually introduce an additional optimizing mode:
+
+* **Global** --- Across multiple instructions, pick the cheapest combination of
+  bank assignments.
+
+``NOTE``:
+On AArch64, we are considering using the Greedy mode even at -O0 (or perhaps at
+backend -O1):  because :ref:`gmir-llt` doesn't distinguish floating point from
+integer scalars, the default assignment for loads and stores is the integer
+bank, introducing cross-bank copies on most floating point operations.
+
+
+.. _instructionselect:
+
+InstructionSelect
+-----------------
+
+This pass transforms generic machine instructions into equivalent
+target-specific instructions.  It traverses the ``MachineFunction`` bottom-up,
+selecting uses before definitions, enabling trivial dead code elimination.
+
+.. _api-instructionselector:
+
+API: InstructionSelector
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+The target implements the ``InstructionSelector`` class, containing the
+target-specific selection logic proper.
+
+The instance is provided by the subtarget, so that it can specialize the
+selector by subtarget feature (with, e.g., a vector selector overriding parts
+of a general-purpose common selector).
+We might also want to parameterize it by MachineFunction, to enable selector
+variants based on function attributes like optsize.
+
+The simple API consists of:
+
+  .. code-block:: c++
+
+    virtual bool select(MachineInstr &MI)
+
+This target-provided method is responsible for mutating (or replacing) a
+possibly-generic MI into a fully target-specific equivalent.
+It is also responsible for doing the necessary constraining of gvregs into the
+appropriate register classes as well as passing through COPY instructions to
+the register allocator.
+
+The ``InstructionSelector`` can fold other instructions into the selected MI,
+by walking the use-def chain of the vreg operands.
+As GlobalISel is Global, this folding can occur across basic blocks.
+
+SelectionDAG Rule Imports
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+TableGen will import SelectionDAG rules and provide the following function to
+execute them:
+
+  .. code-block:: c++
+
+    bool selectImpl(MachineInstr &MI)
+
+The ``--stats`` option can be used to determine what proportion of rules were
+successfully imported. The easiest way to use this is to copy the
+``-gen-globalisel`` tablegen command from ``ninja -v`` and modify it.
+
+Similarly, the ``--warn-on-skipped-patterns`` option can be used to obtain the
+reasons that rules weren't imported. This can be used to focus on the most
+important rejection reasons.
+
+PatLeaf Predicates
+^^^^^^^^^^^^^^^^^^
+
+PatLeafs cannot be imported because their C++ is implemented in terms of
+``SDNode`` objects. PatLeafs that handle immediate predicates should be
+replaced by ``ImmLeaf``, ``IntImmLeaf``, or ``FPImmLeaf`` as appropriate.
+
+There's no standard answer for other PatLeafs. Some standard predicates have
+been baked into TableGen but this should not generally be done.
+
+Custom SDNodes
+^^^^^^^^^^^^^^
+
+Custom SDNodes should be mapped to Target Pseudos using ``GINodeEquiv``. This
+will cause the instruction selector to import them but you will also need to
+ensure the target pseudo is introduced to the MIR before the instruction
+selector. Any preceeding pass is suitable but the legalizer will be a
+particularly common choice.
+
+ComplexPatterns
+^^^^^^^^^^^^^^^
+
+ComplexPatterns cannot be imported because their C++ is implemented in terms of
+``SDNode`` objects. GlobalISel versions should be defined with
+``GIComplexOperandMatcher`` and mapped to ComplexPattern with
+``GIComplexPatternEquiv``.
+
+The following predicates are useful for porting ComplexPattern:
+
+* isBaseWithConstantOffset() - Check for base+offset structures
+* isOperandImmEqual() - Check for a particular constant
+* isObviouslySafeToFold() - Check for reasons an instruction can't be sunk and folded into another.
+
+There are some important points for the C++ implementation:
+
+* Don't modify MIR in the predicate
+* Renderer lambdas should capture by value to avoid use-after-free. They will be used after the predicate returns.
+* Only create instructions in a renderer lambda. GlobalISel won't clean up things you create but don't use.
+
+
+.. _maintainability:
+
+Maintainability
+===============
+
+.. _maintainability-iterative:
+
+Iterative Transformations
+-------------------------
+
+Passes are split into small, iterative transformations, with all state
+represented in the MIR.
+
+This differs from SelectionDAG (in particular, the legalizer) using various
+in-memory side-tables.
+
+
+.. _maintainability-mir:
+
+MIR Serialization
+-----------------
+
+.. FIXME: Update the MIRLangRef to include GMI additions.
+
+:ref:`gmir` is serializable (see :doc:`MIRLangRef`).
+Combined with :ref:`maintainability-iterative`, this enables much finer-grained
+testing, rather than requiring large and fragile IR-to-assembly tests.
+
+The current "stage" in the :ref:`pipeline` is represented by a set of
+``MachineFunctionProperties``:
+
+* ``legalized``
+* ``regBankSelected``
+* ``selected``
+
+
+.. _maintainability-verifier:
+
+MachineVerifier
+---------------
+
+The pass approach lets us use the ``MachineVerifier`` to enforce invariants.
+For instance, a ``regBankSelected`` function may not have gvregs without
+a bank.
+
+``TODO``:
+The ``MachineVerifier`` being monolithic, some of the checks we want to do
+can't be integrated to it:  GlobalISel is a separate library, so we can't
+directly reference it from CodeGen.  For instance, legality checks are
+currently done in RegBankSelect/InstructionSelect proper.  We could #ifdef out
+the checks, or we could add some sort of verifier API.
+
+
+.. _progress:
+
+Progress and Future Work
+========================
+
+The initial goal is to replace FastISel on AArch64.  The next step will be to
+replace SelectionDAG as the optimized ISel.
+
+``NOTE``:
+While we iterate on GlobalISel, we strive to avoid affecting the performance of
+SelectionDAG, FastISel, or the other MIR passes.  For instance, the types of
+:ref:`gmir-gvregs` are stored in a separate table in ``MachineRegisterInfo``,
+that is destroyed after :ref:`instructionselect`.
+
+.. _progress-fastisel:
+
+FastISel Replacement
+--------------------
+
+For the initial FastISel replacement, we intend to fallback to SelectionDAG on
+selection failures.
+
+Currently, compile-time of the fast pipeline is within 1.5x of FastISel.
+We're optimistic we can get to within 1.1/1.2x, but beating FastISel will be
+challenging given the multi-pass approach.
+Still, supporting all IR (via a complete legalizer) and avoiding the fallback
+to SelectionDAG in the worst case should enable better amortized performance
+than SelectionDAG+FastISel.
+
+``NOTE``:
+We considered never having a fallback to SelectionDAG, instead deciding early
+whether a given function is supported by GlobalISel or not.  The decision would
+be based on :ref:`milegalizer` queries.
+We abandoned that for two reasons:
+a) on IR inputs, we'd need to basically simulate the :ref:`irtranslator`;
+b) to be robust against unforeseen failures and to enable iterative
+improvements.
+
+.. _progress-targets:
+
+Support For Other Targets
+-------------------------
+
+In parallel, we're investigating adding support for other - ideally quite
+different - targets.  For instance, there is some initial AMDGPU support.
+
+
+.. _porting:
+
+Porting GlobalISel to A New Target
+==================================
+
+There are four major classes to implement by the target:
+
+* :ref:`CallLowering <api-calllowering>` --- lower calls, returns, and arguments
+  according to the ABI.
+* :ref:`RegisterBankInfo <api-registerbankinfo>` --- describe
+  :ref:`gmir-regbank` coverage, cross-bank copy cost, and the mapping of
+  operands onto banks for each instruction.
+* :ref:`LegalizerInfo <api-legalizerinfo>` --- describe what is legal, and how
+  to legalize what isn't.
+* :ref:`InstructionSelector <api-instructionselector>` --- select generic MIR
+  to target-specific MIR.
+
+Additionally:
+
+* ``TargetPassConfig`` --- create the passes constituting the pipeline,
+  including additional passes not included in the :ref:`pipeline`.
+
+.. _other_resources:
+
+Resources
+=========
+
+* `Global Instruction Selection - A Proposal by Quentin Colombet @LLVMDevMeeting 2015 <https://www.youtube.com/watch?v=F6GGbYtae3g>`_
+* `Global Instruction Selection - Status by Quentin Colombet, Ahmed Bougacha, and Tim Northover @LLVMDevMeeting 2016 <https://www.youtube.com/watch?v=6tfb344A7w8>`_
+* `GlobalISel - LLVM's Latest Instruction Selection Framework by Diana Picus @FOSDEM17 <https://www.youtube.com/watch?v=d6dF6E4BPeU>`_
+* GlobalISel: Past, Present, and Future by Quentin Colombet and Ahmed Bougacha @LLVMDevMeeting 2017
+* Head First into GlobalISel by Daniel Sanders, Aditya Nandakumar, and Justin Bogner @LLVMDevMeeting 2017

Added: www-releases/trunk/8.0.1/docs/_sources/GoldPlugin.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.1/docs/_sources/GoldPlugin.rst.txt?rev=368037&view=auto
==============================================================================
--- www-releases/trunk/8.0.1/docs/_sources/GoldPlugin.rst.txt (added)
+++ www-releases/trunk/8.0.1/docs/_sources/GoldPlugin.rst.txt Tue Aug  6 06:51:02 2019
@@ -0,0 +1,185 @@
+====================
+The LLVM gold plugin
+====================
+
+Introduction
+============
+
+Building with link time optimization requires cooperation from
+the system linker. LTO support on Linux systems is available via the
+`gold linker`_ which supports LTO via plugins. This is the same mechanism
+used by the `GCC LTO`_ project.
+
+The LLVM gold plugin implements the gold plugin interface on top of
+:ref:`libLTO`.  The same plugin can also be used by other tools such as
+``ar`` and ``nm``.  Note that ld.bfd from binutils version 2.21.51.0.2
+and above also supports LTO via plugins.  However, usage of the LLVM
+gold plugin with ld.bfd is not tested and therefore not officially
+supported or recommended.
+
+.. _`gold linker`: http://sourceware.org/binutils
+.. _`GCC LTO`: http://gcc.gnu.org/wiki/LinkTimeOptimization
+.. _`gold plugin interface`: http://gcc.gnu.org/wiki/whopr/driver
+
+.. _lto-how-to-build:
+
+How to build it
+===============
+
+You need to have gold with plugin support and build the LLVMgold plugin.
+The gold linker is installed as ld.gold. To see whether gold is the default
+on your system, run ``/usr/bin/ld -v``. It will report "GNU
+gold" or else "GNU ld" if not. If gold is already installed at
+``/usr/bin/ld.gold``, one option is to simply make that the default by
+backing up your existing ``/usr/bin/ld`` and creating a symbolic link
+with ``ln -s /usr/bin/ld.gold /usr/bin/ld``. Alternatively, you can build
+with clang's ``-fuse-ld=gold`` or add ``-fuse-ld=gold`` to LDFLAGS, which will
+cause the clang driver to invoke ``/usr/bin/ld.gold`` directly.
+
+If you have gold installed, check for plugin support by running
+``/usr/bin/ld.gold -plugin``. If it complains "missing argument" then
+you have plugin support. If not, and you get an error such as "unknown option",
+then you will either need to build gold or install a version with plugin
+support.
+
+* Download, configure and build gold with plugin support:
+
+  .. code-block:: bash
+
+     $ git clone --depth 1 git://sourceware.org/git/binutils-gdb.git binutils
+     $ mkdir build
+     $ cd build
+     $ ../binutils/configure --enable-gold --enable-plugins --disable-werror
+     $ make all-gold
+
+  That should leave you with ``build/gold/ld-new`` which supports
+  the ``-plugin`` option. Running ``make`` will additionally build
+  ``build/binutils/ar`` and ``nm-new`` binaries supporting plugins.
+
+  Once you're ready to switch to using gold, backup your existing
+  ``/usr/bin/ld`` then replace it with ``ld-new``. Alternatively, install
+  in ``/usr/bin/ld.gold`` and use ``-fuse-ld=gold`` as described earlier.
+
+  Optionally, add ``--enable-gold=default`` to the above configure invocation
+  to automatically install the newly built gold as the default linker with
+  ``make install``.
+
+* Build the LLVMgold plugin. Run CMake with
+  ``-DLLVM_BINUTILS_INCDIR=/path/to/binutils/include``.  The correct include
+  path will contain the file ``plugin-api.h``.
+
+Usage
+=====
+
+You should produce bitcode files from ``clang`` with the option
+``-flto``. This flag will also cause ``clang`` to look for the gold plugin in
+the ``lib`` directory under its prefix and pass the ``-plugin`` option to
+``ld``. It will not look for an alternate linker without ``-fuse-ld=gold``,
+which is why you otherwise need gold to be the installed system linker in
+your path.
+
+``ar`` and ``nm`` also accept the ``-plugin`` option and it's possible to
+to install ``LLVMgold.so`` to ``/usr/lib/bfd-plugins`` for a seamless setup.
+If you built your own gold, be sure to install the ``ar`` and ``nm-new`` you
+built to ``/usr/bin``.
+
+
+Example of link time optimization
+---------------------------------
+
+The following example shows a worked example of the gold plugin mixing LLVM
+bitcode and native code.
+
+.. code-block:: c
+
+   --- a.c ---
+   #include <stdio.h>
+
+   extern void foo1(void);
+   extern void foo4(void);
+
+   void foo2(void) {
+     printf("Foo2\n");
+   }
+
+   void foo3(void) {
+     foo4();
+   }
+
+   int main(void) {
+     foo1();
+   }
+
+   --- b.c ---
+   #include <stdio.h>
+
+   extern void foo2(void);
+
+   void foo1(void) {
+     foo2();
+   }
+
+   void foo4(void) {
+     printf("Foo4");
+   }
+
+.. code-block:: bash
+
+   --- command lines ---
+   $ clang -flto a.c -c -o a.o      # <-- a.o is LLVM bitcode file
+   $ ar q a.a a.o                   # <-- a.a is an archive with LLVM bitcode
+   $ clang b.c -c -o b.o            # <-- b.o is native object file
+   $ clang -flto a.a b.o -o main    # <-- link with LLVMgold plugin
+
+Gold informs the plugin that foo3 is never referenced outside the IR,
+leading LLVM to delete that function. However, unlike in the :ref:`libLTO
+example <libLTO-example>` gold does not currently eliminate foo4.
+
+Quickstart for using LTO with autotooled projects
+=================================================
+
+Once your system ``ld``, ``ar``, and ``nm`` all support LLVM bitcode,
+everything is in place for an easy to use LTO build of autotooled projects:
+
+* Follow the instructions :ref:`on how to build LLVMgold.so
+  <lto-how-to-build>`.
+
+* Install the newly built binutils to ``$PREFIX``
+
+* Copy ``Release/lib/LLVMgold.so`` to ``$PREFIX/lib/bfd-plugins/``
+
+* Set environment variables (``$PREFIX`` is where you installed clang and
+  binutils):
+
+  .. code-block:: bash
+
+     export CC="$PREFIX/bin/clang -flto"
+     export CXX="$PREFIX/bin/clang++ -flto"
+     export AR="$PREFIX/bin/ar"
+     export NM="$PREFIX/bin/nm"
+     export RANLIB=/bin/true #ranlib is not needed, and doesn't support .bc files in .a
+
+* Or you can just set your path:
+
+  .. code-block:: bash
+
+     export PATH="$PREFIX/bin:$PATH"
+     export CC="clang -flto"
+     export CXX="clang++ -flto"
+     export RANLIB=/bin/true
+* Configure and build the project as usual:
+
+  .. code-block:: bash
+
+     % ./configure && make && make check
+
+The environment variable settings may work for non-autotooled projects too,
+but you may need to set the ``LD`` environment variable as well.
+
+Licensing
+=========
+
+Gold is licensed under the GPLv3. LLVMgold uses the interface file
+``plugin-api.h`` from gold which means that the resulting ``LLVMgold.so``
+binary is also GPLv3. This can still be used to link non-GPLv3 programs
+just as much as gold could without the plugin.

Added: www-releases/trunk/8.0.1/docs/_sources/HowToAddABuilder.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.1/docs/_sources/HowToAddABuilder.rst.txt?rev=368037&view=auto
==============================================================================
--- www-releases/trunk/8.0.1/docs/_sources/HowToAddABuilder.rst.txt (added)
+++ www-releases/trunk/8.0.1/docs/_sources/HowToAddABuilder.rst.txt Tue Aug  6 06:51:02 2019
@@ -0,0 +1,106 @@
+===================================================================
+How To Add Your Build Configuration To LLVM Buildbot Infrastructure
+===================================================================
+
+Introduction
+============
+
+This document contains information about adding a build configuration and
+buildslave to private slave builder to LLVM Buildbot Infrastructure.
+
+Buildmasters
+============
+
+There are two buildmasters running.
+
+* The main buildmaster at `<http://lab.llvm.org:8011>`_. All builders attached
+  to this machine will notify commit authors every time they break the build.
+* The staging buildbot at `<http://lab.llvm.org:8014>`_. All builders attached
+  to this machine will be completely silent by default when the build is broken.
+  Builders for experimental backends should generally be attached to this
+  buildmaster.
+
+Steps To Add Builder To LLVM Buildbot
+=====================================
+Volunteers can provide their build machines to work as build slaves to
+public LLVM Buildbot.
+
+Here are the steps you can follow to do so:
+
+#. Check the existing build configurations to make sure the one you are
+   interested in is not covered yet or gets built on your computer much
+   faster than on the existing one. We prefer faster builds so developers
+   will get feedback sooner after changes get committed.
+
+#. The computer you will be registering with the LLVM buildbot
+   infrastructure should have all dependencies installed and you can
+   actually build your configuration successfully. Please check what degree
+   of parallelism (-j param) would give the fastest build.  You can build
+   multiple configurations on one computer.
+
+#. Install buildslave (currently we are using buildbot version 0.8.5).
+   Depending on the platform, buildslave could be available to download and
+   install with your package manager, or you can download it directly from
+   `<http://trac.buildbot.net>`_ and install it manually.
+
+#. Create a designated user account, your buildslave will be running under,
+   and set appropriate permissions.
+
+#. Choose the buildslave root directory (all builds will be placed under
+   it), buildslave access name and password the build master will be using
+   to authenticate your buildslave.
+
+#. Create a buildslave in context of that buildslave account.  Point it to
+   the **lab.llvm.org** port **9990** (see `Buildbot documentation,
+   Creating a slave
+   <http://docs.buildbot.net/current/tutorial/firstrun.html#creating-a-slave>`_
+   for more details) by running the following command:
+
+    .. code-block:: bash
+
+       $ buildslave create-slave <buildslave-root-directory> \
+                    lab.llvm.org:9990 \
+                    <buildslave-access-name> <buildslave-access-password>
+
+   To point a slave to silent master please use lab.llvm.org:9994 instead
+   of lab.llvm.org:9990.
+
+#. Fill the buildslave description and admin name/e-mail.  Here is an
+   example of the buildslave description::
+
+       Windows 7 x64
+       Core i7 (2.66GHz), 16GB of RAM
+
+       g++.exe (TDM-1 mingw32) 4.4.0
+       GNU Binutils 2.19.1
+       cmake version 2.8.4
+       Microsoft(R) 32-bit C/C++ Optimizing Compiler Version 16.00.40219.01 for 80x86
+
+#. Make sure you can actually start the buildslave successfully. Then set
+   up your buildslave to start automatically at the start up time.  See the
+   buildbot documentation for help.  You may want to restart your computer
+   to see if it works.
+
+#. Send a patch which adds your build slave and your builder to zorg.
+
+   * slaves are added to ``buildbot/osuosl/master/config/slaves.py``
+   * builders are added to ``buildbot/osuosl/master/config/builders.py``
+
+   Please make sure your builder name and its builddir are unique through the file.
+
+   It is possible to whitelist email addresses to unconditionally receive notifications
+   on build failure; for this you'll need to add an ``InformativeMailNotifier`` to
+   ``buildbot/osuosl/master/config/status.py``. This is particularly useful for the
+   staging buildmaster which is silent otherwise.
+
+#. Send the buildslave access name and the access password directly to
+   `Galina Kistanova <mailto:gkistanova at gmail.com>`_, and wait till she
+   will let you know that your changes are applied and buildmaster is
+   reconfigured.
+
+#. Check the status of your buildslave on the `Waterfall Display
+   <http://lab.llvm.org:8011/waterfall>`_ to make sure it is connected, and
+   ``http://lab.llvm.org:8011/buildslaves/<your-buildslave-name>`` to see
+   if administrator contact and slave information are correct.
+
+#. Wait for the first build to succeed and enjoy.

Added: www-releases/trunk/8.0.1/docs/_sources/HowToBuildOnARM.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.1/docs/_sources/HowToBuildOnARM.rst.txt?rev=368037&view=auto
==============================================================================
--- www-releases/trunk/8.0.1/docs/_sources/HowToBuildOnARM.rst.txt (added)
+++ www-releases/trunk/8.0.1/docs/_sources/HowToBuildOnARM.rst.txt Tue Aug  6 06:51:02 2019
@@ -0,0 +1,85 @@
+===================================================================
+How To Build On ARM
+===================================================================
+
+Introduction
+============
+
+This document contains information about building/testing LLVM and
+Clang on an ARM machine.
+
+This document is *NOT* tailored to help you cross-compile LLVM/Clang
+to ARM on another architecture, for example an x86_64 machine. To find
+out more about cross-compiling, please check :doc:`HowToCrossCompileLLVM`.
+
+Notes On Building LLVM/Clang on ARM
+=====================================
+Here are some notes on building/testing LLVM/Clang on ARM. Note that
+ARM encompasses a wide variety of CPUs; this advice is primarily based
+on the ARMv6 and ARMv7 architectures and may be inapplicable to older chips.
+
+#. The most popular Linaro/Ubuntu OS's for ARM boards, e.g., the
+   Pandaboard, have become hard-float platforms. There are a number of
+   choices when using CMake. Autoconf usage is deprecated as of 3.8.
+
+   Building LLVM/Clang in ``Relese`` mode is preferred since it consumes
+   a lot less memory. Otherwise, the building process will very likely
+   fail due to insufficient memory. It's also a lot quicker to only build
+   the relevant back-ends (ARM and AArch64), since it's very unlikely that
+   you'll use an ARM board to cross-compile to other arches. If you're
+   running Compiler-RT tests, also include the x86 back-end, or some tests
+   will fail.
+
+   .. code-block:: bash
+
+     cmake $LLVM_SRC_DIR -DCMAKE_BUILD_TYPE=Release \
+                         -DLLVM_TARGETS_TO_BUILD="ARM;X86;AArch64"
+
+   Other options you can use are:
+
+   .. code-block:: bash
+
+     Use Ninja instead of Make: "-G Ninja"
+     Build with assertions on: "-DLLVM_ENABLE_ASSERTIONS=True"
+     Force Python2: "-DPYTHON_EXECUTABLE=/usr/bin/python2"
+     Local (non-sudo) install path: "-DCMAKE_INSTALL_PREFIX=$HOME/llvm/instal"
+     CPU flags: "DCMAKE_C_FLAGS=-mcpu=cortex-a15" (same for CXX_FLAGS)
+
+   After that, just typing ``make -jN`` or ``ninja`` will build everything.
+   ``make -jN check-all`` or ``ninja check-all`` will run all compiler tests. For
+   running the test suite, please refer to :doc:`TestingGuide`.
+
+#. If you are building LLVM/Clang on an ARM board with 1G of memory or less,
+   please use ``gold`` rather then GNU ``ld``. In any case it is probably a good
+   idea to set up a swap partition, too.
+
+   .. code-block:: bash
+
+     $ sudo ln -sf /usr/bin/ld /usr/bin/ld.gold
+
+#. ARM development boards can be unstable and you may experience that cores
+   are disappearing, caches being flushed on every big.LITTLE switch, and
+   other similar issues.  To help ease the effect of this, set the Linux
+   scheduler to "performance" on **all** cores using this little script:
+
+   .. code-block:: bash
+
+      # The code below requires the package 'cpufrequtils' to be installed.
+      for ((cpu=0; cpu<`grep -c proc /proc/cpuinfo`; cpu++)); do
+          sudo cpufreq-set -c $cpu -g performance
+      done
+
+   Remember to turn that off after the build, or you may risk burning your
+   CPU. Most modern kernels don't need that, so only use it if you have
+   problems.
+
+#. Running the build on SD cards is ok, but they are more prone to failures
+   than good quality USB sticks, and those are more prone to failures than
+   external hard-drives (those are also a lot faster). So, at least, you
+   should consider to buy a fast USB stick.  On systems with a fast eMMC,
+   that's a good option too.
+
+#. Make sure you have a decent power supply (dozens of dollars worth) that can
+   provide *at least* 4 amperes, this is especially important if you use USB
+   devices with your board. Externally powered USB/SATA harddrives are even
+   better than having a good power supply.

Added: www-releases/trunk/8.0.1/docs/_sources/HowToBuildWithPGO.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.1/docs/_sources/HowToBuildWithPGO.rst.txt?rev=368037&view=auto
==============================================================================
--- www-releases/trunk/8.0.1/docs/_sources/HowToBuildWithPGO.rst.txt (added)
+++ www-releases/trunk/8.0.1/docs/_sources/HowToBuildWithPGO.rst.txt Tue Aug  6 06:51:02 2019
@@ -0,0 +1,163 @@
+=============================================================
+How To Build Clang and LLVM with Profile-Guided Optimizations
+=============================================================
+
+Introduction
+============
+
+PGO (Profile-Guided Optimization) allows your compiler to better optimize code
+for how it actually runs. Users report that applying this to Clang and LLVM can
+decrease overall compile time by 20%.
+
+This guide walks you through how to build Clang with PGO, though it also applies
+to other subprojects, such as LLD.
+
+
+Using the script
+================
+
+We have a script at ``utils/collect_and_build_with_pgo.py``. This script is
+tested on a few Linux flavors, and requires a checkout of LLVM, Clang, and
+compiler-rt. Despite the the name, it performs four clean builds of Clang, so it
+can take a while to run to completion. Please see the script's ``--help`` for
+more information on how to run it, and the different options available to you.
+If you want to get the most out of PGO for a particular use-case (e.g. compiling
+a specific large piece of software), please do read the section below on
+'benchmark' selection.
+
+Please note that this script is only tested on a few Linux distros. Patches to
+add support for other platforms, as always, are highly appreciated. :)
+
+This script also supports a ``--dry-run`` option, which causes it to print
+important commands instead of running them.
+
+
+Selecting 'benchmarks'
+======================
+
+PGO does best when the profiles gathered represent how the user plans to use the
+compiler. Notably, highly accurate profiles of llc building x86_64 code aren't
+incredibly helpful if you're going to be targeting ARM.
+
+By default, the script above does two things to get solid coverage. It:
+
+- runs all of Clang and LLVM's lit tests, and
+- uses the instrumented Clang to build Clang, LLVM, and all of the other
+  LLVM subprojects available to it.
+
+Together, these should give you:
+
+- solid coverage of building C++,
+- good coverage of building C,
+- great coverage of running optimizations,
+- great coverage of the backend for your host's architecture, and
+- some coverage of other architectures (if other arches are supported backends).
+
+Altogether, this should cover a diverse set of uses for Clang and LLVM. If you
+have very specific needs (e.g. your compiler is meant to compile a large browser
+for four different platforms, or similar), you may want to do something else.
+This is configurable in the script itself.
+
+
+Building Clang with PGO
+=======================
+
+If you prefer to not use the script, this briefly goes over how to build
+Clang/LLVM with PGO.
+
+First, you should have at least LLVM, Clang, and compiler-rt checked out
+locally.
+
+Next, at a high level, you're going to need to do the following:
+
+1. Build a standard Release Clang and the relevant libclang_rt.profile library
+2. Build Clang using the Clang you built above, but with instrumentation
+3. Use the instrumented Clang to generate profiles, which consists of two steps:
+
+  - Running the instrumented Clang/LLVM/lld/etc. on tasks that represent how
+    users will use said tools.
+  - Using a tool to convert the "raw" profiles generated above into a single,
+    final PGO profile.
+
+4. Build a final release Clang (along with whatever other binaries you need)
+   using the profile collected from your benchmark
+
+In more detailed steps:
+
+1. Configure a Clang build as you normally would. It's highly recommended that
+   you use the Release configuration for this, since it will be used to build
+   another Clang. Because you need Clang and supporting libraries, you'll want
+   to build the ``all`` target (e.g. ``ninja all`` or ``make -j4 all``).
+
+2. Configure a Clang build as above, but add the following CMake args:
+
+   - ``-DLLVM_BUILD_INSTRUMENTED=IR`` -- This causes us to build everything
+     with instrumentation.
+   - ``-DLLVM_BUILD_RUNTIME=No`` -- A few projects have bad interactions when
+     built with profiling, and aren't necessary to build. This flag turns them
+     off.
+   - ``-DCMAKE_C_COMPILER=/path/to/stage1/clang`` - Use the Clang we built in
+     step 1.
+   - ``-DCMAKE_CXX_COMPILER=/path/to/stage1/clang++`` - Same as above.
+
+ In this build directory, you simply need to build the ``clang`` target (and
+ whatever supporting tooling your benchmark requires).
+
+3. As mentioned above, this has two steps: gathering profile data, and then
+   massaging it into a useful form:
+
+   a. Build your benchmark using the Clang generated in step 2. The 'standard'
+      benchmark recommended is to run ``check-clang`` and ``check-llvm`` in your
+      instrumented Clang's build directory, and to do a full build of Clang/LLVM
+      using your instrumented Clang. So, create yet another build directory,
+      with the following CMake arguments:
+
+      - ``-DCMAKE_C_COMPILER=/path/to/stage2/clang`` - Use the Clang we built in
+        step 2.
+      - ``-DCMAKE_CXX_COMPILER=/path/to/stage2/clang++`` - Same as above.
+
+      If your users are fans of debug info, you may want to consider using
+      ``-DCMAKE_BUILD_TYPE=RelWithDebInfo`` instead of
+      ``-DCMAKE_BUILD_TYPE=Release``. This will grant better coverage of
+      debug info pieces of clang, but will take longer to complete and will
+      result in a much larger build directory.
+
+      It's recommended to build the ``all`` target with your instrumented Clang,
+      since more coverage is often better.
+
+  b. You should now have a few ``*.profraw`` files in
+     ``path/to/stage2/profiles/``. You need to merge these using
+     ``llvm-profdata`` (even if you only have one! The profile merge transforms
+     profraw into actual profile data, as well). This can be done with
+     ``/path/to/stage1/llvm-profdata merge
+     -output=/path/to/output/profdata.prof path/to/stage2/profiles/*.profraw``.
+
+4. Now, build your final, PGO-optimized Clang. To do this, you'll want to pass
+   the following additional arguments to CMake.
+
+   - ``-DLLVM_PROFDATA_FILE=/path/to/output/profdata.prof`` - Use the PGO
+     profile from the previous step.
+   - ``-DCMAKE_C_COMPILER=/path/to/stage1/clang`` - Use the Clang we built in
+     step 1.
+   - ``-DCMAKE_CXX_COMPILER=/path/to/stage1/clang++`` - Same as above.
+
+   From here, you can build whatever targets you need.
+
+   .. note::
+     You may see warnings about a mismatched profile in the build output. These
+     are generally harmless. To silence them, you can add
+     ``-DCMAKE_C_FLAGS='-Wno-backend-plugin'
+     -DCMAKE_CXX_FLAGS='-Wno-backend-plugin'`` to your CMake invocation.
+
+
+Congrats! You now have a Clang built with profile-guided optimizations, and you
+can delete all but the final build directory if you'd like.
+
+If this worked well for you and you plan on doing it often, there's a slight
+optimization that can be made: LLVM and Clang have a tool called tblgen that's
+built and run during the build process. While it's potentially nice to build
+this for coverage as part of step 3, none of your other builds should benefit
+from building it. You can pass the CMake options
+``-DCLANG_TABLEGEN=/path/to/stage1/bin/clang-tblgen
+-DLLVM_TABLEGEN=/path/to/stage1/bin/llvm-tblgen`` to steps 2 and onward to avoid
+these useless rebuilds.

Added: www-releases/trunk/8.0.1/docs/_sources/HowToCrossCompileBuiltinsOnArm.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.1/docs/_sources/HowToCrossCompileBuiltinsOnArm.rst.txt?rev=368037&view=auto
==============================================================================
--- www-releases/trunk/8.0.1/docs/_sources/HowToCrossCompileBuiltinsOnArm.rst.txt (added)
+++ www-releases/trunk/8.0.1/docs/_sources/HowToCrossCompileBuiltinsOnArm.rst.txt Tue Aug  6 06:51:02 2019
@@ -0,0 +1,290 @@
+===================================================================
+How to Cross Compile Compiler-rt Builtins For Arm
+===================================================================
+
+Introduction
+============
+
+This document contains information about building and testing the builtins part
+of compiler-rt for an Arm target, from an x86_64 Linux machine.
+
+While this document concentrates on Arm and Linux the general principles should
+apply to other targets supported by compiler-rt. Further contributions for other
+targets are welcome.
+
+The instructions in this document depend on libraries and programs external to
+LLVM, there are many ways to install and configure these dependencies so you
+may need to adapt the instructions here to fit your own local situation.
+
+Prerequisites
+=============
+
+In this use case we'll be using cmake on a Debian-based Linux system,
+cross-compiling from an x86_64 host to a hard-float Armv7-A target. We'll be
+using as many of the LLVM tools as we can, but it is possible to use GNU
+equivalents.
+
+ * ``A build of LLVM/clang for the llvm-tools and llvm-config``
+ * ``A clang executable with support for the ARM target``
+ * ``compiler-rt sources``
+ * ``The qemu-arm user mode emulator``
+ * ``An arm-linux-gnueabihf sysroot``
+
+In this example we will be using ninja.
+
+See https://compiler-rt.llvm.org/ for more information about the dependencies
+on clang and LLVM.
+
+See https://llvm.org/docs/GettingStarted.html for information about obtaining
+the source for LLVM and compiler-rt. Note that the getting started guide
+places compiler-rt in the projects subdirectory, but this is not essential and
+if you are using the BaremetalARM.cmake cache for v6-M, v7-M and v7-EM then
+compiler-rt must be placed in the runtimes directory.
+
+``qemu-arm`` should be available as a package for your Linux distribution.
+
+The most complicated of the prequisites to satisfy is the arm-linux-gnueabihf
+sysroot. In theory it is possible to use the Linux distributions multiarch
+support to fulfill the dependencies for building but unfortunately due to
+/usr/local/include being added some host includes are selected. The easiest way
+to supply a sysroot is to download the arm-linux-gnueabihf toolchain. This can
+be found at:
+* https://developer.arm.com/open-source/gnu-toolchain/gnu-a/downloads for gcc 8 and above
+* https://releases.linaro.org/components/toolchain/binaries/ for gcc 4.9 to 7.3
+
+Building compiler-rt builtins for Arm
+=====================================
+We will be doing a standalone build of compiler-rt using the following cmake
+options.
+
+* ``path/to/compiler-rt``
+* ``-G Ninja``
+* ``-DCOMPILER_RT_BUILD_BUILTINS=ON``
+* ``-DCOMPILER_RT_BUILD_SANITIZERS=OFF``
+* ``-DCOMPILER_RT_BUILD_XRAY=OFF``
+* ``-DCOMPILER_RT_BUILD_LIBFUZZER=OFF``
+* ``-DCOMPILER_RT_BUILD_PROFILE=OFF``
+* ``-DCMAKE_C_COMPILER=/path/to/clang``
+* ``-DCMAKE_AR=/path/to/llvm-ar``
+* ``-DCMAKE_NM=/path/to/llvm-nm``
+* ``-DCMAKE_RANLIB=/path/to/llvm-ranlib``
+* ``-DCMAKE_EXE_LINKER_FLAGS="-fuse-ld=lld"``
+* ``-DCMAKE_C_COMPILER_TARGET="arm-linux-gnueabihf"``
+* ``-DCMAKE_ASM_COMPILER_TARGET="arm-linux-gnueabihf"``
+* ``-DCOMPILER_RT_DEFAULT_TARGET_ONLY=ON``
+* ``-DLLVM_CONFIG_PATH=/path/to/llvm-config``
+* ``-DCMAKE_C_FLAGS="build-c-flags"``
+* ``-DCMAKE_ASM_FLAGS="build-c-flags"``
+
+The ``build-c-flags`` need to be sufficient to pass the C-make compiler check,
+compile compiler-rt, and if you are running the tests, compile and link the
+tests. When cross-compiling with clang we will need to pass sufficient
+information to generate code for the Arm architecture we are targeting. We will
+need to select the Arm target, select the Armv7-A architecture and choose
+between using Arm or Thumb.
+instructions. For example:
+
+* ``--target=arm-linux-gnueabihf``
+* ``-march=armv7a``
+* ``-mthumb``
+
+When using a GCC arm-linux-gnueabihf toolchain the following flags are
+needed to pick up the includes and libraries:
+
+* ``--gcc-toolchain=/path/to/dir/toolchain``
+* ``--sysroot=/path/to/toolchain/arm-linux-gnueabihf/libc``
+
+In this example we will be adding all of the command line options to both
+``CMAKE_C_FLAGS`` and ``CMAKE_ASM_FLAGS``. There are cmake flags to pass some of
+these options individually which can be used to simplify the ``build-c-flags``:
+
+* ``-DCMAKE_C_COMPILER_TARGET="arm-linux-gnueabihf"``
+* ``-DCMAKE_ASM_COMPILER_TARGET="arm-linux-gnueabihf"``
+* ``-DCMAKE_C_COMPILER_EXTERNAL_TOOLCHAIN=/path/to/dir/toolchain``
+* ``-DCMAKE_SYSROOT=/path/to/dir/toolchain/arm-linux-gnueabihf/libc``
+
+Once cmake has completed the builtins can be built with ``ninja builtins``
+
+Testing compiler-rt builtins using qemu-arm
+===========================================
+To test the builtins library we need to add a few more cmake flags to enable
+testing and set up the compiler and flags for test case. We must also tell
+cmake that we wish to run the tests on ``qemu-arm``.
+
+* ``-DCOMPILER_RT_EMULATOR="qemu-arm -L /path/to/armhf/sysroot``
+* ``-DCOMPILER_RT_INCLUDE_TESTS=ON``
+* ``-DCOMPILER_RT_TEST_COMPILER="/path/to/clang"``
+* ``-DCOMPILER_RT_TEST_COMPILER_CFLAGS="test-c-flags"``
+
+The ``/path/to/armhf/sysroot`` should be the same as the one passed to
+``--sysroot`` in the "build-c-flags".
+
+The "test-c-flags" need to include the target, architecture, gcc-toolchain,
+sysroot and arm/thumb state. The additional cmake defines such as
+``CMAKE_C_COMPILER_EXTERNAL_TOOLCHAIN`` do not apply when building the tests. If
+you have put all of these in "build-c-flags" then these can be repeated. If you
+wish to use lld to link the tests then add ``"-fuse-ld=lld``.
+
+Once cmake has completed the tests can be built and run using
+``ninja check-builtins``
+
+Troubleshooting
+===============
+
+The cmake try compile stage fails
+---------------------------------
+At an early stage cmake will attempt to compile and link a simple C program to
+test if the toolchain is working.
+
+This stage can often fail at link time if the ``--sysroot`` and
+``--gcc-toolchain`` options are not passed to the compiler. Check the
+``CMAKE_C_FLAGS`` and ``CMAKE_C_COMPILER_TARGET`` flags.
+
+It can be useful to build a simple example outside of cmake with your toolchain
+to make sure it is working. For example: ``clang --target=arm-linux-gnueabi -march=armv7a --gcc-toolchain=/path/to/gcc-toolchain --sysroot=/path/to/gcc-toolchain/arm-linux-gnueabihf/libc helloworld.c``
+
+Clang uses the host header files
+--------------------------------
+On debian based systems it is possible to install multiarch support for
+arm-linux-gnueabi and arm-linux-gnueabihf. In many cases clang can successfully
+use this multiarch support when -gcc-toolchain and --sysroot are not supplied.
+Unfortunately clang adds ``/usr/local/include`` before
+``/usr/include/arm-linux-gnueabihf`` leading to errors when compiling the hosts
+header files.
+
+The multiarch support is not sufficient to build the builtins you will need to
+use a separate arm-linux-gnueabihf toolchain.
+
+No target passed to clang
+-------------------------
+If clang is not given a target it will typically use the host target, this will
+not understand the Arm assembly language files resulting in error messages such
+as ``error: unknown directive .syntax unified``.
+
+You can check the clang invocation in the error message to see if there is no
+``--target`` or if it is set incorrectly. The cause is usually
+``CMAKE_ASM_FLAGS`` not containing ``--target`` or ``CMAKE_ASM_COMPILER_TARGET`` not being present.
+
+Arm architecture not given
+--------------------------
+The ``--target=arm-linux-gnueabihf`` will default to arm architecture v4t which
+cannot assemble the barrier instructions used in the synch_and_fetch source
+files.
+
+The cause is usually a missing ``-march=armv7a`` from the ``CMAKE_ASM_FLAGS``.
+
+Compiler-rt builds but the tests fail to build
+----------------------------------------------
+The flags used to build the tests are not the same as those used to build the
+builtins. The c flags are provided by ``COMPILER_RT_TEST_COMPILE_CFLAGS`` and
+the ``CMAKE_C_COMPILER_TARGET``, ``CMAKE_ASM_COMPILER_TARGET``,
+``CMAKE_C_COMPILER_EXTERNAL_TOOLCHAIN`` and ``CMAKE_SYSROOT`` flags are not
+applied.
+
+Make sure that ``COMPILER_RT_TEST_COMPILE_CFLAGS`` contains all the necessary
+information.
+
+
+Modifications for other Targets
+===============================
+
+Arm Soft-Float Target
+---------------------
+The instructions for the Arm hard-float target can be used for the soft-float
+target by substituting soft-float equivalents for the sysroot and target. The
+target to use is:
+
+* ``-DCMAKE_C_COMPILER_TARGET=arm-linux-gnueabi``
+
+Depending on whether you want to use floating point instructions or not you
+may need extra c-flags such as ``-mfloat-abi=softfp`` for use of floating-point
+instructions, and ``-mfloat-abi=soft -mfpu=none`` for software floating-point
+emulation.
+
+You will need to use an arm-linux-gnueabi GNU toolchain for soft-float.
+
+AArch64 Target
+--------------
+The instructions for Arm can be used for AArch64 by substituting AArch64
+equivalents for the sysroot, emulator and target.
+
+* ``-DCMAKE_C_COMPILER_TARGET=aarch64-linux-gnu``
+* ``-DCOMPILER_RT_EMULATOR="qemu-aarch64 -L /path/to/aarch64/sysroot``
+
+The CMAKE_C_FLAGS and COMPILER_RT_TEST_COMPILER_CFLAGS may also need:
+``"--sysroot=/path/to/aarch64/sysroot --gcc-toolchain=/path/to/gcc-toolchain"``
+
+Armv6-m, Armv7-m and Armv7E-M targets
+-------------------------------------
+To build and test the libraries using a similar method to Armv7-A is possible
+but more difficult. The main problems are:
+
+* There isn't a ``qemu-arm`` user-mode emulator for bare-metal systems. The ``qemu-system-arm`` can be used but this is significantly more difficult to setup.
+* The targets to compile compiler-rt have the suffix -none-eabi. This uses the BareMetal driver in clang and by default won't find the libraries needed to pass the cmake compiler check.
+
+As the Armv6-M, Armv7-M and Armv7E-M builds of compiler-rt only use instructions
+that are supported on Armv7-A we can still get most of the value of running the
+tests using the same ``qemu-arm`` that we used for Armv7-A by building and
+running the test cases for Armv7-A but using the builtins compiled for
+Armv6-M, Armv7-M or Armv7E-M. This will test that the builtins can be linked
+into a binary and execute the tests correctly but it will not catch if the
+builtins use instructions that are supported on Armv7-A but not Armv6-M,
+Armv7-M and Armv7E-M.
+
+To get the cmake compile test to pass you will need to pass the libraries
+needed to successfully link the cmake test via ``CMAKE_CFLAGS``. It is
+strongly recommended that you use version 3.6 or above of cmake so you can use
+``CMAKE_TRY_COMPILE_TARGET=STATIC_LIBRARY`` to skip the link step.
+
+* ``-DCMAKE_TRY_COMPILE_TARGET_TYPE=STATIC_LIBRARY``
+* ``-DCOMPILER_RT_OS_DIR="baremetal"``
+* ``-DCOMPILER_RT_BUILD_BUILTINS=ON``
+* ``-DCOMPILER_RT_BUILD_SANITIZERS=OFF``
+* ``-DCOMPILER_RT_BUILD_XRAY=OFF``
+* ``-DCOMPILER_RT_BUILD_LIBFUZZER=OFF``
+* ``-DCOMPILER_RT_BUILD_PROFILE=OFF``
+* ``-DCMAKE_C_COMPILER=${host_install_dir}/bin/clang``
+* ``-DCMAKE_C_COMPILER_TARGET="your *-none-eabi target"``
+* ``-DCMAKE_ASM_COMPILER_TARGET="your *-none-eabi target"``
+* ``-DCMAKE_AR=/path/to/llvm-ar``
+* ``-DCMAKE_NM=/path/to/llvm-nm``
+* ``-DCMAKE_RANLIB=/path/to/llvm-ranlib``
+* ``-DCOMPILER_RT_BAREMETAL_BUILD=ON``
+* ``-DCOMPILER_RT_DEFAULT_TARGET_ONLY=ON``
+* ``-DLLVM_CONFIG_PATH=/path/to/llvm-config``
+* ``-DCMAKE_C_FLAGS="build-c-flags"``
+* ``-DCMAKE_ASM_FLAGS="build-c-flags"``
+* ``-DCOMPILER_RT_EMULATOR="qemu-arm -L /path/to/armv7-A/sysroot"``
+* ``-DCOMPILER_RT_INCLUDE_TESTS=ON``
+* ``-DCOMPILER_RT_TEST_COMPILER="/path/to/clang"``
+* ``-DCOMPILER_RT_TEST_COMPILER_CFLAGS="test-c-flags"``
+
+The Armv6-M builtins will use the soft-float ABI. When compiling the tests for
+Armv7-A we must include ``"-mthumb -mfloat-abi=soft -mfpu=none"`` in the
+test-c-flags. We must use an Armv7-A soft-float abi sysroot for ``qemu-arm``.
+
+Depending on the linker used for the test cases you may encounter BuildAttribute
+mismatches between the M-profile objects from compiler-rt and the A-profile
+objects from the test. The lld linker does not check the profile
+BuildAttribute so it can be used to link the tests by adding -fuse-ld=lld to the
+``COMPILER_RT_TEST_COMPILER_CFLAGS``.
+
+Alternative using a cmake cache
+-------------------------------
+If you wish to build, but not test compiler-rt for Armv6-M, Armv7-M or Armv7E-M
+the easiest way is to use the BaremetalARM.cmake recipe in clang/cmake/caches.
+
+You will need a bare metal sysroot such as that provided by the GNU ARM
+Embedded toolchain.
+
+The libraries can be built with the cmake options:
+
+* ``-DBAREMETAL_ARMV6M_SYSROOT=/path/to/bare/metal/toolchain/arm-none-eabi``
+* ``-DBAREMETAL_ARMV7M_SYSROOT=/path/to/bare/metal/toolchain/arm-none-eabi``
+* ``-DBAREMETAL_ARMV7EM_SYSROOT=/path/to/bare/metal/toolchain/arm-none-eabi``
+* ``-C /path/to/llvm/source/tools/clang/cmake/caches/BaremetalARM.cmake``
+* ``/path/to/llvm``
+
+**Note** that for the recipe to work the compiler-rt source must be checked out
+into the directory llvm/runtimes. You will also need clang and lld checked out.
+

Added: www-releases/trunk/8.0.1/docs/_sources/HowToCrossCompileLLVM.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.1/docs/_sources/HowToCrossCompileLLVM.rst.txt?rev=368037&view=auto
==============================================================================
--- www-releases/trunk/8.0.1/docs/_sources/HowToCrossCompileLLVM.rst.txt (added)
+++ www-releases/trunk/8.0.1/docs/_sources/HowToCrossCompileLLVM.rst.txt Tue Aug  6 06:51:02 2019
@@ -0,0 +1,205 @@
+===================================================================
+How To Cross-Compile Clang/LLVM using Clang/LLVM
+===================================================================
+
+Introduction
+============
+
+This document contains information about building LLVM and
+Clang on host machine, targeting another platform.
+
+For more information on how to use Clang as a cross-compiler,
+please check http://clang.llvm.org/docs/CrossCompilation.html.
+
+TODO: Add MIPS and other platforms to this document.
+
+Cross-Compiling from x86_64 to ARM
+==================================
+
+In this use case, we'll be using CMake and Ninja, on a Debian-based Linux
+system, cross-compiling from an x86_64 host (most Intel and AMD chips
+nowadays) to a hard-float ARM target (most ARM targets nowadays).
+
+The packages you'll need are:
+
+ * ``cmake``
+ * ``ninja-build`` (from backports in Ubuntu)
+ * ``gcc-4.7-arm-linux-gnueabihf``
+ * ``gcc-4.7-multilib-arm-linux-gnueabihf``
+ * ``binutils-arm-linux-gnueabihf``
+ * ``libgcc1-armhf-cross``
+ * ``libsfgcc1-armhf-cross``
+ * ``libstdc++6-armhf-cross``
+ * ``libstdc++6-4.7-dev-armhf-cross``
+
+Configuring CMake
+-----------------
+
+For more information on how to configure CMake for LLVM/Clang,
+see :doc:`CMake`.
+
+The CMake options you need to add are:
+
+ * ``-DCMAKE_CROSSCOMPILING=True``
+ * ``-DCMAKE_INSTALL_PREFIX=<install-dir>``
+ * ``-DLLVM_TABLEGEN=<path-to-host-bin>/llvm-tblgen``
+ * ``-DCLANG_TABLEGEN=<path-to-host-bin>/clang-tblgen``
+ * ``-DLLVM_DEFAULT_TARGET_TRIPLE=arm-linux-gnueabihf``
+ * ``-DLLVM_TARGET_ARCH=ARM``
+ * ``-DLLVM_TARGETS_TO_BUILD=ARM``
+
+If you're compiling with GCC, you can use architecture options for your target,
+and the compiler driver will detect everything that it needs:
+
+ * ``-DCMAKE_CXX_FLAGS='-march=armv7-a -mcpu=cortex-a9 -mfloat-abi=hard'``
+
+However, if you're using Clang, the driver might not be up-to-date with your
+specific Linux distribution, version or GCC layout, so you'll need to fudge.
+
+In addition to the ones above, you'll also need:
+
+ * ``'-target arm-linux-gnueabihf'`` or whatever is the triple of your cross GCC.
+ * ``'--sysroot=/usr/arm-linux-gnueabihf'``, ``'--sysroot=/opt/gcc/arm-linux-gnueabihf'``
+   or whatever is the location of your GCC's sysroot (where /lib, /bin etc are).
+ * Appropriate use of ``-I`` and ``-L``, depending on how the cross GCC is installed,
+   and where are the libraries and headers.
+
+The TableGen options are required to compile it with the host compiler,
+so you'll need to compile LLVM (or at least ``llvm-tblgen``) to your host
+platform before you start. The CXX flags define the target, cpu (which in this case
+defaults to ``fpu=VFP3`` with NEON), and forcing the hard-float ABI. If you're
+using Clang as a cross-compiler, you will *also* have to set ``--sysroot``
+to make sure it picks the correct linker.
+
+When using Clang, it's important that you choose the triple to be *identical*
+to the GCC triple and the sysroot. This will make it easier for Clang to
+find the correct tools and include headers. But that won't mean all headers and
+libraries will be found. You'll still need to use ``-I`` and ``-L`` to locate
+those extra ones, depending on your distribution.
+
+Most of the time, what you want is to have a native compiler to the
+platform itself, but not others. So there's rarely a point in compiling
+all back-ends. For that reason, you should also set the
+``TARGETS_TO_BUILD`` to only build the back-end you're targeting to.
+
+You must set the ``CMAKE_INSTALL_PREFIX``, otherwise a ``ninja install``
+will copy ARM binaries to your root filesystem, which is not what you
+want.
+
+Hacks
+-----
+
+There are some bugs in current LLVM, which require some fiddling before
+running CMake:
+
+#. If you're using Clang as the cross-compiler, there is a problem in
+   the LLVM ARM back-end that is producing absolute relocations on
+   position-independent code (``R_ARM_THM_MOVW_ABS_NC``), so for now, you
+   should disable PIC:
+
+   .. code-block:: bash
+
+      -DLLVM_ENABLE_PIC=False
+
+   This is not a problem, since Clang/LLVM libraries are statically
+   linked anyway, it shouldn't affect much.
+
+#. The ARM libraries won't be installed in your system.
+   But the CMake prepare step, which checks for
+   dependencies, will check the *host* libraries, not the *target*
+   ones. Below there's a list of some dependencies, but your project could
+   have more, or this document could be outdated. You'll see the errors
+   while linking as an indication of that.
+
+   Debian based distros have a way to add ``multiarch``, which adds
+   a new architecture and allows you to install packages for those
+   systems. See https://wiki.debian.org/Multiarch/HOWTO for more info.
+
+   But not all distros will have that, and possibly not an easy way to
+   install them in any anyway, so you'll have to build/download
+   them separately.
+
+   A quick way of getting the libraries is to download them from
+   a distribution repository, like Debian (http://packages.debian.org/jessie/),
+   and download the missing libraries. Note that the ``libXXX``
+   will have the shared objects (``.so``) and the ``libXXX-dev`` will
+   give you the headers and the static (``.a``) library. Just in
+   case, download both.
+
+   The ones you need for ARM are: ``libtinfo``, ``zlib1g``,
+   ``libxml2`` and ``liblzma``. In the Debian repository you'll
+   find downloads for all architectures.
+
+   After you download and unpack all ``.deb`` packages, copy all
+   ``.so`` and ``.a`` to a directory, make the appropriate
+   symbolic links (if necessary), and add the relevant ``-L``
+   and ``-I`` paths to ``-DCMAKE_CXX_FLAGS`` above.
+
+
+Running CMake and Building
+--------------------------
+
+Finally, if you're using your platform compiler, run:
+
+   .. code-block:: bash
+
+     $ cmake -G Ninja <source-dir> <options above>
+
+If you're using Clang as the cross-compiler, run:
+
+   .. code-block:: bash
+
+     $ CC='clang' CXX='clang++' cmake -G Ninja <source-dir> <options above>
+
+If you have ``clang``/``clang++`` on the path, it should just work, and special
+Ninja files will be created in the build directory. I strongly suggest
+you to run ``cmake`` on a separate build directory, *not* inside the
+source tree.
+
+To build, simply type:
+
+   .. code-block:: bash
+
+     $ ninja
+
+It should automatically find out how many cores you have, what are
+the rules that needs building and will build the whole thing.
+
+You can't run ``ninja check-all`` on this tree because the created
+binaries are targeted to ARM, not x86_64.
+
+Installing and Using
+--------------------
+
+After the LLVM/Clang has built successfully, you should install it
+via:
+
+   .. code-block:: bash
+
+     $ ninja install
+
+which will create a sysroot on the install-dir. You can then tar
+that directory into a binary with the full triple name (for easy
+identification), like:
+
+   .. code-block:: bash
+
+     $ ln -sf <install-dir> arm-linux-gnueabihf-clang
+     $ tar zchf arm-linux-gnueabihf-clang.tar.gz arm-linux-gnueabihf-clang
+
+If you copy that tarball to your target board, you'll be able to use
+it for running the test-suite, for example. Follow the guidelines at
+http://llvm.org/docs/lnt/quickstart.html, unpack the tarball in the
+test directory, and use options:
+
+   .. code-block:: bash
+
+     $ ./sandbox/bin/python sandbox/bin/lnt runtest nt \
+         --sandbox sandbox \
+         --test-suite `pwd`/test-suite \
+         --cc `pwd`/arm-linux-gnueabihf-clang/bin/clang \
+         --cxx `pwd`/arm-linux-gnueabihf-clang/bin/clang++
+
+Remember to add the ``-jN`` options to ``lnt`` to the number of CPUs
+on your board. Also, the path to your clang has to be absolute, so
+you'll need the `pwd` trick above.




More information about the llvm-commits mailing list