[www-releases] r372328 - Check in 9.0.0 source and docs
Hans Wennborg via llvm-commits
llvm-commits at lists.llvm.org
Thu Sep 19 07:32:55 PDT 2019
Added: www-releases/trunk/9.0.0/docs/_sources/BitCodeFormat.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/_sources/BitCodeFormat.rst.txt?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/_sources/BitCodeFormat.rst.txt (added)
+++ www-releases/trunk/9.0.0/docs/_sources/BitCodeFormat.rst.txt Thu Sep 19 07:32:46 2019
@@ -0,0 +1,1355 @@
+.. role:: raw-html(raw)
+ :format: html
+
+========================
+LLVM Bitcode File Format
+========================
+
+.. contents::
+ :local:
+
+Abstract
+========
+
+This document describes the LLVM bitstream file format and the encoding of the
+LLVM IR into it.
+
+Overview
+========
+
+What is commonly known as the LLVM bitcode file format (also, sometimes
+anachronistically known as bytecode) is actually two things: a `bitstream
+container format`_ and an `encoding of LLVM IR`_ into the container format.
+
+The bitstream format is an abstract encoding of structured data, very similar to
+XML in some ways. Like XML, bitstream files contain tags, and nested
+structures, and you can parse the file without having to understand the tags.
+Unlike XML, the bitstream format is a binary encoding, and unlike XML it
+provides a mechanism for the file to self-describe "abbreviations", which are
+effectively size optimizations for the content.
+
+LLVM IR files may be optionally embedded into a `wrapper`_ structure, or in a
+`native object file`_. Both of these mechanisms make it easy to embed extra
+data along with LLVM IR files.
+
+This document first describes the LLVM bitstream format, describes the wrapper
+format, then describes the record structure used by LLVM IR files.
+
+.. _bitstream container format:
+
+Bitstream Format
+================
+
+The bitstream format is literally a stream of bits, with a very simple
+structure. This structure consists of the following concepts:
+
+* A "`magic number`_" that identifies the contents of the stream.
+
+* Encoding `primitives`_ like variable bit-rate integers.
+
+* `Blocks`_, which define nested content.
+
+* `Data Records`_, which describe entities within the file.
+
+* Abbreviations, which specify compression optimizations for the file.
+
+Note that the :doc:`llvm-bcanalyzer <CommandGuide/llvm-bcanalyzer>` tool can be
+used to dump and inspect arbitrary bitstreams, which is very useful for
+understanding the encoding.
+
+.. _magic number:
+
+Magic Numbers
+-------------
+
+The first four bytes of a bitstream are used as an application-specific magic
+number. Generic bitcode tools may look at the first four bytes to determine
+whether the stream is a known stream type. However, these tools should *not*
+determine whether a bitstream is valid based on its magic number alone. New
+application-specific bitstream formats are being developed all the time; tools
+should not reject them just because they have a hitherto unseen magic number.
+
+.. _primitives:
+
+Primitives
+----------
+
+A bitstream literally consists of a stream of bits, which are read in order
+starting with the least significant bit of each byte. The stream is made up of
+a number of primitive values that encode a stream of unsigned integer values.
+These integers are encoded in two ways: either as `Fixed Width Integers`_ or as
+`Variable Width Integers`_.
+
+.. _Fixed Width Integers:
+.. _fixed-width value:
+
+Fixed Width Integers
+^^^^^^^^^^^^^^^^^^^^
+
+Fixed-width integer values have their low bits emitted directly to the file.
+For example, a 3-bit integer value encodes 1 as 001. Fixed width integers are
+used when there are a well-known number of options for a field. For example,
+boolean values are usually encoded with a 1-bit wide integer.
+
+.. _Variable Width Integers:
+.. _Variable Width Integer:
+.. _variable-width value:
+
+Variable Width Integers
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Variable-width integer (VBR) values encode values of arbitrary size, optimizing
+for the case where the values are small. Given a 4-bit VBR field, any 3-bit
+value (0 through 7) is encoded directly, with the high bit set to zero. Values
+larger than N-1 bits emit their bits in a series of N-1 bit chunks, where all
+but the last set the high bit.
+
+For example, the value 27 (0x1B) is encoded as 1011 0011 when emitted as a vbr4
+value. The first set of four bits indicates the value 3 (011) with a
+continuation piece (indicated by a high bit of 1). The next word indicates a
+value of 24 (011 << 3) with no continuation. The sum (3+24) yields the value
+27.
+
+.. _char6-encoded value:
+
+6-bit characters
+^^^^^^^^^^^^^^^^
+
+6-bit characters encode common characters into a fixed 6-bit field. They
+represent the following characters with the following 6-bit values:
+
+::
+
+ 'a' .. 'z' --- 0 .. 25
+ 'A' .. 'Z' --- 26 .. 51
+ '0' .. '9' --- 52 .. 61
+ '.' --- 62
+ '_' --- 63
+
+This encoding is only suitable for encoding characters and strings that consist
+only of the above characters. It is completely incapable of encoding characters
+not in the set.
+
+Word Alignment
+^^^^^^^^^^^^^^
+
+Occasionally, it is useful to emit zero bits until the bitstream is a multiple
+of 32 bits. This ensures that the bit position in the stream can be represented
+as a multiple of 32-bit words.
+
+Abbreviation IDs
+----------------
+
+A bitstream is a sequential series of `Blocks`_ and `Data Records`_. Both of
+these start with an abbreviation ID encoded as a fixed-bitwidth field. The
+width is specified by the current block, as described below. The value of the
+abbreviation ID specifies either a builtin ID (which have special meanings,
+defined below) or one of the abbreviation IDs defined for the current block by
+the stream itself.
+
+The set of builtin abbrev IDs is:
+
+* 0 - `END_BLOCK`_ --- This abbrev ID marks the end of the current block.
+
+* 1 - `ENTER_SUBBLOCK`_ --- This abbrev ID marks the beginning of a new
+ block.
+
+* 2 - `DEFINE_ABBREV`_ --- This defines a new abbreviation.
+
+* 3 - `UNABBREV_RECORD`_ --- This ID specifies the definition of an
+ unabbreviated record.
+
+Abbreviation IDs 4 and above are defined by the stream itself, and specify an
+`abbreviated record encoding`_.
+
+.. _Blocks:
+
+Blocks
+------
+
+Blocks in a bitstream denote nested regions of the stream, and are identified by
+a content-specific id number (for example, LLVM IR uses an ID of 12 to represent
+function bodies). Block IDs 0-7 are reserved for `standard blocks`_ whose
+meaning is defined by Bitcode; block IDs 8 and greater are application
+specific. Nested blocks capture the hierarchical structure of the data encoded
+in it, and various properties are associated with blocks as the file is parsed.
+Block definitions allow the reader to efficiently skip blocks in constant time
+if the reader wants a summary of blocks, or if it wants to efficiently skip data
+it does not understand. The LLVM IR reader uses this mechanism to skip function
+bodies, lazily reading them on demand.
+
+When reading and encoding the stream, several properties are maintained for the
+block. In particular, each block maintains:
+
+#. A current abbrev id width. This value starts at 2 at the beginning of the
+ stream, and is set every time a block record is entered. The block entry
+ specifies the abbrev id width for the body of the block.
+
+#. A set of abbreviations. Abbreviations may be defined within a block, in
+ which case they are only defined in that block (neither subblocks nor
+ enclosing blocks see the abbreviation). Abbreviations can also be defined
+ inside a `BLOCKINFO`_ block, in which case they are defined in all blocks
+ that match the ID that the ``BLOCKINFO`` block is describing.
+
+As sub blocks are entered, these properties are saved and the new sub-block has
+its own set of abbreviations, and its own abbrev id width. When a sub-block is
+popped, the saved values are restored.
+
+.. _ENTER_SUBBLOCK:
+
+ENTER_SUBBLOCK Encoding
+^^^^^^^^^^^^^^^^^^^^^^^
+
+:raw-html:`<tt>`
+[ENTER_SUBBLOCK, blockid\ :sub:`vbr8`, newabbrevlen\ :sub:`vbr4`, <align32bits>, blocklen_32]
+:raw-html:`</tt>`
+
+The ``ENTER_SUBBLOCK`` abbreviation ID specifies the start of a new block
+record. The ``blockid`` value is encoded as an 8-bit VBR identifier, and
+indicates the type of block being entered, which can be a `standard block`_ or
+an application-specific block. The ``newabbrevlen`` value is a 4-bit VBR, which
+specifies the abbrev id width for the sub-block. The ``blocklen`` value is a
+32-bit aligned value that specifies the size of the subblock in 32-bit
+words. This value allows the reader to skip over the entire block in one jump.
+
+.. _END_BLOCK:
+
+END_BLOCK Encoding
+^^^^^^^^^^^^^^^^^^
+
+``[END_BLOCK, <align32bits>]``
+
+The ``END_BLOCK`` abbreviation ID specifies the end of the current block record.
+Its end is aligned to 32-bits to ensure that the size of the block is an even
+multiple of 32-bits.
+
+.. _Data Records:
+
+Data Records
+------------
+
+Data records consist of a record code and a number of (up to) 64-bit integer
+values. The interpretation of the code and values is application specific and
+may vary between different block types. Records can be encoded either using an
+unabbrev record, or with an abbreviation. In the LLVM IR format, for example,
+there is a record which encodes the target triple of a module. The code is
+``MODULE_CODE_TRIPLE``, and the values of the record are the ASCII codes for the
+characters in the string.
+
+.. _UNABBREV_RECORD:
+
+UNABBREV_RECORD Encoding
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+:raw-html:`<tt>`
+[UNABBREV_RECORD, code\ :sub:`vbr6`, numops\ :sub:`vbr6`, op0\ :sub:`vbr6`, op1\ :sub:`vbr6`, ...]
+:raw-html:`</tt>`
+
+An ``UNABBREV_RECORD`` provides a default fallback encoding, which is both
+completely general and extremely inefficient. It can describe an arbitrary
+record by emitting the code and operands as VBRs.
+
+For example, emitting an LLVM IR target triple as an unabbreviated record
+requires emitting the ``UNABBREV_RECORD`` abbrevid, a vbr6 for the
+``MODULE_CODE_TRIPLE`` code, a vbr6 for the length of the string, which is equal
+to the number of operands, and a vbr6 for each character. Because there are no
+letters with values less than 32, each letter would need to be emitted as at
+least a two-part VBR, which means that each letter would require at least 12
+bits. This is not an efficient encoding, but it is fully general.
+
+.. _abbreviated record encoding:
+
+Abbreviated Record Encoding
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``[<abbrevid>, fields...]``
+
+An abbreviated record is a abbreviation id followed by a set of fields that are
+encoded according to the `abbreviation definition`_. This allows records to be
+encoded significantly more densely than records encoded with the
+`UNABBREV_RECORD`_ type, and allows the abbreviation types to be specified in
+the stream itself, which allows the files to be completely self describing. The
+actual encoding of abbreviations is defined below.
+
+The record code, which is the first field of an abbreviated record, may be
+encoded in the abbreviation definition (as a literal operand) or supplied in the
+abbreviated record (as a Fixed or VBR operand value).
+
+.. _abbreviation definition:
+
+Abbreviations
+-------------
+
+Abbreviations are an important form of compression for bitstreams. The idea is
+to specify a dense encoding for a class of records once, then use that encoding
+to emit many records. It takes space to emit the encoding into the file, but
+the space is recouped (hopefully plus some) when the records that use it are
+emitted.
+
+Abbreviations can be determined dynamically per client, per file. Because the
+abbreviations are stored in the bitstream itself, different streams of the same
+format can contain different sets of abbreviations according to the needs of the
+specific stream. As a concrete example, LLVM IR files usually emit an
+abbreviation for binary operators. If a specific LLVM module contained no or
+few binary operators, the abbreviation does not need to be emitted.
+
+.. _DEFINE_ABBREV:
+
+DEFINE_ABBREV Encoding
+^^^^^^^^^^^^^^^^^^^^^^
+
+:raw-html:`<tt>`
+[DEFINE_ABBREV, numabbrevops\ :sub:`vbr5`, abbrevop0, abbrevop1, ...]
+:raw-html:`</tt>`
+
+A ``DEFINE_ABBREV`` record adds an abbreviation to the list of currently defined
+abbreviations in the scope of this block. This definition only exists inside
+this immediate block --- it is not visible in subblocks or enclosing blocks.
+Abbreviations are implicitly assigned IDs sequentially starting from 4 (the
+first application-defined abbreviation ID). Any abbreviations defined in a
+``BLOCKINFO`` record for the particular block type receive IDs first, in order,
+followed by any abbreviations defined within the block itself. Abbreviated data
+records reference this ID to indicate what abbreviation they are invoking.
+
+An abbreviation definition consists of the ``DEFINE_ABBREV`` abbrevid followed
+by a VBR that specifies the number of abbrev operands, then the abbrev operands
+themselves. Abbreviation operands come in three forms. They all start with a
+single bit that indicates whether the abbrev operand is a literal operand (when
+the bit is 1) or an encoding operand (when the bit is 0).
+
+#. Literal operands --- :raw-html:`<tt>` [1\ :sub:`1`, litvalue\
+ :sub:`vbr8`] :raw-html:`</tt>` --- Literal operands specify that the value in
+ the result is always a single specific value. This specific value is emitted
+ as a vbr8 after the bit indicating that it is a literal operand.
+
+#. Encoding info without data --- :raw-html:`<tt>` [0\ :sub:`1`, encoding\
+ :sub:`3`] :raw-html:`</tt>` --- Operand encodings that do not have extra data
+ are just emitted as their code.
+
+#. Encoding info with data --- :raw-html:`<tt>` [0\ :sub:`1`, encoding\
+ :sub:`3`, value\ :sub:`vbr5`] :raw-html:`</tt>` --- Operand encodings that do
+ have extra data are emitted as their code, followed by the extra data.
+
+The possible operand encodings are:
+
+* Fixed (code 1): The field should be emitted as a `fixed-width value`_, whose
+ width is specified by the operand's extra data.
+
+* VBR (code 2): The field should be emitted as a `variable-width value`_, whose
+ width is specified by the operand's extra data.
+
+* Array (code 3): This field is an array of values. The array operand has no
+ extra data, but expects another operand to follow it, indicating the element
+ type of the array. When reading an array in an abbreviated record, the first
+ integer is a vbr6 that indicates the array length, followed by the encoded
+ elements of the array. An array may only occur as the last operand of an
+ abbreviation (except for the one final operand that gives the array's
+ type).
+
+* Char6 (code 4): This field should be emitted as a `char6-encoded value`_.
+ This operand type takes no extra data. Char6 encoding is normally used as an
+ array element type.
+
+* Blob (code 5): This field is emitted as a vbr6, followed by padding to a
+ 32-bit boundary (for alignment) and an array of 8-bit objects. The array of
+ bytes is further followed by tail padding to ensure that its total length is a
+ multiple of 4 bytes. This makes it very efficient for the reader to decode
+ the data without having to make a copy of it: it can use a pointer to the data
+ in the mapped in file and poke directly at it. A blob may only occur as the
+ last operand of an abbreviation.
+
+For example, target triples in LLVM modules are encoded as a record of the form
+``[TRIPLE, 'a', 'b', 'c', 'd']``. Consider if the bitstream emitted the
+following abbrev entry:
+
+::
+
+ [0, Fixed, 4]
+ [0, Array]
+ [0, Char6]
+
+When emitting a record with this abbreviation, the above entry would be emitted
+as:
+
+:raw-html:`<tt><blockquote>`
+[4\ :sub:`abbrevwidth`, 2\ :sub:`4`, 4\ :sub:`vbr6`, 0\ :sub:`6`, 1\ :sub:`6`, 2\ :sub:`6`, 3\ :sub:`6`]
+:raw-html:`</blockquote></tt>`
+
+These values are:
+
+#. The first value, 4, is the abbreviation ID for this abbreviation.
+
+#. The second value, 2, is the record code for ``TRIPLE`` records within LLVM IR
+ file ``MODULE_BLOCK`` blocks.
+
+#. The third value, 4, is the length of the array.
+
+#. The rest of the values are the char6 encoded values for ``"abcd"``.
+
+With this abbreviation, the triple is emitted with only 37 bits (assuming a
+abbrev id width of 3). Without the abbreviation, significantly more space would
+be required to emit the target triple. Also, because the ``TRIPLE`` value is
+not emitted as a literal in the abbreviation, the abbreviation can also be used
+for any other string value.
+
+.. _standard blocks:
+.. _standard block:
+
+Standard Blocks
+---------------
+
+In addition to the basic block structure and record encodings, the bitstream
+also defines specific built-in block types. These block types specify how the
+stream is to be decoded or other metadata. In the future, new standard blocks
+may be added. Block IDs 0-7 are reserved for standard blocks.
+
+.. _BLOCKINFO:
+
+#0 - BLOCKINFO Block
+^^^^^^^^^^^^^^^^^^^^
+
+The ``BLOCKINFO`` block allows the description of metadata for other blocks.
+The currently specified records are:
+
+::
+
+ [SETBID (#1), blockid]
+ [DEFINE_ABBREV, ...]
+ [BLOCKNAME, ...name...]
+ [SETRECORDNAME, RecordID, ...name...]
+
+The ``SETBID`` record (code 1) indicates which block ID is being described.
+``SETBID`` records can occur multiple times throughout the block to change which
+block ID is being described. There must be a ``SETBID`` record prior to any
+other records.
+
+Standard ``DEFINE_ABBREV`` records can occur inside ``BLOCKINFO`` blocks, but
+unlike their occurrence in normal blocks, the abbreviation is defined for blocks
+matching the block ID we are describing, *not* the ``BLOCKINFO`` block
+itself. The abbreviations defined in ``BLOCKINFO`` blocks receive abbreviation
+IDs as described in `DEFINE_ABBREV`_.
+
+The ``BLOCKNAME`` record (code 2) can optionally occur in this block. The
+elements of the record are the bytes of the string name of the block.
+llvm-bcanalyzer can use this to dump out bitcode files symbolically.
+
+The ``SETRECORDNAME`` record (code 3) can also optionally occur in this block.
+The first operand value is a record ID number, and the rest of the elements of
+the record are the bytes for the string name of the record. llvm-bcanalyzer can
+use this to dump out bitcode files symbolically.
+
+Note that although the data in ``BLOCKINFO`` blocks is described as "metadata,"
+the abbreviations they contain are essential for parsing records from the
+corresponding blocks. It is not safe to skip them.
+
+.. _wrapper:
+
+Bitcode Wrapper Format
+======================
+
+Bitcode files for LLVM IR may optionally be wrapped in a simple wrapper
+structure. This structure contains a simple header that indicates the offset
+and size of the embedded BC file. This allows additional information to be
+stored alongside the BC file. The structure of this file header is:
+
+:raw-html:`<tt><blockquote>`
+[Magic\ :sub:`32`, Version\ :sub:`32`, Offset\ :sub:`32`, Size\ :sub:`32`, CPUType\ :sub:`32`]
+:raw-html:`</blockquote></tt>`
+
+Each of the fields are 32-bit fields stored in little endian form (as with the
+rest of the bitcode file fields). The Magic number is always ``0x0B17C0DE`` and
+the version is currently always ``0``. The Offset field is the offset in bytes
+to the start of the bitcode stream in the file, and the Size field is the size
+in bytes of the stream. CPUType is a target-specific value that can be used to
+encode the CPU of the target.
+
+.. _native object file:
+
+Native Object File Wrapper Format
+=================================
+
+Bitcode files for LLVM IR may also be wrapped in a native object file
+(i.e. ELF, COFF, Mach-O). The bitcode must be stored in a section of the object
+file named ``__LLVM,__bitcode`` for MachO and ``.llvmbc`` for the other object
+formats. This wrapper format is useful for accommodating LTO in compilation
+pipelines where intermediate objects must be native object files which contain
+metadata in other sections.
+
+Not all tools support this format.
+
+.. _encoding of LLVM IR:
+
+LLVM IR Encoding
+================
+
+LLVM IR is encoded into a bitstream by defining blocks and records. It uses
+blocks for things like constant pools, functions, symbol tables, etc. It uses
+records for things like instructions, global variable descriptors, type
+descriptions, etc. This document does not describe the set of abbreviations
+that the writer uses, as these are fully self-described in the file, and the
+reader is not allowed to build in any knowledge of this.
+
+Basics
+------
+
+LLVM IR Magic Number
+^^^^^^^^^^^^^^^^^^^^
+
+The magic number for LLVM IR files is:
+
+:raw-html:`<tt><blockquote>`
+['B'\ :sub:`8`, 'C'\ :sub:`8`, 0x0\ :sub:`4`, 0xC\ :sub:`4`, 0xE\ :sub:`4`, 0xD\ :sub:`4`]
+:raw-html:`</blockquote></tt>`
+
+.. _Signed VBRs:
+
+Signed VBRs
+^^^^^^^^^^^
+
+`Variable Width Integer`_ encoding is an efficient way to encode arbitrary sized
+unsigned values, but is an extremely inefficient for encoding signed values, as
+signed values are otherwise treated as maximally large unsigned values.
+
+As such, signed VBR values of a specific width are emitted as follows:
+
+* Positive values are emitted as VBRs of the specified width, but with their
+ value shifted left by one.
+
+* Negative values are emitted as VBRs of the specified width, but the negated
+ value is shifted left by one, and the low bit is set.
+
+With this encoding, small positive and small negative values can both be emitted
+efficiently. Signed VBR encoding is used in ``CST_CODE_INTEGER`` and
+``CST_CODE_WIDE_INTEGER`` records within ``CONSTANTS_BLOCK`` blocks.
+It is also used for phi instruction operands in `MODULE_CODE_VERSION`_ 1.
+
+LLVM IR Blocks
+^^^^^^^^^^^^^^
+
+LLVM IR is defined with the following blocks:
+
+* 8 --- `MODULE_BLOCK`_ --- This is the top-level block that contains the entire
+ module, and describes a variety of per-module information.
+
+* 9 --- `PARAMATTR_BLOCK`_ --- This enumerates the parameter attributes.
+
+* 10 --- `PARAMATTR_GROUP_BLOCK`_ --- This describes the attribute group table.
+
+* 11 --- `CONSTANTS_BLOCK`_ --- This describes constants for a module or
+ function.
+
+* 12 --- `FUNCTION_BLOCK`_ --- This describes a function body.
+
+* 14 --- `VALUE_SYMTAB_BLOCK`_ --- This describes a value symbol table.
+
+* 15 --- `METADATA_BLOCK`_ --- This describes metadata items.
+
+* 16 --- `METADATA_ATTACHMENT`_ --- This contains records associating metadata
+ with function instruction values.
+
+* 17 --- `TYPE_BLOCK`_ --- This describes all of the types in the module.
+
+* 23 --- `STRTAB_BLOCK`_ --- The bitcode file's string table.
+
+.. _MODULE_BLOCK:
+
+MODULE_BLOCK Contents
+---------------------
+
+The ``MODULE_BLOCK`` block (id 8) is the top-level block for LLVM bitcode files,
+and each bitcode file must contain exactly one. In addition to records
+(described below) containing information about the module, a ``MODULE_BLOCK``
+block may contain the following sub-blocks:
+
+* `BLOCKINFO`_
+* `PARAMATTR_BLOCK`_
+* `PARAMATTR_GROUP_BLOCK`_
+* `TYPE_BLOCK`_
+* `VALUE_SYMTAB_BLOCK`_
+* `CONSTANTS_BLOCK`_
+* `FUNCTION_BLOCK`_
+* `METADATA_BLOCK`_
+
+.. _MODULE_CODE_VERSION:
+
+MODULE_CODE_VERSION Record
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``[VERSION, version#]``
+
+The ``VERSION`` record (code 1) contains a single value indicating the format
+version. Versions 0, 1 and 2 are supported at this time. The difference between
+version 0 and 1 is in the encoding of instruction operands in
+each `FUNCTION_BLOCK`_.
+
+In version 0, each value defined by an instruction is assigned an ID
+unique to the function. Function-level value IDs are assigned starting from
+``NumModuleValues`` since they share the same namespace as module-level
+values. The value enumerator resets after each function. When a value is
+an operand of an instruction, the value ID is used to represent the operand.
+For large functions or large modules, these operand values can be large.
+
+The encoding in version 1 attempts to avoid large operand values
+in common cases. Instead of using the value ID directly, operands are
+encoded as relative to the current instruction. Thus, if an operand
+is the value defined by the previous instruction, the operand
+will be encoded as 1.
+
+For example, instead of
+
+.. code-block:: none
+
+ #n = load #n-1
+ #n+1 = icmp eq #n, #const0
+ br #n+1, label #(bb1), label #(bb2)
+
+version 1 will encode the instructions as
+
+.. code-block:: none
+
+ #n = load #1
+ #n+1 = icmp eq #1, (#n+1)-#const0
+ br #1, label #(bb1), label #(bb2)
+
+Note in the example that operands which are constants also use
+the relative encoding, while operands like basic block labels
+do not use the relative encoding.
+
+Forward references will result in a negative value.
+This can be inefficient, as operands are normally encoded
+as unsigned VBRs. However, forward references are rare, except in the
+case of phi instructions. For phi instructions, operands are encoded as
+`Signed VBRs`_ to deal with forward references.
+
+In version 2, the meaning of module records ``FUNCTION``, ``GLOBALVAR``,
+``ALIAS``, ``IFUNC`` and ``COMDAT`` change such that the first two operands
+specify an offset and size of a string in a string table (see `STRTAB_BLOCK
+Contents`_), the function name is removed from the ``FNENTRY`` record in the
+value symbol table, and the top-level ``VALUE_SYMTAB_BLOCK`` may only contain
+``FNENTRY`` records.
+
+MODULE_CODE_TRIPLE Record
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``[TRIPLE, ...string...]``
+
+The ``TRIPLE`` record (code 2) contains a variable number of values representing
+the bytes of the ``target triple`` specification string.
+
+MODULE_CODE_DATALAYOUT Record
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``[DATALAYOUT, ...string...]``
+
+The ``DATALAYOUT`` record (code 3) contains a variable number of values
+representing the bytes of the ``target datalayout`` specification string.
+
+MODULE_CODE_ASM Record
+^^^^^^^^^^^^^^^^^^^^^^
+
+``[ASM, ...string...]``
+
+The ``ASM`` record (code 4) contains a variable number of values representing
+the bytes of ``module asm`` strings, with individual assembly blocks separated
+by newline (ASCII 10) characters.
+
+.. _MODULE_CODE_SECTIONNAME:
+
+MODULE_CODE_SECTIONNAME Record
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``[SECTIONNAME, ...string...]``
+
+The ``SECTIONNAME`` record (code 5) contains a variable number of values
+representing the bytes of a single section name string. There should be one
+``SECTIONNAME`` record for each section name referenced (e.g., in global
+variable or function ``section`` attributes) within the module. These records
+can be referenced by the 1-based index in the *section* fields of ``GLOBALVAR``
+or ``FUNCTION`` records.
+
+MODULE_CODE_DEPLIB Record
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``[DEPLIB, ...string...]``
+
+The ``DEPLIB`` record (code 6) contains a variable number of values representing
+the bytes of a single dependent library name string, one of the libraries
+mentioned in a ``deplibs`` declaration. There should be one ``DEPLIB`` record
+for each library name referenced.
+
+MODULE_CODE_GLOBALVAR Record
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``[GLOBALVAR, strtab offset, strtab size, pointer type, isconst, initid, linkage, alignment, section, visibility, threadlocal, unnamed_addr, externally_initialized, dllstorageclass, comdat, attributes, preemptionspecifier]``
+
+The ``GLOBALVAR`` record (code 7) marks the declaration or definition of a
+global variable. The operand fields are:
+
+* *strtab offset*, *strtab size*: Specifies the name of the global variable.
+ See `STRTAB_BLOCK Contents`_.
+
+* *pointer type*: The type index of the pointer type used to point to this
+ global variable
+
+* *isconst*: Non-zero if the variable is treated as constant within the module,
+ or zero if it is not
+
+* *initid*: If non-zero, the value index of the initializer for this variable,
+ plus 1.
+
+.. _linkage type:
+
+* *linkage*: An encoding of the linkage type for this variable:
+
+ * ``external``: code 0
+ * ``weak``: code 1
+ * ``appending``: code 2
+ * ``internal``: code 3
+ * ``linkonce``: code 4
+ * ``dllimport``: code 5
+ * ``dllexport``: code 6
+ * ``extern_weak``: code 7
+ * ``common``: code 8
+ * ``private``: code 9
+ * ``weak_odr``: code 10
+ * ``linkonce_odr``: code 11
+ * ``available_externally``: code 12
+ * deprecated : code 13
+ * deprecated : code 14
+
+* alignment*: The logarithm base 2 of the variable's requested alignment, plus 1
+
+* *section*: If non-zero, the 1-based section index in the table of
+ `MODULE_CODE_SECTIONNAME`_ entries.
+
+.. _visibility:
+
+* *visibility*: If present, an encoding of the visibility of this variable:
+
+ * ``default``: code 0
+ * ``hidden``: code 1
+ * ``protected``: code 2
+
+.. _bcthreadlocal:
+
+* *threadlocal*: If present, an encoding of the thread local storage mode of the
+ variable:
+
+ * ``not thread local``: code 0
+ * ``thread local; default TLS model``: code 1
+ * ``localdynamic``: code 2
+ * ``initialexec``: code 3
+ * ``localexec``: code 4
+
+.. _bcunnamedaddr:
+
+* *unnamed_addr*: If present, an encoding of the ``unnamed_addr`` attribute of this
+ variable:
+
+ * not ``unnamed_addr``: code 0
+ * ``unnamed_addr``: code 1
+ * ``local_unnamed_addr``: code 2
+
+.. _bcdllstorageclass:
+
+* *dllstorageclass*: If present, an encoding of the DLL storage class of this variable:
+
+ * ``default``: code 0
+ * ``dllimport``: code 1
+ * ``dllexport``: code 2
+
+* *comdat*: An encoding of the COMDAT of this function
+
+* *attributes*: If nonzero, the 1-based index into the table of AttributeLists.
+
+.. _bcpreemptionspecifier:
+
+* *preemptionspecifier*: If present, an encoding of the runtime preemption specifier of this variable:
+
+ * ``dso_preemptable``: code 0
+ * ``dso_local``: code 1
+
+.. _FUNCTION:
+
+MODULE_CODE_FUNCTION Record
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``[FUNCTION, strtab offset, strtab size, type, callingconv, isproto, linkage, paramattr, alignment, section, visibility, gc, prologuedata, dllstorageclass, comdat, prefixdata, personalityfn, preemptionspecifier]``
+
+The ``FUNCTION`` record (code 8) marks the declaration or definition of a
+function. The operand fields are:
+
+* *strtab offset*, *strtab size*: Specifies the name of the function.
+ See `STRTAB_BLOCK Contents`_.
+
+* *type*: The type index of the function type describing this function
+
+* *callingconv*: The calling convention number:
+ * ``ccc``: code 0
+ * ``fastcc``: code 8
+ * ``coldcc``: code 9
+ * ``webkit_jscc``: code 12
+ * ``anyregcc``: code 13
+ * ``preserve_mostcc``: code 14
+ * ``preserve_allcc``: code 15
+ * ``swiftcc`` : code 16
+ * ``cxx_fast_tlscc``: code 17
+ * ``x86_stdcallcc``: code 64
+ * ``x86_fastcallcc``: code 65
+ * ``arm_apcscc``: code 66
+ * ``arm_aapcscc``: code 67
+ * ``arm_aapcs_vfpcc``: code 68
+
+* isproto*: Non-zero if this entry represents a declaration rather than a
+ definition
+
+* *linkage*: An encoding of the `linkage type`_ for this function
+
+* *paramattr*: If nonzero, the 1-based parameter attribute index into the table
+ of `PARAMATTR_CODE_ENTRY`_ entries.
+
+* *alignment*: The logarithm base 2 of the function's requested alignment, plus
+ 1
+
+* *section*: If non-zero, the 1-based section index in the table of
+ `MODULE_CODE_SECTIONNAME`_ entries.
+
+* *visibility*: An encoding of the `visibility`_ of this function
+
+* *gc*: If present and nonzero, the 1-based garbage collector index in the table
+ of `MODULE_CODE_GCNAME`_ entries.
+
+* *unnamed_addr*: If present, an encoding of the
+ :ref:`unnamed_addr<bcunnamedaddr>` attribute of this function
+
+* *prologuedata*: If non-zero, the value index of the prologue data for this function,
+ plus 1.
+
+* *dllstorageclass*: An encoding of the
+ :ref:`dllstorageclass<bcdllstorageclass>` of this function
+
+* *comdat*: An encoding of the COMDAT of this function
+
+* *prefixdata*: If non-zero, the value index of the prefix data for this function,
+ plus 1.
+
+* *personalityfn*: If non-zero, the value index of the personality function for this function,
+ plus 1.
+
+* *preemptionspecifier*: If present, an encoding of the :ref:`runtime preemption specifier<bcpreemptionspecifier>` of this function.
+
+MODULE_CODE_ALIAS Record
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+``[ALIAS, strtab offset, strtab size, alias type, aliasee val#, linkage, visibility, dllstorageclass, threadlocal, unnamed_addr, preemptionspecifier]``
+
+The ``ALIAS`` record (code 9) marks the definition of an alias. The operand
+fields are
+
+* *strtab offset*, *strtab size*: Specifies the name of the alias.
+ See `STRTAB_BLOCK Contents`_.
+
+* *alias type*: The type index of the alias
+
+* *aliasee val#*: The value index of the aliased value
+
+* *linkage*: An encoding of the `linkage type`_ for this alias
+
+* *visibility*: If present, an encoding of the `visibility`_ of the alias
+
+* *dllstorageclass*: If present, an encoding of the
+ :ref:`dllstorageclass<bcdllstorageclass>` of the alias
+
+* *threadlocal*: If present, an encoding of the
+ :ref:`thread local property<bcthreadlocal>` of the alias
+
+* *unnamed_addr*: If present, an encoding of the
+ :ref:`unnamed_addr<bcunnamedaddr>` attribute of this alias
+
+* *preemptionspecifier*: If present, an encoding of the :ref:`runtime preemption specifier<bcpreemptionspecifier>` of this alias.
+
+.. _MODULE_CODE_GCNAME:
+
+MODULE_CODE_GCNAME Record
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``[GCNAME, ...string...]``
+
+The ``GCNAME`` record (code 11) contains a variable number of values
+representing the bytes of a single garbage collector name string. There should
+be one ``GCNAME`` record for each garbage collector name referenced in function
+``gc`` attributes within the module. These records can be referenced by 1-based
+index in the *gc* fields of ``FUNCTION`` records.
+
+.. _PARAMATTR_BLOCK:
+
+PARAMATTR_BLOCK Contents
+------------------------
+
+The ``PARAMATTR_BLOCK`` block (id 9) contains a table of entries describing the
+attributes of function parameters. These entries are referenced by 1-based index
+in the *paramattr* field of module block `FUNCTION`_ records, or within the
+*attr* field of function block ``INST_INVOKE`` and ``INST_CALL`` records.
+
+Entries within ``PARAMATTR_BLOCK`` are constructed to ensure that each is unique
+(i.e., no two indices represent equivalent attribute lists).
+
+.. _PARAMATTR_CODE_ENTRY:
+
+PARAMATTR_CODE_ENTRY Record
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``[ENTRY, attrgrp0, attrgrp1, ...]``
+
+The ``ENTRY`` record (code 2) contains a variable number of values describing a
+unique set of function parameter attributes. Each *attrgrp* value is used as a
+key with which to look up an entry in the attribute group table described
+in the ``PARAMATTR_GROUP_BLOCK`` block.
+
+.. _PARAMATTR_CODE_ENTRY_OLD:
+
+PARAMATTR_CODE_ENTRY_OLD Record
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. note::
+ This is a legacy encoding for attributes, produced by LLVM versions 3.2 and
+ earlier. It is guaranteed to be understood by the current LLVM version, as
+ specified in the :ref:`IR backwards compatibility` policy.
+
+``[ENTRY, paramidx0, attr0, paramidx1, attr1...]``
+
+The ``ENTRY`` record (code 1) contains an even number of values describing a
+unique set of function parameter attributes. Each *paramidx* value indicates
+which set of attributes is represented, with 0 representing the return value
+attributes, 0xFFFFFFFF representing function attributes, and other values
+representing 1-based function parameters. Each *attr* value is a bitmap with the
+following interpretation:
+
+* bit 0: ``zeroext``
+* bit 1: ``signext``
+* bit 2: ``noreturn``
+* bit 3: ``inreg``
+* bit 4: ``sret``
+* bit 5: ``nounwind``
+* bit 6: ``noalias``
+* bit 7: ``byval``
+* bit 8: ``nest``
+* bit 9: ``readnone``
+* bit 10: ``readonly``
+* bit 11: ``noinline``
+* bit 12: ``alwaysinline``
+* bit 13: ``optsize``
+* bit 14: ``ssp``
+* bit 15: ``sspreq``
+* bits 16-31: ``align n``
+* bit 32: ``nocapture``
+* bit 33: ``noredzone``
+* bit 34: ``noimplicitfloat``
+* bit 35: ``naked``
+* bit 36: ``inlinehint``
+* bits 37-39: ``alignstack n``, represented as the logarithm
+ base 2 of the requested alignment, plus 1
+
+.. _PARAMATTR_GROUP_BLOCK:
+
+PARAMATTR_GROUP_BLOCK Contents
+------------------------------
+
+The ``PARAMATTR_GROUP_BLOCK`` block (id 10) contains a table of entries
+describing the attribute groups present in the module. These entries can be
+referenced within ``PARAMATTR_CODE_ENTRY`` entries.
+
+.. _PARAMATTR_GRP_CODE_ENTRY:
+
+PARAMATTR_GRP_CODE_ENTRY Record
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``[ENTRY, grpid, paramidx, attr0, attr1, ...]``
+
+The ``ENTRY`` record (code 3) contains *grpid* and *paramidx* values, followed
+by a variable number of values describing a unique group of attributes. The
+*grpid* value is a unique key for the attribute group, which can be referenced
+within ``PARAMATTR_CODE_ENTRY`` entries. The *paramidx* value indicates which
+set of attributes is represented, with 0 representing the return value
+attributes, 0xFFFFFFFF representing function attributes, and other values
+representing 1-based function parameters.
+
+Each *attr* is itself represented as a variable number of values:
+
+``kind, key [, ...], [value [, ...]]``
+
+Each attribute is either a well-known LLVM attribute (possibly with an integer
+value associated with it), or an arbitrary string (possibly with an arbitrary
+string value associated with it). The *kind* value is an integer code
+distinguishing between these possibilities:
+
+* code 0: well-known attribute
+* code 1: well-known attribute with an integer value
+* code 3: string attribute
+* code 4: string attribute with a string value
+
+For well-known attributes (code 0 or 1), the *key* value is an integer code
+identifying the attribute. For attributes with an integer argument (code 1),
+the *value* value indicates the argument.
+
+For string attributes (code 3 or 4), the *key* value is actually a variable
+number of values representing the bytes of a null-terminated string. For
+attributes with a string argument (code 4), the *value* value is similarly a
+variable number of values representing the bytes of a null-terminated string.
+
+The integer codes are mapped to well-known attributes as follows.
+
+* code 1: ``align(<n>)``
+* code 2: ``alwaysinline``
+* code 3: ``byval``
+* code 4: ``inlinehint``
+* code 5: ``inreg``
+* code 6: ``minsize``
+* code 7: ``naked``
+* code 8: ``nest``
+* code 9: ``noalias``
+* code 10: ``nobuiltin``
+* code 11: ``nocapture``
+* code 12: ``noduplicates``
+* code 13: ``noimplicitfloat``
+* code 14: ``noinline``
+* code 15: ``nonlazybind``
+* code 16: ``noredzone``
+* code 17: ``noreturn``
+* code 18: ``nounwind``
+* code 19: ``optsize``
+* code 20: ``readnone``
+* code 21: ``readonly``
+* code 22: ``returned``
+* code 23: ``returns_twice``
+* code 24: ``signext``
+* code 25: ``alignstack(<n>)``
+* code 26: ``ssp``
+* code 27: ``sspreq``
+* code 28: ``sspstrong``
+* code 29: ``sret``
+* code 30: ``sanitize_address``
+* code 31: ``sanitize_thread``
+* code 32: ``sanitize_memory``
+* code 33: ``uwtable``
+* code 34: ``zeroext``
+* code 35: ``builtin``
+* code 36: ``cold``
+* code 37: ``optnone``
+* code 38: ``inalloca``
+* code 39: ``nonnull``
+* code 40: ``jumptable``
+* code 41: ``dereferenceable(<n>)``
+* code 42: ``dereferenceable_or_null(<n>)``
+* code 43: ``convergent``
+* code 44: ``safestack``
+* code 45: ``argmemonly``
+* code 46: ``swiftself``
+* code 47: ``swifterror``
+* code 48: ``norecurse``
+* code 49: ``inaccessiblememonly``
+* code 50: ``inaccessiblememonly_or_argmemonly``
+* code 51: ``allocsize(<EltSizeParam>[, <NumEltsParam>])``
+* code 52: ``writeonly``
+* code 53: ``speculatable``
+* code 54: ``strictfp``
+* code 55: ``sanitize_hwaddress``
+* code 56: ``nocf_check``
+* code 57: ``optforfuzzing``
+* code 58: ``shadowcallstack``
+* code 64: ``sanitize_memtag``
+
+.. note::
+ The ``allocsize`` attribute has a special encoding for its arguments. Its two
+ arguments, which are 32-bit integers, are packed into one 64-bit integer value
+ (i.e. ``(EltSizeParam << 32) | NumEltsParam``), with ``NumEltsParam`` taking on
+ the sentinel value -1 if it is not specified.
+
+.. _TYPE_BLOCK:
+
+TYPE_BLOCK Contents
+-------------------
+
+The ``TYPE_BLOCK`` block (id 17) contains records which constitute a table of
+type operator entries used to represent types referenced within an LLVM
+module. Each record (with the exception of `NUMENTRY`_) generates a single type
+table entry, which may be referenced by 0-based index from instructions,
+constants, metadata, type symbol table entries, or other type operator records.
+
+Entries within ``TYPE_BLOCK`` are constructed to ensure that each entry is
+unique (i.e., no two indices represent structurally equivalent types).
+
+.. _TYPE_CODE_NUMENTRY:
+.. _NUMENTRY:
+
+TYPE_CODE_NUMENTRY Record
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``[NUMENTRY, numentries]``
+
+The ``NUMENTRY`` record (code 1) contains a single value which indicates the
+total number of type code entries in the type table of the module. If present,
+``NUMENTRY`` should be the first record in the block.
+
+TYPE_CODE_VOID Record
+^^^^^^^^^^^^^^^^^^^^^
+
+``[VOID]``
+
+The ``VOID`` record (code 2) adds a ``void`` type to the type table.
+
+TYPE_CODE_HALF Record
+^^^^^^^^^^^^^^^^^^^^^
+
+``[HALF]``
+
+The ``HALF`` record (code 10) adds a ``half`` (16-bit floating point) type to
+the type table.
+
+TYPE_CODE_FLOAT Record
+^^^^^^^^^^^^^^^^^^^^^^
+
+``[FLOAT]``
+
+The ``FLOAT`` record (code 3) adds a ``float`` (32-bit floating point) type to
+the type table.
+
+TYPE_CODE_DOUBLE Record
+^^^^^^^^^^^^^^^^^^^^^^^
+
+``[DOUBLE]``
+
+The ``DOUBLE`` record (code 4) adds a ``double`` (64-bit floating point) type to
+the type table.
+
+TYPE_CODE_LABEL Record
+^^^^^^^^^^^^^^^^^^^^^^
+
+``[LABEL]``
+
+The ``LABEL`` record (code 5) adds a ``label`` type to the type table.
+
+TYPE_CODE_OPAQUE Record
+^^^^^^^^^^^^^^^^^^^^^^^
+
+``[OPAQUE]``
+
+The ``OPAQUE`` record (code 6) adds an ``opaque`` type to the type table, with
+a name defined by a previously encountered ``STRUCT_NAME`` record. Note that
+distinct ``opaque`` types are not unified.
+
+TYPE_CODE_INTEGER Record
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+``[INTEGER, width]``
+
+The ``INTEGER`` record (code 7) adds an integer type to the type table. The
+single *width* field indicates the width of the integer type.
+
+TYPE_CODE_POINTER Record
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+``[POINTER, pointee type, address space]``
+
+The ``POINTER`` record (code 8) adds a pointer type to the type table. The
+operand fields are
+
+* *pointee type*: The type index of the pointed-to type
+
+* *address space*: If supplied, the target-specific numbered address space where
+ the pointed-to object resides. Otherwise, the default address space is zero.
+
+TYPE_CODE_FUNCTION_OLD Record
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. note::
+ This is a legacy encoding for functions, produced by LLVM versions 3.0 and
+ earlier. It is guaranteed to be understood by the current LLVM version, as
+ specified in the :ref:`IR backwards compatibility` policy.
+
+``[FUNCTION_OLD, vararg, ignored, retty, ...paramty... ]``
+
+The ``FUNCTION_OLD`` record (code 9) adds a function type to the type table.
+The operand fields are
+
+* *vararg*: Non-zero if the type represents a varargs function
+
+* *ignored*: This value field is present for backward compatibility only, and is
+ ignored
+
+* *retty*: The type index of the function's return type
+
+* *paramty*: Zero or more type indices representing the parameter types of the
+ function
+
+TYPE_CODE_ARRAY Record
+^^^^^^^^^^^^^^^^^^^^^^
+
+``[ARRAY, numelts, eltty]``
+
+The ``ARRAY`` record (code 11) adds an array type to the type table. The
+operand fields are
+
+* *numelts*: The number of elements in arrays of this type
+
+* *eltty*: The type index of the array element type
+
+TYPE_CODE_VECTOR Record
+^^^^^^^^^^^^^^^^^^^^^^^
+
+``[VECTOR, numelts, eltty]``
+
+The ``VECTOR`` record (code 12) adds a vector type to the type table. The
+operand fields are
+
+* *numelts*: The number of elements in vectors of this type
+
+* *eltty*: The type index of the vector element type
+
+TYPE_CODE_X86_FP80 Record
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``[X86_FP80]``
+
+The ``X86_FP80`` record (code 13) adds an ``x86_fp80`` (80-bit floating point)
+type to the type table.
+
+TYPE_CODE_FP128 Record
+^^^^^^^^^^^^^^^^^^^^^^
+
+``[FP128]``
+
+The ``FP128`` record (code 14) adds an ``fp128`` (128-bit floating point) type
+to the type table.
+
+TYPE_CODE_PPC_FP128 Record
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``[PPC_FP128]``
+
+The ``PPC_FP128`` record (code 15) adds a ``ppc_fp128`` (128-bit floating point)
+type to the type table.
+
+TYPE_CODE_METADATA Record
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``[METADATA]``
+
+The ``METADATA`` record (code 16) adds a ``metadata`` type to the type table.
+
+TYPE_CODE_X86_MMX Record
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+``[X86_MMX]``
+
+The ``X86_MMX`` record (code 17) adds an ``x86_mmx`` type to the type table.
+
+TYPE_CODE_STRUCT_ANON Record
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``[STRUCT_ANON, ispacked, ...eltty...]``
+
+The ``STRUCT_ANON`` record (code 18) adds a literal struct type to the type
+table. The operand fields are
+
+* *ispacked*: Non-zero if the type represents a packed structure
+
+* *eltty*: Zero or more type indices representing the element types of the
+ structure
+
+TYPE_CODE_STRUCT_NAME Record
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``[STRUCT_NAME, ...string...]``
+
+The ``STRUCT_NAME`` record (code 19) contains a variable number of values
+representing the bytes of a struct name. The next ``OPAQUE`` or
+``STRUCT_NAMED`` record will use this name.
+
+TYPE_CODE_STRUCT_NAMED Record
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``[STRUCT_NAMED, ispacked, ...eltty...]``
+
+The ``STRUCT_NAMED`` record (code 20) adds an identified struct type to the
+type table, with a name defined by a previously encountered ``STRUCT_NAME``
+record. The operand fields are
+
+* *ispacked*: Non-zero if the type represents a packed structure
+
+* *eltty*: Zero or more type indices representing the element types of the
+ structure
+
+TYPE_CODE_FUNCTION Record
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``[FUNCTION, vararg, retty, ...paramty... ]``
+
+The ``FUNCTION`` record (code 21) adds a function type to the type table. The
+operand fields are
+
+* *vararg*: Non-zero if the type represents a varargs function
+
+* *retty*: The type index of the function's return type
+
+* *paramty*: Zero or more type indices representing the parameter types of the
+ function
+
+.. _CONSTANTS_BLOCK:
+
+CONSTANTS_BLOCK Contents
+------------------------
+
+The ``CONSTANTS_BLOCK`` block (id 11) ...
+
+.. _FUNCTION_BLOCK:
+
+FUNCTION_BLOCK Contents
+-----------------------
+
+The ``FUNCTION_BLOCK`` block (id 12) ...
+
+In addition to the record types described below, a ``FUNCTION_BLOCK`` block may
+contain the following sub-blocks:
+
+* `CONSTANTS_BLOCK`_
+* `VALUE_SYMTAB_BLOCK`_
+* `METADATA_ATTACHMENT`_
+
+.. _VALUE_SYMTAB_BLOCK:
+
+VALUE_SYMTAB_BLOCK Contents
+---------------------------
+
+The ``VALUE_SYMTAB_BLOCK`` block (id 14) ...
+
+.. _METADATA_BLOCK:
+
+METADATA_BLOCK Contents
+-----------------------
+
+The ``METADATA_BLOCK`` block (id 15) ...
+
+.. _METADATA_ATTACHMENT:
+
+METADATA_ATTACHMENT Contents
+----------------------------
+
+The ``METADATA_ATTACHMENT`` block (id 16) ...
+
+.. _STRTAB_BLOCK:
+
+STRTAB_BLOCK Contents
+---------------------
+
+The ``STRTAB`` block (id 23) contains a single record (``STRTAB_BLOB``, id 1)
+with a single blob operand containing the bitcode file's string table.
+
+Strings in the string table are not null terminated. A record's *strtab
+offset* and *strtab size* operands specify the byte offset and size of a
+string within the string table.
+
+The string table is used by all preceding blocks in the bitcode file that are
+not succeeded by another intervening ``STRTAB`` block. Normally a bitcode
+file will have a single string table, but it may have more than one if it
+was created by binary concatenation of multiple bitcode files.
Added: www-releases/trunk/9.0.0/docs/_sources/BlockFrequencyTerminology.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/_sources/BlockFrequencyTerminology.rst.txt?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/_sources/BlockFrequencyTerminology.rst.txt (added)
+++ www-releases/trunk/9.0.0/docs/_sources/BlockFrequencyTerminology.rst.txt Thu Sep 19 07:32:46 2019
@@ -0,0 +1,130 @@
+================================
+LLVM Block Frequency Terminology
+================================
+
+.. contents::
+ :local:
+
+Introduction
+============
+
+Block Frequency is a metric for estimating the relative frequency of different
+basic blocks. This document describes the terminology that the
+``BlockFrequencyInfo`` and ``MachineBlockFrequencyInfo`` analysis passes use.
+
+Branch Probability
+==================
+
+Blocks with multiple successors have probabilities associated with each
+outgoing edge. These are called branch probabilities. For a given block, the
+sum of its outgoing branch probabilities should be 1.0.
+
+Branch Weight
+=============
+
+Rather than storing fractions on each edge, we store an integer weight.
+Weights are relative to the other edges of a given predecessor block. The
+branch probability associated with a given edge is its own weight divided by
+the sum of the weights on the predecessor's outgoing edges.
+
+For example, consider this IR:
+
+.. code-block:: llvm
+
+ define void @foo() {
+ ; ...
+ A:
+ br i1 %cond, label %B, label %C, !prof !0
+ ; ...
+ }
+ !0 = metadata !{metadata !"branch_weights", i32 7, i32 8}
+
+and this simple graph representation::
+
+ A -> B (edge-weight: 7)
+ A -> C (edge-weight: 8)
+
+The probability of branching from block A to block B is 7/15, and the
+probability of branching from block A to block C is 8/15.
+
+See :doc:`BranchWeightMetadata` for details about the branch weight IR
+representation.
+
+Block Frequency
+===============
+
+Block frequency is a relative metric that represents the number of times a
+block executes. The ratio of a block frequency to the entry block frequency is
+the expected number of times the block will execute per entry to the function.
+
+Block frequency is the main output of the ``BlockFrequencyInfo`` and
+``MachineBlockFrequencyInfo`` analysis passes.
+
+Implementation: a series of DAGs
+================================
+
+The implementation of the block frequency calculation analyses each loop,
+bottom-up, ignoring backedges; i.e., as a DAG. After each loop is processed,
+it's packaged up to act as a pseudo-node in its parent loop's (or the
+function's) DAG analysis.
+
+Block Mass
+==========
+
+For each DAG, the entry node is assigned a mass of ``UINT64_MAX`` and mass is
+distributed to successors according to branch weights. Block Mass uses a
+fixed-point representation where ``UINT64_MAX`` represents ``1.0`` and ``0``
+represents a number just above ``0.0``.
+
+After mass is fully distributed, in any cut of the DAG that separates the exit
+nodes from the entry node, the sum of the block masses of the nodes succeeded
+by a cut edge should equal ``UINT64_MAX``. In other words, mass is conserved
+as it "falls" through the DAG.
+
+If a function's basic block graph is a DAG, then block masses are valid block
+frequencies. This works poorly in practise though, since downstream users rely
+on adding block frequencies together without hitting the maximum.
+
+Loop Scale
+==========
+
+Loop scale is a metric that indicates how many times a loop iterates per entry.
+As mass is distributed through the loop's DAG, the (otherwise ignored) backedge
+mass is collected. This backedge mass is used to compute the exit frequency,
+and thus the loop scale.
+
+Implementation: Getting from mass and scale to frequency
+========================================================
+
+After analysing the complete series of DAGs, each block has a mass (local to
+its containing loop, if any), and each loop pseudo-node has a loop scale and
+its own mass (from its parent's DAG).
+
+We can get an initial frequency assignment (with entry frequency of 1.0) by
+multiplying these masses and loop scales together. A given block's frequency
+is the product of its mass, the mass of containing loops' pseudo nodes, and the
+containing loops' loop scales.
+
+Since downstream users need integers (not floating point), this initial
+frequency assignment is shifted as necessary into the range of ``uint64_t``.
+
+Block Bias
+==========
+
+Block bias is a proposed *absolute* metric to indicate a bias toward or away
+from a given block during a function's execution. The idea is that bias can be
+used in isolation to indicate whether a block is relatively hot or cold, or to
+compare two blocks to indicate whether one is hotter or colder than the other.
+
+The proposed calculation involves calculating a *reference* block frequency,
+where:
+
+* every branch weight is assumed to be 1 (i.e., every branch probability
+ distribution is even) and
+
+* loop scales are ignored.
+
+This reference frequency represents what the block frequency would be in an
+unbiased graph.
+
+The bias is the ratio of the block frequency to this reference block frequency.
Added: www-releases/trunk/9.0.0/docs/_sources/BranchWeightMetadata.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/_sources/BranchWeightMetadata.rst.txt?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/_sources/BranchWeightMetadata.rst.txt (added)
+++ www-releases/trunk/9.0.0/docs/_sources/BranchWeightMetadata.rst.txt Thu Sep 19 07:32:46 2019
@@ -0,0 +1,164 @@
+===========================
+LLVM Branch Weight Metadata
+===========================
+
+.. contents::
+ :local:
+
+Introduction
+============
+
+Branch Weight Metadata represents branch weights as its likeliness to be taken
+(see :doc:`BlockFrequencyTerminology`). Metadata is assigned to an
+``Instruction`` that is a terminator as a ``MDNode`` of the ``MD_prof`` kind.
+The first operator is always a ``MDString`` node with the string
+"branch_weights". Number of operators depends on the terminator type.
+
+Branch weights might be fetch from the profiling file, or generated based on
+`__builtin_expect`_ instruction.
+
+All weights are represented as an unsigned 32-bit values, where higher value
+indicates greater chance to be taken.
+
+Supported Instructions
+======================
+
+``BranchInst``
+^^^^^^^^^^^^^^
+
+Metadata is only assigned to the conditional branches. There are two extra
+operands for the true and the false branch.
+
+.. code-block:: none
+
+ !0 = metadata !{
+ metadata !"branch_weights",
+ i32 <TRUE_BRANCH_WEIGHT>,
+ i32 <FALSE_BRANCH_WEIGHT>
+ }
+
+``SwitchInst``
+^^^^^^^^^^^^^^
+
+Branch weights are assigned to every case (including the ``default`` case which
+is always case #0).
+
+.. code-block:: none
+
+ !0 = metadata !{
+ metadata !"branch_weights",
+ i32 <DEFAULT_BRANCH_WEIGHT>
+ [ , i32 <CASE_BRANCH_WEIGHT> ... ]
+ }
+
+``IndirectBrInst``
+^^^^^^^^^^^^^^^^^^
+
+Branch weights are assigned to every destination.
+
+.. code-block:: none
+
+ !0 = metadata !{
+ metadata !"branch_weights",
+ i32 <LABEL_BRANCH_WEIGHT>
+ [ , i32 <LABEL_BRANCH_WEIGHT> ... ]
+ }
+
+``CallInst``
+^^^^^^^^^^^^^^^^^^
+
+Calls may have branch weight metadata, containing the execution count of
+the call. It is currently used in SamplePGO mode only, to augment the
+block and entry counts which may not be accurate with sampling.
+
+.. code-block:: none
+
+ !0 = metadata !{
+ metadata !"branch_weights",
+ i32 <CALL_BRANCH_WEIGHT>
+ }
+
+Other
+^^^^^
+
+Other terminator instructions are not allowed to contain Branch Weight Metadata.
+
+.. _\__builtin_expect:
+
+Built-in ``expect`` Instructions
+================================
+
+``__builtin_expect(long exp, long c)`` instruction provides branch prediction
+information. The return value is the value of ``exp``.
+
+It is especially useful in conditional statements. Currently Clang supports two
+conditional statements:
+
+``if`` statement
+^^^^^^^^^^^^^^^^
+
+The ``exp`` parameter is the condition. The ``c`` parameter is the expected
+comparison value. If it is equal to 1 (true), the condition is likely to be
+true, in other case condition is likely to be false. For example:
+
+.. code-block:: c++
+
+ if (__builtin_expect(x > 0, 1)) {
+ // This block is likely to be taken.
+ }
+
+``switch`` statement
+^^^^^^^^^^^^^^^^^^^^
+
+The ``exp`` parameter is the value. The ``c`` parameter is the expected
+value. If the expected value doesn't show on the cases list, the ``default``
+case is assumed to be likely taken.
+
+.. code-block:: c++
+
+ switch (__builtin_expect(x, 5)) {
+ default: break;
+ case 0: // ...
+ case 3: // ...
+ case 5: // This case is likely to be taken.
+ }
+
+CFG Modifications
+=================
+
+Branch Weight Metatada is not proof against CFG changes. If terminator operands'
+are changed some action should be taken. In other case some misoptimizations may
+occur due to incorrect branch prediction information.
+
+Function Entry Counts
+=====================
+
+To allow comparing different functions during inter-procedural analysis and
+optimization, ``MD_prof`` nodes can also be assigned to a function definition.
+The first operand is a string indicating the name of the associated counter.
+
+Currently, one counter is supported: "function_entry_count". The second operand
+is a 64-bit counter that indicates the number of times that this function was
+invoked (in the case of instrumentation-based profiles). In the case of
+sampling-based profiles, this operand is an approximation of how many times
+the function was invoked.
+
+For example, in the code below, the instrumentation for function foo()
+indicates that it was called 2,590 times at runtime.
+
+.. code-block:: llvm
+
+ define i32 @foo() !prof !1 {
+ ret i32 0
+ }
+ !1 = !{!"function_entry_count", i64 2590}
+
+If "function_entry_count" has more than 2 operands, the later operands are
+the GUID of the functions that needs to be imported by ThinLTO. This is only
+set by sampling based profile. It is needed because the sampling based profile
+was collected on a binary that had already imported and inlined these functions,
+and we need to ensure the IR matches in the ThinLTO backends for profile
+annotation. The reason why we cannot annotate this on the callsite is that it
+can only goes down 1 level in the call chain. For the cases where
+foo_in_a_cc()->bar_in_b_cc()->baz_in_c_cc(), we will need to go down 2 levels
+in the call chain to import both bar_in_b_cc and baz_in_c_cc.
Added: www-releases/trunk/9.0.0/docs/_sources/BugLifeCycle.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/_sources/BugLifeCycle.rst.txt?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/_sources/BugLifeCycle.rst.txt (added)
+++ www-releases/trunk/9.0.0/docs/_sources/BugLifeCycle.rst.txt Thu Sep 19 07:32:46 2019
@@ -0,0 +1,140 @@
+===================
+LLVM Bug Life Cycle
+===================
+
+.. contents::
+ :local:
+
+
+
+Introduction - Achieving consistency in how we deal with bug reports
+====================================================================
+
+We aim to achieve a basic level of consistency in how reported bugs evolve from
+being reported, to being worked on, and finally getting closed out. The
+consistency helps reporters, developers and others to gain a better
+understanding of what a particular bug state actually means and what to expect
+might happen next.
+
+At the same time, we aim to not over-specify the life cycle of bugs in the
+`the LLVM Bug Tracking System <https://bugs.llvm.org/enter_bug.cgi>`_, as the
+overall goal is to make it easier to work with and understand the bug reports.
+
+The main parts of the life cycle documented here are:
+
+#. `Reporting`_
+#. `Triaging`_
+#. `Actively working on fixing`_
+#. `Closing`_
+
+Furthermore, some of the metadata in the bug tracker, such as who to notify on
+newly reported bugs or what the breakdown into products & components is we use,
+needs to be maintained. See the following for details:
+
+#. `Maintenance of Bug products/component metadata`_
+#. `Maintenance of cc-by-default settings`_
+
+
+.. _Reporting:
+
+Reporting bugs
+==============
+
+See :doc:`HowToSubmitABug` on further details on how to submit good bug reports.
+
+Make sure that you have one or more people on cc on the bug report that you
+think will react to it. We aim to automatically add specific people on cc for
+most products/components, but may not always succeed in doing so.
+
+If you know the area of LLVM code the root cause of the bug is in, good
+candidates to add as cc may be the same people you'd ask for a code review in
+that area. See :ref:`finding-potential-reviewers` for more details.
+
+
+.. _Triaging:
+
+Triaging bugs
+=============
+
+Bugs with status NEW indicate that they still need to be triaged.
+When triage is complete, the status of the bug is moved to CONFIRMED.
+
+The goal of triaging a bug is to make sure a newly reported bug ends up in a
+good, actionable, state. Try to answer the following questions while triaging.
+
+* Is the reported behavior actually wrong?
+
+ * E.g. does a miscompile example depend on undefined behavior?
+
+* Can you easily reproduce the bug?
+
+ * If not, are there reasonable excuses why it cannot easily be reproduced?
+
+* Is it related to an already reported bug?
+
+ * Use the "See also"/"depends on"/"blocks" fields if so.
+ * Close it as a duplicate if so, pointing to the issue it duplicates.
+
+* Are the following fields filled in correctly?
+
+ * Product
+ * Component
+ * Title
+
+* CC others not already ccâed that you happen to know would be good to pull in.
+* Add the "beginner" keyword if you think this would be a good bug to be fixed
+ by someone new to LLVM.
+
+.. _Actively working on fixing:
+
+Actively working on fixing bugs
+===============================
+
+Please remember to assign the bug to yourself if you're actively working on
+fixing it and to unassign it when you're no longer actively working on it. You
+unassign a bug by setting the Assignee field to "unassignedbugs at nondot.org".
+
+.. _Closing:
+
+Resolving/Closing bugs
+======================
+
+For simplicity, we only have 1 status for all resolved or closed bugs:
+RESOLVED.
+
+Resolving bugs is good! Make sure to properly record the reason for resolving.
+Examples of reasons for resolving are:
+
+* Revision NNNNNN fixed the bug.
+* The bug cannot be reproduced with revision NNNNNN.
+* The circumstances for the bug don't apply anymore.
+* There is a sound reason for not fixing it (WONTFIX).
+* There is a specific and plausible reason to think that a given bug is
+ otherwise inapplicable or obsolete.
+
+ * One example is an old open bug that doesn't contain enough information to
+ clearly understand the problem being reported (e.g. not reproducible). It is
+ fine to resolve such a bug e.g. with resolution WORKSFORME and leaving a
+ comment to encourage the reporter to reopen the bug with more information
+ if it's still reproducable on their end.
+
+If a bug is resolved, please fill in the revision number it was fixed in in the
+"Fixed by Commit(s)" field.
+
+
+.. _Maintenance of Bug products/component metadata:
+
+Maintenance of products/components metadata
+===========================================
+
+Please raise a bug against "Bugzilla Admin"/"Products" to request any changes
+to be made to the breakdown of products & components modeled in Bugzilla.
+
+
+.. _Maintenance of cc-by-default settings:
+
+Maintenance of cc-by-default settings
+=====================================
+
+Please raise a bug against "Bugzilla Admin"/"Products" to request any changes
+to be made to the cc-by-default settings for specific components.
Added: www-releases/trunk/9.0.0/docs/_sources/Bugpoint.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/_sources/Bugpoint.rst.txt?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/_sources/Bugpoint.rst.txt (added)
+++ www-releases/trunk/9.0.0/docs/_sources/Bugpoint.rst.txt Thu Sep 19 07:32:46 2019
@@ -0,0 +1,221 @@
+====================================
+LLVM bugpoint tool: design and usage
+====================================
+
+.. contents::
+ :local:
+
+Description
+===========
+
+``bugpoint`` narrows down the source of problems in LLVM tools and passes. It
+can be used to debug three types of failures: optimizer crashes, miscompilations
+by optimizers, or bad native code generation (including problems in the static
+and JIT compilers). It aims to reduce large test cases to small, useful ones.
+For example, if ``opt`` crashes while optimizing a file, it will identify the
+optimization (or combination of optimizations) that causes the crash, and reduce
+the file down to a small example which triggers the crash.
+
+For detailed case scenarios, such as debugging ``opt``, or one of the LLVM code
+generators, see :doc:`HowToSubmitABug`.
+
+Design Philosophy
+=================
+
+``bugpoint`` is designed to be a useful tool without requiring any hooks into
+the LLVM infrastructure at all. It works with any and all LLVM passes and code
+generators, and does not need to "know" how they work. Because of this, it may
+appear to do stupid things or miss obvious simplifications. ``bugpoint`` is
+also designed to trade off programmer time for computer time in the
+compiler-debugging process; consequently, it may take a long period of
+(unattended) time to reduce a test case, but we feel it is still worth it. Note
+that ``bugpoint`` is generally very quick unless debugging a miscompilation
+where each test of the program (which requires executing it) takes a long time.
+
+Automatic Debugger Selection
+----------------------------
+
+``bugpoint`` reads each ``.bc`` or ``.ll`` file specified on the command line
+and links them together into a single module, called the test program. If any
+LLVM passes are specified on the command line, it runs these passes on the test
+program. If any of the passes crash, or if they produce malformed output (which
+causes the verifier to abort), ``bugpoint`` starts the `crash debugger`_.
+
+Otherwise, if the ``-output`` option was not specified, ``bugpoint`` runs the
+test program with the "safe" backend (which is assumed to generate good code) to
+generate a reference output. Once ``bugpoint`` has a reference output for the
+test program, it tries executing it with the selected code generator. If the
+selected code generator crashes, ``bugpoint`` starts the `crash debugger`_ on
+the code generator. Otherwise, if the resulting output differs from the
+reference output, it assumes the difference resulted from a code generator
+failure, and starts the `code generator debugger`_.
+
+Finally, if the output of the selected code generator matches the reference
+output, ``bugpoint`` runs the test program after all of the LLVM passes have
+been applied to it. If its output differs from the reference output, it assumes
+the difference resulted from a failure in one of the LLVM passes, and enters the
+`miscompilation debugger`_. Otherwise, there is no problem ``bugpoint`` can
+debug.
+
+.. _crash debugger:
+
+Crash debugger
+--------------
+
+If an optimizer or code generator crashes, ``bugpoint`` will try as hard as it
+can to reduce the list of passes (for optimizer crashes) and the size of the
+test program. First, ``bugpoint`` figures out which combination of optimizer
+passes triggers the bug. This is useful when debugging a problem exposed by
+``opt``, for example, because it runs over 38 passes.
+
+Next, ``bugpoint`` tries removing functions from the test program, to reduce its
+size. Usually it is able to reduce a test program to a single function, when
+debugging intraprocedural optimizations. Once the number of functions has been
+reduced, it attempts to delete various edges in the control flow graph, to
+reduce the size of the function as much as possible. Finally, ``bugpoint``
+deletes any individual LLVM instructions whose absence does not eliminate the
+failure. At the end, ``bugpoint`` should tell you what passes crash, give you a
+bitcode file, and give you instructions on how to reproduce the failure with
+``opt`` or ``llc``.
+
+.. _code generator debugger:
+
+Code generator debugger
+-----------------------
+
+The code generator debugger attempts to narrow down the amount of code that is
+being miscompiled by the selected code generator. To do this, it takes the test
+program and partitions it into two pieces: one piece which it compiles with the
+"safe" backend (into a shared object), and one piece which it runs with either
+the JIT or the static LLC compiler. It uses several techniques to reduce the
+amount of code pushed through the LLVM code generator, to reduce the potential
+scope of the problem. After it is finished, it emits two bitcode files (called
+"test" [to be compiled with the code generator] and "safe" [to be compiled with
+the "safe" backend], respectively), and instructions for reproducing the
+problem. The code generator debugger assumes that the "safe" backend produces
+good code.
+
+.. _miscompilation debugger:
+
+Miscompilation debugger
+-----------------------
+
+The miscompilation debugger works similarly to the code generator debugger. It
+works by splitting the test program into two pieces, running the optimizations
+specified on one piece, linking the two pieces back together, and then executing
+the result. It attempts to narrow down the list of passes to the one (or few)
+which are causing the miscompilation, then reduce the portion of the test
+program which is being miscompiled. The miscompilation debugger assumes that
+the selected code generator is working properly.
+
+Advice for using bugpoint
+=========================
+
+``bugpoint`` can be a remarkably useful tool, but it sometimes works in
+non-obvious ways. Here are some hints and tips:
+
+* In the code generator and miscompilation debuggers, ``bugpoint`` only works
+ with programs that have deterministic output. Thus, if the program outputs
+ ``argv[0]``, the date, time, or any other "random" data, ``bugpoint`` may
+ misinterpret differences in these data, when output, as the result of a
+ miscompilation. Programs should be temporarily modified to disable outputs
+ that are likely to vary from run to run.
+
+* In the code generator and miscompilation debuggers, debugging will go faster
+ if you manually modify the program or its inputs to reduce the runtime, but
+ still exhibit the problem.
+
+* ``bugpoint`` is extremely useful when working on a new optimization: it helps
+ track down regressions quickly. To avoid having to relink ``bugpoint`` every
+ time you change your optimization however, have ``bugpoint`` dynamically load
+ your optimization with the ``-load`` option.
+
+* ``bugpoint`` can generate a lot of output and run for a long period of time.
+ It is often useful to capture the output of the program to file. For example,
+ in the C shell, you can run:
+
+ .. code-block:: console
+
+ $ bugpoint ... |& tee bugpoint.log
+
+ to get a copy of ``bugpoint``'s output in the file ``bugpoint.log``, as well
+ as on your terminal.
+
+* ``bugpoint`` cannot debug problems with the LLVM linker. If ``bugpoint``
+ crashes before you see its "All input ok" message, you might try ``llvm-link
+ -v`` on the same set of input files. If that also crashes, you may be
+ experiencing a linker bug.
+
+* ``bugpoint`` is useful for proactively finding bugs in LLVM. Invoking
+ ``bugpoint`` with the ``-find-bugs`` option will cause the list of specified
+ optimizations to be randomized and applied to the program. This process will
+ repeat until a bug is found or the user kills ``bugpoint``.
+
+* ``bugpoint`` can produce IR which contains long names. Run ``opt
+ -metarenamer`` over the IR to rename everything using easy-to-read,
+ metasyntactic names. Alternatively, run ``opt -strip -instnamer`` to rename
+ everything with very short (often purely numeric) names.
+
+What to do when bugpoint isn't enough
+=====================================
+
+Sometimes, ``bugpoint`` is not enough. In particular, InstCombine and
+TargetLowering both have visitor structured code with lots of potential
+transformations. If the process of using bugpoint has left you with still too
+much code to figure out and the problem seems to be in instcombine, the
+following steps may help. These same techniques are useful with TargetLowering
+as well.
+
+Turn on ``-debug-only=instcombine`` and see which transformations within
+instcombine are firing by selecting out lines with "``IC``" in them.
+
+At this point, you have a decision to make. Is the number of transformations
+small enough to step through them using a debugger? If so, then try that.
+
+If there are too many transformations, then a source modification approach may
+be helpful. In this approach, you can modify the source code of instcombine to
+disable just those transformations that are being performed on your test input
+and perform a binary search over the set of transformations. One set of places
+to modify are the "``visit*``" methods of ``InstCombiner`` (*e.g.*
+``visitICmpInst``) by adding a "``return false``" as the first line of the
+method.
+
+If that still doesn't remove enough, then change the caller of
+``InstCombiner::DoOneIteration``, ``InstCombiner::runOnFunction`` to limit the
+number of iterations.
+
+You may also find it useful to use "``-stats``" now to see what parts of
+instcombine are firing. This can guide where to put additional reporting code.
+
+At this point, if the amount of transformations is still too large, then
+inserting code to limit whether or not to execute the body of the code in the
+visit function can be helpful. Add a static counter which is incremented on
+every invocation of the function. Then add code which simply returns false on
+desired ranges. For example:
+
+.. code-block:: c++
+
+
+ static int calledCount = 0;
+ calledCount++;
+ LLVM_DEBUG(if (calledCount < 212) return false);
+ LLVM_DEBUG(if (calledCount > 217) return false);
+ LLVM_DEBUG(if (calledCount == 213) return false);
+ LLVM_DEBUG(if (calledCount == 214) return false);
+ LLVM_DEBUG(if (calledCount == 215) return false);
+ LLVM_DEBUG(if (calledCount == 216) return false);
+ LLVM_DEBUG(dbgs() << "visitXOR calledCount: " << calledCount << "\n");
+ LLVM_DEBUG(dbgs() << "I: "; I->dump());
+
+could be added to ``visitXOR`` to limit ``visitXor`` to being applied only to
+calls 212 and 217. This is from an actual test case and raises an important
+point---a simple binary search may not be sufficient, as transformations that
+interact may require isolating more than one call. In TargetLowering, use
+``return SDNode();`` instead of ``return false;``.
+
+Now that the number of transformations is down to a manageable number, try
+examining the output to see if you can figure out which transformations are
+being done. If that can be figured out, then do the usual debugging. If which
+code corresponds to the transformation being performed isn't obvious, set a
+breakpoint after the call count based disabling and step through the code.
+Alternatively, you can use "``printf``" style debugging to report waypoints.
Added: www-releases/trunk/9.0.0/docs/_sources/BuildingADistribution.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/_sources/BuildingADistribution.rst.txt?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/_sources/BuildingADistribution.rst.txt (added)
+++ www-releases/trunk/9.0.0/docs/_sources/BuildingADistribution.rst.txt Thu Sep 19 07:32:46 2019
@@ -0,0 +1,207 @@
+===============================
+Building a Distribution of LLVM
+===============================
+
+.. contents::
+ :local:
+
+Introduction
+============
+
+This document is geared toward people who want to build and package LLVM and any
+combination of LLVM sub-project tools for distribution. This document covers
+useful features of the LLVM build system as well as best practices and general
+information about packaging LLVM.
+
+If you are new to CMake you may find the :doc:`CMake` or :doc:`CMakePrimer`
+documentation useful. Some of the things covered in this document are the inner
+workings of the builds described in the :doc:`AdvancedBuilds` document.
+
+General Distribution Guidance
+=============================
+
+When building a distribution of a compiler it is generally advised to perform a
+bootstrap build of the compiler. That means building a "stage 1" compiler with
+your host toolchain, then building the "stage 2" compiler using the "stage 1"
+compiler. This is done so that the compiler you distribute benefits from all the
+bug fixes, performance optimizations and general improvements provided by the
+new compiler.
+
+In deciding how to build your distribution there are a few trade-offs that you
+will need to evaluate. The big two are:
+
+#. Compile time of the distribution against performance of the built compiler
+
+#. Binary size of the distribution against performance of the built compiler
+
+The guidance for maximizing performance of the generated compiler is to use LTO,
+PGO, and statically link everything. This will result in an overall larger
+distribution, and it will take longer to generate, but it provides the most
+opportunity for the compiler to optimize.
+
+The guidance for minimizing distribution size is to dynamically link LLVM and
+Clang libraries into the tools to reduce code duplication. This will come at a
+substantial performance penalty to the generated binary both because it reduces
+optimization opportunity, and because dynamic linking requires resolving symbols
+at process launch time, which can be very slow for C++ code.
+
+.. _shared_libs:
+
+.. warning::
+ One very important note: Distributions should never be built using the
+ *BUILD_SHARED_LIBS* CMake option. That option exists for optimizing developer
+ workflow only. Due to design and implementation decisions, LLVM relies on
+ global data which can end up being duplicated across shared libraries
+ resulting in bugs. As such this is not a safe way to distribute LLVM or
+ LLVM-based tools.
+
+The simplest example of building a distribution with reasonable performance is
+captured in the DistributionExample CMake cache file located at
+clang/cmake/caches/DistributionExample.cmake. The following command will perform
+and install the distribution build:
+
+.. code-block:: console
+
+ $ cmake -G Ninja -C <path to clang>/cmake/caches/DistributionExample.cmake <path to LLVM source>
+ $ ninja stage2-distribution
+ $ ninja stage2-install-distribution
+
+Difference between ``install`` and ``install-distribution``
+-----------------------------------------------------------
+
+One subtle but important thing to note is the difference between the ``install``
+and ``install-distribution`` targets. The ``install`` target is expected to
+install every part of LLVM that your build is configured to generate except the
+LLVM testing tools. Alternatively the ``install-distribution`` target, which is
+recommended for building distributions, only installs specific parts of LLVM as
+specified at configuration time by *LLVM_DISTRIBUTION_COMPONENTS*.
+
+Additionally by default the ``install`` target will install the LLVM testing
+tools as the public tools. This can be changed well by setting
+*LLVM_INSTALL_TOOLCHAIN_ONLY* to ``On``. The LLVM tools are intended for
+development and testing of LLVM, and should only be included in distributions
+that support LLVM development.
+
+When building with *LLVM_DISTRIBUTION_COMPONENTS* the build system also
+generates a ``distribution`` target which builds all the components specified in
+the list. This is a convenience build target to allow building just the
+distributed pieces without needing to build all configured targets.
+
+Special Notes for Library-only Distributions
+--------------------------------------------
+
+One of the most powerful features of LLVM is its library-first design mentality
+and the way you can compose a wide variety of tools using different portions of
+LLVM. Even in this situation using *BUILD_SHARED_LIBS* is not supported. If you
+want to distribute LLVM as a shared library for use in a tool, the recommended
+method is using *LLVM_BUILD_LLVM_DYLIB*, and you can use *LLVM_DYLIB_COMPONENTS*
+to configure which LLVM components are part of libLLVM.
+
+Options for Optimizing LLVM
+===========================
+
+There are four main build optimizations that our CMake build system supports.
+When performing a bootstrap build it is not beneficial to do anything other than
+setting *CMAKE_BUILD_TYPE* to ``Release`` for the stage-1 compiler. This is
+because the more intensive optimizations are expensive to perform and the
+stage-1 compiler is thrown away. All of the further options described should be
+set on the stage-2 compiler either using a CMake cache file, or by prefixing the
+option with *BOOTSTRAP_*.
+
+The first and simplest to use is the compiler optimization level by setting the
+*CMAKE_BUILD_TYPE* option. The main values of interest are ``Release`` or
+``RelWithDebInfo``. By default the ``Release`` option uses the ``-O3``
+optimization level, and ``RelWithDebInfo`` uses ``-O2``. If you want to generate
+debug information and use ``-O3`` you can override the
+*CMAKE_<LANG>_FLAGS_RELWITHDEBINFO* option for C and CXX.
+DistributionExample.cmake does this.
+
+Another easy to use option is Link-Time-Optimization. You can set the
+*LLVM_ENABLE_LTO* option on your stage-2 build to ``Thin`` or ``Full`` to enable
+building LLVM with LTO. These options will significantly increase link time of
+the binaries in the distribution, but it will create much faster binaries. This
+option should not be used if your distribution includes static archives, as the
+objects inside the archive will be LLVM bitcode, which is not portable.
+
+The :doc:`AdvancedBuilds` documentation describes the built-in tooling for
+generating LLVM profiling information to drive Profile-Guided-Optimization. The
+in-tree profiling tests are very limited, and generating the profile takes a
+significant amount of time, but it can result in a significant improvement in
+the performance of the generated binaries.
+
+In addition to PGO profiling we also have limited support in-tree for generating
+linker order files. These files provide the linker with a suggested ordering for
+functions in the final binary layout. This can measurably speed up clang by
+physically grouping functions that are called temporally close to eachother. The
+current tooling is only available on Darwin systems with ``dtrace(1)``. It is
+worth noting that dtrace is non-deterministic, and so the order file generation
+using dtrace is also non-deterministic.
+
+Options for Reducing Size
+=========================
+
+.. warning::
+ Any steps taken to reduce the binary size will come at a cost of runtime
+ performance in the generated binaries.
+
+The simplest and least significant way to reduce binary size is to set the
+*CMAKE_BUILD_TYPE* variable to ``MinSizeRel``, which will set the compiler
+optimization level to ``-Os`` which optimizes for binary size. This will have
+both the least benefit to size and the least impact on performance.
+
+The most impactful way to reduce binary size is to dynamically link LLVM into
+all the tools. This reduces code size by decreasing duplication of common code
+between the LLVM-based tools. This can be done by setting the following two
+CMake options to ``On``: *LLVM_BUILD_LLVM_DYLIB* and *LLVM_LINK_LLVM_DYLIB*.
+
+.. warning::
+ Distributions should never be built using the *BUILD_SHARED_LIBS* CMake
+ option. (:ref:`See the warning above for more explanation <shared_libs>`.).
+
+Relevant CMake Options
+======================
+
+This section provides documentation of the CMake options that are intended to
+help construct distributions. This is not an exhaustive list, and many
+additional options are documented in the :doc:`CMake` page. Some key options
+that are already documented include: *LLVM_TARGETS_TO_BUILD*,
+*LLVM_ENABLE_PROJECTS*, *LLVM_BUILD_LLVM_DYLIB*, and *LLVM_LINK_LLVM_DYLIB*.
+
+**LLVM_ENABLE_RUNTIMES**:STRING
+ When building a distribution that includes LLVM runtime projects (i.e. libcxx,
+ compiler-rt, libcxxabi, libunwind...), it is important to build those projects
+ with the just-built compiler.
+
+**LLVM_DISTRIBUTION_COMPONENTS**:STRING
+ This variable can be set to a semi-colon separated list of LLVM build system
+ components to install. All LLVM-based tools are components, as well as most
+ of the libraries and runtimes. Component names match the names of the build
+ system targets.
+
+**LLVM_RUNTIME_DISTRIBUTION_COMPONENTS**:STRING
+ This variable can be set to a semi-colon separated list of runtime library
+ components. This is used in conjunction with *LLVM_ENABLE_RUNTIMES* to specify
+ components of runtime libraries that you want to include in your distribution.
+ Just like with *LLVM_DISTRIBUTION_COMPONENTS*, component names match the names
+ of the build system targets.
+
+**LLVM_DYLIB_COMPONENTS**:STRING
+ This variable can be set to a semi-colon separated name of LLVM library
+ components. LLVM library components are either library names with the LLVM
+ prefix removed (i.e. Support, Demangle...), LLVM target names, or special
+ purpose component names. The special purpose component names are:
+
+ #. ``all`` - All LLVM available component libraries
+ #. ``Native`` - The LLVM target for the Native system
+ #. ``AllTargetsAsmPrinters`` - All the included target ASM printers libraries
+ #. ``AllTargetsAsmParsers`` - All the included target ASM parsers libraries
+ #. ``AllTargetsDescs`` - All the included target descriptions libraries
+ #. ``AllTargetsDisassemblers`` - All the included target dissassemblers libraries
+ #. ``AllTargetsInfos`` - All the included target info libraries
+
+**LLVM_INSTALL_TOOLCHAIN_ONLY**:BOOL
+ This option defaults to ``Off``: when set to ``On`` it removes many of the
+ LLVM development and testing tools as well as component libraries from the
+ default ``install`` target. Including the development tools is not recommended
+ for distributions as many of the LLVM tools are only intended for development
+ and testing use.
Added: www-releases/trunk/9.0.0/docs/_sources/CFIVerify.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/_sources/CFIVerify.rst.txt?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/_sources/CFIVerify.rst.txt (added)
+++ www-releases/trunk/9.0.0/docs/_sources/CFIVerify.rst.txt Thu Sep 19 07:32:46 2019
@@ -0,0 +1,93 @@
+==============================================
+Control Flow Verification Tool Design Document
+==============================================
+
+.. contents::
+ :local:
+
+Objective
+=========
+
+This document provides an overview of an external tool to verify the protection
+mechanisms implemented by Clang's *Control Flow Integrity* (CFI) schemes
+(``-fsanitize=cfi``). This tool, provided a binary or DSO, should infer whether
+indirect control flow operations are protected by CFI, and should output these
+results in a human-readable form.
+
+This tool should also be added as part of Clang's continuous integration testing
+framework, where modifications to the compiler ensure that CFI protection
+schemes are still present in the final binary.
+
+Location
+========
+
+This tool will be present as a part of the LLVM toolchain, and will reside in
+the "/llvm/tools/llvm-cfi-verify" directory, relative to the LLVM trunk. It will
+be tested in two methods:
+
+- Unit tests to validate code sections, present in
+ "/llvm/unittests/tools/llvm-cfi-verify".
+- Integration tests, present in "/llvm/tools/clang/test/LLVMCFIVerify". These
+ integration tests are part of clang as part of a continuous integration
+ framework, ensuring updates to the compiler that reduce CFI coverage on
+ indirect control flow instructions are identified.
+
+Background
+==========
+
+This tool will continuously validate that CFI directives are properly
+implemented around all indirect control flows by analysing the output machine
+code. The analysis of machine code is important as it ensures that any bugs
+present in linker or compiler do not subvert CFI protections in the final
+shipped binary.
+
+Unprotected indirect control flow instructions will be flagged for manual
+review. These unexpected control flows may simply have not been accounted for in
+the compiler implementation of CFI (e.g. indirect jumps to facilitate switch
+statements may not be fully protected).
+
+It may be possible in the future to extend this tool to flag unnecessary CFI
+directives (e.g. CFI directives around a static call to a non-polymorphic base
+type). This type of directive has no security implications, but may present
+performance impacts.
+
+Design Ideas
+============
+
+This tool will disassemble binaries and DSO's from their machine code format and
+analyse the disassembled machine code. The tool will inspect virtual calls and
+indirect function calls. This tool will also inspect indirect jumps, as inlined
+functions and jump tables should also be subject to CFI protections. Non-virtual
+calls (``-fsanitize=cfi-nvcall``) and cast checks (``-fsanitize=cfi-*cast*``)
+are not implemented due to a lack of information provided by the bytecode.
+
+The tool would operate by searching for indirect control flow instructions in
+the disassembly. A control flow graph would be generated from a small buffer of
+the instructions surrounding the 'target' control flow instruction. If the
+target instruction is branched-to, the fallthrough of the branch should be the
+CFI trap (on x86, this is a ``ud2`` instruction). If the target instruction is
+the fallthrough (i.e. immediately succeeds) of a conditional jump, the
+conditional jump target should be the CFI trap. If an indirect control flow
+instruction does not conform to one of these formats, the target will be noted
+as being CFI-unprotected.
+
+Note that in the second case outlined above (where the target instruction is the
+fallthrough of a conditional jump), if the target represents a vcall that takes
+arguments, these arguments may be pushed to the stack after the branch but
+before the target instruction. In these cases, a secondary 'spill graph' in
+constructed, to ensure the register argument used by the indirect jump/call is
+not spilled from the stack at any point in the interim period. If there are no
+spills that affect the target register, the target is marked as CFI-protected.
+
+Other Design Notes
+~~~~~~~~~~~~~~~~~~
+
+Only machine code sections that are marked as executable will be subject to this
+analysis. Non-executable sections do not require analysis as any execution
+present in these sections has already violated the control flow integrity.
+
+Suitable extensions may be made at a later date to include analysis for indirect
+control flow operations across DSO boundaries. Currently, these CFI features are
+only experimental with an unstable ABI, making them unsuitable for analysis.
+
+The tool currently only supports the x86, x86_64, and AArch64 architectures.
Added: www-releases/trunk/9.0.0/docs/_sources/CMake.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/_sources/CMake.rst.txt?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/_sources/CMake.rst.txt (added)
+++ www-releases/trunk/9.0.0/docs/_sources/CMake.rst.txt Thu Sep 19 07:32:46 2019
@@ -0,0 +1,843 @@
+========================
+Building LLVM with CMake
+========================
+
+.. contents::
+ :local:
+
+Introduction
+============
+
+`CMake <http://www.cmake.org/>`_ is a cross-platform build-generator tool. CMake
+does not build the project, it generates the files needed by your build tool
+(GNU make, Visual Studio, etc.) for building LLVM.
+
+If **you are a new contributor**, please start with the :doc:`GettingStarted`
+page. This page is geared for existing contributors moving from the
+legacy configure/make system.
+
+If you are really anxious about getting a functional LLVM build, go to the
+`Quick start`_ section. If you are a CMake novice, start with `Basic CMake usage`_
+and then go back to the `Quick start`_ section once you know what you are doing. The
+`Options and variables`_ section is a reference for customizing your build. If
+you already have experience with CMake, this is the recommended starting point.
+
+This page is geared towards users of the LLVM CMake build. If you're looking for
+information about modifying the LLVM CMake build system you may want to see the
+:doc:`CMakePrimer` page. It has a basic overview of the CMake language.
+
+.. _Quick start:
+
+Quick start
+===========
+
+We use here the command-line, non-interactive CMake interface.
+
+#. `Download <http://www.cmake.org/cmake/resources/software.html>`_ and install
+ CMake. Version 3.4.3 is the minimum required.
+
+#. Open a shell. Your development tools must be reachable from this shell
+ through the PATH environment variable.
+
+#. Create a build directory. Building LLVM in the source
+ directory is not supported. cd to this directory:
+
+ .. code-block:: console
+
+ $ mkdir mybuilddir
+ $ cd mybuilddir
+
+#. Execute this command in the shell replacing `path/to/llvm/source/root` with
+ the path to the root of your LLVM source tree:
+
+ .. code-block:: console
+
+ $ cmake path/to/llvm/source/root
+
+ CMake will detect your development environment, perform a series of tests, and
+ generate the files required for building LLVM. CMake will use default values
+ for all build parameters. See the `Options and variables`_ section for
+ a list of build parameters that you can modify.
+
+ This can fail if CMake can't detect your toolset, or if it thinks that the
+ environment is not sane enough. In this case, make sure that the toolset that
+ you intend to use is the only one reachable from the shell, and that the shell
+ itself is the correct one for your development environment. CMake will refuse
+ to build MinGW makefiles if you have a POSIX shell reachable through the PATH
+ environment variable, for instance. You can force CMake to use a given build
+ tool; for instructions, see the `Usage`_ section, below.
+
+#. After CMake has finished running, proceed to use IDE project files, or start
+ the build from the build directory:
+
+ .. code-block:: console
+
+ $ cmake --build .
+
+ The ``--build`` option tells ``cmake`` to invoke the underlying build
+ tool (``make``, ``ninja``, ``xcodebuild``, ``msbuild``, etc.)
+
+ The underlying build tool can be invoked directly, of course, but
+ the ``--build`` option is portable.
+
+#. After LLVM has finished building, install it from the build directory:
+
+ .. code-block:: console
+
+ $ cmake --build . --target install
+
+ The ``--target`` option with ``install`` parameter in addition to
+ the ``--build`` option tells ``cmake`` to build the ``install`` target.
+
+ It is possible to set a different install prefix at installation time
+ by invoking the ``cmake_install.cmake`` script generated in the
+ build directory:
+
+ .. code-block:: console
+
+ $ cmake -DCMAKE_INSTALL_PREFIX=/tmp/llvm -P cmake_install.cmake
+
+.. _Basic CMake usage:
+.. _Usage:
+
+Basic CMake usage
+=================
+
+This section explains basic aspects of CMake
+which you may need in your day-to-day usage.
+
+CMake comes with extensive documentation, in the form of html files, and as
+online help accessible via the ``cmake`` executable itself. Execute ``cmake
+--help`` for further help options.
+
+CMake allows you to specify a build tool (e.g., GNU make, Visual Studio,
+or Xcode). If not specified on the command line, CMake tries to guess which
+build tool to use, based on your environment. Once it has identified your
+build tool, CMake uses the corresponding *Generator* to create files for your
+build tool (e.g., Makefiles or Visual Studio or Xcode project files). You can
+explicitly specify the generator with the command line option ``-G "Name of the
+generator"``. To see a list of the available generators on your system, execute
+
+.. code-block:: console
+
+ $ cmake --help
+
+This will list the generator names at the end of the help text.
+
+Generators' names are case-sensitive, and may contain spaces. For this reason,
+you should enter them exactly as they are listed in the ``cmake --help``
+output, in quotes. For example, to generate project files specifically for
+Visual Studio 12, you can execute:
+
+.. code-block:: console
+
+ $ cmake -G "Visual Studio 12" path/to/llvm/source/root
+
+For a given development platform there can be more than one adequate
+generator. If you use Visual Studio, "NMake Makefiles" is a generator you can use
+for building with NMake. By default, CMake chooses the most specific generator
+supported by your development environment. If you want an alternative generator,
+you must tell this to CMake with the ``-G`` option.
+
+.. todo::
+
+ Explain variables and cache. Move explanation here from #options section.
+
+.. _Options and variables:
+
+Options and variables
+=====================
+
+Variables customize how the build will be generated. Options are boolean
+variables, with possible values ON/OFF. Options and variables are defined on the
+CMake command line like this:
+
+.. code-block:: console
+
+ $ cmake -DVARIABLE=value path/to/llvm/source
+
+You can set a variable after the initial CMake invocation to change its
+value. You can also undefine a variable:
+
+.. code-block:: console
+
+ $ cmake -UVARIABLE path/to/llvm/source
+
+Variables are stored in the CMake cache. This is a file named ``CMakeCache.txt``
+stored at the root of your build directory that is generated by ``cmake``.
+Editing it yourself is not recommended.
+
+Variables are listed in the CMake cache and later in this document with
+the variable name and type separated by a colon. You can also specify the
+variable and type on the CMake command line:
+
+.. code-block:: console
+
+ $ cmake -DVARIABLE:TYPE=value path/to/llvm/source
+
+Frequently-used CMake variables
+-------------------------------
+
+Here are some of the CMake variables that are used often, along with a
+brief explanation and LLVM-specific notes. For full documentation, consult the
+CMake manual, or execute ``cmake --help-variable VARIABLE_NAME``.
+
+**CMAKE_BUILD_TYPE**:STRING
+ Sets the build type for ``make``-based generators. Possible values are
+ Release, Debug, RelWithDebInfo and MinSizeRel. If you are using an IDE such as
+ Visual Studio, you should use the IDE settings to set the build type.
+ Be aware that Release and RelWithDebInfo use different optimization levels on
+ most platforms.
+
+**CMAKE_INSTALL_PREFIX**:PATH
+ Path where LLVM will be installed if "make install" is invoked or the
+ "install" target is built.
+
+**LLVM_LIBDIR_SUFFIX**:STRING
+ Extra suffix to append to the directory where libraries are to be
+ installed. On a 64-bit architecture, one could use ``-DLLVM_LIBDIR_SUFFIX=64``
+ to install libraries to ``/usr/lib64``.
+
+**CMAKE_C_FLAGS**:STRING
+ Extra flags to use when compiling C source files.
+
+**CMAKE_CXX_FLAGS**:STRING
+ Extra flags to use when compiling C++ source files.
+
+.. _LLVM-specific variables:
+
+LLVM-specific variables
+-----------------------
+
+**LLVM_TARGETS_TO_BUILD**:STRING
+ Semicolon-separated list of targets to build, or *all* for building all
+ targets. Case-sensitive. Defaults to *all*. Example:
+ ``-DLLVM_TARGETS_TO_BUILD="X86;PowerPC"``.
+
+**LLVM_BUILD_TOOLS**:BOOL
+ Build LLVM tools. Defaults to ON. Targets for building each tool are generated
+ in any case. You can build a tool separately by invoking its target. For
+ example, you can build *llvm-as* with a Makefile-based system by executing *make
+ llvm-as* at the root of your build directory.
+
+**LLVM_INCLUDE_TOOLS**:BOOL
+ Generate build targets for the LLVM tools. Defaults to ON. You can use this
+ option to disable the generation of build targets for the LLVM tools.
+
+**LLVM_INSTALL_BINUTILS_SYMLINKS**:BOOL
+ Install symlinks from the binutils tool names to the corresponding LLVM tools.
+ For example, ar will be symlinked to llvm-ar.
+
+**LLVM_BUILD_EXAMPLES**:BOOL
+ Build LLVM examples. Defaults to OFF. Targets for building each example are
+ generated in any case. See documentation for *LLVM_BUILD_TOOLS* above for more
+ details.
+
+**LLVM_INCLUDE_EXAMPLES**:BOOL
+ Generate build targets for the LLVM examples. Defaults to ON. You can use this
+ option to disable the generation of build targets for the LLVM examples.
+
+**LLVM_BUILD_TESTS**:BOOL
+ Build LLVM unit tests. Defaults to OFF. Targets for building each unit test
+ are generated in any case. You can build a specific unit test using the
+ targets defined under *unittests*, such as ADTTests, IRTests, SupportTests,
+ etc. (Search for ``add_llvm_unittest`` in the subdirectories of *unittests*
+ for a complete list of unit tests.) It is possible to build all unit tests
+ with the target *UnitTests*.
+
+**LLVM_INCLUDE_TESTS**:BOOL
+ Generate build targets for the LLVM unit tests. Defaults to ON. You can use
+ this option to disable the generation of build targets for the LLVM unit
+ tests.
+
+**LLVM_BUILD_BENCHMARKS**:BOOL
+ Adds benchmarks to the list of default targets. Defaults to OFF.
+
+**LLVM_INCLUDE_BENCHMARKS**:BOOL
+ Generate build targets for the LLVM benchmarks. Defaults to ON.
+
+**LLVM_APPEND_VC_REV**:BOOL
+ Embed version control revision info (svn revision number or Git revision id).
+ The version info is provided by the ``LLVM_REVISION`` macro in
+ ``llvm/include/llvm/Support/VCSRevision.h``. Developers using git who don't
+ need revision info can disable this option to avoid re-linking most binaries
+ after a branch switch. Defaults to ON.
+
+**LLVM_ENABLE_THREADS**:BOOL
+ Build with threads support, if available. Defaults to ON.
+
+**LLVM_ENABLE_UNWIND_TABLES**:BOOL
+ Enable unwind tables in the binary. Disabling unwind tables can reduce the
+ size of the libraries. Defaults to ON.
+
+**LLVM_CXX_STD**:STRING
+ Build with the specified C++ standard. Defaults to "c++11".
+
+**LLVM_ENABLE_ASSERTIONS**:BOOL
+ Enables code assertions. Defaults to ON if and only if ``CMAKE_BUILD_TYPE``
+ is *Debug*.
+
+**LLVM_ENABLE_EH**:BOOL
+ Build LLVM with exception-handling support. This is necessary if you wish to
+ link against LLVM libraries and make use of C++ exceptions in your own code
+ that need to propagate through LLVM code. Defaults to OFF.
+
+**LLVM_ENABLE_EXPENSIVE_CHECKS**:BOOL
+ Enable additional time/memory expensive checking. Defaults to OFF.
+
+**LLVM_ENABLE_IDE**:BOOL
+ Tell the build system that an IDE is being used. This in turn disables the
+ creation of certain convenience build system targets, such as the various
+ ``install-*`` and ``check-*`` targets, since IDEs don't always deal well with
+ a large number of targets. This is usually autodetected, but it can be
+ configured manually to explicitly control the generation of those targets. One
+ scenario where a manual override may be desirable is when using Visual Studio
+ 2017's CMake integration, which would not be detected as an IDE otherwise.
+
+**LLVM_ENABLE_PIC**:BOOL
+ Add the ``-fPIC`` flag to the compiler command-line, if the compiler supports
+ this flag. Some systems, like Windows, do not need this flag. Defaults to ON.
+
+**LLVM_ENABLE_RTTI**:BOOL
+ Build LLVM with run-time type information. Defaults to OFF.
+
+**LLVM_ENABLE_WARNINGS**:BOOL
+ Enable all compiler warnings. Defaults to ON.
+
+**LLVM_ENABLE_PEDANTIC**:BOOL
+ Enable pedantic mode. This disables compiler-specific extensions, if
+ possible. Defaults to ON.
+
+**LLVM_ENABLE_WERROR**:BOOL
+ Stop and fail the build, if a compiler warning is triggered. Defaults to OFF.
+
+**LLVM_ABI_BREAKING_CHECKS**:STRING
+ Used to decide if LLVM should be built with ABI breaking checks or
+ not. Allowed values are `WITH_ASSERTS` (default), `FORCE_ON` and
+ `FORCE_OFF`. `WITH_ASSERTS` turns on ABI breaking checks in an
+ assertion enabled build. `FORCE_ON` (`FORCE_OFF`) turns them on
+ (off) irrespective of whether normal (`NDEBUG`-based) assertions are
+ enabled or not. A version of LLVM built with ABI breaking checks
+ is not ABI compatible with a version built without it.
+
+**LLVM_BUILD_32_BITS**:BOOL
+ Build 32-bit executables and libraries on 64-bit systems. This option is
+ available only on some 64-bit Unix systems. Defaults to OFF.
+
+**LLVM_TARGET_ARCH**:STRING
+ LLVM target to use for native code generation. This is required for JIT
+ generation. It defaults to "host", meaning that it shall pick the architecture
+ of the machine where LLVM is being built. If you are cross-compiling, set it
+ to the target architecture name.
+
+**LLVM_TABLEGEN**:STRING
+ Full path to a native TableGen executable (usually named ``llvm-tblgen``). This is
+ intended for cross-compiling: if the user sets this variable, no native
+ TableGen will be created.
+
+**LLVM_LIT_ARGS**:STRING
+ Arguments given to lit. ``make check`` and ``make clang-test`` are affected.
+ By default, ``'-sv --no-progress-bar'`` on Visual C++ and Xcode, ``'-sv'`` on
+ others.
+
+**LLVM_LIT_TOOLS_DIR**:PATH
+ The path to GnuWin32 tools for tests. Valid on Windows host. Defaults to
+ the empty string, in which case lit will look for tools needed for tests
+ (e.g. ``grep``, ``sort``, etc.) in your %PATH%. If GnuWin32 is not in your
+ %PATH%, then you can set this variable to the GnuWin32 directory so that
+ lit can find tools needed for tests in that directory.
+
+**LLVM_ENABLE_FFI**:BOOL
+ Indicates whether the LLVM Interpreter will be linked with the Foreign Function
+ Interface library (libffi) in order to enable calling external functions.
+ If the library or its headers are installed in a custom
+ location, you can also set the variables FFI_INCLUDE_DIR and
+ FFI_LIBRARY_DIR to the directories where ffi.h and libffi.so can be found,
+ respectively. Defaults to OFF.
+
+**LLVM_EXTERNAL_{CLANG,LLD,POLLY}_SOURCE_DIR**:PATH
+ These variables specify the path to the source directory for the external
+ LLVM projects Clang, lld, and Polly, respectively, relative to the top-level
+ source directory. If the in-tree subdirectory for an external project
+ exists (e.g., llvm/tools/clang for Clang), then the corresponding variable
+ will not be used. If the variable for an external project does not point
+ to a valid path, then that project will not be built.
+
+**LLVM_ENABLE_PROJECTS**:STRING
+ Semicolon-separated list of projects to build, or *all* for building all
+ (clang, libcxx, libcxxabi, lldb, compiler-rt, lld, polly) projects.
+ This flag assumes that projects are checked out side-by-side and not nested,
+ i.e. clang needs to be in parallel of llvm instead of nested in `llvm/tools`.
+ This feature allows to have one build for only LLVM and another for clang+llvm
+ using the same source checkout.
+
+**LLVM_EXTERNAL_PROJECTS**:STRING
+ Semicolon-separated list of additional external projects to build as part of
+ llvm. For each project LLVM_EXTERNAL_<NAME>_SOURCE_DIR have to be specified
+ with the path for the source code of the project. Example:
+ ``-DLLVM_EXTERNAL_PROJECTS="Foo;Bar"
+ -DLLVM_EXTERNAL_FOO_SOURCE_DIR=/src/foo
+ -DLLVM_EXTERNAL_BAR_SOURCE_DIR=/src/bar``.
+
+**LLVM_USE_OPROFILE**:BOOL
+ Enable building OProfile JIT support. Defaults to OFF.
+
+**LLVM_PROFDATA_FILE**:PATH
+ Path to a profdata file to pass into clang's -fprofile-instr-use flag. This
+ can only be specified if you're building with clang.
+
+**LLVM_USE_INTEL_JITEVENTS**:BOOL
+ Enable building support for Intel JIT Events API. Defaults to OFF.
+
+**LLVM_ENABLE_LIBPFM**:BOOL
+ Enable building with libpfm to support hardware counter measurements in LLVM
+ tools.
+ Defaults to ON.
+
+ **LLVM_USE_PERF**:BOOL
+ Enable building support for Perf (linux profiling tool) JIT support. Defaults to OFF.
+
+**LLVM_ENABLE_ZLIB**:BOOL
+ Enable building with zlib to support compression/uncompression in LLVM tools.
+ Defaults to ON.
+
+**LLVM_ENABLE_DIA_SDK**:BOOL
+ Enable building with MSVC DIA SDK for PDB debugging support. Available
+ only with MSVC. Defaults to ON.
+
+**LLVM_USE_SANITIZER**:STRING
+ Define the sanitizer used to build LLVM binaries and tests. Possible values
+ are ``Address``, ``Memory``, ``MemoryWithOrigins``, ``Undefined``, ``Thread``,
+ and ``Address;Undefined``. Defaults to empty string.
+
+**LLVM_ENABLE_LTO**:STRING
+ Add ``-flto`` or ``-flto=`` flags to the compile and link command
+ lines, enabling link-time optimization. Possible values are ``Off``,
+ ``On``, ``Thin`` and ``Full``. Defaults to OFF.
+
+**LLVM_USE_LINKER**:STRING
+ Add ``-fuse-ld={name}`` to the link invocation. The possible value depend on
+ your compiler, for clang the value can be an absolute path to your custom
+ linker, otherwise clang will prefix the name with ``ld.`` and apply its usual
+ search. For example to link LLVM with the Gold linker, cmake can be invoked
+ with ``-DLLVM_USE_LINKER=gold``.
+
+**LLVM_ENABLE_LLD**:BOOL
+ This option is equivalent to `-DLLVM_USE_LINKER=lld`, except during a 2-stage
+ build where a dependency is added from the first stage to the second ensuring
+ that lld is built before stage2 begins.
+
+**LLVM_PARALLEL_COMPILE_JOBS**:STRING
+ Define the maximum number of concurrent compilation jobs.
+
+**LLVM_PARALLEL_LINK_JOBS**:STRING
+ Define the maximum number of concurrent link jobs.
+
+**LLVM_BUILD_DOCS**:BOOL
+ Adds all *enabled* documentation targets (i.e. Doxgyen and Sphinx targets) as
+ dependencies of the default build targets. This results in all of the (enabled)
+ documentation targets being as part of a normal build. If the ``install``
+ target is run then this also enables all built documentation targets to be
+ installed. Defaults to OFF. To enable a particular documentation target, see
+ see LLVM_ENABLE_SPHINX and LLVM_ENABLE_DOXYGEN.
+
+**LLVM_ENABLE_DOXYGEN**:BOOL
+ Enables the generation of browsable HTML documentation using doxygen.
+ Defaults to OFF.
+
+**LLVM_ENABLE_DOXYGEN_QT_HELP**:BOOL
+ Enables the generation of a Qt Compressed Help file. Defaults to OFF.
+ This affects the make target ``doxygen-llvm``. When enabled, apart from
+ the normal HTML output generated by doxygen, this will produce a QCH file
+ named ``org.llvm.qch``. You can then load this file into Qt Creator.
+ This option is only useful in combination with ``-DLLVM_ENABLE_DOXYGEN=ON``;
+ otherwise this has no effect.
+
+**LLVM_DOXYGEN_QCH_FILENAME**:STRING
+ The filename of the Qt Compressed Help file that will be generated when
+ ``-DLLVM_ENABLE_DOXYGEN=ON`` and
+ ``-DLLVM_ENABLE_DOXYGEN_QT_HELP=ON`` are given. Defaults to
+ ``org.llvm.qch``.
+ This option is only useful in combination with
+ ``-DLLVM_ENABLE_DOXYGEN_QT_HELP=ON``;
+ otherwise it has no effect.
+
+**LLVM_DOXYGEN_QHP_NAMESPACE**:STRING
+ Namespace under which the intermediate Qt Help Project file lives. See `Qt
+ Help Project`_
+ for more information. Defaults to "org.llvm". This option is only useful in
+ combination with ``-DLLVM_ENABLE_DOXYGEN_QT_HELP=ON``; otherwise
+ it has no effect.
+
+**LLVM_DOXYGEN_QHP_CUST_FILTER_NAME**:STRING
+ See `Qt Help Project`_ for
+ more information. Defaults to the CMake variable ``${PACKAGE_STRING}`` which
+ is a combination of the package name and version string. This filter can then
+ be used in Qt Creator to select only documentation from LLVM when browsing
+ through all the help files that you might have loaded. This option is only
+ useful in combination with ``-DLLVM_ENABLE_DOXYGEN_QT_HELP=ON``;
+ otherwise it has no effect.
+
+.. _Qt Help Project: http://qt-project.org/doc/qt-4.8/qthelpproject.html#custom-filters
+
+**LLVM_DOXYGEN_QHELPGENERATOR_PATH**:STRING
+ The path to the ``qhelpgenerator`` executable. Defaults to whatever CMake's
+ ``find_program()`` can find. This option is only useful in combination with
+ ``-DLLVM_ENABLE_DOXYGEN_QT_HELP=ON``; otherwise it has no
+ effect.
+
+**LLVM_DOXYGEN_SVG**:BOOL
+ Uses .svg files instead of .png files for graphs in the Doxygen output.
+ Defaults to OFF.
+
+**LLVM_INSTALL_DOXYGEN_HTML_DIR**:STRING
+ The path to install Doxygen-generated HTML documentation to. This path can
+ either be absolute or relative to the CMAKE_INSTALL_PREFIX. Defaults to
+ `share/doc/llvm/doxygen-html`.
+
+**LLVM_ENABLE_SPHINX**:BOOL
+ If specified, CMake will search for the ``sphinx-build`` executable and will make
+ the ``SPHINX_OUTPUT_HTML`` and ``SPHINX_OUTPUT_MAN`` CMake options available.
+ Defaults to OFF.
+
+**SPHINX_EXECUTABLE**:STRING
+ The path to the ``sphinx-build`` executable detected by CMake.
+ For installation instructions, see
+ http://www.sphinx-doc.org/en/latest/install.html
+
+**SPHINX_OUTPUT_HTML**:BOOL
+ If enabled (and ``LLVM_ENABLE_SPHINX`` is enabled) then the targets for
+ building the documentation as html are added (but not built by default unless
+ ``LLVM_BUILD_DOCS`` is enabled). There is a target for each project in the
+ source tree that uses sphinx (e.g. ``docs-llvm-html``, ``docs-clang-html``
+ and ``docs-lld-html``). Defaults to ON.
+
+**SPHINX_OUTPUT_MAN**:BOOL
+ If enabled (and ``LLVM_ENABLE_SPHINX`` is enabled) the targets for building
+ the man pages are added (but not built by default unless ``LLVM_BUILD_DOCS``
+ is enabled). Currently the only target added is ``docs-llvm-man``. Defaults
+ to ON.
+
+**SPHINX_WARNINGS_AS_ERRORS**:BOOL
+ If enabled then sphinx documentation warnings will be treated as
+ errors. Defaults to ON.
+
+**LLVM_INSTALL_SPHINX_HTML_DIR**:STRING
+ The path to install Sphinx-generated HTML documentation to. This path can
+ either be absolute or relative to the CMAKE_INSTALL_PREFIX. Defaults to
+ `share/doc/llvm/html`.
+
+**LLVM_INSTALL_OCAMLDOC_HTML_DIR**:STRING
+ The path to install OCamldoc-generated HTML documentation to. This path can
+ either be absolute or relative to the CMAKE_INSTALL_PREFIX. Defaults to
+ `share/doc/llvm/ocaml-html`.
+
+**LLVM_CREATE_XCODE_TOOLCHAIN**:BOOL
+ macOS Only: If enabled CMake will generate a target named
+ 'install-xcode-toolchain'. This target will create a directory at
+ $CMAKE_INSTALL_PREFIX/Toolchains containing an xctoolchain directory which can
+ be used to override the default system tools.
+
+**LLVM_BUILD_LLVM_DYLIB**:BOOL
+ If enabled, the target for building the libLLVM shared library is added.
+ This library contains all of LLVM's components in a single shared library.
+ Defaults to OFF. This cannot be used in conjunction with BUILD_SHARED_LIBS.
+ Tools will only be linked to the libLLVM shared library if LLVM_LINK_LLVM_DYLIB
+ is also ON.
+ The components in the library can be customised by setting LLVM_DYLIB_COMPONENTS
+ to a list of the desired components.
+
+**LLVM_LINK_LLVM_DYLIB**:BOOL
+ If enabled, tools will be linked with the libLLVM shared library. Defaults
+ to OFF. Setting LLVM_LINK_LLVM_DYLIB to ON also sets LLVM_BUILD_LLVM_DYLIB
+ to ON.
+
+**BUILD_SHARED_LIBS**:BOOL
+ Flag indicating if each LLVM component (e.g. Support) is built as a shared
+ library (ON) or as a static library (OFF). Its default value is OFF. On
+ Windows, shared libraries may be used when building with MinGW, including
+ mingw-w64, but not when building with the Microsoft toolchain.
+
+ .. note:: BUILD_SHARED_LIBS is only recommended for use by LLVM developers.
+ If you want to build LLVM as a shared library, you should use the
+ ``LLVM_BUILD_LLVM_DYLIB`` option.
+
+**LLVM_OPTIMIZED_TABLEGEN**:BOOL
+ If enabled and building a debug or asserts build the CMake build system will
+ generate a Release build tree to build a fully optimized tablegen for use
+ during the build. Enabling this option can significantly speed up build times
+ especially when building LLVM in Debug configurations.
+
+**LLVM_REVERSE_ITERATION**:BOOL
+ If enabled, all supported unordered llvm containers would be iterated in
+ reverse order. This is useful for uncovering non-determinism caused by
+ iteration of unordered containers.
+
+**LLVM_BUILD_INSTRUMENTED_COVERAGE**:BOOL
+ If enabled, `source-based code coverage
+ <http://clang.llvm.org/docs/SourceBasedCodeCoverage.html>`_ instrumentation
+ is enabled while building llvm.
+
+**LLVM_CCACHE_BUILD**:BOOL
+ If enabled and the ``ccache`` program is available, then LLVM will be
+ built using ``ccache`` to speed up rebuilds of LLVM and its components.
+ Defaults to OFF. The size and location of the cache maintained
+ by ``ccache`` can be adjusted via the LLVM_CCACHE_MAXSIZE and LLVM_CCACHE_DIR
+ options, which are passed to the CCACHE_MAXSIZE and CCACHE_DIR environment
+ variables, respectively.
+
+**LLVM_FORCE_USE_OLD_TOOLCHAIN**:BOOL
+ If enabled, the compiler and standard library versions won't be checked. LLVM
+ may not compile at all, or might fail at runtime due to known bugs in these
+ toolchains.
+
+**LLVM_TEMPORARILY_ALLOW_OLD_TOOLCHAIN**:BOOL
+ If enabled, the compiler version check will only warn when using a toolchain
+ which is about to be deprecated, instead of emitting an error.
+
+**LLVM_USE_NEWPM**:BOOL
+ If enabled, use the experimental new pass manager.
+
+**LLVM_ENABLE_BINDINGS**:BOOL
+ If disabled, do not try to build the OCaml and go bindings.
+
+CMake Caches
+============
+
+Recently LLVM and Clang have been adding some more complicated build system
+features. Utilizing these new features often involves a complicated chain of
+CMake variables passed on the command line. Clang provides a collection of CMake
+cache scripts to make these features more approachable.
+
+CMake cache files are utilized using CMake's -C flag:
+
+.. code-block:: console
+
+ $ cmake -C <path to cache file> <path to sources>
+
+CMake cache scripts are processed in an isolated scope, only cached variables
+remain set when the main configuration runs. CMake cached variables do not reset
+variables that are already set unless the FORCE option is specified.
+
+A few notes about CMake Caches:
+
+- Order of command line arguments is important
+
+ - -D arguments specified before -C are set before the cache is processed and
+ can be read inside the cache file
+ - -D arguments specified after -C are set after the cache is processed and
+ are unset inside the cache file
+
+- All -D arguments will override cache file settings
+- CMAKE_TOOLCHAIN_FILE is evaluated after both the cache file and the command
+ line arguments
+- It is recommended that all -D options should be specified *before* -C
+
+For more information about some of the advanced build configurations supported
+via Cache files see :doc:`AdvancedBuilds`.
+
+Executing the Tests
+===================
+
+Testing is performed when the *check-all* target is built. For instance, if you are
+using Makefiles, execute this command in the root of your build directory:
+
+.. code-block:: console
+
+ $ make check-all
+
+On Visual Studio, you may run tests by building the project "check-all".
+For more information about testing, see the :doc:`TestingGuide`.
+
+Cross compiling
+===============
+
+See `this wiki page <http://www.vtk.org/Wiki/CMake_Cross_Compiling>`_ for
+generic instructions on how to cross-compile with CMake. It goes into detailed
+explanations and may seem daunting, but it is not. On the wiki page there are
+several examples including toolchain files. Go directly to `this section
+<http://www.vtk.org/Wiki/CMake_Cross_Compiling#Information_how_to_set_up_various_cross_compiling_toolchains>`_
+for a quick solution.
+
+Also see the `LLVM-specific variables`_ section for variables used when
+cross-compiling.
+
+Embedding LLVM in your project
+==============================
+
+From LLVM 3.5 onwards the CMake build system exports LLVM libraries as
+importable CMake targets. This means that clients of LLVM can now reliably use
+CMake to develop their own LLVM-based projects against an installed version of
+LLVM regardless of how it was built.
+
+Here is a simple example of a CMakeLists.txt file that imports the LLVM libraries
+and uses them to build a simple application ``simple-tool``.
+
+.. code-block:: cmake
+
+ cmake_minimum_required(VERSION 3.4.3)
+ project(SimpleProject)
+
+ find_package(LLVM REQUIRED CONFIG)
+
+ message(STATUS "Found LLVM ${LLVM_PACKAGE_VERSION}")
+ message(STATUS "Using LLVMConfig.cmake in: ${LLVM_DIR}")
+
+ # Set your project compile flags.
+ # E.g. if using the C++ header files
+ # you will need to enable C++11 support
+ # for your compiler.
+
+ include_directories(${LLVM_INCLUDE_DIRS})
+ add_definitions(${LLVM_DEFINITIONS})
+
+ # Now build our tools
+ add_executable(simple-tool tool.cpp)
+
+ # Find the libraries that correspond to the LLVM components
+ # that we wish to use
+ llvm_map_components_to_libnames(llvm_libs support core irreader)
+
+ # Link against LLVM libraries
+ target_link_libraries(simple-tool ${llvm_libs})
+
+The ``find_package(...)`` directive when used in CONFIG mode (as in the above
+example) will look for the ``LLVMConfig.cmake`` file in various locations (see
+cmake manual for details). It creates a ``LLVM_DIR`` cache entry to save the
+directory where ``LLVMConfig.cmake`` is found or allows the user to specify the
+directory (e.g. by passing ``-DLLVM_DIR=/usr/lib/cmake/llvm`` to
+the ``cmake`` command or by setting it directly in ``ccmake`` or ``cmake-gui``).
+
+This file is available in two different locations.
+
+* ``<INSTALL_PREFIX>/lib/cmake/llvm/LLVMConfig.cmake`` where
+ ``<INSTALL_PREFIX>`` is the install prefix of an installed version of LLVM.
+ On Linux typically this is ``/usr/lib/cmake/llvm/LLVMConfig.cmake``.
+
+* ``<LLVM_BUILD_ROOT>/lib/cmake/llvm/LLVMConfig.cmake`` where
+ ``<LLVM_BUILD_ROOT>`` is the root of the LLVM build tree. **Note: this is only
+ available when building LLVM with CMake.**
+
+If LLVM is installed in your operating system's normal installation prefix (e.g.
+on Linux this is usually ``/usr/``) ``find_package(LLVM ...)`` will
+automatically find LLVM if it is installed correctly. If LLVM is not installed
+or you wish to build directly against the LLVM build tree you can use
+``LLVM_DIR`` as previously mentioned.
+
+The ``LLVMConfig.cmake`` file sets various useful variables. Notable variables
+include
+
+``LLVM_CMAKE_DIR``
+ The path to the LLVM CMake directory (i.e. the directory containing
+ LLVMConfig.cmake).
+
+``LLVM_DEFINITIONS``
+ A list of preprocessor defines that should be used when building against LLVM.
+
+``LLVM_ENABLE_ASSERTIONS``
+ This is set to ON if LLVM was built with assertions, otherwise OFF.
+
+``LLVM_ENABLE_EH``
+ This is set to ON if LLVM was built with exception handling (EH) enabled,
+ otherwise OFF.
+
+``LLVM_ENABLE_RTTI``
+ This is set to ON if LLVM was built with run time type information (RTTI),
+ otherwise OFF.
+
+``LLVM_INCLUDE_DIRS``
+ A list of include paths to directories containing LLVM header files.
+
+``LLVM_PACKAGE_VERSION``
+ The LLVM version. This string can be used with CMake conditionals, e.g., ``if
+ (${LLVM_PACKAGE_VERSION} VERSION_LESS "3.5")``.
+
+``LLVM_TOOLS_BINARY_DIR``
+ The path to the directory containing the LLVM tools (e.g. ``llvm-as``).
+
+Notice that in the above example we link ``simple-tool`` against several LLVM
+libraries. The list of libraries is determined by using the
+``llvm_map_components_to_libnames()`` CMake function. For a list of available
+components look at the output of running ``llvm-config --components``.
+
+Note that for LLVM < 3.5 ``llvm_map_components_to_libraries()`` was
+used instead of ``llvm_map_components_to_libnames()``. This is now deprecated
+and will be removed in a future version of LLVM.
+
+.. _cmake-out-of-source-pass:
+
+Developing LLVM passes out of source
+------------------------------------
+
+It is possible to develop LLVM passes out of LLVM's source tree (i.e. against an
+installed or built LLVM). An example of a project layout is provided below.
+
+.. code-block:: none
+
+ <project dir>/
+ |
+ CMakeLists.txt
+ <pass name>/
+ |
+ CMakeLists.txt
+ Pass.cpp
+ ...
+
+Contents of ``<project dir>/CMakeLists.txt``:
+
+.. code-block:: cmake
+
+ find_package(LLVM REQUIRED CONFIG)
+
+ add_definitions(${LLVM_DEFINITIONS})
+ include_directories(${LLVM_INCLUDE_DIRS})
+
+ add_subdirectory(<pass name>)
+
+Contents of ``<project dir>/<pass name>/CMakeLists.txt``:
+
+.. code-block:: cmake
+
+ add_library(LLVMPassname MODULE Pass.cpp)
+
+Note if you intend for this pass to be merged into the LLVM source tree at some
+point in the future it might make more sense to use LLVM's internal
+``add_llvm_library`` function with the MODULE argument instead by...
+
+
+Adding the following to ``<project dir>/CMakeLists.txt`` (after
+``find_package(LLVM ...)``)
+
+.. code-block:: cmake
+
+ list(APPEND CMAKE_MODULE_PATH "${LLVM_CMAKE_DIR}")
+ include(AddLLVM)
+
+And then changing ``<project dir>/<pass name>/CMakeLists.txt`` to
+
+.. code-block:: cmake
+
+ add_llvm_library(LLVMPassname MODULE
+ Pass.cpp
+ )
+
+When you are done developing your pass, you may wish to integrate it
+into the LLVM source tree. You can achieve it in two easy steps:
+
+#. Copying ``<pass name>`` folder into ``<LLVM root>/lib/Transform`` directory.
+
+#. Adding ``add_subdirectory(<pass name>)`` line into
+ ``<LLVM root>/lib/Transform/CMakeLists.txt``.
+
+Compiler/Platform-specific topics
+=================================
+
+Notes for specific compilers and/or platforms.
+
+Microsoft Visual C++
+--------------------
+
+**LLVM_COMPILER_JOBS**:STRING
+ Specifies the maximum number of parallel compiler jobs to use per project
+ when building with msbuild or Visual Studio. Only supported for the Visual
+ Studio 2010 CMake generator. 0 means use all processors. Default is 0.
Added: www-releases/trunk/9.0.0/docs/_sources/CMakePrimer.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/_sources/CMakePrimer.rst.txt?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/_sources/CMakePrimer.rst.txt (added)
+++ www-releases/trunk/9.0.0/docs/_sources/CMakePrimer.rst.txt Thu Sep 19 07:32:46 2019
@@ -0,0 +1,439 @@
+============
+CMake Primer
+============
+
+.. contents::
+ :local:
+
+.. warning::
+ Disclaimer: This documentation is written by LLVM project contributors `not`
+ anyone affiliated with the CMake project. This document may contain
+ inaccurate terminology, phrasing, or technical details. It is provided with
+ the best intentions.
+
+
+Introduction
+============
+
+The LLVM project and many of the core projects built on LLVM build using CMake.
+This document aims to provide a brief overview of CMake for developers modifying
+LLVM projects or building their own projects on top of LLVM.
+
+The official CMake language references is available in the cmake-language
+manpage and `cmake-language online documentation
+<https://cmake.org/cmake/help/v3.4/manual/cmake-language.7.html>`_.
+
+10,000 ft View
+==============
+
+CMake is a tool that reads script files in its own language that describe how a
+software project builds. As CMake evaluates the scripts it constructs an
+internal representation of the software project. Once the scripts have been
+fully processed, if there are no errors, CMake will generate build files to
+actually build the project. CMake supports generating build files for a variety
+of command line build tools as well as for popular IDEs.
+
+When a user runs CMake it performs a variety of checks similar to how autoconf
+worked historically. During the checks and the evaluation of the build
+description scripts CMake caches values into the CMakeCache. This is useful
+because it allows the build system to skip long-running checks during
+incremental development. CMake caching also has some drawbacks, but that will be
+discussed later.
+
+Scripting Overview
+==================
+
+CMake's scripting language has a very simple grammar. Every language construct
+is a command that matches the pattern _name_(_args_). Commands come in three
+primary types: language-defined (commands implemented in C++ in CMake), defined
+functions, and defined macros. The CMake distribution also contains a suite of
+CMake modules that contain definitions for useful functionality.
+
+The example below is the full CMake build for building a C++ "Hello World"
+program. The example uses only CMake language-defined functions.
+
+.. code-block:: cmake
+
+ cmake_minimum_required(VERSION 3.2)
+ project(HelloWorld)
+ add_executable(HelloWorld HelloWorld.cpp)
+
+The CMake language provides control flow constructs in the form of foreach loops
+and if blocks. To make the example above more complicated you could add an if
+block to define "APPLE" when targeting Apple platforms:
+
+.. code-block:: cmake
+
+ cmake_minimum_required(VERSION 3.2)
+ project(HelloWorld)
+ add_executable(HelloWorld HelloWorld.cpp)
+ if(APPLE)
+ target_compile_definitions(HelloWorld PUBLIC APPLE)
+ endif()
+
+Variables, Types, and Scope
+===========================
+
+Dereferencing
+-------------
+
+In CMake variables are "stringly" typed. All variables are represented as
+strings throughout evaluation. Wrapping a variable in ``${}`` dereferences it
+and results in a literal substitution of the name for the value. CMake refers to
+this as "variable evaluation" in their documentation. Dereferences are performed
+*before* the command being called receives the arguments. This means
+dereferencing a list results in multiple separate arguments being passed to the
+command.
+
+Variable dereferences can be nested and be used to model complex data. For
+example:
+
+.. code-block:: cmake
+
+ set(var_name var1)
+ set(${var_name} foo) # same as "set(var1 foo)"
+ set(${${var_name}}_var bar) # same as "set(foo_var bar)"
+
+Dereferencing an unset variable results in an empty expansion. It is a common
+pattern in CMake to conditionally set variables knowing that it will be used in
+code paths that the variable isn't set. There are examples of this throughout
+the LLVM CMake build system.
+
+An example of variable empty expansion is:
+
+.. code-block:: cmake
+
+ if(APPLE)
+ set(extra_sources Apple.cpp)
+ endif()
+ add_executable(HelloWorld HelloWorld.cpp ${extra_sources})
+
+In this example the ``extra_sources`` variable is only defined if you're
+targeting an Apple platform. For all other targets the ``extra_sources`` will be
+evaluated as empty before add_executable is given its arguments.
+
+Lists
+-----
+
+In CMake lists are semi-colon delimited strings, and it is strongly advised that
+you avoid using semi-colons in lists; it doesn't go smoothly. A few examples of
+defining lists:
+
+.. code-block:: cmake
+
+ # Creates a list with members a, b, c, and d
+ set(my_list a b c d)
+ set(my_list "a;b;c;d")
+
+ # Creates a string "a b c d"
+ set(my_string "a b c d")
+
+Lists of Lists
+--------------
+
+One of the more complicated patterns in CMake is lists of lists. Because a list
+cannot contain an element with a semi-colon to construct a list of lists you
+make a list of variable names that refer to other lists. For example:
+
+.. code-block:: cmake
+
+ set(list_of_lists a b c)
+ set(a 1 2 3)
+ set(b 4 5 6)
+ set(c 7 8 9)
+
+With this layout you can iterate through the list of lists printing each value
+with the following code:
+
+.. code-block:: cmake
+
+ foreach(list_name IN LISTS list_of_lists)
+ foreach(value IN LISTS ${list_name})
+ message(${value})
+ endforeach()
+ endforeach()
+
+You'll notice that the inner foreach loop's list is doubly dereferenced. This is
+because the first dereference turns ``list_name`` into the name of the sub-list
+(a, b, or c in the example), then the second dereference is to get the value of
+the list.
+
+This pattern is used throughout CMake, the most common example is the compiler
+flags options, which CMake refers to using the following variable expansions:
+CMAKE_${LANGUAGE}_FLAGS and CMAKE_${LANGUAGE}_FLAGS_${CMAKE_BUILD_TYPE}.
+
+Other Types
+-----------
+
+Variables that are cached or specified on the command line can have types
+associated with them. The variable's type is used by CMake's UI tool to display
+the right input field. A variable's type generally doesn't impact evaluation,
+however CMake does have special handling for some variables such as PATH.
+You can read more about the special handling in `CMake's set documentation
+<https://cmake.org/cmake/help/v3.5/command/set.html#set-cache-entry>`_.
+
+Scope
+-----
+
+CMake inherently has a directory-based scoping. Setting a variable in a
+CMakeLists file, will set the variable for that file, and all subdirectories.
+Variables set in a CMake module that is included in a CMakeLists file will be
+set in the scope they are included from, and all subdirectories.
+
+When a variable that is already set is set again in a subdirectory it overrides
+the value in that scope and any deeper subdirectories.
+
+The CMake set command provides two scope-related options. PARENT_SCOPE sets a
+variable into the parent scope, and not the current scope. The CACHE option sets
+the variable in the CMakeCache, which results in it being set in all scopes. The
+CACHE option will not set a variable that already exists in the CACHE unless the
+FORCE option is specified.
+
+In addition to directory-based scope, CMake functions also have their own scope.
+This means variables set inside functions do not bleed into the parent scope.
+This is not true of macros, and it is for this reason LLVM prefers functions
+over macros whenever reasonable.
+
+.. note::
+ Unlike C-based languages, CMake's loop and control flow blocks do not have
+ their own scopes.
+
+Control Flow
+============
+
+CMake features the same basic control flow constructs you would expect in any
+scripting language, but there are a few quirks because, as with everything in
+CMake, control flow constructs are commands.
+
+If, ElseIf, Else
+----------------
+
+.. note::
+ For the full documentation on the CMake if command go
+ `here <https://cmake.org/cmake/help/v3.4/command/if.html>`_. That resource is
+ far more complete.
+
+In general CMake if blocks work the way you'd expect:
+
+.. code-block:: cmake
+
+ if(<condition>)
+ message("do stuff")
+ elseif(<condition>)
+ message("do other stuff")
+ else()
+ message("do other other stuff")
+ endif()
+
+The single most important thing to know about CMake's if blocks coming from a C
+background is that they do not have their own scope. Variables set inside
+conditional blocks persist after the ``endif()``.
+
+Loops
+-----
+
+The most common form of the CMake ``foreach`` block is:
+
+.. code-block:: cmake
+
+ foreach(var ...)
+ message("do stuff")
+ endforeach()
+
+The variable argument portion of the ``foreach`` block can contain dereferenced
+lists, values to iterate, or a mix of both:
+
+.. code-block:: cmake
+
+ foreach(var foo bar baz)
+ message(${var})
+ endforeach()
+ # prints:
+ # foo
+ # bar
+ # baz
+
+ set(my_list 1 2 3)
+ foreach(var ${my_list})
+ message(${var})
+ endforeach()
+ # prints:
+ # 1
+ # 2
+ # 3
+
+ foreach(var ${my_list} out_of_bounds)
+ message(${var})
+ endforeach()
+ # prints:
+ # 1
+ # 2
+ # 3
+ # out_of_bounds
+
+There is also a more modern CMake foreach syntax. The code below is equivalent
+to the code above:
+
+.. code-block:: cmake
+
+ foreach(var IN ITEMS foo bar baz)
+ message(${var})
+ endforeach()
+ # prints:
+ # foo
+ # bar
+ # baz
+
+ set(my_list 1 2 3)
+ foreach(var IN LISTS my_list)
+ message(${var})
+ endforeach()
+ # prints:
+ # 1
+ # 2
+ # 3
+
+ foreach(var IN LISTS my_list ITEMS out_of_bounds)
+ message(${var})
+ endforeach()
+ # prints:
+ # 1
+ # 2
+ # 3
+ # out_of_bounds
+
+Similar to the conditional statements, these generally behave how you would
+expect, and they do not have their own scope.
+
+CMake also supports ``while`` loops, although they are not widely used in LLVM.
+
+Modules, Functions and Macros
+=============================
+
+Modules
+-------
+
+Modules are CMake's vehicle for enabling code reuse. CMake modules are just
+CMake script files. They can contain code to execute on include as well as
+definitions for commands.
+
+In CMake macros and functions are universally referred to as commands, and they
+are the primary method of defining code that can be called multiple times.
+
+In LLVM we have several CMake modules that are included as part of our
+distribution for developers who don't build our project from source. Those
+modules are the fundamental pieces needed to build LLVM-based projects with
+CMake. We also rely on modules as a way of organizing the build system's
+functionality for maintainability and re-use within LLVM projects.
+
+Argument Handling
+-----------------
+
+When defining a CMake command handling arguments is very useful. The examples
+in this section will all use the CMake ``function`` block, but this all applies
+to the ``macro`` block as well.
+
+CMake commands can have named arguments that are requried at every call site. In
+addition, all commands will implicitly accept a variable number of extra
+arguments (In C parlance, all commands are varargs functions). When a command is
+invoked with extra arguments (beyond the named ones) CMake will store the full
+list of arguments (both named and unnamed) in a list named ``ARGV``, and the
+sublist of unnamed arguments in ``ARGN``. Below is a trivial example of
+providing a wrapper function for CMake's built in function ``add_dependencies``.
+
+.. code-block:: cmake
+
+ function(add_deps target)
+ add_dependencies(${target} ${ARGN})
+ endfunction()
+
+This example defines a new macro named ``add_deps`` which takes a required first
+argument, and just calls another function passing through the first argument and
+all trailing arguments.
+
+CMake provides a module ``CMakeParseArguments`` which provides an implementation
+of advanced argument parsing. We use this all over LLVM, and it is recommended
+for any function that has complex argument-based behaviors or optional
+arguments. CMake's official documentation for the module is in the
+``cmake-modules`` manpage, and is also available at the
+`cmake-modules online documentation
+<https://cmake.org/cmake/help/v3.4/module/CMakeParseArguments.html>`_.
+
+.. note::
+ As of CMake 3.5 the cmake_parse_arguments command has become a native command
+ and the CMakeParseArguments module is empty and only left around for
+ compatibility.
+
+Functions Vs Macros
+-------------------
+
+Functions and Macros look very similar in how they are used, but there is one
+fundamental difference between the two. Functions have their own scope, and
+macros don't. This means variables set in macros will bleed out into the calling
+scope. That makes macros suitable for defining very small bits of functionality
+only.
+
+The other difference between CMake functions and macros is how arguments are
+passed. Arguments to macros are not set as variables, instead dereferences to
+the parameters are resolved across the macro before executing it. This can
+result in some unexpected behavior if using unreferenced variables. For example:
+
+.. code-block:: cmake
+
+ macro(print_list my_list)
+ foreach(var IN LISTS my_list)
+ message("${var}")
+ endforeach()
+ endmacro()
+
+ set(my_list a b c d)
+ set(my_list_of_numbers 1 2 3 4)
+ print_list(my_list_of_numbers)
+ # prints:
+ # a
+ # b
+ # c
+ # d
+
+Generally speaking this issue is uncommon because it requires using
+non-dereferenced variables with names that overlap in the parent scope, but it
+is important to be aware of because it can lead to subtle bugs.
+
+LLVM Project Wrappers
+=====================
+
+LLVM projects provide lots of wrappers around critical CMake built-in commands.
+We use these wrappers to provide consistent behaviors across LLVM components
+and to reduce code duplication.
+
+We generally (but not always) follow the convention that commands prefaced with
+``llvm_`` are intended to be used only as building blocks for other commands.
+Wrapper commands that are intended for direct use are generally named following
+with the project in the middle of the command name (i.e. ``add_llvm_executable``
+is the wrapper for ``add_executable``). The LLVM ``add_*`` wrapper functions are
+all defined in ``AddLLVM.cmake`` which is installed as part of the LLVM
+distribution. It can be included and used by any LLVM sub-project that requires
+LLVM.
+
+.. note::
+
+ Not all LLVM projects require LLVM for all use cases. For example compiler-rt
+ can be built without LLVM, and the compiler-rt sanitizer libraries are used
+ with GCC.
+
+Useful Built-in Commands
+========================
+
+CMake has a bunch of useful built-in commands. This document isn't going to
+go into details about them because The CMake project has excellent
+documentation. To highlight a few useful functions see:
+
+* `add_custom_command <https://cmake.org/cmake/help/v3.4/command/add_custom_command.html>`_
+* `add_custom_target <https://cmake.org/cmake/help/v3.4/command/add_custom_target.html>`_
+* `file <https://cmake.org/cmake/help/v3.4/command/file.html>`_
+* `list <https://cmake.org/cmake/help/v3.4/command/list.html>`_
+* `math <https://cmake.org/cmake/help/v3.4/command/math.html>`_
+* `string <https://cmake.org/cmake/help/v3.4/command/string.html>`_
+
+The full documentation for CMake commands is in the ``cmake-commands`` manpage
+and available on `CMake's website <https://cmake.org/cmake/help/v3.4/manual/cmake-commands.7.html>`_
Added: www-releases/trunk/9.0.0/docs/_sources/CodeGenerator.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/_sources/CodeGenerator.rst.txt?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/_sources/CodeGenerator.rst.txt (added)
+++ www-releases/trunk/9.0.0/docs/_sources/CodeGenerator.rst.txt Thu Sep 19 07:32:46 2019
@@ -0,0 +1,2688 @@
+==========================================
+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.
+
+If a target has legal vector types, it is expected to produce efficient machine
+code for common forms of the shufflevector IR instruction using those types.
+This may require custom legalization for SelectionDAG vector operations that
+are created from the shufflevector IR. The shufflevector forms that should be
+handled include:
+
+* Vector select --- Each element of the vector is chosen from either of the
+ corresponding elements of the 2 input vectors. This operation may also be
+ known as a "blend" or "bitwise select" in target assembly. This type of shuffle
+ maps directly to the ``shuffle_vector`` SelectionDAG node.
+
+* Insert subvector --- A vector is placed into a longer vector type starting
+ at index 0. This type of shuffle maps directly to the ``insert_subvector``
+ SelectionDAG node with the ``index`` operand set to 0.
+
+* Extract subvector --- A vector is pulled from a longer vector type starting
+ at index 0. This type of shuffle maps directly to the ``extract_subvector``
+ SelectionDAG node with the ``index`` operand set to 0.
+
+* Splat --- All elements of the vector have identical scalar elements. This
+ operation may also be known as a "broadcast" or "duplicate" in target assembly.
+ The shufflevector IR instruction may change the vector length, so this operation
+ may map to multiple SelectionDAG nodes including ``shuffle_vector``,
+ ``concat_vectors``, ``insert_subvector``, and ``extract_subvector``.
+
+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, PowerPC, and WebAssembly. It is performed on x86/x86-64
+and PowerPC 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.
+
+On WebAssembly, tail calls are lowered to ``return_call`` and
+``return_call_indirect`` instructions whenever the 'tail-call' target attribute
+is enabled.
+
+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 0x1 use src_reg register as source operand
+ BPF_K 0x0 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/9.0.0/docs/_sources/CodeOfConduct.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/_sources/CodeOfConduct.rst.txt?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/_sources/CodeOfConduct.rst.txt (added)
+++ www-releases/trunk/9.0.0/docs/_sources/CodeOfConduct.rst.txt Thu Sep 19 07:32:46 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/9.0.0/docs/_sources/CodingStandards.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/_sources/CodingStandards.rst.txt?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/_sources/CodingStandards.rst.txt (added)
+++ www-releases/trunk/9.0.0/docs/_sources/CodingStandards.rst.txt Thu Sep 19 07:32:46 2019
@@ -0,0 +1,1729 @@
+=====================
+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++ -*-===//
+ //
+ // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+ // See https://llvm.org/LICENSE.txt for license information.
+ // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+ //
+ //===----------------------------------------------------------------------===//
+ ///
+ /// \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/9.0.0/docs/_sources/CommandGuide/FileCheck.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/_sources/CommandGuide/FileCheck.rst.txt?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/_sources/CommandGuide/FileCheck.rst.txt (added)
+++ www-releases/trunk/9.0.0/docs/_sources/CommandGuide/FileCheck.rst.txt Thu Sep 19 07:32:46 2019
@@ -0,0 +1,682 @@
+FileCheck - Flexible pattern matching file verifier
+===================================================
+
+.. program:: FileCheck
+
+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 pattern variable ``VAR`` with value ``VALUE`` that can be
+ used in ``CHECK:`` lines.
+
+.. option:: -D#<NUMVAR>=<VALUE EXPRESSION>
+
+ Sets a filecheck numeric variable ``NUMVAR`` to the result of evaluating
+ ``<VALUE EXPRESSION>`` that can be used in ``CHECK:`` lines. See section
+ ``FileCheck Numeric Variables and Expressions`` for details on the format
+ and meaning of ``<VALUE EXPRESSION>``.
+
+.. option:: -version
+
+ Show the version number of this program.
+
+.. option:: -v
+
+ Print good directive pattern matches. However, if ``-input-dump=fail`` or
+ ``-input-dump=always``, add those matches as input annotations instead.
+
+.. 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``.
+ However, if ``-input-dump=fail`` or ``-input-dump=always``, just add that
+ information as input annotations instead.
+
+.. 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 Regex 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 String Substitution Blocks
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+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` supports string substitution blocks that allow
+string 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
+string variable ``REGISTER``. The second line verifies that whatever is in
+``REGISTER`` occurs later in the file after an "``andw``". :program:`FileCheck`
+string substitution blocks are always contained in ``[[ ]]`` pairs, and string
+variable 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 substitution.
+
+:program:`FileCheck` variables can be defined multiple times, and substitutions
+always get the latest value. Variables can also be substituted 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 Numeric Substitution Blocks
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+:program:`FileCheck` also supports numeric substitution blocks that allow
+defining numeric variables and checking for numeric values that satisfy a
+numeric expression constraint based on those variables via a numeric
+substitution. This allows ``CHECK:`` directives to verify a numeric relation
+between two numbers, such as the need for consecutive registers to be used.
+
+The syntax to define a numeric variable is ``[[#<NUMVAR>:]]`` where
+``<NUMVAR>`` is the name of the numeric variable to define to the matching
+value.
+
+For example:
+
+.. code-block:: llvm
+
+ ; CHECK: mov r[[#REG:]], 42
+
+would match ``mov r5, 42`` and set ``REG`` to the value ``5``.
+
+The syntax of a numeric substitution is ``[[#<expr>]]`` where ``<expr>`` is an
+expression. An expression is recursively defined as:
+
+* a numeric operand, or
+* an expression followed by an operator and a numeric operand.
+
+A numeric operand is a previously defined numeric variable, or an integer
+literal. The supported operators are ``+`` and ``-``. Spaces are accepted
+before, after and between any of these elements.
+
+For example:
+
+.. code-block:: llvm
+
+ ; CHECK: load r[[#REG:]], [r0]
+ ; CHECK: load r[[#REG+1]], [r1]
+
+The above example would match the text:
+
+.. code-block:: gas
+
+ load r5, [r0]
+ load r6, [r1]
+
+but would not match the text:
+
+.. code-block:: gas
+
+ load r5, [r0]
+ load r7, [r1]
+
+due to ``7`` being unequal to ``5 + 1``.
+
+The ``--enable-var-scope`` option has the same effect on numeric variables as
+on string variables.
+
+Important note: In its current implementation, an expression cannot use a
+numeric variable defined on the same line.
+
+FileCheck Pseudo Numeric Variables
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Sometimes there's a need to verify output that contains 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 expressions understand the ``@LINE`` pseudo
+numeric variable which evaluates to the line number of the CHECK pattern where
+it is found.
+
+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
+
+To support legacy uses of ``@LINE`` as a special string variable,
+:program:`FileCheck` also accepts the following uses of ``@LINE`` with string
+substitution block syntax: ``[[@LINE]]``, ``[[@LINE+<offset>]]`` and
+``[[@LINE-<offset>]]`` without any spaces inside the brackets and where
+``offset`` is an integer.
+
+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/9.0.0/docs/_sources/CommandGuide/bugpoint.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/_sources/CommandGuide/bugpoint.rst.txt?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/_sources/CommandGuide/bugpoint.rst.txt (added)
+++ www-releases/trunk/9.0.0/docs/_sources/CommandGuide/bugpoint.rst.txt Thu Sep 19 07:32:46 2019
@@ -0,0 +1,197 @@
+bugpoint - automatic test case reduction tool
+=============================================
+
+.. program:: bugpoint
+
+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
+--------
+
+:manpage:`opt(1)`
Added: www-releases/trunk/9.0.0/docs/_sources/CommandGuide/dsymutil.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/_sources/CommandGuide/dsymutil.rst.txt?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/_sources/CommandGuide/dsymutil.rst.txt (added)
+++ www-releases/trunk/9.0.0/docs/_sources/CommandGuide/dsymutil.rst.txt Thu Sep 19 07:32:46 2019
@@ -0,0 +1,116 @@
+dsymutil - manipulate archived DWARF debug symbol files
+=======================================================
+
+.. program:: dsymutil
+
+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/9.0.0/docs/_sources/CommandGuide/index.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/_sources/CommandGuide/index.rst.txt?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/_sources/CommandGuide/index.rst.txt (added)
+++ www-releases/trunk/9.0.0/docs/_sources/CommandGuide/index.rst.txt Thu Sep 19 07:32:46 2019
@@ -0,0 +1,76 @@
+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-lib
+ llvm-lipo
+ llvm-config
+ llvm-cxxmap
+ llvm-diff
+ llvm-cov
+ llvm-profdata
+ llvm-stress
+ llvm-symbolizer
+ llvm-dwarfdump
+ dsymutil
+ llvm-mca
+ llvm-readobj
+
+GNU binutils replacements
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. toctree::
+ :maxdepth: 1
+
+ llvm-addr2line
+ llvm-ar
+ llvm-cxxfilt
+ llvm-nm
+ llvm-objcopy
+ llvm-objdump
+ llvm-ranlib
+ llvm-readelf
+ llvm-size
+ llvm-strings
+ llvm-strip
+
+Debugging Tools
+~~~~~~~~~~~~~~~
+
+.. toctree::
+ :maxdepth: 1
+
+ bugpoint
+ llvm-extract
+ llvm-bcanalyzer
+
+Developer Tools
+~~~~~~~~~~~~~~~
+
+.. toctree::
+ :maxdepth: 1
+
+ FileCheck
+ tblgen
+ lit
+ llvm-build
+ llvm-exegesis
+ llvm-pdbutil
Added: www-releases/trunk/9.0.0/docs/_sources/CommandGuide/lit.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/_sources/CommandGuide/lit.rst.txt?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/_sources/CommandGuide/lit.rst.txt (added)
+++ www-releases/trunk/9.0.0/docs/_sources/CommandGuide/lit.rst.txt Thu Sep 19 07:32:46 2019
@@ -0,0 +1,489 @@
+lit - LLVM Integrated Tester
+============================
+
+.. program:: lit
+
+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.
+
+:program:`lit` parses options from the environment variable ``LIT_OPTS`` after
+parsing options from the command line. ``LIT_OPTS`` is primarily useful for
+supplementing or overriding the command-line options supplied to :program:`lit`
+by ``check`` targets defined by a project's build system.
+
+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/9.0.0/docs/_sources/CommandGuide/llc.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llc.rst.txt?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llc.rst.txt (added)
+++ www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llc.rst.txt Thu Sep 19 07:32:46 2019
@@ -0,0 +1,214 @@
+llc - LLVM static compiler
+==========================
+
+.. program:: llc
+
+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 <filename>
+
+ Use ``<filename>`` as the output filename. See the summary above for more
+ details.
+
+.. 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.
+
+.. option:: -remarks-section
+
+ Emit the .remarks (ELF) / __remarks (MachO) section which contains metadata
+ about remark diagnostics.
+
+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
+--------
+
+:manpage:`lli(1)`
Added: www-releases/trunk/9.0.0/docs/_sources/CommandGuide/lli.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/_sources/CommandGuide/lli.rst.txt?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/_sources/CommandGuide/lli.rst.txt (added)
+++ www-releases/trunk/9.0.0/docs/_sources/CommandGuide/lli.rst.txt Thu Sep 19 07:32:46 2019
@@ -0,0 +1,217 @@
+lli - directly execute programs from LLVM bitcode
+=================================================
+
+.. program:: lli
+
+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
+--------
+
+:manpage:`llc(1)`
Added: www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-addr2line.md.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-addr2line.md.txt?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-addr2line.md.txt (added)
+++ www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-addr2line.md.txt Thu Sep 19 07:32:46 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/9.0.0/docs/_sources/CommandGuide/llvm-ar.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-ar.rst.txt?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-ar.rst.txt (added)
+++ www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-ar.rst.txt Thu Sep 19 07:32:46 2019
@@ -0,0 +1,292 @@
+llvm-ar - LLVM archiver
+=======================
+
+.. program:: llvm-ar
+
+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
+macOS) 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 macOS
+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/9.0.0/docs/_sources/CommandGuide/llvm-as.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-as.rst.txt?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-as.rst.txt (added)
+++ www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-as.rst.txt Thu Sep 19 07:32:46 2019
@@ -0,0 +1,58 @@
+llvm-as - LLVM assembler
+========================
+
+.. program:: llvm-as
+
+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
+--------
+
+:manpage:`llvm-dis(1)`, as(1)
Added: www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-bcanalyzer.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-bcanalyzer.rst.txt?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-bcanalyzer.rst.txt (added)
+++ www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-bcanalyzer.rst.txt Thu Sep 19 07:32:46 2019
@@ -0,0 +1,306 @@
+llvm-bcanalyzer - LLVM bitcode analyzer
+=======================================
+
+.. program:: llvm-bcanalyzer
+
+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
+--------
+
+:manpage:`llvm-dis(1)`, :doc:`/BitCodeFormat`
Added: www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-build.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-build.rst.txt?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-build.rst.txt (added)
+++ www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-build.rst.txt Thu Sep 19 07:32:46 2019
@@ -0,0 +1,79 @@
+llvm-build - LLVM Project Build Utility
+=======================================
+
+.. program:: llvm-build
+
+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/9.0.0/docs/_sources/CommandGuide/llvm-config.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-config.rst.txt?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-config.rst.txt (added)
+++ www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-config.rst.txt Thu Sep 19 07:32:46 2019
@@ -0,0 +1,126 @@
+llvm-config - Print LLVM compilation options
+============================================
+
+.. program:: llvm-config
+
+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/9.0.0/docs/_sources/CommandGuide/llvm-cov.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-cov.rst.txt?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-cov.rst.txt (added)
+++ www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-cov.rst.txt Thu Sep 19 07:32:46 2019
@@ -0,0 +1,441 @@
+llvm-cov - emit coverage information
+====================================
+
+.. program:: llvm-cov
+
+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.
+
+.. option:: -x, --hash-filenames
+
+ Use md5 hash of file name when naming the coverage output files. The source
+ file name will be suffixed by ``##`` followed by MD5 hash calculated for it.
+
+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*.
+
+*BIN* may be an executable, object file, dynamic library, or archive (thin or
+otherwise).
+
+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*.
+
+*BIN* may be an executable, object file, dynamic library, or archive (thin or
+otherwise).
+
+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.
+
+ .. option:: -skip-expansions
+
+ Skip exporting macro expansion coverage data.
+
+ .. option:: -skip-functions
+
+ Skip exporting per-function coverage data.
+
+ .. option:: -num-threads=N, -j=N
+
+ Use N threads to export coverage data. When N=0, llvm-cov auto-detects an
+ appropriate number of threads to use. This is the default.
Added: www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-cxxfilt.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-cxxfilt.rst.txt?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-cxxfilt.rst.txt (added)
+++ www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-cxxfilt.rst.txt Thu Sep 19 07:32:46 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/9.0.0/docs/_sources/CommandGuide/llvm-cxxmap.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-cxxmap.rst.txt?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-cxxmap.rst.txt (added)
+++ www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-cxxmap.rst.txt Thu Sep 19 07:32:46 2019
@@ -0,0 +1,93 @@
+llvm-cxxmap - Mangled name remapping tool
+=========================================
+
+.. program:: llvm-cxxmap
+
+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/9.0.0/docs/_sources/CommandGuide/llvm-diff.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-diff.rst.txt?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-diff.rst.txt (added)
+++ www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-diff.rst.txt Thu Sep 19 07:32:46 2019
@@ -0,0 +1,50 @@
+llvm-diff - LLVM structural 'diff'
+==================================
+
+.. program:: llvm-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/9.0.0/docs/_sources/CommandGuide/llvm-dis.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-dis.rst.txt?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-dis.rst.txt (added)
+++ www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-dis.rst.txt Thu Sep 19 07:32:46 2019
@@ -0,0 +1,54 @@
+llvm-dis - LLVM disassembler
+============================
+
+.. program:: llvm-dis
+
+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
+--------
+
+:manpage:`llvm-as(1)`
Added: www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-dwarfdump.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-dwarfdump.rst.txt?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-dwarfdump.rst.txt (added)
+++ www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-dwarfdump.rst.txt Thu Sep 19 07:32:46 2019
@@ -0,0 +1,170 @@
+llvm-dwarfdump - dump and verify DWARF debug information
+========================================================
+
+.. program:: llvm-dwarfdump
+
+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.
+
+If no input file is specified, `a.out` is used instead. If `-` is used as the
+input file, :program:`llvm-dwarfdump` reads the input from its standard input
+stream.
+
+OPTIONS
+-------
+
+.. option:: -a, --all
+
+ Dump 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 selectively printing with
+ the `=<offset>` argument of :option:`--debug-info`, or options such
+ as :option:`--find` or :option:`--name`.
+
+.. option:: --color
+
+ Use colors in output.
+
+.. 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:: --help-list
+
+ Show help and usage for this command without grouping the options
+ into categories.
+
+.. option:: -i, --ignore-case
+
+ Ignore case distinctions when using :option:`--name`.
+
+.. option:: -n <name>, --name=<name>
+
+ Find and print all debug info entries whose name
+ (`DW_AT_name` attribute) is <name>.
+
+.. option:: --lookup=<address>
+
+ Look up <address> in the debug information and print out the file,
+ function, block, and line table details.
+
+.. option:: -o <path>
+
+ Redirect output to a file specified by <path>, where `-` is the
+ standard output stream.
+
+.. option:: -p, --show-parents
+
+ Show a debug info entry's parents when selectively printing with
+ the `=<offset>` argument of :option:`--debug-info`, or options such
+ as :option:`--find` or :option:`--name`.
+
+.. option:: --parent-recurse-depth=<N>
+
+ When displaying debug info entry parents, only show them to a
+ maximum depth of <N>.
+
+.. option:: --quiet
+
+ Use with :option:`--verify` to not emit to `STDOUT`.
+
+.. option:: -r <N>, --recurse-depth=<N>
+
+ When displaying debug info entries, only show children to a maximum
+ depth of <N>.
+
+.. option:: --statistics
+
+ Collect debug info quality metrics and print the results
+ as machine-readable single-line JSON output.
+
+.. option:: --summarize-types
+
+ Abbreviate the description of type unit entries.
+
+.. option:: -x, --regex
+
+ Treat any <name> strings as regular expressions when searching
+ with :option:`--name`. If :option:`--ignore-case` is also specified,
+ the regular expression becomes case-insensitive.
+
+.. 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-addr, --debug-aranges, --debug-cu-index, --debug-frame [=<offset>], --debug-gnu-pubnames, --debug-gnu-pubtypes, --debug-info [=<offset>], --debug-line [=<offset>], --debug-line-str, --debug-loc [=<offset>], --debug-loclists [=<offset>], --debug-macro, --debug-names, --debug-pubnames, --debug-pubtypes, --debug-ranges, --debug-rnglists, --debug-str, --debug-str-offsets, --debug-tu-index, --debug-types, --eh-frame [=<offset>], --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.
+
+.. option:: @<FILE>
+
+ Read command-line options from `<FILE>`.
+
+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/9.0.0/docs/_sources/CommandGuide/llvm-exegesis.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-exegesis.rst.txt?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-exegesis.rst.txt (added)
+++ www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-exegesis.rst.txt Thu Sep 19 07:32:46 2019
@@ -0,0 +1,266 @@
+llvm-exegesis - LLVM Machine Instruction Benchmark
+==================================================
+
+.. program:: llvm-exegesis
+
+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,
+throughput, 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. inverse throughput/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 or inverse throughput of an instruction works similarly:
+
+.. code-block:: bash
+
+ $ llvm-exegesis -mode=uops -opcode-name=ADD64rr
+ $ llvm-exegesis -mode=inverse_throughput -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|inverse_throughput|analysis]
+
+ Specify the run mode. Note that if you pick `analysis` mode, you also need
+ to specify at least one of the `-analysis-clusters-output-file=` and
+ `-analysis-inconsistencies-output-file=`.
+
+.. 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`/`inverse_throughput`
+ 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. By default, this analysis is not run.
+
+.. option:: -analysis-inconsistencies-output-file=</path/to/file>
+
+ If non-empty, write inconsistencies found during analysis to this file. `-`
+ prints to stdout. By default, this analysis is not run.
+
+.. option:: -analysis-clustering=[dbscan,naive]
+
+ Specify the clustering algorithm to use. By default DBSCAN will be used.
+ Naive clustering algorithm is better for doing further work on the
+ `-analysis-inconsistencies-output-file=` output, it will create one cluster
+ per opcode, and check that the cluster is stable (all points are neighbours).
+
+.. option:: -analysis-numpoints=<dbscan numPoints parameter>
+
+ Specify the numPoints parameters to be used for DBSCAN clustering
+ (`analysis` mode, DBSCAN only).
+
+.. option:: -analysis-clustering-epsilon=<dbscan epsilon parameter>
+
+ Specify the epsilon parameter used for clustering of benchmark points
+ (`analysis` mode).
+
+.. option:: -analysis-inconsistency-epsilon=<epsilon>
+
+ Specify the epsilon parameter used for detection of when the cluster
+ is different from the LLVM schedule profile values (`analysis` mode).
+
+.. option:: -analysis-display-unstable-clusters
+
+ If there is more than one benchmark for an opcode, said benchmarks may end up
+ not being clustered into the same cluster if the measured performance
+ characteristics are different. by default all such opcodes are filtered out.
+ This flag will instead show only such unstable opcodes.
+
+.. 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).
+
+.. option:: --dump-object-to-disk=true
+
+ By default, llvm-exegesis will dump the generated code to a temporary file to
+ enable code inspection. You may disable it to speed up the execution and save
+ disk space.
+
+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/9.0.0/docs/_sources/CommandGuide/llvm-extract.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-extract.rst.txt?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-extract.rst.txt (added)
+++ www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-extract.rst.txt Thu Sep 19 07:32:46 2019
@@ -0,0 +1,80 @@
+llvm-extract - extract a function from an LLVM module
+=====================================================
+
+.. program:: llvm-extract
+
+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
+--------
+
+:manpage:`bugpoint(1)`
Added: www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-lib.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-lib.rst.txt?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-lib.rst.txt (added)
+++ www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-lib.rst.txt Thu Sep 19 07:32:46 2019
@@ -0,0 +1,29 @@
+llvm-lib - LLVM lib.exe compatible library tool
+===============================================
+
+.. program:: llvm-lib
+
+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/9.0.0/docs/_sources/CommandGuide/llvm-link.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-link.rst.txt?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-link.rst.txt (added)
+++ www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-link.rst.txt Thu Sep 19 07:32:46 2019
@@ -0,0 +1,56 @@
+llvm-link - LLVM bitcode linker
+===============================
+
+.. program:: llvm-link
+
+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/9.0.0/docs/_sources/CommandGuide/llvm-lipo.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-lipo.rst.txt?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-lipo.rst.txt (added)
+++ www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-lipo.rst.txt Thu Sep 19 07:32:46 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/9.0.0/docs/_sources/CommandGuide/llvm-mca.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-mca.rst.txt?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-mca.rst.txt (added)
+++ www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-mca.rst.txt Thu Sep 19 07:32:46 2019
@@ -0,0 +1,840 @@
+llvm-mca - LLVM Machine Code Analyzer
+=====================================
+
+.. program:: llvm-mca
+
+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
+
+Scheduling models are not just used to compute instruction latencies and
+throughput, but also to understand what processor resources are available
+and how to simulate them.
+
+By design, the quality of the analysis conducted by :program:`llvm-mca` is
+inevitably affected by the quality of the scheduling models in LLVM.
+
+If you see that the performance report is not accurate for a processor,
+please `file a bug <https://bugs.llvm.org/enter_bug.cgi?product=libraries>`_
+against the appropriate backend.
+
+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:: -o <filename>
+
+ Use ``<filename>`` as the output filename. See the summary above for more
+ details.
+
+.. 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.
+
+.. option:: -bottleneck-analysis
+
+ Print information about bottlenecks that affect the throughput. This analysis
+ can be expensive, and it is disabled by default. Bottlenecks are highlighted
+ in the summary view.
+
+
+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
+ ...
+ # LLVM-MCA-END
+
+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.
+
+Code regions can have names. For example:
+
+.. code-block:: none
+
+ # LLVM-MCA-BEGIN A simple example
+ add %eax, %eax
+ # LLVM-MCA-END
+
+The code from the example above defines a region named "A simple example" with a
+single instruction in it. Note how the region name doesn't have to be repeated
+in the ``LLVM-MCA-END`` directive. In the absence of overlapping regions,
+an anonymous ``LLVM-MCA-END`` directive always ends the currently active user
+defined region.
+
+Example of nesting regions:
+
+.. code-block:: none
+
+ # LLVM-MCA-BEGIN foo
+ add %eax, %edx
+ # LLVM-MCA-BEGIN bar
+ sub %eax, %edx
+ # LLVM-MCA-END bar
+ # LLVM-MCA-END foo
+
+Example of overlapping regions:
+
+.. code-block:: none
+
+ # LLVM-MCA-BEGIN foo
+ add %eax, %edx
+ # LLVM-MCA-BEGIN bar
+ sub %eax, %edx
+ # LLVM-MCA-END foo
+ add %eax, %edx
+ # LLVM-MCA-END bar
+
+Note that multiple anonymous regions cannot overlap. Also, overlapping regions
+cannot have the same name.
+
+There is no support for marking regions from high-level source code, like C or
+C++. As a workaround, inline assembly directives may be used:
+
+.. 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;
+ }
+
+However, this interferes with optimizations like loop vectorization and may have
+an impact on the code generated. This is because the ``__asm`` statements are
+seen as real code having important side effects, which limits how the code
+around them can be transformed. If users want to make use of inline assembly
+to emit markers, then the recommendation is to always verify that the output
+assembly is equivalent to the assembly generated in the absence of markers.
+The `Clang options to emit optimization reports <https://clang.llvm.org/docs/UsersManual.html#options-to-emit-optimization-reports>`_
+can also help in detecting missed optimizations.
+
+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 micro opcodes 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 micro opcodes issued on some number of cycles. In
+this case, of the 610 simulated cycles, single opcodes were issued 306 times
+(50.2%) and there were 7 cycles where no opcodes 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/9.0.0/docs/_sources/CommandGuide/llvm-nm.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-nm.rst.txt?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-nm.rst.txt (added)
+++ www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-nm.rst.txt Thu Sep 19 07:32:46 2019
@@ -0,0 +1,283 @@
+llvm-nm - list LLVM bitcode and object file's symbol table
+==========================================================
+
+.. program:: llvm-nm
+
+SYNOPSIS
+--------
+
+:program:`llvm-nm` [*options*] [*filenames...*]
+
+DESCRIPTION
+-----------
+
+The :program:`llvm-nm` utility lists the names of symbols from LLVM bitcode
+files, object files, and archives. Each symbol is listed along with some simple
+information about its provenance. If no filename is specified, *a.out* is used
+as the input. If *-* is used as a filename, :program:`llvm-nm` will read a file
+from 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.
+
+The supported type code characters are as follows. Where both lower and
+upper-case characters are listed for the same meaning, a lower-case character
+represents a local symbol, whilst an upper-case character represents a global
+(external) symbol:
+
+a, A
+
+ Absolute symbol.
+
+b, B
+
+ Unitialized data (bss) object.
+
+C
+
+ Common symbol. Multiple definitions link together into one definition.
+
+d, D
+
+ Writable data object.
+
+i, I
+
+ COFF: .idata symbol or symbol in a section with IMAGE_SCN_LNK_INFO set.
+
+n
+
+ ELF: local symbol from non-alloc section.
+
+ COFF: debug symbol.
+
+N
+
+ ELF: debug section symbol, or global symbol from non-alloc section.
+
+s, S
+
+ COFF: section symbol.
+
+ Mach-O: absolute symbol or symbol from a section other than __TEXT_EXEC __text,
+ __TEXT __text, __DATA __data, or __DATA __bss.
+
+r, R
+
+ Read-only data object.
+
+t, T
+
+ Code (text) object.
+
+u
+
+ ELF: GNU unique symbol.
+
+U
+
+ Named object is undefined in this file.
+
+v
+
+ ELF: Undefined weak object. It is not a link failure if the object is not
+ defined.
+
+V
+
+ ELF: Defined weak object symbol. This definition will only be used if no
+ regular definitions exist in a link. If multiple weak definitions and no
+ regular definitons exist, one of the weak definitions will be used.
+
+w
+
+ Undefined weak symbol other than an ELF object symbol. It is not a link failure
+ if the symbol is not defined.
+
+W
+
+ Defined weak symbol other than an ELF object symbol. This definition will only
+ be used if no regular definitions exist in a link. If multiple weak definitions
+ and no regular definitons exist, one of the weak definitions will be used.
+
+\-
+
+ Mach-O: N_STAB symbol.
+
+?
+
+ 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
+
+ Use BSD output format. Alias for ``--format=bsd``.
+
+.. option:: --debug-syms, -a
+
+ Show all symbols, even those usually suppressed.
+
+.. option:: --defined-only, -U
+
+ Print only symbols defined in this file.
+
+.. option:: --demangle, -C
+
+ Demangle symbol names.
+
+.. 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:: --format=<format>, -f
+
+ Select an output format; *format* may be *sysv*, *posix*, *darwin*, or *bsd*.
+ The default is *bsd*.
+
+.. option:: --help, -h
+
+ Print a summary of command-line options and their meanings.
+
+.. option:: --help-list
+
+ Print an uncategorized summary of command-line options and their meanings.
+
+.. option:: --just-symbol-name, -j
+
+ Print just the symbol names.
+
+.. option:: -m
+
+ Use Darwin format. Alias for ``--format=darwin``.
+
+.. option:: --no-demangle
+
+ Don't demangle symbol names. This is the default.
+
+.. option:: --no-llvm-bc
+
+ Disable the LLVM bitcode reader.
+
+.. option:: --no-sort, -p
+
+ Show symbols in the order encountered.
+
+.. option:: --no-weak, -W
+
+ Don't print weak symbols.
+
+.. option:: --numeric-sort, -n, -v
+
+ Sort symbols by address.
+
+.. option:: --portability, -P
+
+ Use POSIX.2 output format. Alias for ``--format=posix``.
+
+.. option:: --print-armap, -M
+
+ Print the archive symbol table, in addition to the symbols.
+
+.. option:: --print-file-name, -A, -o
+
+ Precede each symbol with the file it came from.
+
+.. option:: --print-size, -S
+
+ Show symbol size as well as address (not applicable for Mach-O).
+
+.. option:: --radix=<RADIX>, -t
+
+ Specify the radix of the symbol address(es). Values accepted are *d* (decimal),
+ *x* (hexadecimal) and *o* (octal).
+
+.. option:: --reverse-sort, -r
+
+ Sort symbols in reverse order.
+
+.. option:: --size-sort
+
+ Sort symbols by size.
+
+.. option:: --special-syms
+
+ Ignored. For GNU compatibility only.
+
+.. option:: --undefined-only, -u
+
+ Print only undefined symbols.
+
+.. option:: --version
+
+ Display the version of this program. Does not stack with other commands.
+
+.. option:: --without-aliases
+
+ Exclude aliases from the output.
+
+.. option:: @<FILE>
+
+ Read command-line options from response file `<FILE>`.
+
+MACH-O SPECIFIC OPTIONS
+-----------------------
+
+.. option:: --add-dyldinfo
+
+ Add symbols from the dyldinfo, if they are not already in the symbol table.
+ This is the default.
+
+.. option:: --arch=<arch1[,arch2,...]>
+
+ Dump the symbols from the specified architecture(s).
+
+.. option:: --dyldinfo-only
+
+ Dump only symbols from the dyldinfo.
+
+.. option:: --no-dyldinfo
+
+ Do not add any symbols from the dyldinfo.
+
+.. option:: -s=<segment section>
+
+ Dump only symbols from this segment and section name.
+
+.. option:: -x
+
+ Print symbol entry in hex.
+
+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
+--------
+
+:manpage:`llvm-ar(1)`, :manpage:`llvm-objdump(1)`, :manpage:`llvm-readelf(1)`,
+:manpage:`llvm-readobj(1)`
Added: www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-objcopy.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-objcopy.rst.txt?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-objcopy.rst.txt (added)
+++ www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-objcopy.rst.txt Thu Sep 19 07:32:46 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/9.0.0/docs/_sources/CommandGuide/llvm-objdump.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-objdump.rst.txt?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-objdump.rst.txt (added)
+++ www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-objdump.rst.txt Thu Sep 19 07:32:46 2019
@@ -0,0 +1,331 @@
+llvm-objdump - LLVM's object file dumper
+========================================
+
+.. program:: llvm-objdump
+
+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:: -a, --archive-headers
+
+ Display the information contained within an archive's headers.
+
+.. option:: -d, --disassemble
+
+ Disassemble all text sections found in the input files.
+
+.. option:: -D, --disassemble-all
+
+ Disassemble all sections found in the input files.
+
+.. option:: --disassemble-functions=<symbol1[,symbol2,...]>
+
+ Disassemble only the specified symbols. Takes demangled symbol names when
+ :option:`--demangle` is specified, otherwise takes mangled symbol names.
+ Implies :option:`--disassemble`.
+
+.. option:: --dwarf=<value>
+
+ Dump the specified DWARF debug sections. The supported values are:
+
+ `frames` - .debug_frame
+
+.. option:: -f, --file-headers
+
+ Display the contents of the overall file header.
+
+.. option:: --fault-map-section
+
+ Display the content of the fault map section.
+
+.. option:: -h, --headers, --section-headers
+
+ Display summaries of the headers for each section.
+
+.. option:: --help
+
+ Display usage information and exit. Does not stack with other commands.
+
+.. option:: -p, --private-headers
+
+ Display format-specific file headers.
+
+.. option:: -r, --reloc
+
+ Display the relocation entries in the file.
+
+.. option:: -R, --dynamic-reloc
+
+ Display the dynamic relocation entries in the file.
+
+.. option:: --raw-clang-ast
+
+ Dump the raw binary contents of the clang AST section.
+
+.. option:: -s, --full-contents
+
+ Display the contents of each section.
+
+.. option:: -t, --syms
+
+ Display the symbol table.
+
+.. option:: -u, --unwind-info
+
+ Display the unwind info of the input(s).
+
+.. option:: --version
+
+ Display the version of this program. Does not stack with other commands.
+
+.. option:: -x, --all-headers
+
+ Display all available header information. Equivalent to specifying
+ :option:`--archive-headers`, :option:`--file-headers`,
+ :option:`--private-headers`, :option:`--reloc`, :option:`--section-headers`,
+ and :option:`--syms`.
+
+OPTIONS
+-------
+:program:`llvm-objdump` supports the following options:
+
+.. option:: --adjust-vma=<offset>
+
+ Increase the displayed address in disassembly or section header printing by
+ the specified offset.
+
+.. option:: --arch-name=<string>
+
+ Specify the target architecture when disassembling. Use :option:`--version`
+ for a list of available targets.
+
+.. option:: -C, --demangle
+
+ Demangle symbol names in the output.
+
+.. option:: -j, --section=<section1[,section2,...]>
+
+ Perform commands on the specified sections only. For Mach-O use
+ `segment,section` to specify the section name.
+
+.. option:: -l, --line-numbers
+
+ When disassembling, display source line numbers. Implies
+ :option:`--disassemble`.
+
+.. option:: -M, --disassembler-options=<opt1[,opt2,...]>
+
+ Pass target-specific disassembler options. Currently supported for ARM targets
+ only. Available options are ``reg-names-std`` and ``reg-names-raw``.
+
+.. option:: --mcpu=<cpu-name>
+
+ Target a specific CPU type for disassembly. Specify ``--mcpu=help`` to display
+ available CPUs.
+
+.. option:: --mattr=<a1,+a2,-a3,...>
+
+ Enable/disable target-specific attributes. Specify ``--mcpu=help`` to display
+ the available attributes.
+
+.. option:: --no-leading-addr
+
+ When disassembling, do not print leading addresses.
+
+.. option:: --no-show-raw-insn
+
+ When disassembling, do not print the raw bytes of each instruction.
+
+.. option:: --print-imm-hex
+
+ Use hex format when printing immediate values in disassembly output.
+
+.. option:: -S, --source
+
+ When disassembling, display source interleaved with the disassembly. Implies
+ :option:`--disassemble`.
+
+.. option:: --show-lma
+
+ Display the LMA column when dumping ELF section headers. Defaults to off
+ unless any section has different VMA and LMAs.
+
+.. option:: --start-address=<address>
+
+ When disassembling, only disassemble from the specified address.
+
+ When printing relocations, only print the relocations patching offsets from at least ``address``.
+
+ When printing symbols, only print symbols with a value of at least ``address``.
+
+.. option:: --stop-address=<address>
+
+ When disassembling, only disassemble up to, but not including the specified address.
+
+ When printing relocations, only print the relocations patching offsets up to ``address``.
+
+ When printing symbols, only print symbols with a value up to ``address``.
+
+.. option:: --triple=<string>
+
+ Target triple to disassemble for, see ``--version`` for available targets.
+
+.. option:: -w, --wide
+
+ Ignored for compatibility with GNU objdump.
+
+.. option:: --x86-asm-syntax=<style>
+
+ When used with :option:`--disassemble`, 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**.
+
+.. option:: -z, --disassemble-zeroes
+
+ Do not skip blocks of zeroes when disassembling.
+
+.. option:: @<FILE>
+
+ Read command-line options and commands from response file `<FILE>`.
+
+MACH-O ONLY OPTIONS AND COMMANDS
+--------------------------------
+
+.. option:: --arch=<architecture>
+
+ Specify the architecture to disassemble. see ``--version`` for available
+ architectures.
+
+.. option:: --archive-member-offsets
+
+ Print the offset to each archive member for Mach-O archives (requires
+ :option:`--archive-headers`).
+
+.. option:: --bind
+
+ Display binding info
+
+.. option:: --cfg
+
+ Create a CFG for every symbol in the object file and write it to a graphviz
+ file.
+
+.. option:: --data-in-code
+
+ Display the data in code table.
+
+.. option:: --dis-symname=<name>
+
+ Disassemble just the specified symbol's instructions.
+
+.. option:: --dylibs-used
+
+ Display the shared libraries used for linked files.
+
+.. option:: --dsym=<string>
+
+ Use .dSYM file for debug info.
+
+.. option:: --dylib-id
+
+ Display the shared library's ID for dylib files.
+
+.. option:: --exports-trie
+
+ Display exported symbols.
+
+.. option:: -g
+
+ Print line information from debug info if available.
+
+.. option:: --full-leading-addr
+
+ Print the full leading address when disassembling.
+
+.. option:: --indirect-symbols
+
+ Display the indirect symbol table.
+
+.. option:: --info-plist
+
+ Display the info plist section as strings.
+
+.. option:: --lazy-bind
+
+ Display lazy binding info.
+
+.. option:: --link-opt-hints
+
+ Display the linker optimization hints.
+
+.. option:: -m, --macho
+
+ Use Mach-O specific object file parser. Commands and other options may behave
+ differently when used with ``--macho``.
+
+.. option:: --no-leading-headers
+
+ Do not print any leading headers.
+
+.. option:: --no-symbolic-operands
+
+ Do not print symbolic operands when disassembling.
+
+.. option:: --non-verbose
+
+ Display the information for Mach-O objects in non-verbose or numeric form.
+
+.. option:: --objc-meta-data
+
+ Display the Objective-C runtime meta data.
+
+.. option:: --private-header
+
+ Display only the first format specific file header.
+
+.. option:: --rebase
+
+ Display rebasing information.
+
+.. option:: --universal-headers
+
+ Display universal headers.
+
+.. option:: --weak-bind
+
+ Display weak binding information.
+
+BUGS
+----
+
+To report bugs, please visit <http://llvm.org/bugs/>.
+
+SEE ALSO
+--------
+
+:manpage:`llvm-nm(1)`, :manpage:`llvm-readelf(1)`, :manpage:`llvm-readobj(1)`
Added: www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-pdbutil.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-pdbutil.rst.txt?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-pdbutil.rst.txt (added)
+++ www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-pdbutil.rst.txt Thu Sep 19 07:32:46 2019
@@ -0,0 +1,587 @@
+llvm-pdbutil - PDB File forensics and diagnostics
+=================================================
+
+.. program:: llvm-pdbutil
+
+.. 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/9.0.0/docs/_sources/CommandGuide/llvm-profdata.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-profdata.rst.txt?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-profdata.rst.txt (added)
+++ www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-profdata.rst.txt Thu Sep 19 07:32:46 2019
@@ -0,0 +1,306 @@
+llvm-profdata - Profile data tool
+=================================
+
+.. program:: llvm-profdata
+
+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>`
+* :ref:`overlap <profdata-overlap>`
+
+.. 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.
+
+.. option:: -showcs
+
+ Only show context sensitive profile counts. The default is to filter all
+ context sensitive profile counts.
+
+.. program:: llvm-profdata overlap
+
+.. _profdata-overlap:
+
+OVERLAP
+-------
+
+SYNOPSIS
+^^^^^^^^
+
+:program:`llvm-profdata overlap` [*options*] [*base profile file*] [*test profile file*]
+
+DESCRIPTION
+^^^^^^^^^^^
+
+:program:`llvm-profdata overlap` takes two profile data files and displays the
+*overlap* of counter distribution between the whole files and between any of the
+specified functions.
+
+In this command, *overlap* is defined as follows:
+Suppose *base profile file* has the following counts:
+{c1_1, c1_2, ..., c1_n, c1_u_1, c2_u_2, ..., c2_u_s},
+and *test profile file* has
+{c2_1, c2_2, ..., c2_n, c2_v_1, c2_v_2, ..., c2_v_t}.
+Here c{1|2}_i (i = 1 .. n) are matched counters and c1_u_i (i = 1 .. s) and
+c2_v_i (i = 1 .. v) are unmatched counters (or counters only existing in)
+*base profile file* and *test profile file*, respectively.
+Let sum_1 = c1_1 + c1_2 + ... + c1_n + c1_u_1 + c2_u_2 + ... + c2_u_s, and
+sum_2 = c2_1 + c2_2 + ... + c2_n + c2_v_1 + c2_v_2 + ... + c2_v_t.
+*overlap* = min(c1_1/sum_1, c2_1/sum_2) + min(c1_2/sum_1, c2_2/sum_2) + ...
++ min(c1_n/sum_1, c2_n/sum_2).
+
+The result overlap distribution is a percentage number, ranging from 0.0% to
+100.0%, where 0.0% means there is no overlap and 100.0% means a perfect
+overlap.
+
+Here is an example, if *base profile file* has counts of {400, 600}, and
+*test profile file* has matched counts of {60000, 40000}. The *overlap* is 80%.
+
+OPTIONS
+^^^^^^^
+
+.. 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:: -o=output or -o output
+
+ Specify the output file name. If *output* is ``-`` or it isn't specified,
+ then the output is sent to standard output.
+
+.. 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 max of unsigned long long.
+
+.. option:: -cs
+
+ Only show overlap for the context sensitive profile counts. The default is to show
+ non-context sensitive profile counts.
+
+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/9.0.0/docs/_sources/CommandGuide/llvm-ranlib.md.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-ranlib.md.txt?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-ranlib.md.txt (added)
+++ www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-ranlib.md.txt Thu Sep 19 07:32:46 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/9.0.0/docs/_sources/CommandGuide/llvm-readelf.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-readelf.rst.txt?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-readelf.rst.txt (added)
+++ www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-readelf.rst.txt Thu Sep 19 07:32:46 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/9.0.0/docs/_sources/CommandGuide/llvm-readobj.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-readobj.rst.txt?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-readobj.rst.txt (added)
+++ www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-readobj.rst.txt Thu Sep 19 07:32:46 2019
@@ -0,0 +1,308 @@
+llvm-readobj - LLVM Object Reader
+=================================
+
+.. program:: llvm-readobj
+
+SYNOPSIS
+--------
+
+:program:`llvm-readobj` [*options*] [*input...*]
+
+DESCRIPTION
+-----------
+
+The :program:`llvm-readobj` tool displays low-level format-specific information
+about one or more object files.
+
+If ``input`` is "``-``" or omitted, :program:`llvm-readobj` reads from standard
+input. Otherwise, it will read from the specified ``filenames``.
+
+DIFFERENCES TO LLVM-READELF
+---------------------------
+
+:program:`llvm-readelf` is an alias for the :manpage:`llvm-readobj` tool with a
+slightly different command-line interface and output that is GNU compatible.
+Following is a list of differences between :program:`llvm-readelf` and
+:program:`llvm-readobj`:
+
+- :program:`llvm-readelf` uses `GNU` for the :option:`--elf-output-style` option
+ by default. :program:`llvm-readobj` uses `LLVM`.
+- :program:`llvm-readelf` allows single-letter grouped flags (e.g.
+ ``llvm-readelf -SW`` is the same as ``llvm-readelf -S -W``).
+ :program:`llvm-readobj` does not allow grouping.
+- :program:`llvm-readelf` provides :option:`-s` as an alias for
+ :option:`--symbols`, for GNU :program:`readelf` compatibility, whereas it is
+ an alias for :option:`--section-headers` in :program:`llvm-readobj`.
+- :program:`llvm-readobj` provides ``-t`` as an alias for :option:`--symbols`.
+ :program:`llvm-readelf` does not.
+- :program:`llvm-readobj` provides ``--sr``, ``--sd``, ``--st`` and ``--dt`` as
+ aliases for :option:`--section-relocations`, :option:`--section-data`,
+ :option:`--section-symbols` and :option:`--dyn-symbols` respectively.
+ :program:`llvm-readelf` does not provide these aliases, to avoid conflicting
+ with grouped flags.
+
+GENERAL AND MULTI-FORMAT OPTIONS
+--------------------------------
+
+These options are applicable to more than one file format, or are unrelated to
+file formats.
+
+.. option:: --all
+
+ Equivalent to specifying all the main display options relevant to the file
+ format.
+
+.. option:: --addrsig
+
+ Display the address-significance table.
+
+.. option:: --color
+
+ Use colors in the output for warnings and errors.
+
+.. 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:: --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:: --relocations, --relocs, -r
+
+ Display the relocation entries in the file.
+
+.. option:: --sections, --section-headers, -s, -S
+
+ Display all sections.
+
+.. option:: --section-data, --sd
+
+ When used with :option:`--sections`, display section data for each section
+ shown. This option has no effect for GNU style output.
+
+.. option:: --section-relocations, --sr
+
+ When used with :option:`--sections`, display relocations for each section
+ shown. This option has no effect for GNU style output.
+
+.. option:: --section-symbols, --st
+
+ 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, -t
+
+ Display the symbol table.
+
+.. option:: --unwind, -u
+
+ Display unwind information.
+
+.. option:: --version
+
+ Display the version of this program.
+
+.. option:: @<FILE>
+
+ Read command-line options from response file `<FILE>`.
+
+ELF SPECIFIC OPTIONS
+--------------------
+
+The following options are implemented only for the ELF file format.
+
+.. option:: --arm-attributes
+
+ Display the ARM attributes section. Only applicable for ARM architectures.
+
+.. option:: --demangle, -C
+
+ Display demangled symbol names in the output.
+
+.. option:: --dyn-relocations
+
+ Display the dynamic relocation entries.
+
+.. option:: --dyn-symbols, --dyn-syms, --dt
+
+ 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 (the default) is an expanded and structured format,
+ whilst ``GNU`` output mimics the equivalent GNU :program:`readelf` output.
+
+.. option:: --elf-section-groups, --section-groups, -g
+
+ Display section groups.
+
+.. 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:: --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:: --section-mapping
+
+ Display the section to segment mapping.
+
+.. option:: --version-info, -V
+
+ Display version sections.
+
+MACH-O SPECIFIC OPTIONS
+-----------------------
+
+The following options are implemented only for the Mach-O file format.
+
+.. option:: --macho-data-in-code
+
+ Display the Data in Code command.
+
+.. option:: --macho-dsymtab
+
+ Display the Dsymtab command.
+
+.. option:: --macho-indirect-symbols
+
+ Display indirect symbols.
+
+.. option:: --macho-linker-options
+
+ Display the Mach-O-specific linker options.
+
+.. option:: --macho-segment
+
+ Display the Segment command.
+
+.. option:: --macho-version-min
+
+ Display the version min command.
+
+PE/COFF SPECIFIC OPTIONS
+------------------------
+
+The following options are implemented only for the PE/COFF file format.
+
+.. option:: --codeview
+
+ Display CodeView debug information.
+
+.. option:: --codeview-ghash
+
+ Enable global hashing for CodeView type stream de-duplication.
+
+.. option:: --codeview-merged-types
+
+ Display the merged CodeView type stream.
+
+.. option:: --codeview-subsection-bytes
+
+ Dump raw contents of CodeView debug sections and records.
+
+.. option:: --coff-basereloc
+
+ Display the .reloc section.
+
+.. option:: --coff-debug-directory
+
+ Display the debug directory.
+
+.. option:: --coff-directives
+
+ Display the .drectve section.
+
+.. option:: --coff-exports
+
+ Display the export table.
+
+.. option:: --coff-imports
+
+ Display the import table.
+
+.. option:: --coff-load-config
+
+ Display the load config.
+
+.. option:: --coff-resources
+
+ Display the .rsrc section.
+
+EXIT STATUS
+-----------
+
+:program:`llvm-readobj` 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-readelf(1)`
Added: www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-size.md.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-size.md.txt?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-size.md.txt (added)
+++ www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-size.md.txt Thu Sep 19 07:32:46 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/9.0.0/docs/_sources/CommandGuide/llvm-stress.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-stress.rst.txt?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-stress.rst.txt (added)
+++ www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-stress.rst.txt Thu Sep 19 07:32:46 2019
@@ -0,0 +1,35 @@
+llvm-stress - generate random .ll files
+=======================================
+
+.. program:: llvm-stress
+
+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/9.0.0/docs/_sources/CommandGuide/llvm-strings.md.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-strings.md.txt?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-strings.md.txt (added)
+++ www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-strings.md.txt Thu Sep 19 07:32:46 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/9.0.0/docs/_sources/CommandGuide/llvm-strip.md.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-strip.md.txt?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-strip.md.txt (added)
+++ www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-strip.md.txt Thu Sep 19 07:32:46 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/9.0.0/docs/_sources/CommandGuide/llvm-symbolizer.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-symbolizer.rst.txt?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-symbolizer.rst.txt (added)
+++ www-releases/trunk/9.0.0/docs/_sources/CommandGuide/llvm-symbolizer.rst.txt Thu Sep 19 07:32:46 2019
@@ -0,0 +1,354 @@
+llvm-symbolizer - convert addresses into source code locations
+==============================================================
+
+.. program:: llvm-symbolizer
+
+SYNOPSIS
+--------
+
+:program:`llvm-symbolizer` [*options*] [*addresses...*]
+
+DESCRIPTION
+-----------
+
+:program:`llvm-symbolizer` reads object file names and addresses from the
+command-line and prints corresponding source code locations to standard output.
+
+If no address is specified on the command-line, it reads the addresses from
+standard input. If no object file is specified on the command-line, but
+addresses are, or if at any time an input value is not recognized, the input is
+simply echoed to the output.
+
+A positional argument or standard input value can be preceded by "DATA" or
+"CODE" to indicate that the address should be symbolized as data or executable
+code respectively. If neither is specified, "CODE" is assumed. DATA is
+symbolized as address and symbol size rather than line number.
+
+Object files can be specified together with the addresses either on standard
+input or as positional arguments on the command-line, following any "DATA" or
+"CODE" prefix.
+
+EXAMPLES
+--------
+
+All of the following examples use the following two source files as input. They
+use a mixture of C-style and C++-style linkage to illustrate how these names are
+printed differently (see :option:`--demangle`).
+
+.. code-block:: c
+
+ // test.h
+ extern "C" inline int foz() {
+ return 1234;
+ }
+
+.. code-block:: c
+
+ // test.cpp
+ #include "test.h"
+ int bar=42;
+
+ int foo() {
+ return bar;
+ }
+
+ int baz() {
+ volatile int k = 42;
+ return foz() + k;
+ }
+
+ int main() {
+ return foo() + baz();
+ }
+
+These files are built as follows:
+
+.. code-block:: console
+
+ $ clang -g test.cpp -o test.elf
+ $ clang -g -O2 test.cpp -o inlined.elf
+
+Example 1 - addresses and object on command-line:
+
+.. code-block:: console
+
+ $ llvm-symbolizer --obj=test.elf 0x4004d0 0x400490
+ foz
+ /tmp/test.h:1:0
+
+ baz()
+ /tmp/test.cpp:11:0
+
+Example 2 - addresses on standard input:
+
+.. code-block:: console
+
+ $ cat addr.txt
+ 0x4004a0
+ 0x400490
+ 0x4004d0
+ $ llvm-symbolizer --obj=test.elf < addr.txt
+ main
+ /tmp/test.cpp:15:0
+
+ baz()
+ /tmp/test.cpp:11:0
+
+ foz
+ /tmp/./test.h:1:0
+
+Example 3 - object specified with address:
+
+.. code-block:: console
+
+ $ llvm-symbolizer "test.elf 0x400490" "inlined.elf 0x400480"
+ baz()
+ /tmp/test.cpp:11:0
+
+ foo()
+ /tmp/test.cpp:8:10
+
+ $ cat addr2.txt
+ test.elf 0x4004a0
+ inlined.elf 0x400480
+
+ $ llvm-symbolizer < addr2.txt
+ main
+ /tmp/test.cpp:15:0
+
+ foo()
+ /tmp/test.cpp:8:10
+
+Example 4 - CODE and DATA prefixes:
+
+.. code-block:: console
+
+ $ llvm-symbolizer --obj=test.elf "CODE 0x400490" "DATA 0x601028"
+ baz()
+ /tmp/test.cpp:11:0
+
+ bar
+ 6295592 4
+
+ $ cat addr3.txt
+ CODE test.elf 0x4004a0
+ DATA inlined.elf 0x601028
+
+ $ llvm-symbolizer < addr3.txt
+ main
+ /tmp/test.cpp:15:0
+
+ bar
+ 6295592 4
+
+OPTIONS
+-------
+
+.. option:: --adjust-vma <offset>
+
+ Add the specified offset to object file addresses when performing lookups.
+ This can be used to perform lookups as if the object were relocated by the
+ offset.
+
+.. option:: --basenames, -s
+
+ Strip directories when printing the file path.
+
+.. _llvm-symbolizer-opt-C:
+
+.. option:: --demangle, -C
+
+ Print demangled function names, if the names are mangled (e.g. the mangled
+ name `_Z3bazv` becomes `baz()`, whilst the non-mangled name `foz` is printed
+ as is). Defaults to true.
+
+.. option:: --dwp <path>
+
+ Use the specified DWP file at ``<path>`` for any CUs that have split DWARF
+ debug data.
+
+.. option:: --fallback-debug-path <path>
+
+ When a separate file contains debug data, and is referenced by a GNU debug
+ link section, use the specified path as a basis for locating the debug data if
+ it cannot be found relative to the object.
+
+.. _llvm-symbolizer-opt-f:
+
+.. option:: --functions [<none|short|linkage>], -f
+
+ Specify the way function names are printed (omit function name, print short
+ function name, or print full linkage name, respectively). Defaults to
+ ``linkage``.
+
+.. option:: --help, -h
+
+ Show help and usage for this command.
+
+.. option:: --help-list
+
+ Show help and usage for this command without grouping the options into categories.
+
+.. _llvm-symbolizer-opt-i:
+
+.. option:: --inlining, --inlines, -i
+
+ If a source code location is in an inlined function, prints all the inlined
+ frames. Defaults to true.
+
+.. option:: --no-demangle
+
+ Don't print demangled function names.
+
+.. option:: --obj <path>, --exe, -e
+
+ Path to object file to be symbolized. If ``-`` is specified, read the object
+ directly from the standard input stream.
+
+.. _llvm-symbolizer-opt-output-style:
+
+.. option:: --output-style <LLVM|GNU>
+
+ Specify the preferred output style. Defaults to ``LLVM``. When the output
+ style is set to ``GNU``, the tool follows the style of GNU's **addr2line**.
+ The differences from the ``LLVM`` style are:
+
+ * Does not print the column of a source code location.
+
+ * Does not add an empty line after the report for an address.
+
+ * Does not replace the name of an inlined function with the name of the
+ topmost caller when inlined frames are not shown and :option:`--use-symbol-table`
+ is on.
+
+ .. code-block:: console
+
+ $ llvm-symbolizer --obj=inlined.elf 0x4004be 0x400486 -p
+ baz() at /tmp/test.cpp:11:18
+ (inlined by) main at /tmp/test.cpp:15:0
+
+ foo() at /tmp/test.cpp:6:3
+
+ $ llvm-symbolizer --output-style=LLVM --obj=inlined.elf 0x4004be 0x400486 -p -i=0
+ main at /tmp/test.cpp:11:18
+
+ foo() at /tmp/test.cpp:6:3
+
+ $ llvm-symbolizer --output-style=GNU --obj=inlined.elf 0x4004be 0x400486 -p -i=0
+ baz() at /tmp/test.cpp:11
+ foo() at /tmp/test.cpp:6
+
+.. option:: --pretty-print, -p
+
+ Print human readable output. If :option:`--inlining` is specified, the
+ enclosing scope is prefixed by (inlined by).
+
+.. code-block:: console
+
+ $ llvm-symbolizer --obj=inlined.elf 0x4004be --inlining --pretty-print
+ baz() at /tmp/test.cpp:11:18
+ (inlined by) main at /tmp/test.cpp:15:0
+
+.. option:: --print-address, --addresses, -a
+
+ Print address before the source code location. Defaults to false.
+
+.. code-block:: console
+
+ $ llvm-symbolizer --obj=inlined.elf --print-address 0x4004be
+ 0x4004be
+ baz()
+ /tmp/test.cpp:11:18
+ main
+ /tmp/test.cpp:15:0
+
+ $ llvm-symbolizer --obj=inlined.elf 0x4004be --pretty-print --print-address
+ 0x4004be: baz() at /tmp/test.cpp:11:18
+ (inlined by) main at /tmp/test.cpp:15:0
+
+.. option:: --print-source-context-lines <N>
+
+ Print ``N`` lines of source context for each symbolized address.
+
+.. code-block:: console
+
+ $ llvm-symbolizer --obj=test.elf 0x400490 --print-source-context-lines=2
+ baz()
+ /tmp/test.cpp:11:0
+ 10 : volatile int k = 42;
+ 11 >: return foz() + k;
+ 12 : }
+
+.. _llvm-symbolizer-opt-use-symbol-table:
+
+.. option:: --use-symbol-table
+
+ Prefer function names stored in symbol table to function names in debug info
+ sections. Defaults to true.
+
+.. option:: --verbose
+
+ Print verbose line and column information.
+
+.. code-block:: console
+
+ $ llvm-symbolizer --obj=inlined.elf --verbose 0x4004be
+ baz()
+ Filename: /tmp/test.cpp
+ Function start line: 9
+ Line: 11
+ Column: 18
+ main
+ Filename: /tmp/test.cpp
+ Function start line: 14
+ Line: 15
+ Column: 0
+
+.. option:: --version
+
+ Print version information for the tool.
+
+.. option:: @<FILE>
+
+ Read command-line options from response file `<FILE>`.
+
+MACH-O SPECIFIC OPTIONS
+-----------------------
+
+.. option:: --default-arch <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 the architecture by writing ``binary_name:arch_name`` in
+ the input (see example below). If the architecture is not specified in either
+ way, the address will not be symbolized. Defaults to empty string.
+
+.. code-block:: console
+
+ $ cat addr.txt
+ /tmp/mach_universal_binary:i386 0x1f84
+ /tmp/mach_universal_binary:x86_64 0x100000f24
+
+ $ llvm-symbolizer < addr.txt
+ _main
+ /tmp/source_i386.cc:8
+
+ _main
+ /tmp/source_x86_64.cc:8
+
+.. option:: --dsym-hint <path/to/file.dSYM>
+
+ 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 this option. This flag can be
+ used multiple times.
+
+EXIT STATUS
+-----------
+
+:program:`llvm-symbolizer` returns 0. Other exit codes imply an internal program
+error.
+
+SEE ALSO
+--------
+
+:manpage:`llvm-addr2line(1)`
Added: www-releases/trunk/9.0.0/docs/_sources/CommandGuide/opt.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/_sources/CommandGuide/opt.rst.txt?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/_sources/CommandGuide/opt.rst.txt (added)
+++ www-releases/trunk/9.0.0/docs/_sources/CommandGuide/opt.rst.txt Thu Sep 19 07:32:46 2019
@@ -0,0 +1,124 @@
+opt - LLVM optimizer
+====================
+
+.. program:: opt
+
+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/9.0.0/docs/_sources/CommandGuide/tblgen.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/_sources/CommandGuide/tblgen.rst.txt?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/_sources/CommandGuide/tblgen.rst.txt (added)
+++ www-releases/trunk/9.0.0/docs/_sources/CommandGuide/tblgen.rst.txt Thu Sep 19 07:32:46 2019
@@ -0,0 +1,147 @@
+tblgen - Target Description To C++ Code Generator
+=================================================
+
+.. program:: tblgen
+
+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/9.0.0/docs/_sources/CommandLine.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/_sources/CommandLine.rst.txt?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/_sources/CommandLine.rst.txt (added)
+++ www-releases/trunk/9.0.0/docs/_sources/CommandLine.rst.txt Thu Sep 19 07:32:46 2019
@@ -0,0 +1,1752 @@
+==============================
+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:
+ -h - Alias for -help
+ -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:
+ -h - Alias for -help
+ -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:
+
+Controlling options grouping
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The **cl::Grouping** modifier can be combined with any formatting types except
+for `cl::Positional`_. It 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 can have values only if they are used
+separately or at the end of the groups. For `cl::ValueRequired`_, it is
+a runtime error if such an option is used elsewhere in the group.
+
+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 (!Input.empty() && !isOption(Input)) Input.pop_back(); // Remove the last letter
+ 4. while (!Input.empty()) {
+ string MaybeValue = OrigInput.substr(Input.length())
+ if (getOption(Input).isPrefix())
+ return getOption(Input).parse(MaybeValue)
+ if (!MaybeValue.empty() && MaybeValue[0] == '=')
+ return getOption(Input).parse(MaybeValue.substr(1))
+ if (!getOption(Input).isGrouping())
+ return error()
+ getOption(Input).parse()
+ Input = OrigInput = MaybeValue
+ while (!Input.empty() && !isOption(Input)) Input.pop_back();
+ if (!Input.empty() && !getOption(Input).isGrouping())
+ return error()
+ }
+ 5. 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::DefaultOption:
+
+* The **cl::DefaultOption** modifier is used to specify that the option is a
+ default that can be overridden by application specific parsers. For example,
+ the ``-help`` alias, ``-h``, is registered this way, so it can be overridden
+ by applications that need to use the ``-h`` option for another purpose,
+ either as a regular option or an alias for another 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.
+
+.. _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 writer 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/9.0.0/docs/_sources/CompileCudaWithLLVM.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/_sources/CompileCudaWithLLVM.rst.txt?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/_sources/CompileCudaWithLLVM.rst.txt (added)
+++ www-releases/trunk/9.0.0/docs/_sources/CompileCudaWithLLVM.rst.txt Thu Sep 19 07:32:46 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/llvm-test-suite/blob/master/External/CUDA/math_h.cu>`_
+`tests
+<https://github.com/llvm/llvm-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/9.0.0/docs/_sources/CompilerWriterInfo.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/_sources/CompilerWriterInfo.rst.txt?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/_sources/CompilerWriterInfo.rst.txt (added)
+++ www-releases/trunk/9.0.0/docs/_sources/CompilerWriterInfo.rst.txt Thu Sep 19 07:32:46 2019
@@ -0,0 +1,172 @@
+========================================================
+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 <https://developer.arm.com/docs/ddi0487/latest>`_ This document covers both AArch64 and ARM instructions
+
+* `ARMv7-A Architecture Reference Manual <https://developer.arm.com/docs/ddi0406/latest>`_ This has some useful info on what is supported by older architecture versions.
+
+* `ARMv7-M Architecture Reference Manual <https://developer.arm.com/docs/ddi0403/latest>`_ This covers the Thumb2-only microcontrollers
+
+* `ARMv6-M Architecture Reference Manual <https://developer.arm.com/docs/ddi0419/latest>`_ 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>`_
+
+* `ARM NEON Intrinsics Reference <http://infocenter.arm.com/help/topic/com.arm.doc.ihi0073b/IHI0073B_arm_neon_intrinsics_ref.pdf>`_
+
+* AArch32 `ABI Addenda and Errata <http://infocenter.arm.com/help/topic/com.arm.doc.ihi0045d/IHI0045D_ABI_addenda.pdf>`_
+
+* `Cortex-A57 Software Optimization Guide <http://infocenter.arm.com/help/topic/com.arm.doc.uan0015b/Cortex_A57_Software_Optimization_Guide_external.pdf>`_
+
+* `Run-time ABI for the ARM Architecture <http://infocenter.arm.com/help/topic/com.arm.doc.ihi0043d/IHI0043D_rtabi.pdf>`_ This documents the __aeabi_* helper functions.
+
+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/>`_ (This is used for all non-Windows targets.)
+
+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>`_
+* `Procedure Call Standard for the ARM Architecture <https://developer.arm.com/docs/ihi0042/latest>`_
+* `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>`_
+
+macOS
+-----
+
+* `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>`_
+* `ARM64 Function Calling Conventions <https://developer.apple.com/library/archive/documentation/Xcode/Conceptual/iPhoneOSABIReference/Articles/ARM64FunctionCallingConventions.html>`_
+
+Windows
+-------
+
+* `Microsoft PE/COFF Specification <http://www.microsoft.com/whdc/system/platform/firmware/pecoff.mspx>`_
+* `ARM64 exception handling <https://docs.microsoft.com/en-us/cpp/build/arm64-exception-handling>`_
+* `ARM exception handling <https://docs.microsoft.com/en-us/cpp/build/arm-exception-handling>`_
+* `Overview of ARM64 ABI conventions <https://docs.microsoft.com/en-us/cpp/build/arm64-windows-abi-conventions>`_
+* `Overview of ARM32 ABI Conventions <https://docs.microsoft.com/en-us/cpp/build/overview-of-arm-abi-conventions>`_
+
+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/9.0.0/docs/_sources/Contributing.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/_sources/Contributing.rst.txt?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/_sources/Contributing.rst.txt (added)
+++ www-releases/trunk/9.0.0/docs/_sources/Contributing.rst.txt Thu Sep 19 07:32:46 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/9.0.0/docs/_sources/Coroutines.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/_sources/Coroutines.rst.txt?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/_sources/Coroutines.rst.txt (added)
+++ www-releases/trunk/9.0.0/docs/_sources/Coroutines.rst.txt Thu Sep 19 07:32:46 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/9.0.0/docs/_sources/CoverageMappingFormat.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/_sources/CoverageMappingFormat.rst.txt?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/_sources/CoverageMappingFormat.rst.txt (added)
+++ www-releases/trunk/9.0.0/docs/_sources/CoverageMappingFormat.rst.txt Thu Sep 19 07:32:46 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/9.0.0/docs/_sources/DebuggingJITedCode.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/_sources/DebuggingJITedCode.rst.txt?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/_sources/DebuggingJITedCode.rst.txt (added)
+++ www-releases/trunk/9.0.0/docs/_sources/DebuggingJITedCode.rst.txt Thu Sep 19 07:32:46 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 macOS.
+
+
+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/9.0.0/docs/_sources/DeveloperPolicy.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/_sources/DeveloperPolicy.rst.txt?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/_sources/DeveloperPolicy.rst.txt (added)
+++ www-releases/trunk/9.0.0/docs/_sources/DeveloperPolicy.rst.txt Thu Sep 19 07:32:46 2019
@@ -0,0 +1,944 @@
+=====================
+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
+licensing terms 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.
+
+Here's a `sample RFC
+<http://lists.llvm.org/pipermail/llvm-dev/2019-January/129452.html>`_ and the
+`corresponding change <https://reviews.llvm.org/D57264>`_.
+
+.. _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 a licensed attorney.
+
+This section addresses the issues of copyright, license and patents for the LLVM
+project. The copyright for the code is held by the contributors of
+the code. The code is licensed under permissive `open source licensing terms`_,
+namely the Apache 2 license, which includes a copyright and `patent license`_.
+When you contribute code to the LLVM project, you license it under these terms.
+
+If you have questions or comments about these topics, please contact the
+`LLVM Developer's Mailing List <mailto:llvm-dev at lists.llvm.org>`_. However,
+please realize that most compiler developers are not lawyers, and therefore you
+will not be getting official legal advice.
+
+Copyright
+---------
+
+The LLVM project does not collect copyright assignments, which means that the
+copyright for the code in the project is held by the respective contributors.
+Because you (or your company)
+retain ownership of the code you contribute, you know it may only be used under
+the terms of the open source license you contributed it under: the license for
+your contributions cannot be changed in the future without your approval.
+
+Because the LLVM project does not require copyright assignments, changing the
+LLVM license requires tracking down the
+contributors to LLVM and getting them to agree that a license change is
+acceptable for their contributions. We feel that a high burden for relicensing
+is good for the project, because contributors do not have to fear that their
+code will be used in a way with which they disagree.
+
+Relicensing
+-----------
+
+The last paragraph notwithstanding, the LLVM Project is in the middle of a large
+effort to change licenses, which aims to solve several problems:
+
+* The old licenses made it difficult to move code from (e.g.) the compiler to
+ runtime libraries, because runtime libraries used a different license from the
+ rest of the compiler.
+* Some contributions were not submitted to LLVM due to concerns that
+ the patent grant required by the project was overly broad.
+* The patent grant was unique to the LLVM Project, not written by a lawyer, and
+ was difficult to determine what protection was provided (if any).
+
+The scope of relicensing is all code that is considered part of the LLVM
+project, including the main LLVM repository, runtime libraries (compiler_rt,
+OpenMP, etc), Polly, and all other subprojects. There are a few exceptions:
+
+* Code imported from other projects (e.g. Google Test, Autoconf, etc) will
+ remain as it is. This code isn't developed as part of the LLVM project, it
+ is used by LLVM.
+* Some subprojects are impractical or uninteresting to relicense (e.g. llvm-gcc
+ and dragonegg). These will be split off from the LLVM project (e.g. to
+ separate Github projects), allowing interested people to continue their
+ development elsewhere.
+
+To relicense LLVM, we will be seeking approval from all of the copyright holders
+of code in the repository, or potentially remove/rewrite code if we cannot.
+This is a large
+and challenging project which will take a significant amount of time to
+complete. In the interim, **all contributions to the project will be made under
+the terms of both the new license and the legacy license scheme** (each of which
+is described below). The exception to this is the legacy patent grant, which
+will not be required for new contributions.
+
+When all of the code in the project has been converted to the new license or
+removed, we will drop the requirement to contribute under the legacy license.
+This will achieve the goal of having
+a single standardized license for the entire codebase.
+
+If you are a prior contributor to LLVM and have not done so already, please do
+*TODO* to allow us to use your code. *Add a link to a separate page here, which
+is probably a click through web form or something like that. Details to be
+determined later*.
+
+
+.. _open source licensing terms:
+
+New LLVM Project License Framework
+----------------------------------
+
+Contributions to LLVM are licensed under the `Apache License, Version 2.0
+<https://www.apache.org/licenses/LICENSE-2.0>`_, with two limited
+exceptions intended to ensure that LLVM is very permissively licensed.
+Collectively, the name of this license is "Apache 2.0 License with LLVM
+exceptions". The exceptions read:
+
+::
+
+ ---- LLVM Exceptions to the Apache 2.0 License ----
+
+ As an exception, if, as a result of your compiling your source code, portions
+ of this Software are embedded into an Object form of such source code, you
+ may redistribute such embedded portions in such Object form without complying
+ with the conditions of Sections 4(a), 4(b) and 4(d) of the License.
+
+ In addition, if you combine or link compiled forms of this Software with
+ software that is licensed under the GPLv2 ("Combined Software") and if a
+ court of competent jurisdiction determines that the patent provision (Section
+ 3), the indemnity provision (Section 9) or other Section of the License
+ conflicts with the conditions of the GPLv2, you may retroactively and
+ prospectively choose to deem waived or otherwise exclude such Section(s) of
+ the License, but only in their entirety and only with respect to the Combined
+ Software.
+
+
+We intend to keep LLVM perpetually open source and available under a permissive
+license - this fosters the widest adoption of LLVM by
+**allowing commercial products to be derived from LLVM** with few restrictions
+and without a requirement for making any derived works also open source. In
+particular, LLVM's license is not a "copyleft" license like the GPL.
+
+The "Apache 2.0 License with LLVM exceptions" allows you to:
+
+* freely download and use LLVM (in whole or in part) for personal, internal, or
+ commercial purposes.
+* include LLVM in packages or distributions you create.
+* combine LLVM with code licensed under every other major open source
+ license (including BSD, MIT, GPLv2, GPLv3...).
+* make changes to LLVM code without being required to contribute it back
+ to the project - contributions are appreciated though!
+
+However, it imposes these limitations on you:
+
+* You must retain the copyright notice if you redistribute LLVM: You cannot
+ strip the copyright headers off or replace them with your own.
+* Binaries that include LLVM must reproduce the copyright notice (e.g. in an
+ included README file or in an "About" box), unless the LLVM code was added as
+ a by-product of compilation. For example, if an LLVM runtime library like
+ compiler_rt or libc++ was automatically included into your application by the
+ compiler, you do not need to attribute it.
+* You can't use our names to promote your products (LLVM derived or not) -
+ though you can make truthful statements about your use of the LLVM code,
+ without implying our sponsorship.
+* There's no warranty on LLVM at all.
+
+We want LLVM code to be widely used, and believe that this provides a model that
+is great for contributors and users of the project. For more information about
+the Apache 2.0 License, please see the `Apache License FAQ
+<http://www.apache.org/foundation/license-faq.html>`_, maintained by the
+Apache Project.
+
+
+.. note::
+
+ The LLVM Project includes some really old subprojects (dragonegg,
+ llvm-gcc-4.0, and llvm-gcc-4.2), which are licensed under **GPL
+ licenses**. This code is not actively maintained - it does not even
+ build successfully. This code is cleanly separated into distinct SVN
+ repositories from the rest of LLVM, and the LICENSE.txt files specifically
+ indicate that they contain GPL code. When LLVM transitions from SVN to Git,
+ we plan to drop these code bases from the new repository structure.
+
+
+.. _patent license:
+
+Patents
+-------
+
+Section 3 of the Apache 2.0 license is a patent grant under which
+contributors of code to the project contribute the rights to use any of
+their patents that would otherwise be infringed by that code contribution
+(protecting uses of that code). Further, the patent grant is revoked
+from anyone who files a patent lawsuit about code in LLVM - this protects the
+community by providing a "patent commons" for the code base and reducing the
+odds of patent lawsuits in general.
+
+The license specifically scopes which patents are included with code
+contributions. To help explain this, the `Apache License FAQ
+<http://www.apache.org/foundation/license-faq.html>`_ explains this scope using
+some questions and answers, which we reproduce here for your convenience (for
+reference, the "ASF" is the Apache Software Foundation, the guidance still
+holds though)::
+
+ Q1: If I own a patent and contribute to a Work, and, at the time my
+ contribution is included in that Work, none of my patent's claims are subject
+ to Apache's Grant of Patent License, is there a way any of those claims would
+ later become subject to the Grant of Patent License solely due to subsequent
+ contributions by other parties who are not licensees of that patent.
+
+ A1: No.
+
+ Q2: If at any time after my contribution, I am able to license other patent
+ claims that would have been subject to Apache's Grant of Patent License if
+ they were licenseable by me at the time of my contribution, do those other
+ claims become subject to the Grant of Patent License?
+
+ A2: Yes.
+
+ Q3: If I own or control a licensable patent and contribute code to a specific
+ Apache product, which of my patent claims are subject to Apache's Grant of
+ Patent License?
+
+ A3: The only patent claims that are licensed to the ASF are those you own or
+ have the right to license that read on your contribution or on the
+ combination of your contribution with the specific Apache product to which
+ you contributed as it existed at the time of your contribution. No additional
+ patent claims become licensed as a result of subsequent combinations of your
+ contribution with any other software. Note, however, that licensable patent
+ claims include those that you acquire in the future, as long as they read on
+ your original contribution as made at the original time. Once a patent claim
+ is subject to Apache's Grant of Patent License, it is licensed under the
+ terms of that Grant to the ASF and to recipients of any software distributed
+ by the ASF for any Apache software product whatsoever.
+
+.. _legacy:
+
+Legacy License Structure
+------------------------
+
+.. note::
+ The code base was previously licensed under the Terms described here.
+ We are in the middle of relicensing to a new approach (described above), but
+ until this effort is complete, the code is also still available under these
+ terms. Once we finish the relicensing project, new versions of the code will
+ not be available under these terms. However, nothing takes away your right
+ to use old versions under the licensing terms under which they were
+ originally released.
+
+We intend to keep LLVM perpetually open source and to use a permissive open
+source license. 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.
Added: www-releases/trunk/9.0.0/docs/_sources/Docker.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/_sources/Docker.rst.txt?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/_sources/Docker.rst.txt (added)
+++ www-releases/trunk/9.0.0/docs/_sources/Docker.rst.txt Thu Sep 19 07:32:46 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-resource-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-resource-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-resource-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-resource-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/9.0.0/docs/_sources/ExceptionHandling.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/_sources/ExceptionHandling.rst.txt?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/_sources/ExceptionHandling.rst.txt (added)
+++ www-releases/trunk/9.0.0/docs/_sources/ExceptionHandling.rst.txt Thu Sep 19 07:32:46 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/9.0.0/docs/_sources/ExtendingLLVM.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/_sources/ExtendingLLVM.rst.txt?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/_sources/ExtendingLLVM.rst.txt (added)
+++ www-releases/trunk/9.0.0/docs/_sources/ExtendingLLVM.rst.txt Thu Sep 19 07:32:46 2019
@@ -0,0 +1,321 @@
+============================================================
+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). If any arguments need to be immediates, these
+ must be indicated with the ImmArg property. 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/9.0.0/docs/_sources/Extensions.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/_sources/Extensions.rst.txt?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/_sources/Extensions.rst.txt (added)
+++ www-releases/trunk/9.0.0/docs/_sources/Extensions.rst.txt Thu Sep 19 07:32:46 2019
@@ -0,0 +1,558 @@
+===============
+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_DEPENDENT_LIBRARIES`` Section (Dependent Libraries)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This section contains strings specifying libraries to be added to the link by
+the linker.
+
+The section should be consumed by the linker and not written to the output.
+
+The strings are encoded as standard null-terminated UTF-8 strings.
+
+For example:
+
+.. code-block:: gas
+
+ .section ".deplibs","MS", at llvm_dependent_libraries,1
+ .asciz "library specifier 1"
+ .asciz "library specifier 2"
+
+The interpretation of the library specifiers is defined by the consuming linker.
+
+``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.
+
+``SHT_LLVM_SYMPART`` Section (symbol partition specification)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This section is used to mark symbols with the `partition`_ that they
+belong to. An ``.llvm_sympart`` section consists of a null-terminated string
+specifying the name of the partition followed by a relocation referring to
+the symbol that belongs to the partition. It may be constructed as follows:
+
+.. code-block:: gas
+
+ .section ".llvm_sympart","", at llvm_sympart
+ .asciz "libpartition.so"
+ .word symbol_in_partition
+
+.. _partition: https://lld.llvm.org/Partitions.html
+
+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/9.0.0/docs/_sources/FAQ.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/_sources/FAQ.rst.txt?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/_sources/FAQ.rst.txt (added)
+++ www-releases/trunk/9.0.0/docs/_sources/FAQ.rst.txt Thu Sep 19 07:32:46 2019
@@ -0,0 +1,339 @@
+================================
+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.
+
+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/9.0.0/docs/_sources/FaultMaps.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/_sources/FaultMaps.rst.txt?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/_sources/FaultMaps.rst.txt (added)
+++ www-releases/trunk/9.0.0/docs/_sources/FaultMaps.rst.txt Thu Sep 19 07:32:46 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/9.0.0/docs/_sources/Frontend/PerformanceTips.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/_sources/Frontend/PerformanceTips.rst.txt?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/_sources/Frontend/PerformanceTips.rst.txt (added)
+++ www-releases/trunk/9.0.0/docs/_sources/Frontend/PerformanceTips.rst.txt Thu Sep 19 07:32:46 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/9.0.0/docs/_sources/FuzzingLLVM.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/_sources/FuzzingLLVM.rst.txt?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/_sources/FuzzingLLVM.rst.txt (added)
+++ www-releases/trunk/9.0.0/docs/_sources/FuzzingLLVM.rst.txt Thu Sep 19 07:32:46 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.
More information about the llvm-commits
mailing list