[www-releases] r297634 - Check in the 4.0.0 release
Hans Wennborg via llvm-commits
llvm-commits at lists.llvm.org
Mon Mar 13 09:30:21 PDT 2017
Added: www-releases/trunk/4.0.0/tools/clang/docs/PCHInternals.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/4.0.0/tools/clang/docs/PCHInternals.html?rev=297634&view=auto
==============================================================================
--- www-releases/trunk/4.0.0/tools/clang/docs/PCHInternals.html (added)
+++ www-releases/trunk/4.0.0/tools/clang/docs/PCHInternals.html Mon Mar 13 11:30:12 2017
@@ -0,0 +1,590 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>Precompiled Header and Modules Internals — Clang 4 documentation</title>
+
+ <link rel="stylesheet" href="_static/haiku.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: './',
+ VERSION: '4',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+ <link rel="top" title="Clang 4 documentation" href="index.html" />
+ <link rel="next" title="ABI tags" href="ItaniumMangleAbiTags.html" />
+ <link rel="prev" title="Pretokenized Headers (PTH)" href="PTHInternals.html" />
+ </head>
+ <body>
+ <div class="header"><h1 class="heading"><a href="index.html">
+ <span>Clang 4 documentation</span></a></h1>
+ <h2 class="heading"><span>Precompiled Header and Modules Internals</span></h2>
+ </div>
+ <div class="topnav">
+
+ <p>
+ « <a href="PTHInternals.html">Pretokenized Headers (PTH)</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="ItaniumMangleAbiTags.html">ABI tags</a> »
+ </p>
+
+ </div>
+ <div class="content">
+
+
+ <div class="section" id="precompiled-header-and-modules-internals">
+<h1>Precompiled Header and Modules Internals<a class="headerlink" href="#precompiled-header-and-modules-internals" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#using-precompiled-headers-with-clang" id="id1">Using Precompiled Headers with <tt class="docutils literal"><span class="pre">clang</span></tt></a></li>
+<li><a class="reference internal" href="#design-philosophy" id="id2">Design Philosophy</a></li>
+<li><a class="reference internal" href="#ast-file-contents" id="id3">AST File Contents</a><ul>
+<li><a class="reference internal" href="#metadata-block" id="id4">Metadata Block</a></li>
+<li><a class="reference internal" href="#source-manager-block" id="id5">Source Manager Block</a></li>
+<li><a class="reference internal" href="#preprocessor-block" id="id6">Preprocessor Block</a></li>
+<li><a class="reference internal" href="#types-block" id="id7">Types Block</a></li>
+<li><a class="reference internal" href="#declarations-block" id="id8">Declarations Block</a></li>
+<li><a class="reference internal" href="#statements-and-expressions" id="id9">Statements and Expressions</a></li>
+<li><a class="reference internal" href="#pchinternals-ident-table" id="id10">Identifier Table Block</a></li>
+<li><a class="reference internal" href="#method-pool-block" id="id11">Method Pool Block</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#ast-reader-integration-points" id="id12">AST Reader Integration Points</a></li>
+<li><a class="reference internal" href="#chained-precompiled-headers" id="id13">Chained precompiled headers</a></li>
+<li><a class="reference internal" href="#modules" id="id14">Modules</a></li>
+</ul>
+</div>
+<p>This document describes the design and implementation of Clang’s precompiled
+headers (PCH) and modules. If you are interested in the end-user view, please
+see the <a class="reference internal" href="UsersManual.html#usersmanual-precompiled-headers"><em>User’s Manual</em></a>.</p>
+<div class="section" id="using-precompiled-headers-with-clang">
+<h2><a class="toc-backref" href="#id1">Using Precompiled Headers with <tt class="docutils literal"><span class="pre">clang</span></tt></a><a class="headerlink" href="#using-precompiled-headers-with-clang" title="Permalink to this headline">¶</a></h2>
+<p>The Clang compiler frontend, <tt class="docutils literal"><span class="pre">clang</span> <span class="pre">-cc1</span></tt>, supports two command line options
+for generating and using PCH files.</p>
+<p>To generate PCH files using <tt class="docutils literal"><span class="pre">clang</span> <span class="pre">-cc1</span></tt>, use the option <cite>-emit-pch</cite>:</p>
+<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>clang -cc1 test.h -emit-pch -o test.h.pch
+</pre></div>
+</div>
+<p>This option is transparently used by <tt class="docutils literal"><span class="pre">clang</span></tt> when generating PCH files. The
+resulting PCH file contains the serialized form of the compiler’s internal
+representation after it has completed parsing and semantic analysis. The PCH
+file can then be used as a prefix header with the <cite>-include-pch</cite>
+option:</p>
+<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>clang -cc1 -include-pch test.h.pch test.c -o test.s
+</pre></div>
+</div>
+</div>
+<div class="section" id="design-philosophy">
+<h2><a class="toc-backref" href="#id2">Design Philosophy</a><a class="headerlink" href="#design-philosophy" title="Permalink to this headline">¶</a></h2>
+<p>Precompiled headers are meant to improve overall compile times for projects, so
+the design of precompiled headers is entirely driven by performance concerns.
+The use case for precompiled headers is relatively simple: when there is a
+common set of headers that is included in nearly every source file in the
+project, we <em>precompile</em> that bundle of headers into a single precompiled
+header (PCH file). Then, when compiling the source files in the project, we
+load the PCH file first (as a prefix header), which acts as a stand-in for that
+bundle of headers.</p>
+<p>A precompiled header implementation improves performance when:</p>
+<ul class="simple">
+<li>Loading the PCH file is significantly faster than re-parsing the bundle of
+headers stored within the PCH file. Thus, a precompiled header design
+attempts to minimize the cost of reading the PCH file. Ideally, this cost
+should not vary with the size of the precompiled header file.</li>
+<li>The cost of generating the PCH file initially is not so large that it
+counters the per-source-file performance improvement due to eliminating the
+need to parse the bundled headers in the first place. This is particularly
+important on multi-core systems, because PCH file generation serializes the
+build when all compilations require the PCH file to be up-to-date.</li>
+</ul>
+<p>Modules, as implemented in Clang, use the same mechanisms as precompiled
+headers to save a serialized AST file (one per module) and use those AST
+modules. From an implementation standpoint, modules are a generalization of
+precompiled headers, lifting a number of restrictions placed on precompiled
+headers. In particular, there can only be one precompiled header and it must
+be included at the beginning of the translation unit. The extensions to the
+AST file format required for modules are discussed in the section on
+<a class="reference internal" href="#pchinternals-modules"><em>modules</em></a>.</p>
+<p>Clang’s AST files are designed with a compact on-disk representation, which
+minimizes both creation time and the time required to initially load the AST
+file. The AST file itself contains a serialized representation of Clang’s
+abstract syntax trees and supporting data structures, stored using the same
+compressed bitstream as <a class="reference external" href="http://llvm.org/docs/BitCodeFormat.html">LLVM’s bitcode file format</a>.</p>
+<p>Clang’s AST files are loaded “lazily” from disk. When an AST file is initially
+loaded, Clang reads only a small amount of data from the AST file to establish
+where certain important data structures are stored. The amount of data read in
+this initial load is independent of the size of the AST file, such that a
+larger AST file does not lead to longer AST load times. The actual header data
+in the AST file — macros, functions, variables, types, etc. — is loaded
+only when it is referenced from the user’s code, at which point only that
+entity (and those entities it depends on) are deserialized from the AST file.
+With this approach, the cost of using an AST file for a translation unit is
+proportional to the amount of code actually used from the AST file, rather than
+being proportional to the size of the AST file itself.</p>
+<p>When given the <cite>-print-stats</cite> option, Clang produces statistics
+describing how much of the AST file was actually loaded from disk. For a
+simple “Hello, World!” program that includes the Apple <tt class="docutils literal"><span class="pre">Cocoa.h</span></tt> header
+(which is built as a precompiled header), this option illustrates how little of
+the actual precompiled header is required:</p>
+<div class="highlight-none"><div class="highlight"><pre>*** AST File Statistics:
+ 895/39981 source location entries read (2.238563%)
+ 19/15315 types read (0.124061%)
+ 20/82685 declarations read (0.024188%)
+ 154/58070 identifiers read (0.265197%)
+ 0/7260 selectors read (0.000000%)
+ 0/30842 statements read (0.000000%)
+ 4/8400 macros read (0.047619%)
+ 1/4995 lexical declcontexts read (0.020020%)
+ 0/4413 visible declcontexts read (0.000000%)
+ 0/7230 method pool entries read (0.000000%)
+ 0 method pool misses
+</pre></div>
+</div>
+<p>For this small program, only a tiny fraction of the source locations, types,
+declarations, identifiers, and macros were actually deserialized from the
+precompiled header. These statistics can be useful to determine whether the
+AST file implementation can be improved by making more of the implementation
+lazy.</p>
+<p>Precompiled headers can be chained. When you create a PCH while including an
+existing PCH, Clang can create the new PCH by referencing the original file and
+only writing the new data to the new file. For example, you could create a PCH
+out of all the headers that are very commonly used throughout your project, and
+then create a PCH for every single source file in the project that includes the
+code that is specific to that file, so that recompiling the file itself is very
+fast, without duplicating the data from the common headers for every file. The
+mechanisms behind chained precompiled headers are discussed in a <a class="reference internal" href="#pchinternals-chained"><em>later
+section</em></a>.</p>
+</div>
+<div class="section" id="ast-file-contents">
+<h2><a class="toc-backref" href="#id3">AST File Contents</a><a class="headerlink" href="#ast-file-contents" title="Permalink to this headline">¶</a></h2>
+<p>An AST file produced by clang is an object file container with a <tt class="docutils literal"><span class="pre">clangast</span></tt>
+(COFF) or <tt class="docutils literal"><span class="pre">__clangast</span></tt> (ELF and Mach-O) section containing the serialized AST.
+Other target-specific sections in the object file container are used to hold
+debug information for the data types defined in the AST. Tools built on top of
+libclang that do not need debug information may also produce raw AST files that
+only contain the serialized AST.</p>
+<p>The <tt class="docutils literal"><span class="pre">clangast</span></tt> section is organized into several different blocks, each of
+which contains the serialized representation of a part of Clang’s internal
+representation. Each of the blocks corresponds to either a block or a record
+within <a class="reference external" href="http://llvm.org/docs/BitCodeFormat.html">LLVM’s bitstream format</a>.
+The contents of each of these logical blocks are described below.</p>
+<img alt="_images/PCHLayout.png" src="_images/PCHLayout.png" />
+<p>The <tt class="docutils literal"><span class="pre">llvm-objdump</span></tt> utility provides a <tt class="docutils literal"><span class="pre">-raw-clang-ast</span></tt> option to extract the
+binary contents of the AST section from an object file container.</p>
+<p>The <a class="reference external" href="http://llvm.org/docs/CommandGuide/llvm-bcanalyzer.html">llvm-bcanalyzer</a>
+utility can be used to examine the actual structure of the bitstream for the AST
+section. This information can be used both to help understand the structure of
+the AST section and to isolate areas where the AST representation can still be
+optimized, e.g., through the introduction of abbreviations.</p>
+<div class="section" id="metadata-block">
+<h3><a class="toc-backref" href="#id4">Metadata Block</a><a class="headerlink" href="#metadata-block" title="Permalink to this headline">¶</a></h3>
+<p>The metadata block contains several records that provide information about how
+the AST file was built. This metadata is primarily used to validate the use of
+an AST file. For example, a precompiled header built for a 32-bit x86 target
+cannot be used when compiling for a 64-bit x86 target. The metadata block
+contains information about:</p>
+<dl class="docutils">
+<dt>Language options</dt>
+<dd>Describes the particular language dialect used to compile the AST file,
+including major options (e.g., Objective-C support) and more minor options
+(e.g., support for “<tt class="docutils literal"><span class="pre">//</span></tt>” comments). The contents of this record correspond to
+the <tt class="docutils literal"><span class="pre">LangOptions</span></tt> class.</dd>
+<dt>Target architecture</dt>
+<dd>The target triple that describes the architecture, platform, and ABI for
+which the AST file was generated, e.g., <tt class="docutils literal"><span class="pre">i386-apple-darwin9</span></tt>.</dd>
+<dt>AST version</dt>
+<dd>The major and minor version numbers of the AST file format. Changes in the
+minor version number should not affect backward compatibility, while changes
+in the major version number imply that a newer compiler cannot read an older
+precompiled header (and vice-versa).</dd>
+<dt>Original file name</dt>
+<dd>The full path of the header that was used to generate the AST file.</dd>
+<dt>Predefines buffer</dt>
+<dd>Although not explicitly stored as part of the metadata, the predefines buffer
+is used in the validation of the AST file. The predefines buffer itself
+contains code generated by the compiler to initialize the preprocessor state
+according to the current target, platform, and command-line options. For
+example, the predefines buffer will contain “<tt class="docutils literal"><span class="pre">#define</span> <span class="pre">__STDC__</span> <span class="pre">1</span></tt>” when we
+are compiling C without Microsoft extensions. The predefines buffer itself
+is stored within the <a class="reference internal" href="#pchinternals-sourcemgr"><em>Source Manager Block</em></a>, but its contents are
+verified along with the rest of the metadata.</dd>
+</dl>
+<p>A chained PCH file (that is, one that references another PCH) and a module
+(which may import other modules) have additional metadata containing the list
+of all AST files that this AST file depends on. Each of those files will be
+loaded along with this AST file.</p>
+<p>For chained precompiled headers, the language options, target architecture and
+predefines buffer data is taken from the end of the chain, since they have to
+match anyway.</p>
+</div>
+<div class="section" id="source-manager-block">
+<span id="pchinternals-sourcemgr"></span><h3><a class="toc-backref" href="#id5">Source Manager Block</a><a class="headerlink" href="#source-manager-block" title="Permalink to this headline">¶</a></h3>
+<p>The source manager block contains the serialized representation of Clang’s
+<a class="reference internal" href="InternalsManual.html#sourcemanager"><em>SourceManager</em></a> class, which handles the mapping from
+source locations (as represented in Clang’s abstract syntax tree) into actual
+column/line positions within a source file or macro instantiation. The AST
+file’s representation of the source manager also includes information about all
+of the headers that were (transitively) included when building the AST file.</p>
+<p>The bulk of the source manager block is dedicated to information about the
+various files, buffers, and macro instantiations into which a source location
+can refer. Each of these is referenced by a numeric “file ID”, which is a
+unique number (allocated starting at 1) stored in the source location. Clang
+serializes the information for each kind of file ID, along with an index that
+maps file IDs to the position within the AST file where the information about
+that file ID is stored. The data associated with a file ID is loaded only when
+required by the front end, e.g., to emit a diagnostic that includes a macro
+instantiation history inside the header itself.</p>
+<p>The source manager block also contains information about all of the headers
+that were included when building the AST file. This includes information about
+the controlling macro for the header (e.g., when the preprocessor identified
+that the contents of the header dependent on a macro like
+<tt class="docutils literal"><span class="pre">LLVM_CLANG_SOURCEMANAGER_H</span></tt>).</p>
+</div>
+<div class="section" id="preprocessor-block">
+<span id="pchinternals-preprocessor"></span><h3><a class="toc-backref" href="#id6">Preprocessor Block</a><a class="headerlink" href="#preprocessor-block" title="Permalink to this headline">¶</a></h3>
+<p>The preprocessor block contains the serialized representation of the
+preprocessor. Specifically, it contains all of the macros that have been
+defined by the end of the header used to build the AST file, along with the
+token sequences that comprise each macro. The macro definitions are only read
+from the AST file when the name of the macro first occurs in the program. This
+lazy loading of macro definitions is triggered by lookups into the
+<a class="reference internal" href="#pchinternals-ident-table"><em>identifier table</em></a>.</p>
+</div>
+<div class="section" id="types-block">
+<span id="pchinternals-types"></span><h3><a class="toc-backref" href="#id7">Types Block</a><a class="headerlink" href="#types-block" title="Permalink to this headline">¶</a></h3>
+<p>The types block contains the serialized representation of all of the types
+referenced in the translation unit. Each Clang type node (<tt class="docutils literal"><span class="pre">PointerType</span></tt>,
+<tt class="docutils literal"><span class="pre">FunctionProtoType</span></tt>, etc.) has a corresponding record type in the AST file.
+When types are deserialized from the AST file, the data within the record is
+used to reconstruct the appropriate type node using the AST context.</p>
+<p>Each type has a unique type ID, which is an integer that uniquely identifies
+that type. Type ID 0 represents the NULL type, type IDs less than
+<tt class="docutils literal"><span class="pre">NUM_PREDEF_TYPE_IDS</span></tt> represent predefined types (<tt class="docutils literal"><span class="pre">void</span></tt>, <tt class="docutils literal"><span class="pre">float</span></tt>, etc.),
+while other “user-defined” type IDs are assigned consecutively from
+<tt class="docutils literal"><span class="pre">NUM_PREDEF_TYPE_IDS</span></tt> upward as the types are encountered. The AST file has
+an associated mapping from the user-defined types block to the location within
+the types block where the serialized representation of that type resides,
+enabling lazy deserialization of types. When a type is referenced from within
+the AST file, that reference is encoded using the type ID shifted left by 3
+bits. The lower three bits are used to represent the <tt class="docutils literal"><span class="pre">const</span></tt>, <tt class="docutils literal"><span class="pre">volatile</span></tt>,
+and <tt class="docutils literal"><span class="pre">restrict</span></tt> qualifiers, as in Clang’s <a class="reference internal" href="InternalsManual.html#qualtype"><em>QualType</em></a> class.</p>
+</div>
+<div class="section" id="declarations-block">
+<span id="pchinternals-decls"></span><h3><a class="toc-backref" href="#id8">Declarations Block</a><a class="headerlink" href="#declarations-block" title="Permalink to this headline">¶</a></h3>
+<p>The declarations block contains the serialized representation of all of the
+declarations referenced in the translation unit. Each Clang declaration node
+(<tt class="docutils literal"><span class="pre">VarDecl</span></tt>, <tt class="docutils literal"><span class="pre">FunctionDecl</span></tt>, etc.) has a corresponding record type in the
+AST file. When declarations are deserialized from the AST file, the data
+within the record is used to build and populate a new instance of the
+corresponding <tt class="docutils literal"><span class="pre">Decl</span></tt> node. As with types, each declaration node has a
+numeric ID that is used to refer to that declaration within the AST file. In
+addition, a lookup table provides a mapping from that numeric ID to the offset
+within the precompiled header where that declaration is described.</p>
+<p>Declarations in Clang’s abstract syntax trees are stored hierarchically. At
+the top of the hierarchy is the translation unit (<tt class="docutils literal"><span class="pre">TranslationUnitDecl</span></tt>),
+which contains all of the declarations in the translation unit but is not
+actually written as a specific declaration node. Its child declarations (such
+as functions or struct types) may also contain other declarations inside them,
+and so on. Within Clang, each declaration is stored within a <a class="reference internal" href="InternalsManual.html#declcontext"><em>declaration
+context</em></a>, as represented by the <tt class="docutils literal"><span class="pre">DeclContext</span></tt> class.
+Declaration contexts provide the mechanism to perform name lookup within a
+given declaration (e.g., find the member named <tt class="docutils literal"><span class="pre">x</span></tt> in a structure) and
+iterate over the declarations stored within a context (e.g., iterate over all
+of the fields of a structure for structure layout).</p>
+<p>In Clang’s AST file format, deserializing a declaration that is a
+<tt class="docutils literal"><span class="pre">DeclContext</span></tt> is a separate operation from deserializing all of the
+declarations stored within that declaration context. Therefore, Clang will
+deserialize the translation unit declaration without deserializing the
+declarations within that translation unit. When required, the declarations
+stored within a declaration context will be deserialized. There are two
+representations of the declarations within a declaration context, which
+correspond to the name-lookup and iteration behavior described above:</p>
+<ul class="simple">
+<li>When the front end performs name lookup to find a name <tt class="docutils literal"><span class="pre">x</span></tt> within a given
+declaration context (for example, during semantic analysis of the expression
+<tt class="docutils literal"><span class="pre">p->x</span></tt>, where <tt class="docutils literal"><span class="pre">p</span></tt>‘s type is defined in the precompiled header), Clang
+refers to an on-disk hash table that maps from the names within that
+declaration context to the declaration IDs that represent each visible
+declaration with that name. The actual declarations will then be
+deserialized to provide the results of name lookup.</li>
+<li>When the front end performs iteration over all of the declarations within a
+declaration context, all of those declarations are immediately
+de-serialized. For large declaration contexts (e.g., the translation unit),
+this operation is expensive; however, large declaration contexts are not
+traversed in normal compilation, since such a traversal is unnecessary.
+However, it is common for the code generator and semantic analysis to
+traverse declaration contexts for structs, classes, unions, and
+enumerations, although those contexts contain relatively few declarations in
+the common case.</li>
+</ul>
+</div>
+<div class="section" id="statements-and-expressions">
+<h3><a class="toc-backref" href="#id9">Statements and Expressions</a><a class="headerlink" href="#statements-and-expressions" title="Permalink to this headline">¶</a></h3>
+<p>Statements and expressions are stored in the AST file in both the <a class="reference internal" href="#pchinternals-types"><em>types</em></a> and the <a class="reference internal" href="#pchinternals-decls"><em>declarations</em></a> blocks,
+because every statement or expression will be associated with either a type or
+declaration. The actual statement and expression records are stored
+immediately following the declaration or type that owns the statement or
+expression. For example, the statement representing the body of a function
+will be stored directly following the declaration of the function.</p>
+<p>As with types and declarations, each statement and expression kind in Clang’s
+abstract syntax tree (<tt class="docutils literal"><span class="pre">ForStmt</span></tt>, <tt class="docutils literal"><span class="pre">CallExpr</span></tt>, etc.) has a corresponding
+record type in the AST file, which contains the serialized representation of
+that statement or expression. Each substatement or subexpression within an
+expression is stored as a separate record (which keeps most records to a fixed
+size). Within the AST file, the subexpressions of an expression are stored, in
+reverse order, prior to the expression that owns those expression, using a form
+of <a class="reference external" href="http://en.wikipedia.org/wiki/Reverse_Polish_notation">Reverse Polish Notation</a>. For example, an
+expression <tt class="docutils literal"><span class="pre">3</span> <span class="pre">-</span> <span class="pre">4</span> <span class="pre">+</span> <span class="pre">5</span></tt> would be represented as follows:</p>
+<table border="1" class="docutils">
+<colgroup>
+<col width="100%" />
+</colgroup>
+<tbody valign="top">
+<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">IntegerLiteral(5)</span></tt></td>
+</tr>
+<tr class="row-even"><td><tt class="docutils literal"><span class="pre">IntegerLiteral(4)</span></tt></td>
+</tr>
+<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">IntegerLiteral(3)</span></tt></td>
+</tr>
+<tr class="row-even"><td><tt class="docutils literal"><span class="pre">IntegerLiteral(-)</span></tt></td>
+</tr>
+<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">IntegerLiteral(+)</span></tt></td>
+</tr>
+<tr class="row-even"><td><tt class="docutils literal"><span class="pre">STOP</span></tt></td>
+</tr>
+</tbody>
+</table>
+<p>When reading this representation, Clang evaluates each expression record it
+encounters, builds the appropriate abstract syntax tree node, and then pushes
+that expression on to a stack. When a record contains <em>N</em> subexpressions —
+<tt class="docutils literal"><span class="pre">BinaryOperator</span></tt> has two of them — those expressions are popped from the
+top of the stack. The special STOP code indicates that we have reached the end
+of a serialized expression or statement; other expression or statement records
+may follow, but they are part of a different expression.</p>
+</div>
+<div class="section" id="pchinternals-ident-table">
+<span id="identifier-table-block"></span><h3><a class="toc-backref" href="#id10">Identifier Table Block</a><a class="headerlink" href="#pchinternals-ident-table" title="Permalink to this headline">¶</a></h3>
+<p>The identifier table block contains an on-disk hash table that maps each
+identifier mentioned within the AST file to the serialized representation of
+the identifier’s information (e.g, the <tt class="docutils literal"><span class="pre">IdentifierInfo</span></tt> structure). The
+serialized representation contains:</p>
+<ul class="simple">
+<li>The actual identifier string.</li>
+<li>Flags that describe whether this identifier is the name of a built-in, a
+poisoned identifier, an extension token, or a macro.</li>
+<li>If the identifier names a macro, the offset of the macro definition within
+the <a class="reference internal" href="#pchinternals-preprocessor"><em>Preprocessor Block</em></a>.</li>
+<li>If the identifier names one or more declarations visible from translation
+unit scope, the <a class="reference internal" href="#pchinternals-decls"><em>declaration IDs</em></a> of these
+declarations.</li>
+</ul>
+<p>When an AST file is loaded, the AST file reader mechanism introduces itself
+into the identifier table as an external lookup source. Thus, when the user
+program refers to an identifier that has not yet been seen, Clang will perform
+a lookup into the identifier table. If an identifier is found, its contents
+(macro definitions, flags, top-level declarations, etc.) will be deserialized,
+at which point the corresponding <tt class="docutils literal"><span class="pre">IdentifierInfo</span></tt> structure will have the
+same contents it would have after parsing the headers in the AST file.</p>
+<p>Within the AST file, the identifiers used to name declarations are represented
+with an integral value. A separate table provides a mapping from this integral
+value (the identifier ID) to the location within the on-disk hash table where
+that identifier is stored. This mapping is used when deserializing the name of
+a declaration, the identifier of a token, or any other construct in the AST
+file that refers to a name.</p>
+</div>
+<div class="section" id="method-pool-block">
+<span id="pchinternals-method-pool"></span><h3><a class="toc-backref" href="#id11">Method Pool Block</a><a class="headerlink" href="#method-pool-block" title="Permalink to this headline">¶</a></h3>
+<p>The method pool block is represented as an on-disk hash table that serves two
+purposes: it provides a mapping from the names of Objective-C selectors to the
+set of Objective-C instance and class methods that have that particular
+selector (which is required for semantic analysis in Objective-C) and also
+stores all of the selectors used by entities within the AST file. The design
+of the method pool is similar to that of the <a class="reference internal" href="#pchinternals-ident-table"><em>identifier table</em></a>: the first time a particular selector is formed
+during the compilation of the program, Clang will search in the on-disk hash
+table of selectors; if found, Clang will read the Objective-C methods
+associated with that selector into the appropriate front-end data structure
+(<tt class="docutils literal"><span class="pre">Sema::InstanceMethodPool</span></tt> and <tt class="docutils literal"><span class="pre">Sema::FactoryMethodPool</span></tt> for instance and
+class methods, respectively).</p>
+<p>As with identifiers, selectors are represented by numeric values within the AST
+file. A separate index maps these numeric selector values to the offset of the
+selector within the on-disk hash table, and will be used when de-serializing an
+Objective-C method declaration (or other Objective-C construct) that refers to
+the selector.</p>
+</div>
+</div>
+<div class="section" id="ast-reader-integration-points">
+<h2><a class="toc-backref" href="#id12">AST Reader Integration Points</a><a class="headerlink" href="#ast-reader-integration-points" title="Permalink to this headline">¶</a></h2>
+<p>The “lazy” deserialization behavior of AST files requires their integration
+into several completely different submodules of Clang. For example, lazily
+deserializing the declarations during name lookup requires that the name-lookup
+routines be able to query the AST file to find entities stored there.</p>
+<p>For each Clang data structure that requires direct interaction with the AST
+reader logic, there is an abstract class that provides the interface between
+the two modules. The <tt class="docutils literal"><span class="pre">ASTReader</span></tt> class, which handles the loading of an AST
+file, inherits from all of these abstract classes to provide lazy
+deserialization of Clang’s data structures. <tt class="docutils literal"><span class="pre">ASTReader</span></tt> implements the
+following abstract classes:</p>
+<dl class="docutils">
+<dt><tt class="docutils literal"><span class="pre">ExternalSLocEntrySource</span></tt></dt>
+<dd>This abstract interface is associated with the <tt class="docutils literal"><span class="pre">SourceManager</span></tt> class, and
+is used whenever the <a class="reference internal" href="#pchinternals-sourcemgr"><em>source manager</em></a> needs to
+load the details of a file, buffer, or macro instantiation.</dd>
+<dt><tt class="docutils literal"><span class="pre">IdentifierInfoLookup</span></tt></dt>
+<dd>This abstract interface is associated with the <tt class="docutils literal"><span class="pre">IdentifierTable</span></tt> class, and
+is used whenever the program source refers to an identifier that has not yet
+been seen. In this case, the AST reader searches for this identifier within
+its <a class="reference internal" href="#pchinternals-ident-table"><em>identifier table</em></a> to load any top-level
+declarations or macros associated with that identifier.</dd>
+<dt><tt class="docutils literal"><span class="pre">ExternalASTSource</span></tt></dt>
+<dd>This abstract interface is associated with the <tt class="docutils literal"><span class="pre">ASTContext</span></tt> class, and is
+used whenever the abstract syntax tree nodes need to loaded from the AST
+file. It provides the ability to de-serialize declarations and types
+identified by their numeric values, read the bodies of functions when
+required, and read the declarations stored within a declaration context
+(either for iteration or for name lookup).</dd>
+<dt><tt class="docutils literal"><span class="pre">ExternalSemaSource</span></tt></dt>
+<dd>This abstract interface is associated with the <tt class="docutils literal"><span class="pre">Sema</span></tt> class, and is used
+whenever semantic analysis needs to read information from the <a class="reference internal" href="#pchinternals-method-pool"><em>global
+method pool</em></a>.</dd>
+</dl>
+</div>
+<div class="section" id="chained-precompiled-headers">
+<span id="pchinternals-chained"></span><h2><a class="toc-backref" href="#id13">Chained precompiled headers</a><a class="headerlink" href="#chained-precompiled-headers" title="Permalink to this headline">¶</a></h2>
+<p>Chained precompiled headers were initially intended to improve the performance
+of IDE-centric operations such as syntax highlighting and code completion while
+a particular source file is being edited by the user. To minimize the amount
+of reparsing required after a change to the file, a form of precompiled header
+— called a precompiled <em>preamble</em> — is automatically generated by parsing
+all of the headers in the source file, up to and including the last
+<tt class="docutils literal"><span class="pre">#include</span></tt>. When only the source file changes (and none of the headers it
+depends on), reparsing of that source file can use the precompiled preamble and
+start parsing after the <tt class="docutils literal"><span class="pre">#include</span></tt>s, so parsing time is proportional to the
+size of the source file (rather than all of its includes). However, the
+compilation of that translation unit may already use a precompiled header: in
+this case, Clang will create the precompiled preamble as a chained precompiled
+header that refers to the original precompiled header. This drastically
+reduces the time needed to serialize the precompiled preamble for use in
+reparsing.</p>
+<p>Chained precompiled headers get their name because each precompiled header can
+depend on one other precompiled header, forming a chain of dependencies. A
+translation unit will then include the precompiled header that starts the chain
+(i.e., nothing depends on it). This linearity of dependencies is important for
+the semantic model of chained precompiled headers, because the most-recent
+precompiled header can provide information that overrides the information
+provided by the precompiled headers it depends on, just like a header file
+<tt class="docutils literal"><span class="pre">B.h</span></tt> that includes another header <tt class="docutils literal"><span class="pre">A.h</span></tt> can modify the state produced by
+parsing <tt class="docutils literal"><span class="pre">A.h</span></tt>, e.g., by <tt class="docutils literal"><span class="pre">#undef</span></tt>‘ing a macro defined in <tt class="docutils literal"><span class="pre">A.h</span></tt>.</p>
+<p>There are several ways in which chained precompiled headers generalize the AST
+file model:</p>
+<dl class="docutils">
+<dt>Numbering of IDs</dt>
+<dd>Many different kinds of entities — identifiers, declarations, types, etc.
+— have ID numbers that start at 1 or some other predefined constant and
+grow upward. Each precompiled header records the maximum ID number it has
+assigned in each category. Then, when a new precompiled header is generated
+that depends on (chains to) another precompiled header, it will start
+counting at the next available ID number. This way, one can determine, given
+an ID number, which AST file actually contains the entity.</dd>
+<dt>Name lookup</dt>
+<dd>When writing a chained precompiled header, Clang attempts to write only
+information that has changed from the precompiled header on which it is
+based. This changes the lookup algorithm for the various tables, such as the
+<a class="reference internal" href="#pchinternals-ident-table"><em>identifier table</em></a>: the search starts at the
+most-recent precompiled header. If no entry is found, lookup then proceeds
+to the identifier table in the precompiled header it depends on, and so one.
+Once a lookup succeeds, that result is considered definitive, overriding any
+results from earlier precompiled headers.</dd>
+<dt>Update records</dt>
+<dd>There are various ways in which a later precompiled header can modify the
+entities described in an earlier precompiled header. For example, later
+precompiled headers can add entries into the various name-lookup tables for
+the translation unit or namespaces, or add new categories to an Objective-C
+class. Each of these updates is captured in an “update record” that is
+stored in the chained precompiled header file and will be loaded along with
+the original entity.</dd>
+</dl>
+</div>
+<div class="section" id="modules">
+<span id="pchinternals-modules"></span><h2><a class="toc-backref" href="#id14">Modules</a><a class="headerlink" href="#modules" title="Permalink to this headline">¶</a></h2>
+<p>Modules generalize the chained precompiled header model yet further, from a
+linear chain of precompiled headers to an arbitrary directed acyclic graph
+(DAG) of AST files. All of the same techniques used to make chained
+precompiled headers work — ID number, name lookup, update records — are
+shared with modules. However, the DAG nature of modules introduce a number of
+additional complications to the model:</p>
+<dl class="docutils">
+<dt>Numbering of IDs</dt>
+<dd>The simple, linear numbering scheme used in chained precompiled headers falls
+apart with the module DAG, because different modules may end up with
+different numbering schemes for entities they imported from common shared
+modules. To account for this, each module file provides information about
+which modules it depends on and which ID numbers it assigned to the entities
+in those modules, as well as which ID numbers it took for its own new
+entities. The AST reader then maps these “local” ID numbers into a “global”
+ID number space for the current translation unit, providing a 1-1 mapping
+between entities (in whatever AST file they inhabit) and global ID numbers.
+If that translation unit is then serialized into an AST file, this mapping
+will be stored for use when the AST file is imported.</dd>
+<dt>Declaration merging</dt>
+<dd>It is possible for a given entity (from the language’s perspective) to be
+declared multiple times in different places. For example, two different
+headers can have the declaration of <tt class="docutils literal"><span class="pre">printf</span></tt> or could forward-declare
+<tt class="docutils literal"><span class="pre">struct</span> <span class="pre">stat</span></tt>. If each of those headers is included in a module, and some
+third party imports both of those modules, there is a potentially serious
+problem: name lookup for <tt class="docutils literal"><span class="pre">printf</span></tt> or <tt class="docutils literal"><span class="pre">struct</span> <span class="pre">stat</span></tt> will find both
+declarations, but the AST nodes are unrelated. This would result in a
+compilation error, due to an ambiguity in name lookup. Therefore, the AST
+reader performs declaration merging according to the appropriate language
+semantics, ensuring that the two disjoint declarations are merged into a
+single redeclaration chain (with a common canonical declaration), so that it
+is as if one of the headers had been included before the other.</dd>
+<dt>Name Visibility</dt>
+<dd>Modules allow certain names that occur during module creation to be “hidden”,
+so that they are not part of the public interface of the module and are not
+visible to its clients. The AST reader maintains a “visible” bit on various
+AST nodes (declarations, macros, etc.) to indicate whether that particular
+AST node is currently visible; the various name lookup mechanisms in Clang
+inspect the visible bit to determine whether that entity, which is still in
+the AST (because other, visible AST nodes may depend on it), can actually be
+found by name lookup. When a new (sub)module is imported, it may make
+existing, non-visible, already-deserialized AST nodes visible; it is the
+responsibility of the AST reader to find and update these AST nodes when it
+is notified of the import.</dd>
+</dl>
+</div>
+</div>
+
+
+ </div>
+ <div class="bottomnav">
+
+ <p>
+ « <a href="PTHInternals.html">Pretokenized Headers (PTH)</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="ItaniumMangleAbiTags.html">ABI tags</a> »
+ </p>
+
+ </div>
+
+ <div class="footer">
+ © Copyright 2007-2017, The Clang Team.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/4.0.0/tools/clang/docs/PTHInternals.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/4.0.0/tools/clang/docs/PTHInternals.html?rev=297634&view=auto
==============================================================================
--- www-releases/trunk/4.0.0/tools/clang/docs/PTHInternals.html (added)
+++ www-releases/trunk/4.0.0/tools/clang/docs/PTHInternals.html Mon Mar 13 11:30:12 2017
@@ -0,0 +1,214 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>Pretokenized Headers (PTH) — Clang 4 documentation</title>
+
+ <link rel="stylesheet" href="_static/haiku.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: './',
+ VERSION: '4',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+ <link rel="top" title="Clang 4 documentation" href="index.html" />
+ <link rel="next" title="Precompiled Header and Modules Internals" href="PCHInternals.html" />
+ <link rel="prev" title="Driver Design & Internals" href="DriverInternals.html" />
+ </head>
+ <body>
+ <div class="header"><h1 class="heading"><a href="index.html">
+ <span>Clang 4 documentation</span></a></h1>
+ <h2 class="heading"><span>Pretokenized Headers (PTH)</span></h2>
+ </div>
+ <div class="topnav">
+
+ <p>
+ « <a href="DriverInternals.html">Driver Design & Internals</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="PCHInternals.html">Precompiled Header and Modules Internals</a> »
+ </p>
+
+ </div>
+ <div class="content">
+
+
+ <div class="section" id="pretokenized-headers-pth">
+<h1>Pretokenized Headers (PTH)<a class="headerlink" href="#pretokenized-headers-pth" title="Permalink to this headline">¶</a></h1>
+<p>This document first describes the low-level interface for using PTH and
+then briefly elaborates on its design and implementation. If you are
+interested in the end-user view, please see the <a class="reference internal" href="UsersManual.html#usersmanual-precompiled-headers"><em>User’s Manual</em></a>.</p>
+<div class="section" id="using-pretokenized-headers-with-clang-low-level-interface">
+<h2>Using Pretokenized Headers with <tt class="docutils literal"><span class="pre">clang</span></tt> (Low-level Interface)<a class="headerlink" href="#using-pretokenized-headers-with-clang-low-level-interface" title="Permalink to this headline">¶</a></h2>
+<p>The Clang compiler frontend, <tt class="docutils literal"><span class="pre">clang</span> <span class="pre">-cc1</span></tt>, supports three command line
+options for generating and using PTH files.</p>
+<p>To generate PTH files using <tt class="docutils literal"><span class="pre">clang</span> <span class="pre">-cc1</span></tt>, use the option <tt class="docutils literal"><span class="pre">-emit-pth</span></tt>:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> clang -cc1 test.h -emit-pth -o test.h.pth
+</pre></div>
+</div>
+<p>This option is transparently used by <tt class="docutils literal"><span class="pre">clang</span></tt> when generating PTH
+files. Similarly, PTH files can be used as prefix headers using the
+<tt class="docutils literal"><span class="pre">-include-pth</span></tt> option:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> clang -cc1 -include-pth test.h.pth test.c -o test.s
+</pre></div>
+</div>
+<p>Alternatively, Clang’s PTH files can be used as a raw “token-cache” (or
+“content” cache) of the source included by the original header file.
+This means that the contents of the PTH file are searched as substitutes
+for <em>any</em> source files that are used by <tt class="docutils literal"><span class="pre">clang</span> <span class="pre">-cc1</span></tt> to process a
+source file. This is done by specifying the <tt class="docutils literal"><span class="pre">-token-cache</span></tt> option:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> cat test.h
+<span class="gp">#</span>include <stdio.h>
+<span class="gp">$</span> clang -cc1 -emit-pth test.h -o test.h.pth
+<span class="gp">$</span> cat test.c
+<span class="gp">#</span>include <span class="s2">"test.h"</span>
+<span class="gp">$</span> clang -cc1 test.c -o <span class="nb">test</span> -token-cache test.h.pth
+</pre></div>
+</div>
+<p>In this example the contents of <tt class="docutils literal"><span class="pre">stdio.h</span></tt> (and the files it includes)
+will be retrieved from <tt class="docutils literal"><span class="pre">test.h.pth</span></tt>, as the PTH file is being used in
+this case as a raw cache of the contents of <tt class="docutils literal"><span class="pre">test.h</span></tt>. This is a
+low-level interface used to both implement the high-level PTH interface
+as well as to provide alternative means to use PTH-style caching.</p>
+</div>
+<div class="section" id="pth-design-and-implementation">
+<h2>PTH Design and Implementation<a class="headerlink" href="#pth-design-and-implementation" title="Permalink to this headline">¶</a></h2>
+<p>Unlike GCC’s precompiled headers, which cache the full ASTs and
+preprocessor state of a header file, Clang’s pretokenized header files
+mainly cache the raw lexer <em>tokens</em> that are needed to segment the
+stream of characters in a source file into keywords, identifiers, and
+operators. Consequently, PTH serves to mainly directly speed up the
+lexing and preprocessing of a source file, while parsing and
+type-checking must be completely redone every time a PTH file is used.</p>
+<div class="section" id="basic-design-tradeoffs">
+<h3>Basic Design Tradeoffs<a class="headerlink" href="#basic-design-tradeoffs" title="Permalink to this headline">¶</a></h3>
+<p>In the long term there are plans to provide an alternate PCH
+implementation for Clang that also caches the work for parsing and type
+checking the contents of header files. The current implementation of PCH
+in Clang as pretokenized header files was motivated by the following
+factors:</p>
+<dl class="docutils">
+<dt><strong>Language independence</strong></dt>
+<dd>PTH files work with any language that
+Clang’s lexer can handle, including C, Objective-C, and (in the early
+stages) C++. This means development on language features at the
+parsing level or above (which is basically almost all interesting
+pieces) does not require PTH to be modified.</dd>
+<dt><strong>Simple design</strong></dt>
+<dd>Relatively speaking, PTH has a simple design and
+implementation, making it easy to test. Further, because the
+machinery for PTH resides at the lower-levels of the Clang library
+stack it is fairly straightforward to profile and optimize.</dd>
+</dl>
+<p>Further, compared to GCC’s PCH implementation (which is the dominate
+precompiled header file implementation that Clang can be directly
+compared against) the PTH design in Clang yields several attractive
+features:</p>
+<dl class="docutils">
+<dt><strong>Architecture independence</strong></dt>
+<dd><p class="first">In contrast to GCC’s PCH files (and
+those of several other compilers), Clang’s PTH files are architecture
+independent, requiring only a single PTH file when building a
+program for multiple architectures.</p>
+<p class="last">For example, on Mac OS X one may wish to compile a “universal binary”
+that runs on PowerPC, 32-bit Intel (i386), and 64-bit Intel
+architectures. In contrast, GCC requires a PCH file for each
+architecture, as the definitions of types in the AST are
+architecture-specific. Since a Clang PTH file essentially represents
+a lexical cache of header files, a single PTH file can be safely used
+when compiling for multiple architectures. This can also reduce
+compile times because only a single PTH file needs to be generated
+during a build instead of several.</p>
+</dd>
+<dt><strong>Reduced memory pressure</strong></dt>
+<dd>Similar to GCC, Clang reads PTH files
+via the use of memory mapping (i.e., <tt class="docutils literal"><span class="pre">mmap</span></tt>). Clang, however,
+memory maps PTH files as read-only, meaning that multiple invocations
+of <tt class="docutils literal"><span class="pre">clang</span> <span class="pre">-cc1</span></tt> can share the same pages in memory from a
+memory-mapped PTH file. In comparison, GCC also memory maps its PCH
+files but also modifies those pages in memory, incurring the
+copy-on-write costs. The read-only nature of PTH can greatly reduce
+memory pressure for builds involving multiple cores, thus improving
+overall scalability.</dd>
+<dt><strong>Fast generation</strong></dt>
+<dd>PTH files can be generated in a small fraction
+of the time needed to generate GCC’s PCH files. Since PTH/PCH
+generation is a serial operation that typically blocks progress
+during a build, faster generation time leads to improved processor
+utilization with parallel builds on multicore machines.</dd>
+</dl>
+<p>Despite these strengths, PTH’s simple design suffers some algorithmic
+handicaps compared to other PCH strategies such as those used by GCC.
+While PTH can greatly speed up the processing time of a header file, the
+amount of work required to process a header file is still roughly linear
+in the size of the header file. In contrast, the amount of work done by
+GCC to process a precompiled header is (theoretically) constant (the
+ASTs for the header are literally memory mapped into the compiler). This
+means that only the pieces of the header file that are referenced by the
+source file including the header are the only ones the compiler needs to
+process during actual compilation. While GCC’s particular implementation
+of PCH mitigates some of these algorithmic strengths via the use of
+copy-on-write pages, the approach itself can fundamentally dominate at
+an algorithmic level, especially when one considers header files of
+arbitrary size.</p>
+<p>There is also a PCH implementation for Clang based on the lazy
+deserialization of ASTs. This approach theoretically has the same
+constant-time algorithmic advantages just mentioned but also retains some
+of the strengths of PTH such as reduced memory pressure (ideal for
+multi-core builds).</p>
+</div>
+<div class="section" id="internal-pth-optimizations">
+<h3>Internal PTH Optimizations<a class="headerlink" href="#internal-pth-optimizations" title="Permalink to this headline">¶</a></h3>
+<p>While the main optimization employed by PTH is to reduce lexing time of
+header files by caching pre-lexed tokens, PTH also employs several other
+optimizations to speed up the processing of header files:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">stat</span></tt> caching: PTH files cache information obtained via calls to
+<tt class="docutils literal"><span class="pre">stat</span></tt> that <tt class="docutils literal"><span class="pre">clang</span> <span class="pre">-cc1</span></tt> uses to resolve which files are included
+by <tt class="docutils literal"><span class="pre">#include</span></tt> directives. This greatly reduces the overhead
+involved in context-switching to the kernel to resolve included
+files.</li>
+<li>Fast skipping of <tt class="docutils literal"><span class="pre">#ifdef</span></tt> ... <tt class="docutils literal"><span class="pre">#endif</span></tt> chains: PTH files
+record the basic structure of nested preprocessor blocks. When the
+condition of the preprocessor block is false, all of its tokens are
+immediately skipped instead of requiring them to be handled by
+Clang’s preprocessor.</li>
+</ul>
+</div>
+</div>
+</div>
+
+
+ </div>
+ <div class="bottomnav">
+
+ <p>
+ « <a href="DriverInternals.html">Driver Design & Internals</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="PCHInternals.html">Precompiled Header and Modules Internals</a> »
+ </p>
+
+ </div>
+
+ <div class="footer">
+ © Copyright 2007-2017, The Clang Team.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/4.0.0/tools/clang/docs/RAVFrontendAction.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/4.0.0/tools/clang/docs/RAVFrontendAction.html?rev=297634&view=auto
==============================================================================
--- www-releases/trunk/4.0.0/tools/clang/docs/RAVFrontendAction.html (added)
+++ www-releases/trunk/4.0.0/tools/clang/docs/RAVFrontendAction.html Mon Mar 13 11:30:12 2017
@@ -0,0 +1,266 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>How to write RecursiveASTVisitor based ASTFrontendActions. — Clang 4 documentation</title>
+
+ <link rel="stylesheet" href="_static/haiku.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: './',
+ VERSION: '4',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+ <link rel="top" title="Clang 4 documentation" href="index.html" />
+ <link rel="next" title="Tutorial for building tools using LibTooling and LibASTMatchers" href="LibASTMatchersTutorial.html" />
+ <link rel="prev" title="Clang Plugins" href="ClangPlugins.html" />
+ </head>
+ <body>
+ <div class="header"><h1 class="heading"><a href="index.html">
+ <span>Clang 4 documentation</span></a></h1>
+ <h2 class="heading"><span>How to write RecursiveASTVisitor based ASTFrontendActions.</span></h2>
+ </div>
+ <div class="topnav">
+
+ <p>
+ « <a href="ClangPlugins.html">Clang Plugins</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="LibASTMatchersTutorial.html">Tutorial for building tools using LibTooling and LibASTMatchers</a> »
+ </p>
+
+ </div>
+ <div class="content">
+
+
+ <div class="section" id="how-to-write-recursiveastvisitor-based-astfrontendactions">
+<h1>How to write RecursiveASTVisitor based ASTFrontendActions.<a class="headerlink" href="#how-to-write-recursiveastvisitor-based-astfrontendactions" title="Permalink to this headline">¶</a></h1>
+<div class="section" id="introduction">
+<h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>In this tutorial you will learn how to create a FrontendAction that uses
+a RecursiveASTVisitor to find CXXRecordDecl AST nodes with a specified
+name.</p>
+</div>
+<div class="section" id="creating-a-frontendaction">
+<h2>Creating a FrontendAction<a class="headerlink" href="#creating-a-frontendaction" title="Permalink to this headline">¶</a></h2>
+<p>When writing a clang based tool like a Clang Plugin or a standalone tool
+based on LibTooling, the common entry point is the FrontendAction.
+FrontendAction is an interface that allows execution of user specific
+actions as part of the compilation. To run tools over the AST clang
+provides the convenience interface ASTFrontendAction, which takes care
+of executing the action. The only part left is to implement the
+CreateASTConsumer method that returns an ASTConsumer per translation
+unit.</p>
+<div class="highlight-python"><div class="highlight"><pre>class FindNamedClassAction : public clang::ASTFrontendAction {
+public:
+ virtual std::unique_ptr<clang::ASTConsumer> CreateASTConsumer(
+ clang::CompilerInstance &Compiler, llvm::StringRef InFile) {
+ return std::unique_ptr<clang::ASTConsumer>(
+ new FindNamedClassConsumer);
+ }
+};
+</pre></div>
+</div>
+</div>
+<div class="section" id="creating-an-astconsumer">
+<h2>Creating an ASTConsumer<a class="headerlink" href="#creating-an-astconsumer" title="Permalink to this headline">¶</a></h2>
+<p>ASTConsumer is an interface used to write generic actions on an AST,
+regardless of how the AST was produced. ASTConsumer provides many
+different entry points, but for our use case the only one needed is
+HandleTranslationUnit, which is called with the ASTContext for the
+translation unit.</p>
+<div class="highlight-python"><div class="highlight"><pre>class FindNamedClassConsumer : public clang::ASTConsumer {
+public:
+ virtual void HandleTranslationUnit(clang::ASTContext &Context) {
+ // Traversing the translation unit decl via a RecursiveASTVisitor
+ // will visit all nodes in the AST.
+ Visitor.TraverseDecl(Context.getTranslationUnitDecl());
+ }
+private:
+ // A RecursiveASTVisitor implementation.
+ FindNamedClassVisitor Visitor;
+};
+</pre></div>
+</div>
+</div>
+<div class="section" id="using-the-recursiveastvisitor">
+<h2>Using the RecursiveASTVisitor<a class="headerlink" href="#using-the-recursiveastvisitor" title="Permalink to this headline">¶</a></h2>
+<p>Now that everything is hooked up, the next step is to implement a
+RecursiveASTVisitor to extract the relevant information from the AST.</p>
+<p>The RecursiveASTVisitor provides hooks of the form bool
+VisitNodeType(NodeType *) for most AST nodes; the exception are TypeLoc
+nodes, which are passed by-value. We only need to implement the methods
+for the relevant node types.</p>
+<p>Let’s start by writing a RecursiveASTVisitor that visits all
+CXXRecordDecl’s.</p>
+<div class="highlight-python"><div class="highlight"><pre>class FindNamedClassVisitor
+ : public RecursiveASTVisitor<FindNamedClassVisitor> {
+public:
+ bool VisitCXXRecordDecl(CXXRecordDecl *Declaration) {
+ // For debugging, dumping the AST nodes will show which nodes are already
+ // being visited.
+ Declaration->dump();
+
+ // The return value indicates whether we want the visitation to proceed.
+ // Return false to stop the traversal of the AST.
+ return true;
+ }
+};
+</pre></div>
+</div>
+<p>In the methods of our RecursiveASTVisitor we can now use the full power
+of the Clang AST to drill through to the parts that are interesting for
+us. For example, to find all class declaration with a certain name, we
+can check for a specific qualified name:</p>
+<div class="highlight-python"><div class="highlight"><pre>bool VisitCXXRecordDecl(CXXRecordDecl *Declaration) {
+ if (Declaration->getQualifiedNameAsString() == "n::m::C")
+ Declaration->dump();
+ return true;
+}
+</pre></div>
+</div>
+</div>
+<div class="section" id="accessing-the-sourcemanager-and-astcontext">
+<h2>Accessing the SourceManager and ASTContext<a class="headerlink" href="#accessing-the-sourcemanager-and-astcontext" title="Permalink to this headline">¶</a></h2>
+<p>Some of the information about the AST, like source locations and global
+identifier information, are not stored in the AST nodes themselves, but
+in the ASTContext and its associated source manager. To retrieve them we
+need to hand the ASTContext into our RecursiveASTVisitor implementation.</p>
+<p>The ASTContext is available from the CompilerInstance during the call to
+CreateASTConsumer. We can thus extract it there and hand it into our
+freshly created FindNamedClassConsumer:</p>
+<div class="highlight-python"><div class="highlight"><pre>virtual std::unique_ptr<clang::ASTConsumer> CreateASTConsumer(
+ clang::CompilerInstance &Compiler, llvm::StringRef InFile) {
+ return std::unique_ptr<clang::ASTConsumer>(
+ new FindNamedClassConsumer(&Compiler.getASTContext()));
+}
+</pre></div>
+</div>
+<p>Now that the ASTContext is available in the RecursiveASTVisitor, we can
+do more interesting things with AST nodes, like looking up their source
+locations:</p>
+<div class="highlight-python"><div class="highlight"><pre>bool VisitCXXRecordDecl(CXXRecordDecl *Declaration) {
+ if (Declaration->getQualifiedNameAsString() == "n::m::C") {
+ // getFullLoc uses the ASTContext's SourceManager to resolve the source
+ // location and break it up into its line and column parts.
+ FullSourceLoc FullLocation = Context->getFullLoc(Declaration->getLocStart());
+ if (FullLocation.isValid())
+ llvm::outs() << "Found declaration at "
+ << FullLocation.getSpellingLineNumber() << ":"
+ << FullLocation.getSpellingColumnNumber() << "\n";
+ }
+ return true;
+}
+</pre></div>
+</div>
+</div>
+<div class="section" id="putting-it-all-together">
+<h2>Putting it all together<a class="headerlink" href="#putting-it-all-together" title="Permalink to this headline">¶</a></h2>
+<p>Now we can combine all of the above into a small example program:</p>
+<div class="highlight-python"><div class="highlight"><pre>#include "clang/AST/ASTConsumer.h"
+#include "clang/AST/RecursiveASTVisitor.h"
+#include "clang/Frontend/CompilerInstance.h"
+#include "clang/Frontend/FrontendAction.h"
+#include "clang/Tooling/Tooling.h"
+
+using namespace clang;
+
+class FindNamedClassVisitor
+ : public RecursiveASTVisitor<FindNamedClassVisitor> {
+public:
+ explicit FindNamedClassVisitor(ASTContext *Context)
+ : Context(Context) {}
+
+ bool VisitCXXRecordDecl(CXXRecordDecl *Declaration) {
+ if (Declaration->getQualifiedNameAsString() == "n::m::C") {
+ FullSourceLoc FullLocation = Context->getFullLoc(Declaration->getLocStart());
+ if (FullLocation.isValid())
+ llvm::outs() << "Found declaration at "
+ << FullLocation.getSpellingLineNumber() << ":"
+ << FullLocation.getSpellingColumnNumber() << "\n";
+ }
+ return true;
+ }
+
+private:
+ ASTContext *Context;
+};
+
+class FindNamedClassConsumer : public clang::ASTConsumer {
+public:
+ explicit FindNamedClassConsumer(ASTContext *Context)
+ : Visitor(Context) {}
+
+ virtual void HandleTranslationUnit(clang::ASTContext &Context) {
+ Visitor.TraverseDecl(Context.getTranslationUnitDecl());
+ }
+private:
+ FindNamedClassVisitor Visitor;
+};
+
+class FindNamedClassAction : public clang::ASTFrontendAction {
+public:
+ virtual std::unique_ptr<clang::ASTConsumer> CreateASTConsumer(
+ clang::CompilerInstance &Compiler, llvm::StringRef InFile) {
+ return std::unique_ptr<clang::ASTConsumer>(
+ new FindNamedClassConsumer(&Compiler.getASTContext()));
+ }
+};
+
+int main(int argc, char **argv) {
+ if (argc > 1) {
+ clang::tooling::runToolOnCode(new FindNamedClassAction, argv[1]);
+ }
+}
+</pre></div>
+</div>
+<p>We store this into a file called FindClassDecls.cpp and create the
+following CMakeLists.txt to link it:</p>
+<div class="highlight-python"><div class="highlight"><pre>add_clang_executable(find-class-decls FindClassDecls.cpp)
+
+target_link_libraries(find-class-decls clangTooling)
+</pre></div>
+</div>
+<p>When running this tool over a small code snippet it will output all
+declarations of a class n::m::C it found:</p>
+<div class="highlight-python"><div class="highlight"><pre>$ ./bin/find-class-decls "namespace n { namespace m { class C {}; } }"
+Found declaration at 1:29
+</pre></div>
+</div>
+</div>
+</div>
+
+
+ </div>
+ <div class="bottomnav">
+
+ <p>
+ « <a href="ClangPlugins.html">Clang Plugins</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="LibASTMatchersTutorial.html">Tutorial for building tools using LibTooling and LibASTMatchers</a> »
+ </p>
+
+ </div>
+
+ <div class="footer">
+ © Copyright 2007-2017, The Clang Team.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/4.0.0/tools/clang/docs/ReleaseNotes.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/4.0.0/tools/clang/docs/ReleaseNotes.html?rev=297634&view=auto
==============================================================================
--- www-releases/trunk/4.0.0/tools/clang/docs/ReleaseNotes.html (added)
+++ www-releases/trunk/4.0.0/tools/clang/docs/ReleaseNotes.html Mon Mar 13 11:30:12 2017
@@ -0,0 +1,264 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>Clang 4.0.0 Release Notes — Clang 4 documentation</title>
+
+ <link rel="stylesheet" href="_static/haiku.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: './',
+ VERSION: '4',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+ <link rel="top" title="Clang 4 documentation" href="index.html" />
+ <link rel="next" title="Clang Compiler Userâs Manual" href="UsersManual.html" />
+ <link rel="prev" title="Using Clang as a Compiler" href="index.html" />
+ </head>
+ <body>
+ <div class="header"><h1 class="heading"><a href="index.html">
+ <span>Clang 4 documentation</span></a></h1>
+ <h2 class="heading"><span>Clang 4.0.0 Release Notes</span></h2>
+ </div>
+ <div class="topnav">
+
+ <p>
+ « <a href="index.html">Using Clang as a Compiler</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="UsersManual.html">Clang Compiler User’s Manual</a> »
+ </p>
+
+ </div>
+ <div class="content">
+
+
+ <div class="section" id="clang-4-0-0-release-notes">
+<h1>Clang 4.0.0 Release Notes<a class="headerlink" href="#clang-4-0-0-release-notes" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#introduction" id="id1">Introduction</a></li>
+<li><a class="reference internal" href="#what-s-new-in-clang-4-0-0" id="id2">What’s New in Clang 4.0.0?</a><ul>
+<li><a class="reference internal" href="#major-new-features" id="id3">Major New Features</a></li>
+<li><a class="reference internal" href="#improvements-to-thinlto-flto-thin" id="id4">Improvements to ThinLTO (-flto=thin)</a></li>
+<li><a class="reference internal" href="#new-compiler-flags" id="id5">New Compiler Flags</a></li>
+<li><a class="reference internal" href="#opencl-c-language-changes-in-clang" id="id6">OpenCL C Language Changes in Clang</a></li>
+<li><a class="reference internal" href="#static-analyzer" id="id7">Static Analyzer</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#additional-information" id="id8">Additional Information</a></li>
+</ul>
+</div>
+<p>Written by the <a class="reference external" href="http://llvm.org/">LLVM Team</a></p>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id1">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>This document contains the release notes for the Clang C/C++/Objective-C/OpenCL
+frontend, part of the LLVM Compiler Infrastructure, release 4.0.0. Here we
+describe the status of Clang in some detail, including major
+improvements from the previous release and new feature work. For the
+general LLVM release notes, see <a class="reference external" href="http://llvm.org/docs/ReleaseNotes.html">the LLVM
+documentation</a>. All LLVM
+releases may be downloaded from the <a class="reference external" href="http://llvm.org/releases/">LLVM releases web
+site</a>.</p>
+<p>For more information about Clang or LLVM, including information about
+the latest release, please check out the main please see the <a class="reference external" href="http://clang.llvm.org">Clang Web
+Site</a> or the <a class="reference external" href="http://llvm.org">LLVM Web
+Site</a>.</p>
+</div>
+<div class="section" id="what-s-new-in-clang-4-0-0">
+<h2><a class="toc-backref" href="#id2">What’s New in Clang 4.0.0?</a><a class="headerlink" href="#what-s-new-in-clang-4-0-0" title="Permalink to this headline">¶</a></h2>
+<p>Some of the major new features and improvements to Clang are listed
+here. Generic improvements to Clang as a whole or to its underlying
+infrastructure are described first, followed by language-specific
+sections with improvements to Clang’s support for those languages.</p>
+<div class="section" id="major-new-features">
+<h3><a class="toc-backref" href="#id3">Major New Features</a><a class="headerlink" href="#major-new-features" title="Permalink to this headline">¶</a></h3>
+<ul>
+<li><p class="first">The <a class="reference external" href="AttributeReference.html#diagnose-if">diagnose_if</a> attribute has been
+added to clang. This attribute allows
+clang to emit a warning or error if a function call meets one or more
+user-specified conditions.</p>
+</li>
+<li><p class="first">Enhanced devirtualization with
+<a class="reference external" href="UsersManual.html#cmdoption-fstrict-vtable-pointers">-fstrict-vtable-pointers</a>.
+Clang devirtualizes across different basic blocks, like loops:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">struct</span> <span class="n">A</span> <span class="p">{</span>
+ <span class="k">virtual</span> <span class="kt">void</span> <span class="n">foo</span><span class="p">();</span>
+<span class="p">};</span>
+<span class="kt">void</span> <span class="nf">indirect</span><span class="p">(</span><span class="n">A</span> <span class="o">&</span><span class="n">a</span><span class="p">,</span> <span class="kt">int</span> <span class="n">n</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">for</span> <span class="p">(</span><span class="kt">int</span> <span class="n">i</span> <span class="o">=</span> <span class="mi">0</span> <span class="p">;</span> <span class="n">i</span> <span class="o"><</span> <span class="n">n</span><span class="p">;</span> <span class="n">i</span><span class="o">++</span><span class="p">)</span>
+ <span class="n">a</span><span class="p">.</span><span class="n">foo</span><span class="p">();</span>
+<span class="p">}</span>
+<span class="kt">void</span> <span class="nf">test</span><span class="p">(</span><span class="kt">int</span> <span class="n">n</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">A</span> <span class="n">a</span><span class="p">;</span>
+ <span class="n">indirect</span><span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="n">n</span><span class="p">);</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</li>
+</ul>
+</div>
+<div class="section" id="improvements-to-thinlto-flto-thin">
+<h3><a class="toc-backref" href="#id4">Improvements to ThinLTO (-flto=thin)</a><a class="headerlink" href="#improvements-to-thinlto-flto-thin" title="Permalink to this headline">¶</a></h3>
+<ul class="simple">
+<li>Integration with profile data (PGO). When available, profile data enables
+more accurate function importing decisions, as well as cross-module indirect
+call promotion.</li>
+<li>Significant build-time and binary-size improvements when compiling with debug
+info (<tt class="docutils literal"><span class="pre">-g</span></tt>).</li>
+</ul>
+</div>
+<div class="section" id="new-compiler-flags">
+<h3><a class="toc-backref" href="#id5">New Compiler Flags</a><a class="headerlink" href="#new-compiler-flags" title="Permalink to this headline">¶</a></h3>
+<ul class="simple">
+<li>The option <tt class="docutils literal"><span class="pre">-Og</span></tt> has been added to optimize the debugging experience.
+For now, this option is exactly the same as <tt class="docutils literal"><span class="pre">-O1</span></tt>. However, in the future,
+some other optimizations might be enabled or disabled.</li>
+<li>The option <tt class="docutils literal"><span class="pre">-MJ</span></tt> has been added to simplify adding JSON compilation
+database output into existing build systems.</li>
+</ul>
+</div>
+<div class="section" id="opencl-c-language-changes-in-clang">
+<h3><a class="toc-backref" href="#id6">OpenCL C Language Changes in Clang</a><a class="headerlink" href="#opencl-c-language-changes-in-clang" title="Permalink to this headline">¶</a></h3>
+<p><strong>The following bugs in the OpenCL header have been fixed:</strong></p>
+<ul class="simple">
+<li>Added missing <tt class="docutils literal"><span class="pre">overloadable</span></tt> and <tt class="docutils literal"><span class="pre">convergent</span></tt> attributes.</li>
+<li>Removed some erroneous extra <tt class="docutils literal"><span class="pre">native_*</span></tt> functions.</li>
+</ul>
+<p><strong>The following bugs in the generation of metadata have been fixed:</strong></p>
+<ul class="simple">
+<li>Corrected the SPIR version depending on the OpenCL version.</li>
+<li>Source level address spaces are taken from the SPIR specification.</li>
+<li>Image types now contain no access qualifier.</li>
+</ul>
+<p><strong>The following bugs in the AMD target have been fixed:</strong></p>
+<ul class="simple">
+<li>Corrected the bitwidth of <tt class="docutils literal"><span class="pre">size_t</span></tt> and NULL pointer value with respect to
+address spaces.</li>
+<li>Added <tt class="docutils literal"><span class="pre">cl_khr_subgroups</span></tt>, <tt class="docutils literal"><span class="pre">cl_amd_media_ops</span></tt> and <tt class="docutils literal"><span class="pre">cl_amd_media_ops2</span></tt>
+extensions.</li>
+<li>Added <tt class="docutils literal"><span class="pre">cl-denorms-are-zero</span></tt> support.</li>
+<li>Changed address spaces for image objects to be <tt class="docutils literal"><span class="pre">constant</span></tt>.</li>
+<li>Added little-endian.</li>
+</ul>
+<p><strong>The following bugs in OpenCL 2.0 have been fixed:</strong></p>
+<ul class="simple">
+<li>Fixed pipe builtin function return type, added extra argument to generated
+IR intrinsics to propagate size and alignment information of the pipe packed
+type.</li>
+<li>Improved pipe type to accommodate access qualifiers.</li>
+<li>Added correct address space to the ObjC block generation and <tt class="docutils literal"><span class="pre">enqueue_kernel</span></tt>
+prototype.</li>
+<li>Improved handling of integer parameters of <tt class="docutils literal"><span class="pre">enqueue_kernel</span></tt> prototype. We
+now allow <tt class="docutils literal"><span class="pre">size_t</span></tt> instead of <tt class="docutils literal"><span class="pre">int</span></tt> for specifying block parameter sizes.</li>
+<li>Allow using NULL (aka <tt class="docutils literal"><span class="pre">CLK_NULL_QUEUE</span></tt>) with <tt class="docutils literal"><span class="pre">queue_t</span></tt>.</li>
+</ul>
+<p><strong>Improved the following diagnostics:</strong></p>
+<ul class="simple">
+<li>Disallow address spaces other than <tt class="docutils literal"><span class="pre">global</span></tt> for kernel pointer parameters.</li>
+<li>Correct the use of half type argument and pointer assignment with
+dereferencing.</li>
+<li>Disallow variadic arguments in functions and blocks.</li>
+<li>Allow partial initializer for array and struct.</li>
+</ul>
+<p><strong>Some changes to OpenCL extensions have been made:</strong></p>
+<ul>
+<li><p class="first">Added <tt class="docutils literal"><span class="pre">cl_khr_mipmap_image</span></tt>.</p>
+</li>
+<li><p class="first">Added <tt class="docutils literal"><span class="pre">-cl-ext</span></tt> flag to allow overwriting supported extensions otherwise
+set by the target compiled for (Example: <tt class="docutils literal"><span class="pre">-cl-ext=-all,+cl_khr_fp16</span></tt>).</p>
+</li>
+<li><p class="first">New types and functions can now be flexibly added to extensions using the
+following pragmas instead of modifying the Clang source code:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="cp">#pragma OPENCL EXTENSION the_new_extension_name : begin</span>
+<span class="c1">// declare types and functions associated with the extension here</span>
+<span class="cp">#pragma OPENCL EXTENSION the_new_extension_name : end</span>
+</pre></div>
+</div>
+</li>
+</ul>
+<p><strong>Miscellaneous changes:</strong></p>
+<ul class="simple">
+<li>Fix <tt class="docutils literal"><span class="pre">__builtin_astype</span></tt> to cast between different address space objects.</li>
+<li>Allow using <tt class="docutils literal"><span class="pre">opencl_unroll_hint</span></tt> with earlier OpenCL versions than 2.0.</li>
+<li>Improved handling of floating point literal to default to single precision if
+fp64 extension is not enabled.</li>
+<li>Refactor <tt class="docutils literal"><span class="pre">sampler_t</span></tt> implementation to simplify initializer representation
+which is now handled as a compiler builtin function with an integer value
+passed into it.</li>
+<li>Change fake address space map to use the SPIR convention.</li>
+<li>Added <a class="reference external" href="UsersManual.html#opencl-features">the OpenCL manual</a> to Clang
+documentation.</li>
+</ul>
+</div>
+<div class="section" id="static-analyzer">
+<h3><a class="toc-backref" href="#id7">Static Analyzer</a><a class="headerlink" href="#static-analyzer" title="Permalink to this headline">¶</a></h3>
+<p>With the option <tt class="docutils literal"><span class="pre">--show-description</span></tt>, scan-build’s list of defects will also
+show the description of the defects.</p>
+<p>The analyzer now provides better support of code that uses gtest.</p>
+<p>Several new checks were added:</p>
+<ul class="simple">
+<li>The analyzer warns when virtual calls are made from constructors or
+destructors. This check is off by default but can be enabled by passing the
+following command to scan-build: <tt class="docutils literal"><span class="pre">-enable-checker</span> <span class="pre">optin.cplusplus.VirtualCall</span></tt>.</li>
+<li>The analyzer checks for synthesized copy properties of mutable types in
+Objective C, such as <tt class="docutils literal"><span class="pre">NSMutableArray</span></tt>. Calling the setter for these properties
+will store an immutable copy of the value.</li>
+<li>The analyzer checks for calls to <tt class="docutils literal"><span class="pre">dispatch_once()</span></tt> that use an Objective-C
+instance variable as the predicate. Using an instance variable as a predicate
+may result in the passed-in block being executed multiple times or not at all.
+These calls should be rewritten either to use a lock or to store the predicate
+in a global or static variable.</li>
+<li>The analyzer checks for unintended comparisons of <tt class="docutils literal"><span class="pre">NSNumber</span></tt>, <tt class="docutils literal"><span class="pre">CFNumberRef</span></tt>, and
+other Cocoa number objects to scalar values.</li>
+</ul>
+</div>
+</div>
+<div class="section" id="additional-information">
+<h2><a class="toc-backref" href="#id8">Additional Information</a><a class="headerlink" href="#additional-information" title="Permalink to this headline">¶</a></h2>
+<p>A wide variety of additional information is available on the <a class="reference external" href="http://clang.llvm.org/">Clang web
+page</a>. The web page contains versions of the
+API documentation which are up-to-date with the Subversion version of
+the source code. You can access versions of these documents specific to
+this release by going into the “<tt class="docutils literal"><span class="pre">clang/docs/</span></tt>” directory in the Clang
+tree.</p>
+<p>If you have any questions or comments about Clang, please feel free to
+contact us via the <a class="reference external" href="http://lists.llvm.org/mailman/listinfo/cfe-dev">mailing
+list</a>.</p>
+</div>
+</div>
+
+
+ </div>
+ <div class="bottomnav">
+
+ <p>
+ « <a href="index.html">Using Clang as a Compiler</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="UsersManual.html">Clang Compiler User’s Manual</a> »
+ </p>
+
+ </div>
+
+ <div class="footer">
+ © Copyright 2007-2017, The Clang Team.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/4.0.0/tools/clang/docs/SafeStack.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/4.0.0/tools/clang/docs/SafeStack.html?rev=297634&view=auto
==============================================================================
--- www-releases/trunk/4.0.0/tools/clang/docs/SafeStack.html (added)
+++ www-releases/trunk/4.0.0/tools/clang/docs/SafeStack.html Mon Mar 13 11:30:12 2017
@@ -0,0 +1,268 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>SafeStack — Clang 4 documentation</title>
+
+ <link rel="stylesheet" href="_static/haiku.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: './',
+ VERSION: '4',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+ <link rel="top" title="Clang 4 documentation" href="index.html" />
+ <link rel="next" title="Source-based Code Coverage" href="SourceBasedCodeCoverage.html" />
+ <link rel="prev" title="LTO Visibility" href="LTOVisibility.html" />
+ </head>
+ <body>
+ <div class="header"><h1 class="heading"><a href="index.html">
+ <span>Clang 4 documentation</span></a></h1>
+ <h2 class="heading"><span>SafeStack</span></h2>
+ </div>
+ <div class="topnav">
+
+ <p>
+ « <a href="LTOVisibility.html">LTO Visibility</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="SourceBasedCodeCoverage.html">Source-based Code Coverage</a> »
+ </p>
+
+ </div>
+ <div class="content">
+
+
+ <div class="section" id="safestack">
+<h1>SafeStack<a class="headerlink" href="#safestack" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#introduction" id="id1">Introduction</a><ul>
+<li><a class="reference internal" href="#performance" id="id2">Performance</a></li>
+<li><a class="reference internal" href="#compatibility" id="id3">Compatibility</a><ul>
+<li><a class="reference internal" href="#known-compatibility-limitations" id="id4">Known compatibility limitations</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#security" id="id5">Security</a><ul>
+<li><a class="reference internal" href="#known-security-limitations" id="id6">Known security limitations</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#usage" id="id7">Usage</a><ul>
+<li><a class="reference internal" href="#supported-platforms" id="id8">Supported Platforms</a></li>
+<li><a class="reference internal" href="#low-level-api" id="id9">Low-level API</a><ul>
+<li><a class="reference internal" href="#has-feature-safe-stack" id="id10"><tt class="docutils literal"><span class="pre">__has_feature(safe_stack)</span></tt></a></li>
+<li><a class="reference internal" href="#attribute-no-sanitize-safe-stack" id="id11"><tt class="docutils literal"><span class="pre">__attribute__((no_sanitize("safe-stack")))</span></tt></a></li>
+<li><a class="reference internal" href="#builtin-get-unsafe-stack-ptr" id="id12"><tt class="docutils literal"><span class="pre">__builtin___get_unsafe_stack_ptr()</span></tt></a></li>
+<li><a class="reference internal" href="#builtin-get-unsafe-stack-start" id="id13"><tt class="docutils literal"><span class="pre">__builtin___get_unsafe_stack_start()</span></tt></a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#design" id="id14">Design</a><ul>
+<li><a class="reference internal" href="#setjmp-and-exception-handling" id="id15">setjmp and exception handling</a></li>
+<li><a class="reference internal" href="#publications" id="id16">Publications</a></li>
+</ul>
+</li>
+</ul>
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id1">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>SafeStack is an instrumentation pass that protects programs against attacks
+based on stack buffer overflows, without introducing any measurable performance
+overhead. It works by separating the program stack into two distinct regions:
+the safe stack and the unsafe stack. The safe stack stores return addresses,
+register spills, and local variables that are always accessed in a safe way,
+while the unsafe stack stores everything else. This separation ensures that
+buffer overflows on the unsafe stack cannot be used to overwrite anything
+on the safe stack.</p>
+<p>SafeStack is a part of the <a class="reference external" href="http://dslab.epfl.ch/proj/cpi/">Code-Pointer Integrity (CPI) Project</a>.</p>
+<div class="section" id="performance">
+<h3><a class="toc-backref" href="#id2">Performance</a><a class="headerlink" href="#performance" title="Permalink to this headline">¶</a></h3>
+<p>The performance overhead of the SafeStack instrumentation is less than 0.1% on
+average across a variety of benchmarks (see the <a class="reference external" href="http://dslab.epfl.ch/pubs/cpi.pdf">Code-Pointer Integrity</a> paper for details). This is mainly
+because most small functions do not have any variables that require the unsafe
+stack and, hence, do not need unsafe stack frames to be created. The cost of
+creating unsafe stack frames for large functions is amortized by the cost of
+executing the function.</p>
+<p>In some cases, SafeStack actually improves the performance. Objects that end up
+being moved to the unsafe stack are usually large arrays or variables that are
+used through multiple stack frames. Moving such objects away from the safe
+stack increases the locality of frequently accessed values on the stack, such
+as register spills, return addresses, and small local variables.</p>
+</div>
+<div class="section" id="compatibility">
+<h3><a class="toc-backref" href="#id3">Compatibility</a><a class="headerlink" href="#compatibility" title="Permalink to this headline">¶</a></h3>
+<p>Most programs, static libraries, or individual files can be compiled
+with SafeStack as is. SafeStack requires basic runtime support, which, on most
+platforms, is implemented as a compiler-rt library that is automatically linked
+in when the program is compiled with SafeStack.</p>
+<p>Linking a DSO with SafeStack is not currently supported.</p>
+<div class="section" id="known-compatibility-limitations">
+<h4><a class="toc-backref" href="#id4">Known compatibility limitations</a><a class="headerlink" href="#known-compatibility-limitations" title="Permalink to this headline">¶</a></h4>
+<p>Certain code that relies on low-level stack manipulations requires adaption to
+work with SafeStack. One example is mark-and-sweep garbage collection
+implementations for C/C++ (e.g., Oilpan in chromium/blink), which must be
+changed to look for the live pointers on both safe and unsafe stacks.</p>
+<p>SafeStack supports linking statically modules that are compiled with and
+without SafeStack. An executable compiled with SafeStack can load dynamic
+libraries that are not compiled with SafeStack. At the moment, compiling
+dynamic libraries with SafeStack is not supported.</p>
+<p>Signal handlers that use <tt class="docutils literal"><span class="pre">sigaltstack()</span></tt> must not use the unsafe stack (see
+<tt class="docutils literal"><span class="pre">__attribute__((no_sanitize("safe-stack")))</span></tt> below).</p>
+<p>Programs that use APIs from <tt class="docutils literal"><span class="pre">ucontext.h</span></tt> are not supported yet.</p>
+</div>
+</div>
+<div class="section" id="security">
+<h3><a class="toc-backref" href="#id5">Security</a><a class="headerlink" href="#security" title="Permalink to this headline">¶</a></h3>
+<p>SafeStack protects return addresses, spilled registers and local variables that
+are always accessed in a safe way by separating them in a dedicated safe stack
+region. The safe stack is automatically protected against stack-based buffer
+overflows, since it is disjoint from the unsafe stack in memory, and it itself
+is always accessed in a safe way. In the current implementation, the safe stack
+is protected against arbitrary memory write vulnerabilities though
+randomization and information hiding: the safe stack is allocated at a random
+address and the instrumentation ensures that no pointers to the safe stack are
+ever stored outside of the safe stack itself (see limitations below).</p>
+<div class="section" id="known-security-limitations">
+<h4><a class="toc-backref" href="#id6">Known security limitations</a><a class="headerlink" href="#known-security-limitations" title="Permalink to this headline">¶</a></h4>
+<p>A complete protection against control-flow hijack attacks requires combining
+SafeStack with another mechanism that enforces the integrity of code pointers
+that are stored on the heap or the unsafe stack, such as <a class="reference external" href="http://dslab.epfl.ch/proj/cpi/">CPI</a>, or a forward-edge control flow integrity
+mechanism that enforces correct calling conventions at indirect call sites,
+such as <a class="reference external" href="http://research.google.com/pubs/archive/42808.pdf">IFCC</a> with arity
+checks. Clang has control-flow integrity protection scheme for <a class="reference internal" href="ControlFlowIntegrity.html"><em>C++ virtual
+calls</em></a>, but not non-virtual indirect calls. With
+SafeStack alone, an attacker can overwrite a function pointer on the heap or
+the unsafe stack and cause a program to call arbitrary location, which in turn
+might enable stack pivoting and return-oriented programming.</p>
+<p>In its current implementation, SafeStack provides precise protection against
+stack-based buffer overflows, but protection against arbitrary memory write
+vulnerabilities is probabilistic and relies on randomization and information
+hiding. The randomization is currently based on system-enforced ASLR and shares
+its known security limitations. The safe stack pointer hiding is not perfect
+yet either: system library functions such as <tt class="docutils literal"><span class="pre">swapcontext</span></tt>, exception
+handling mechanisms, intrinsics such as <tt class="docutils literal"><span class="pre">__builtin_frame_address</span></tt>, or
+low-level bugs in runtime support could leak the safe stack pointer. In the
+future, such leaks could be detected by static or dynamic analysis tools and
+prevented by adjusting such functions to either encrypt the stack pointer when
+storing it in the heap (as already done e.g., by <tt class="docutils literal"><span class="pre">setjmp</span></tt>/<tt class="docutils literal"><span class="pre">longjmp</span></tt>
+implementation in glibc), or store it in a safe region instead.</p>
+<p>The <a class="reference external" href="http://dslab.epfl.ch/pubs/cpi.pdf">CPI paper</a> describes two alternative,
+stronger safe stack protection mechanisms, that rely on software fault
+isolation, or hardware segmentation (as available on x86-32 and some x86-64
+CPUs).</p>
+<p>At the moment, SafeStack assumes that the compiler’s implementation is correct.
+This has not been verified except through manual code inspection, and could
+always regress in the future. It’s therefore desirable to have a separate
+static or dynamic binary verification tool that would check the correctness of
+the SafeStack instrumentation in final binaries.</p>
+</div>
+</div>
+</div>
+<div class="section" id="usage">
+<h2><a class="toc-backref" href="#id7">Usage</a><a class="headerlink" href="#usage" title="Permalink to this headline">¶</a></h2>
+<p>To enable SafeStack, just pass <tt class="docutils literal"><span class="pre">-fsanitize=safe-stack</span></tt> flag to both compile
+and link command lines.</p>
+<div class="section" id="supported-platforms">
+<h3><a class="toc-backref" href="#id8">Supported Platforms</a><a class="headerlink" href="#supported-platforms" title="Permalink to this headline">¶</a></h3>
+<p>SafeStack was tested on Linux, FreeBSD and MacOSX.</p>
+</div>
+<div class="section" id="low-level-api">
+<h3><a class="toc-backref" href="#id9">Low-level API</a><a class="headerlink" href="#low-level-api" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="has-feature-safe-stack">
+<h4><a class="toc-backref" href="#id10"><tt class="docutils literal"><span class="pre">__has_feature(safe_stack)</span></tt></a><a class="headerlink" href="#has-feature-safe-stack" title="Permalink to this headline">¶</a></h4>
+<p>In some rare cases one may need to execute different code depending on
+whether SafeStack is enabled. The macro <tt class="docutils literal"><span class="pre">__has_feature(safe_stack)</span></tt> can
+be used for this purpose.</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="cp">#if __has_feature(safe_stack)</span>
+<span class="c1">// code that builds only under SafeStack</span>
+<span class="cp">#endif</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="attribute-no-sanitize-safe-stack">
+<h4><a class="toc-backref" href="#id11"><tt class="docutils literal"><span class="pre">__attribute__((no_sanitize("safe-stack")))</span></tt></a><a class="headerlink" href="#attribute-no-sanitize-safe-stack" title="Permalink to this headline">¶</a></h4>
+<p>Use <tt class="docutils literal"><span class="pre">__attribute__((no_sanitize("safe-stack")))</span></tt> on a function declaration
+to specify that the safe stack instrumentation should not be applied to that
+function, even if enabled globally (see <tt class="docutils literal"><span class="pre">-fsanitize=safe-stack</span></tt> flag). This
+attribute may be required for functions that make assumptions about the
+exact layout of their stack frames.</p>
+<p>All local variables in functions with this attribute will be stored on the safe
+stack. The safe stack remains unprotected against memory errors when accessing
+these variables, so extra care must be taken to manually ensure that all such
+accesses are safe. Furthermore, the addresses of such local variables should
+never be stored on the heap, as it would leak the location of the SafeStack.</p>
+</div>
+<div class="section" id="builtin-get-unsafe-stack-ptr">
+<h4><a class="toc-backref" href="#id12"><tt class="docutils literal"><span class="pre">__builtin___get_unsafe_stack_ptr()</span></tt></a><a class="headerlink" href="#builtin-get-unsafe-stack-ptr" title="Permalink to this headline">¶</a></h4>
+<p>This builtin function returns current unsafe stack pointer of the current
+thread.</p>
+</div>
+<div class="section" id="builtin-get-unsafe-stack-start">
+<h4><a class="toc-backref" href="#id13"><tt class="docutils literal"><span class="pre">__builtin___get_unsafe_stack_start()</span></tt></a><a class="headerlink" href="#builtin-get-unsafe-stack-start" title="Permalink to this headline">¶</a></h4>
+<p>This builtin function returns a pointer to the start of the unsafe stack of the
+current thread.</p>
+</div>
+</div>
+</div>
+<div class="section" id="design">
+<h2><a class="toc-backref" href="#id14">Design</a><a class="headerlink" href="#design" title="Permalink to this headline">¶</a></h2>
+<p>Please refer to the <a class="reference external" href="http://dslab.epfl.ch/proj/cpi/">Code-Pointer Integrity</a>
+project page for more information about the design of the SafeStack and its
+related technologies.</p>
+<div class="section" id="setjmp-and-exception-handling">
+<h3><a class="toc-backref" href="#id15">setjmp and exception handling</a><a class="headerlink" href="#setjmp-and-exception-handling" title="Permalink to this headline">¶</a></h3>
+<p>The <a class="reference external" href="http://dslab.epfl.ch/pubs/cpi.pdf">OSDI‘14 paper</a> mentions that
+on Linux the instrumentation pass finds calls to setjmp or functions that
+may throw an exception, and inserts required instrumentation at their call
+sites. Specifically, the instrumentation pass saves the shadow stack pointer
+on the safe stack before the call site, and restores it either after the
+call to setjmp or after an exception has been caught. This is implemented
+in the function <tt class="docutils literal"><span class="pre">SafeStack::createStackRestorePoints</span></tt>.</p>
+</div>
+<div class="section" id="publications">
+<h3><a class="toc-backref" href="#id16">Publications</a><a class="headerlink" href="#publications" title="Permalink to this headline">¶</a></h3>
+<p><a class="reference external" href="http://dslab.epfl.ch/pubs/cpi.pdf">Code-Pointer Integrity</a>.
+Volodymyr Kuznetsov, Laszlo Szekeres, Mathias Payer, George Candea, R. Sekar, Dawn Song.
+USENIX Symposium on Operating Systems Design and Implementation
+(<a class="reference external" href="https://www.usenix.org/conference/osdi14">OSDI</a>), Broomfield, CO, October 2014</p>
+</div>
+</div>
+</div>
+
+
+ </div>
+ <div class="bottomnav">
+
+ <p>
+ « <a href="LTOVisibility.html">LTO Visibility</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="SourceBasedCodeCoverage.html">Source-based Code Coverage</a> »
+ </p>
+
+ </div>
+
+ <div class="footer">
+ © Copyright 2007-2017, The Clang Team.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/4.0.0/tools/clang/docs/SanitizerCoverage.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/4.0.0/tools/clang/docs/SanitizerCoverage.html?rev=297634&view=auto
==============================================================================
--- www-releases/trunk/4.0.0/tools/clang/docs/SanitizerCoverage.html (added)
+++ www-releases/trunk/4.0.0/tools/clang/docs/SanitizerCoverage.html Mon Mar 13 11:30:12 2017
@@ -0,0 +1,754 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>SanitizerCoverage — Clang 4 documentation</title>
+
+ <link rel="stylesheet" href="_static/haiku.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: './',
+ VERSION: '4',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+ <link rel="top" title="Clang 4 documentation" href="index.html" />
+ <link rel="next" title="SanitizerStats" href="SanitizerStats.html" />
+ <link rel="prev" title="LeakSanitizer" href="LeakSanitizer.html" />
+ </head>
+ <body>
+ <div class="header"><h1 class="heading"><a href="index.html">
+ <span>Clang 4 documentation</span></a></h1>
+ <h2 class="heading"><span>SanitizerCoverage</span></h2>
+ </div>
+ <div class="topnav">
+
+ <p>
+ « <a href="LeakSanitizer.html">LeakSanitizer</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="SanitizerStats.html">SanitizerStats</a> »
+ </p>
+
+ </div>
+ <div class="content">
+
+
+ <div class="section" id="sanitizercoverage">
+<h1>SanitizerCoverage<a class="headerlink" href="#sanitizercoverage" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#introduction" id="id1">Introduction</a></li>
+<li><a class="reference internal" href="#how-to-build-and-run" id="id2">How to build and run</a></li>
+<li><a class="reference internal" href="#postprocessing" id="id3">Postprocessing</a></li>
+<li><a class="reference internal" href="#sancov-tool" id="id4">Sancov Tool</a></li>
+<li><a class="reference internal" href="#coverage-reports-experimental" id="id5">Coverage Reports (Experimental)</a></li>
+<li><a class="reference internal" href="#how-good-is-the-coverage" id="id6">How good is the coverage?</a></li>
+<li><a class="reference internal" href="#edge-coverage" id="id7">Edge coverage</a></li>
+<li><a class="reference internal" href="#bitset" id="id8">Bitset</a></li>
+<li><a class="reference internal" href="#caller-callee-coverage" id="id9">Caller-callee coverage</a></li>
+<li><a class="reference internal" href="#coverage-counters" id="id10">Coverage counters</a></li>
+<li><a class="reference internal" href="#tracing-basic-blocks" id="id11">Tracing basic blocks</a></li>
+<li><a class="reference internal" href="#tracing-pcs" id="id12">Tracing PCs</a></li>
+<li><a class="reference internal" href="#tracing-pcs-with-guards" id="id13">Tracing PCs with guards</a></li>
+<li><a class="reference internal" href="#tracing-data-flow" id="id14">Tracing data flow</a></li>
+<li><a class="reference internal" href="#output-directory" id="id15">Output directory</a></li>
+<li><a class="reference internal" href="#sudden-death" id="id16">Sudden death</a></li>
+<li><a class="reference internal" href="#in-process-fuzzing" id="id17">In-process fuzzing</a></li>
+<li><a class="reference internal" href="#performance" id="id18">Performance</a></li>
+<li><a class="reference internal" href="#why-another-coverage" id="id19">Why another coverage?</a></li>
+</ul>
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id1">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>Sanitizer tools have a very simple code coverage tool built in. It allows to
+get function-level, basic-block-level, and edge-level coverage at a very low
+cost.</p>
+</div>
+<div class="section" id="how-to-build-and-run">
+<h2><a class="toc-backref" href="#id2">How to build and run</a><a class="headerlink" href="#how-to-build-and-run" title="Permalink to this headline">¶</a></h2>
+<p>SanitizerCoverage can be used with <a class="reference internal" href="AddressSanitizer.html"><em>AddressSanitizer</em></a>,
+<a class="reference internal" href="LeakSanitizer.html"><em>LeakSanitizer</em></a>, <a class="reference internal" href="MemorySanitizer.html"><em>MemorySanitizer</em></a>,
+UndefinedBehaviorSanitizer, or without any sanitizer. Pass one of the
+following compile-time flags:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">-fsanitize-coverage=func</span></tt> for function-level coverage (very fast).</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize-coverage=bb</span></tt> for basic-block-level coverage (may add up to 30%
+<strong>extra</strong> slowdown).</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize-coverage=edge</span></tt> for edge-level coverage (up to 40% slowdown).</li>
+</ul>
+<p>You may also specify <tt class="docutils literal"><span class="pre">-fsanitize-coverage=indirect-calls</span></tt> for
+additional <a class="reference internal" href="#caller-callee-coverage">caller-callee coverage</a>.</p>
+<p>At run time, pass <tt class="docutils literal"><span class="pre">coverage=1</span></tt> in <tt class="docutils literal"><span class="pre">ASAN_OPTIONS</span></tt>,
+<tt class="docutils literal"><span class="pre">LSAN_OPTIONS</span></tt>, <tt class="docutils literal"><span class="pre">MSAN_OPTIONS</span></tt> or <tt class="docutils literal"><span class="pre">UBSAN_OPTIONS</span></tt>, as
+appropriate. For the standalone coverage mode, use <tt class="docutils literal"><span class="pre">UBSAN_OPTIONS</span></tt>.</p>
+<p>To get <a class="reference internal" href="#coverage-counters">Coverage counters</a>, add <tt class="docutils literal"><span class="pre">-fsanitize-coverage=8bit-counters</span></tt>
+to one of the above compile-time flags. At runtime, use
+<tt class="docutils literal"><span class="pre">*SAN_OPTIONS=coverage=1:coverage_counters=1</span></tt>.</p>
+<p>Example:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> cat -n cov.cc
+<span class="go"> 1 #include <stdio.h></span>
+<span class="go"> 2 __attribute__((noinline))</span>
+<span class="go"> 3 void foo() { printf("foo\n"); }</span>
+<span class="go"> 4</span>
+<span class="go"> 5 int main(int argc, char **argv) {</span>
+<span class="go"> 6 if (argc == 2)</span>
+<span class="go"> 7 foo();</span>
+<span class="go"> 8 printf("main\n");</span>
+<span class="go"> 9 }</span>
+<span class="gp">%</span> clang++ -g cov.cc -fsanitize<span class="o">=</span>address -fsanitize-coverage<span class="o">=</span>func
+<span class="gp">%</span> <span class="nv">ASAN_OPTIONS</span><span class="o">=</span><span class="nv">coverage</span><span class="o">=</span>1 ./a.out; ls -l *sancov
+<span class="go">main</span>
+<span class="go">-rw-r----- 1 kcc eng 4 Nov 27 12:21 a.out.22673.sancov</span>
+<span class="gp">%</span> <span class="nv">ASAN_OPTIONS</span><span class="o">=</span><span class="nv">coverage</span><span class="o">=</span>1 ./a.out foo ; ls -l *sancov
+<span class="go">foo</span>
+<span class="go">main</span>
+<span class="go">-rw-r----- 1 kcc eng 4 Nov 27 12:21 a.out.22673.sancov</span>
+<span class="go">-rw-r----- 1 kcc eng 8 Nov 27 12:21 a.out.22679.sancov</span>
+</pre></div>
+</div>
+<p>Every time you run an executable instrumented with SanitizerCoverage
+one <tt class="docutils literal"><span class="pre">*.sancov</span></tt> file is created during the process shutdown.
+If the executable is dynamically linked against instrumented DSOs,
+one <tt class="docutils literal"><span class="pre">*.sancov</span></tt> file will be also created for every DSO.</p>
+</div>
+<div class="section" id="postprocessing">
+<h2><a class="toc-backref" href="#id3">Postprocessing</a><a class="headerlink" href="#postprocessing" title="Permalink to this headline">¶</a></h2>
+<p>The format of <tt class="docutils literal"><span class="pre">*.sancov</span></tt> files is very simple: the first 8 bytes is the magic,
+one of <tt class="docutils literal"><span class="pre">0xC0BFFFFFFFFFFF64</span></tt> and <tt class="docutils literal"><span class="pre">0xC0BFFFFFFFFFFF32</span></tt>. The last byte of the
+magic defines the size of the following offsets. The rest of the data is the
+offsets in the corresponding binary/DSO that were executed during the run.</p>
+<p>A simple script
+<tt class="docutils literal"><span class="pre">$LLVM/projects/compiler-rt/lib/sanitizer_common/scripts/sancov.py</span></tt> is
+provided to dump these offsets.</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> sancov.py print a.out.22679.sancov a.out.22673.sancov
+<span class="go">sancov.py: read 2 PCs from a.out.22679.sancov</span>
+<span class="go">sancov.py: read 1 PCs from a.out.22673.sancov</span>
+<span class="go">sancov.py: 2 files merged; 2 PCs total</span>
+<span class="go">0x465250</span>
+<span class="go">0x4652a0</span>
+</pre></div>
+</div>
+<p>You can then filter the output of <tt class="docutils literal"><span class="pre">sancov.py</span></tt> through <tt class="docutils literal"><span class="pre">addr2line</span> <span class="pre">--exe</span>
+<span class="pre">ObjectFile</span></tt> or <tt class="docutils literal"><span class="pre">llvm-symbolizer</span> <span class="pre">--obj</span> <span class="pre">ObjectFile</span></tt> to get file names and line
+numbers:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> sancov.py print a.out.22679.sancov a.out.22673.sancov 2> /dev/null | llvm-symbolizer --obj a.out
+<span class="go">cov.cc:3</span>
+<span class="go">cov.cc:5</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="sancov-tool">
+<h2><a class="toc-backref" href="#id4">Sancov Tool</a><a class="headerlink" href="#sancov-tool" title="Permalink to this headline">¶</a></h2>
+<p>A new experimental <tt class="docutils literal"><span class="pre">sancov</span></tt> tool is developed to process coverage files.
+The tool is part of LLVM project and is currently supported only on Linux.
+It can handle symbolization tasks autonomously without any extra support
+from the environment. You need to pass .sancov files (named
+<tt class="docutils literal"><span class="pre"><module_name>.<pid>.sancov</span></tt> and paths to all corresponding binary elf files.
+Sancov matches these files using module names and binaries file names.</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="go">USAGE: sancov [options] <action> (<binary file>|<.sancov file>)...</span>
+
+<span class="go">Action (required)</span>
+<span class="go"> -print - Print coverage addresses</span>
+<span class="go"> -covered-functions - Print all covered functions.</span>
+<span class="go"> -not-covered-functions - Print all not covered functions.</span>
+<span class="go"> -symbolize - Symbolizes the report.</span>
+
+<span class="go">Options</span>
+<span class="go"> -blacklist=<string> - Blacklist file (sanitizer blacklist format).</span>
+<span class="go"> -demangle - Print demangled function name.</span>
+<span class="go"> -strip_path_prefix=<string> - Strip this prefix from file paths in reports</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="coverage-reports-experimental">
+<h2><a class="toc-backref" href="#id5">Coverage Reports (Experimental)</a><a class="headerlink" href="#coverage-reports-experimental" title="Permalink to this headline">¶</a></h2>
+<p><tt class="docutils literal"><span class="pre">.sancov</span></tt> files do not contain enough information to generate a source-level
+coverage report. The missing information is contained
+in debug info of the binary. Thus the <tt class="docutils literal"><span class="pre">.sancov</span></tt> has to be symbolized
+to produce a <tt class="docutils literal"><span class="pre">.symcov</span></tt> file first:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="go">sancov -symbolize my_program.123.sancov my_program > my_program.123.symcov</span>
+</pre></div>
+</div>
+<p>The <tt class="docutils literal"><span class="pre">.symcov</span></tt> file can be browsed overlayed over the source code by
+running <tt class="docutils literal"><span class="pre">tools/sancov/coverage-report-server.py</span></tt> script that will start
+an HTTP server.</p>
+</div>
+<div class="section" id="how-good-is-the-coverage">
+<h2><a class="toc-backref" href="#id6">How good is the coverage?</a><a class="headerlink" href="#how-good-is-the-coverage" title="Permalink to this headline">¶</a></h2>
+<p>It is possible to find out which PCs are not covered, by subtracting the covered
+set from the set of all instrumented PCs. The latter can be obtained by listing
+all callsites of <tt class="docutils literal"><span class="pre">__sanitizer_cov()</span></tt> in the binary. On Linux, <tt class="docutils literal"><span class="pre">sancov.py</span></tt>
+can do this for you. Just supply the path to binary and a list of covered PCs:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> sancov.py print a.out.12345.sancov > covered.txt
+<span class="go">sancov.py: read 2 64-bit PCs from a.out.12345.sancov</span>
+<span class="go">sancov.py: 1 file merged; 2 PCs total</span>
+<span class="gp">%</span> sancov.py missing a.out < covered.txt
+<span class="go">sancov.py: found 3 instrumented PCs in a.out</span>
+<span class="go">sancov.py: read 2 PCs from stdin</span>
+<span class="go">sancov.py: 1 PCs missing from coverage</span>
+<span class="go">0x4cc61c</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="edge-coverage">
+<h2><a class="toc-backref" href="#id7">Edge coverage</a><a class="headerlink" href="#edge-coverage" title="Permalink to this headline">¶</a></h2>
+<p>Consider this code:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="nf">foo</span><span class="p">(</span><span class="kt">int</span> <span class="o">*</span><span class="n">a</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">a</span><span class="p">)</span>
+ <span class="o">*</span><span class="n">a</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>It contains 3 basic blocks, let’s name them A, B, C:</p>
+<div class="highlight-none"><div class="highlight"><pre>A
+|\
+| \
+| B
+| /
+|/
+C
+</pre></div>
+</div>
+<p>If blocks A, B, and C are all covered we know for certain that the edges A=>B
+and B=>C were executed, but we still don’t know if the edge A=>C was executed.
+Such edges of control flow graph are called
+<a class="reference external" href="http://en.wikipedia.org/wiki/Control_flow_graph#Special_edges">critical</a>. The
+edge-level coverage (<tt class="docutils literal"><span class="pre">-fsanitize-coverage=edge</span></tt>) simply splits all critical
+edges by introducing new dummy blocks and then instruments those blocks:</p>
+<div class="highlight-none"><div class="highlight"><pre>A
+|\
+| \
+D B
+| /
+|/
+C
+</pre></div>
+</div>
+</div>
+<div class="section" id="bitset">
+<h2><a class="toc-backref" href="#id8">Bitset</a><a class="headerlink" href="#bitset" title="Permalink to this headline">¶</a></h2>
+<p>When <tt class="docutils literal"><span class="pre">coverage_bitset=1</span></tt> run-time flag is given, the coverage will also be
+dumped as a bitset (text file with 1 for blocks that have been executed and 0
+for blocks that were not).</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> clang++ -fsanitize<span class="o">=</span>address -fsanitize-coverage<span class="o">=</span>edge cov.cc
+<span class="gp">%</span> <span class="nv">ASAN_OPTIONS</span><span class="o">=</span><span class="s2">"coverage=1:coverage_bitset=1"</span> ./a.out
+<span class="go">main</span>
+<span class="gp">%</span> <span class="nv">ASAN_OPTIONS</span><span class="o">=</span><span class="s2">"coverage=1:coverage_bitset=1"</span> ./a.out 1
+<span class="go">foo</span>
+<span class="go">main</span>
+<span class="gp">%</span> head *bitset*
+<span class="go">==> a.out.38214.bitset-sancov <==</span>
+<span class="go">01101</span>
+<span class="go">==> a.out.6128.bitset-sancov <==</span>
+<span class="go">11011%</span>
+</pre></div>
+</div>
+<p>For a given executable the length of the bitset is always the same (well,
+unless dlopen/dlclose come into play), so the bitset coverage can be
+easily used for bitset-based corpus distillation.</p>
+</div>
+<div class="section" id="caller-callee-coverage">
+<h2><a class="toc-backref" href="#id9">Caller-callee coverage</a><a class="headerlink" href="#caller-callee-coverage" title="Permalink to this headline">¶</a></h2>
+<p>(Experimental!)
+Every indirect function call is instrumented with a run-time function call that
+captures caller and callee. At the shutdown time the process dumps a separate
+file called <tt class="docutils literal"><span class="pre">caller-callee.PID.sancov</span></tt> which contains caller/callee pairs as
+pairs of lines (odd lines are callers, even lines are callees)</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="go">a.out 0x4a2e0c</span>
+<span class="go">a.out 0x4a6510</span>
+<span class="go">a.out 0x4a2e0c</span>
+<span class="go">a.out 0x4a87f0</span>
+</pre></div>
+</div>
+<p>Current limitations:</p>
+<ul class="simple">
+<li>Only the first 14 callees for every caller are recorded, the rest are silently
+ignored.</li>
+<li>The output format is not very compact since caller and callee may reside in
+different modules and we need to spell out the module names.</li>
+<li>The routine that dumps the output is not optimized for speed</li>
+<li>Only Linux x86_64 is tested so far.</li>
+<li>Sandboxes are not supported.</li>
+</ul>
+</div>
+<div class="section" id="coverage-counters">
+<h2><a class="toc-backref" href="#id10">Coverage counters</a><a class="headerlink" href="#coverage-counters" title="Permalink to this headline">¶</a></h2>
+<p>This experimental feature is inspired by
+<a class="reference external" href="http://lcamtuf.coredump.cx/afl/technical_details.txt">AFL</a>‘s coverage
+instrumentation. With additional compile-time and run-time flags you can get
+more sensitive coverage information. In addition to boolean values assigned to
+every basic block (edge) the instrumentation will collect imprecise counters.
+On exit, every counter will be mapped to a 8-bit bitset representing counter
+ranges: <tt class="docutils literal"><span class="pre">1,</span> <span class="pre">2,</span> <span class="pre">3,</span> <span class="pre">4-7,</span> <span class="pre">8-15,</span> <span class="pre">16-31,</span> <span class="pre">32-127,</span> <span class="pre">128+</span></tt> and those 8-bit bitsets will
+be dumped to disk.</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> clang++ -g cov.cc -fsanitize<span class="o">=</span>address -fsanitize-coverage<span class="o">=</span>edge,8bit-counters
+<span class="gp">%</span> <span class="nv">ASAN_OPTIONS</span><span class="o">=</span><span class="s2">"coverage=1:coverage_counters=1"</span> ./a.out
+<span class="gp">%</span> ls -l *counters-sancov
+<span class="go">... a.out.17110.counters-sancov</span>
+<span class="gp">%</span> xxd *counters-sancov
+<span class="go">0000000: 0001 0100 01</span>
+</pre></div>
+</div>
+<p>These counters may also be used for in-process coverage-guided fuzzers. See
+<tt class="docutils literal"><span class="pre">include/sanitizer/coverage_interface.h</span></tt>:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="c1">// The coverage instrumentation may optionally provide imprecise counters.</span>
+<span class="c1">// Rather than exposing the counter values to the user we instead map</span>
+<span class="c1">// the counters to a bitset.</span>
+<span class="c1">// Every counter is associated with 8 bits in the bitset.</span>
+<span class="c1">// We define 8 value ranges: 1, 2, 3, 4-7, 8-15, 16-31, 32-127, 128+</span>
+<span class="c1">// The i-th bit is set to 1 if the counter value is in the i-th range.</span>
+<span class="c1">// This counter-based coverage implementation is *not* thread-safe.</span>
+
+<span class="c1">// Returns the number of registered coverage counters.</span>
+<span class="kt">uintptr_t</span> <span class="nf">__sanitizer_get_number_of_counters</span><span class="p">();</span>
+<span class="c1">// Updates the counter 'bitset', clears the counters and returns the number of</span>
+<span class="c1">// new bits in 'bitset'.</span>
+<span class="c1">// If 'bitset' is nullptr, only clears the counters.</span>
+<span class="c1">// Otherwise 'bitset' should be at least</span>
+<span class="c1">// __sanitizer_get_number_of_counters bytes long and 8-aligned.</span>
+<span class="kt">uintptr_t</span>
+<span class="nf">__sanitizer_update_counter_bitset_and_clear_counters</span><span class="p">(</span><span class="kt">uint8_t</span> <span class="o">*</span><span class="n">bitset</span><span class="p">);</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="tracing-basic-blocks">
+<h2><a class="toc-backref" href="#id11">Tracing basic blocks</a><a class="headerlink" href="#tracing-basic-blocks" title="Permalink to this headline">¶</a></h2>
+<p>Experimental support for basic block (or edge) tracing.
+With <tt class="docutils literal"><span class="pre">-fsanitize-coverage=trace-bb</span></tt> the compiler will insert
+<tt class="docutils literal"><span class="pre">__sanitizer_cov_trace_basic_block(s32</span> <span class="pre">*id)</span></tt> before every function, basic block, or edge
+(depending on the value of <tt class="docutils literal"><span class="pre">-fsanitize-coverage=[func,bb,edge]</span></tt>).
+Example:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> clang -g -fsanitize<span class="o">=</span>address -fsanitize-coverage<span class="o">=</span>edge,trace-bb foo.cc
+<span class="gp">%</span> <span class="nv">ASAN_OPTIONS</span><span class="o">=</span><span class="nv">coverage</span><span class="o">=</span>1 ./a.out
+</pre></div>
+</div>
+<p>This will produce two files after the process exit:
+<cite>trace-points.PID.sancov</cite> and <cite>trace-events.PID.sancov</cite>.
+The first file will contain a textual description of all the instrumented points in the program
+in the form that you can feed into llvm-symbolizer (e.g. <cite>a.out 0x4dca89</cite>), one per line.
+The second file will contain the actual execution trace as a sequence of 4-byte integers
+– these integers are the indices into the array of instrumented points (the first file).</p>
+<p>Basic block tracing is currently supported only for single-threaded applications.</p>
+</div>
+<div class="section" id="tracing-pcs">
+<h2><a class="toc-backref" href="#id12">Tracing PCs</a><a class="headerlink" href="#tracing-pcs" title="Permalink to this headline">¶</a></h2>
+<p><em>Experimental</em> feature similar to tracing basic blocks, but with a different API.
+With <tt class="docutils literal"><span class="pre">-fsanitize-coverage=trace-pc</span></tt> the compiler will insert
+<tt class="docutils literal"><span class="pre">__sanitizer_cov_trace_pc()</span></tt> on every edge.
+With an additional <tt class="docutils literal"><span class="pre">...=trace-pc,indirect-calls</span></tt> flag
+<tt class="docutils literal"><span class="pre">__sanitizer_cov_trace_pc_indirect(void</span> <span class="pre">*callee)</span></tt> will be inserted on every indirect call.
+These callbacks are not implemented in the Sanitizer run-time and should be defined
+by the user. So, these flags do not require the other sanitizer to be used.
+This mechanism is used for fuzzing the Linux kernel (<a class="reference external" href="https://github.com/google/syzkaller">https://github.com/google/syzkaller</a>)
+and can be used with <a class="reference external" href="http://lcamtuf.coredump.cx/afl">AFL</a>.</p>
+</div>
+<div class="section" id="tracing-pcs-with-guards">
+<h2><a class="toc-backref" href="#id13">Tracing PCs with guards</a><a class="headerlink" href="#tracing-pcs-with-guards" title="Permalink to this headline">¶</a></h2>
+<p>Another <em>experimental</em> feature that tries to combine the functionality of <cite>trace-pc</cite>,
+<cite>8bit-counters</cite> and boolean coverage.</p>
+<p>With <tt class="docutils literal"><span class="pre">-fsanitize-coverage=trace-pc-guard</span></tt> the compiler will insert the following code
+on every edge:</p>
+<div class="highlight-none"><div class="highlight"><pre>if (guard_variable)
+ __sanitizer_cov_trace_pc_guard(&guard_variable)
+</pre></div>
+</div>
+<p>Every edge will have its own <cite>guard_variable</cite> (uint32_t).</p>
+<p>The compler will also insert a module constructor that will call</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="c1">// The guards are [start, stop).</span>
+<span class="c1">// This function may be called multiple times with the same values of start/stop.</span>
+<span class="n">__sanitizer_cov_trace_pc_guard_init</span><span class="p">(</span><span class="kt">uint32_t</span> <span class="o">*</span><span class="n">start</span><span class="p">,</span> <span class="kt">uint32_t</span> <span class="o">*</span><span class="n">stop</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>Similarly to <cite>trace-pc,indirect-calls</cite>, with <cite>trace-pc-guards,indirect-calls</cite>
+<tt class="docutils literal"><span class="pre">__sanitizer_cov_trace_pc_indirect(void</span> <span class="pre">*callee)</span></tt> will be inserted on every indirect call.</p>
+<p>The functions <cite>__sanitizer_cov_trace_pc_*</cite> should be defined by the user.</p>
+<p>Example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="c1">// trace-pc-guard-cb.cc</span>
+<span class="cp">#include <stdint.h></span>
+<span class="cp">#include <stdio.h></span>
+<span class="cp">#include <sanitizer/coverage_interface.h></span>
+
+<span class="c1">// This callback is inserted by the compiler as a module constructor</span>
+<span class="c1">// into every compilation unit. 'start' and 'stop' correspond to the</span>
+<span class="c1">// beginning and end of the section with the guards for the entire</span>
+<span class="c1">// binary (executable or DSO) and so it will be called multiple times</span>
+<span class="c1">// with the same parameters.</span>
+<span class="k">extern</span> <span class="s">"C"</span> <span class="kt">void</span> <span class="n">__sanitizer_cov_trace_pc_guard_init</span><span class="p">(</span><span class="kt">uint32_t</span> <span class="o">*</span><span class="n">start</span><span class="p">,</span>
+ <span class="kt">uint32_t</span> <span class="o">*</span><span class="n">stop</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">static</span> <span class="kt">uint64_t</span> <span class="n">N</span><span class="p">;</span> <span class="c1">// Counter for the guards.</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">start</span> <span class="o">==</span> <span class="n">stop</span> <span class="o">||</span> <span class="o">*</span><span class="n">start</span><span class="p">)</span> <span class="k">return</span><span class="p">;</span> <span class="c1">// Initialize only once.</span>
+ <span class="n">printf</span><span class="p">(</span><span class="s">"INIT: %p %p</span><span class="se">\n</span><span class="s">"</span><span class="p">,</span> <span class="n">start</span><span class="p">,</span> <span class="n">stop</span><span class="p">);</span>
+ <span class="k">for</span> <span class="p">(</span><span class="kt">uint32_t</span> <span class="o">*</span><span class="n">x</span> <span class="o">=</span> <span class="n">start</span><span class="p">;</span> <span class="n">x</span> <span class="o"><</span> <span class="n">stop</span><span class="p">;</span> <span class="n">x</span><span class="o">++</span><span class="p">)</span>
+ <span class="o">*</span><span class="n">x</span> <span class="o">=</span> <span class="o">++</span><span class="n">N</span><span class="p">;</span> <span class="c1">// Guards should start from 1.</span>
+<span class="p">}</span>
+
+<span class="c1">// This callback is inserted by the compiler on every edge in the</span>
+<span class="c1">// control flow (some optimizations apply).</span>
+<span class="c1">// Typically, the compiler will emit the code like this:</span>
+<span class="c1">// if(*guard)</span>
+<span class="c1">// __sanitizer_cov_trace_pc_guard(guard);</span>
+<span class="c1">// But for large functions it will emit a simple call:</span>
+<span class="c1">// __sanitizer_cov_trace_pc_guard(guard);</span>
+<span class="k">extern</span> <span class="s">"C"</span> <span class="kt">void</span> <span class="n">__sanitizer_cov_trace_pc_guard</span><span class="p">(</span><span class="kt">uint32_t</span> <span class="o">*</span><span class="n">guard</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">if</span> <span class="p">(</span><span class="o">!*</span><span class="n">guard</span><span class="p">)</span> <span class="k">return</span><span class="p">;</span> <span class="c1">// Duplicate the guard check.</span>
+ <span class="c1">// If you set *guard to 0 this code will not be called again for this edge.</span>
+ <span class="c1">// Now you can get the PC and do whatever you want:</span>
+ <span class="c1">// store it somewhere or symbolize it and print right away.</span>
+ <span class="c1">// The values of `*guard` are as you set them in</span>
+ <span class="c1">// __sanitizer_cov_trace_pc_guard_init and so you can make them consecutive</span>
+ <span class="c1">// and use them to dereference an array or a bit vector.</span>
+ <span class="kt">void</span> <span class="o">*</span><span class="n">PC</span> <span class="o">=</span> <span class="n">__builtin_return_address</span><span class="p">(</span><span class="mi">0</span><span class="p">);</span>
+ <span class="kt">char</span> <span class="n">PcDescr</span><span class="p">[</span><span class="mi">1024</span><span class="p">];</span>
+ <span class="c1">// This function is a part of the sanitizer run-time.</span>
+ <span class="c1">// To use it, link with AddressSanitizer or other sanitizer.</span>
+ <span class="n">__sanitizer_symbolize_pc</span><span class="p">(</span><span class="n">PC</span><span class="p">,</span> <span class="s">"%p %F %L"</span><span class="p">,</span> <span class="n">PcDescr</span><span class="p">,</span> <span class="k">sizeof</span><span class="p">(</span><span class="n">PcDescr</span><span class="p">));</span>
+ <span class="n">printf</span><span class="p">(</span><span class="s">"guard: %p %x PC %s</span><span class="se">\n</span><span class="s">"</span><span class="p">,</span> <span class="n">guard</span><span class="p">,</span> <span class="o">*</span><span class="n">guard</span><span class="p">,</span> <span class="n">PcDescr</span><span class="p">);</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<div class="highlight-c++"><div class="highlight"><pre><span class="c1">// trace-pc-guard-example.cc</span>
+<span class="kt">void</span> <span class="nf">foo</span><span class="p">()</span> <span class="p">{</span> <span class="p">}</span>
+<span class="kt">int</span> <span class="nf">main</span><span class="p">(</span><span class="kt">int</span> <span class="n">argc</span><span class="p">,</span> <span class="kt">char</span> <span class="o">**</span><span class="n">argv</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">argc</span> <span class="o">></span> <span class="mi">1</span><span class="p">)</span> <span class="n">foo</span><span class="p">();</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<div class="highlight-console"><div class="highlight"><pre><span class="go">clang++ -g -fsanitize-coverage=trace-pc-guard trace-pc-guard-example.cc -c</span>
+<span class="go">clang++ trace-pc-guard-cb.cc trace-pc-guard-example.o -fsanitize=address</span>
+<span class="go">ASAN_OPTIONS=strip_path_prefix=`pwd`/ ./a.out</span>
+</pre></div>
+</div>
+<div class="highlight-console"><div class="highlight"><pre><span class="go">INIT: 0x71bcd0 0x71bce0</span>
+<span class="go">guard: 0x71bcd4 2 PC 0x4ecd5b in main trace-pc-guard-example.cc:2</span>
+<span class="go">guard: 0x71bcd8 3 PC 0x4ecd9e in main trace-pc-guard-example.cc:3:7</span>
+</pre></div>
+</div>
+<div class="highlight-console"><div class="highlight"><pre><span class="go">ASAN_OPTIONS=strip_path_prefix=`pwd`/ ./a.out with-foo</span>
+</pre></div>
+</div>
+<div class="highlight-console"><div class="highlight"><pre><span class="go">INIT: 0x71bcd0 0x71bce0</span>
+<span class="go">guard: 0x71bcd4 2 PC 0x4ecd5b in main trace-pc-guard-example.cc:3</span>
+<span class="go">guard: 0x71bcdc 4 PC 0x4ecdc7 in main trace-pc-guard-example.cc:4:17</span>
+<span class="go">guard: 0x71bcd0 1 PC 0x4ecd20 in foo() trace-pc-guard-example.cc:2:14</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="tracing-data-flow">
+<h2><a class="toc-backref" href="#id14">Tracing data flow</a><a class="headerlink" href="#tracing-data-flow" title="Permalink to this headline">¶</a></h2>
+<p>Support for data-flow-guided fuzzing.
+With <tt class="docutils literal"><span class="pre">-fsanitize-coverage=trace-cmp</span></tt> the compiler will insert extra instrumentation
+around comparison instructions and switch statements.
+Similarly, with <tt class="docutils literal"><span class="pre">-fsanitize-coverage=trace-div</span></tt> the compiler will instrument
+integer division instructions (to capture the right argument of division)
+and with <tt class="docutils literal"><span class="pre">-fsanitize-coverage=trace-gep</span></tt> –
+the <a class="reference external" href="http://llvm.org/docs/GetElementPtr.html">LLVM GEP instructions</a>
+(to capture array indices).</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="c1">// Called before a comparison instruction.</span>
+<span class="c1">// Arg1 and Arg2 are arguments of the comparison.</span>
+<span class="kt">void</span> <span class="nf">__sanitizer_cov_trace_cmp1</span><span class="p">(</span><span class="kt">uint8_t</span> <span class="n">Arg1</span><span class="p">,</span> <span class="kt">uint8_t</span> <span class="n">Arg2</span><span class="p">);</span>
+<span class="kt">void</span> <span class="nf">__sanitizer_cov_trace_cmp2</span><span class="p">(</span><span class="kt">uint16_t</span> <span class="n">Arg1</span><span class="p">,</span> <span class="kt">uint16_t</span> <span class="n">Arg2</span><span class="p">);</span>
+<span class="kt">void</span> <span class="nf">__sanitizer_cov_trace_cmp4</span><span class="p">(</span><span class="kt">uint32_t</span> <span class="n">Arg1</span><span class="p">,</span> <span class="kt">uint32_t</span> <span class="n">Arg2</span><span class="p">);</span>
+<span class="kt">void</span> <span class="nf">__sanitizer_cov_trace_cmp8</span><span class="p">(</span><span class="kt">uint64_t</span> <span class="n">Arg1</span><span class="p">,</span> <span class="kt">uint64_t</span> <span class="n">Arg2</span><span class="p">);</span>
+
+<span class="c1">// Called before a switch statement.</span>
+<span class="c1">// Val is the switch operand.</span>
+<span class="c1">// Cases[0] is the number of case constants.</span>
+<span class="c1">// Cases[1] is the size of Val in bits.</span>
+<span class="c1">// Cases[2:] are the case constants.</span>
+<span class="kt">void</span> <span class="nf">__sanitizer_cov_trace_switch</span><span class="p">(</span><span class="kt">uint64_t</span> <span class="n">Val</span><span class="p">,</span> <span class="kt">uint64_t</span> <span class="o">*</span><span class="n">Cases</span><span class="p">);</span>
+
+<span class="c1">// Called before a division statement.</span>
+<span class="c1">// Val is the second argument of division.</span>
+<span class="kt">void</span> <span class="nf">__sanitizer_cov_trace_div4</span><span class="p">(</span><span class="kt">uint32_t</span> <span class="n">Val</span><span class="p">);</span>
+<span class="kt">void</span> <span class="nf">__sanitizer_cov_trace_div8</span><span class="p">(</span><span class="kt">uint64_t</span> <span class="n">Val</span><span class="p">);</span>
+
+<span class="c1">// Called before a GetElemementPtr (GEP) instruction</span>
+<span class="c1">// for every non-constant array index.</span>
+<span class="kt">void</span> <span class="nf">__sanitizer_cov_trace_gep</span><span class="p">(</span><span class="kt">uintptr_t</span> <span class="n">Idx</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>This interface is a subject to change.
+The current implementation is not thread-safe and thus can be safely used only for single-threaded targets.</p>
+</div>
+<div class="section" id="output-directory">
+<h2><a class="toc-backref" href="#id15">Output directory</a><a class="headerlink" href="#output-directory" title="Permalink to this headline">¶</a></h2>
+<p>By default, .sancov files are created in the current working directory.
+This can be changed with <tt class="docutils literal"><span class="pre">ASAN_OPTIONS=coverage_dir=/path</span></tt>:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> <span class="nv">ASAN_OPTIONS</span><span class="o">=</span><span class="s2">"coverage=1:coverage_dir=/tmp/cov"</span> ./a.out foo
+<span class="gp">%</span> ls -l /tmp/cov/*sancov
+<span class="go">-rw-r----- 1 kcc eng 4 Nov 27 12:21 a.out.22673.sancov</span>
+<span class="go">-rw-r----- 1 kcc eng 8 Nov 27 12:21 a.out.22679.sancov</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="sudden-death">
+<h2><a class="toc-backref" href="#id16">Sudden death</a><a class="headerlink" href="#sudden-death" title="Permalink to this headline">¶</a></h2>
+<p>Normally, coverage data is collected in memory and saved to disk when the
+program exits (with an <tt class="docutils literal"><span class="pre">atexit()</span></tt> handler), when a SIGSEGV is caught, or when
+<tt class="docutils literal"><span class="pre">__sanitizer_cov_dump()</span></tt> is called.</p>
+<p>If the program ends with a signal that ASan does not handle (or can not handle
+at all, like SIGKILL), coverage data will be lost. This is a big problem on
+Android, where SIGKILL is a normal way of evicting applications from memory.</p>
+<p>With <tt class="docutils literal"><span class="pre">ASAN_OPTIONS=coverage=1:coverage_direct=1</span></tt> coverage data is written to a
+memory-mapped file as soon as it collected.</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> <span class="nv">ASAN_OPTIONS</span><span class="o">=</span><span class="s2">"coverage=1:coverage_direct=1"</span> ./a.out
+<span class="go">main</span>
+<span class="gp">%</span> ls
+<span class="go">7036.sancov.map 7036.sancov.raw a.out</span>
+<span class="gp">%</span> sancov.py rawunpack 7036.sancov.raw
+<span class="go">sancov.py: reading map 7036.sancov.map</span>
+<span class="go">sancov.py: unpacking 7036.sancov.raw</span>
+<span class="go">writing 1 PCs to a.out.7036.sancov</span>
+<span class="gp">%</span> sancov.py print a.out.7036.sancov
+<span class="go">sancov.py: read 1 PCs from a.out.7036.sancov</span>
+<span class="go">sancov.py: 1 files merged; 1 PCs total</span>
+<span class="go">0x4b2bae</span>
+</pre></div>
+</div>
+<p>Note that on 64-bit platforms, this method writes 2x more data than the default,
+because it stores full PC values instead of 32-bit offsets.</p>
+</div>
+<div class="section" id="in-process-fuzzing">
+<h2><a class="toc-backref" href="#id17">In-process fuzzing</a><a class="headerlink" href="#in-process-fuzzing" title="Permalink to this headline">¶</a></h2>
+<p>Coverage data could be useful for fuzzers and sometimes it is preferable to run
+a fuzzer in the same process as the code being fuzzed (in-process fuzzer).</p>
+<p>You can use <tt class="docutils literal"><span class="pre">__sanitizer_get_total_unique_coverage()</span></tt> from
+<tt class="docutils literal"><span class="pre"><sanitizer/coverage_interface.h></span></tt> which returns the number of currently
+covered entities in the program. This will tell the fuzzer if the coverage has
+increased after testing every new input.</p>
+<p>If a fuzzer finds a bug in the ASan run, you will need to save the reproducer
+before exiting the process. Use <tt class="docutils literal"><span class="pre">__asan_set_death_callback</span></tt> from
+<tt class="docutils literal"><span class="pre"><sanitizer/asan_interface.h></span></tt> to do that.</p>
+<p>An example of such fuzzer can be found in <a class="reference external" href="http://llvm.org/viewvc/llvm-project/llvm/trunk/lib/Fuzzer/README.txt?view=markup">the LLVM tree</a>.</p>
+</div>
+<div class="section" id="performance">
+<h2><a class="toc-backref" href="#id18">Performance</a><a class="headerlink" href="#performance" title="Permalink to this headline">¶</a></h2>
+<p>This coverage implementation is <strong>fast</strong>. With function-level coverage
+(<tt class="docutils literal"><span class="pre">-fsanitize-coverage=func</span></tt>) the overhead is not measurable. With
+basic-block-level coverage (<tt class="docutils literal"><span class="pre">-fsanitize-coverage=bb</span></tt>) the overhead varies
+between 0 and 25%.</p>
+<table border="1" class="docutils">
+<colgroup>
+<col width="21%" />
+<col width="13%" />
+<col width="13%" />
+<col width="13%" />
+<col width="13%" />
+<col width="13%" />
+<col width="13%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">benchmark</th>
+<th class="head">cov0</th>
+<th class="head">cov1</th>
+<th class="head">diff 0-1</th>
+<th class="head">cov2</th>
+<th class="head">diff 0-2</th>
+<th class="head">diff 1-2</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>400.perlbench</td>
+<td>1296.00</td>
+<td>1307.00</td>
+<td>1.01</td>
+<td>1465.00</td>
+<td>1.13</td>
+<td>1.12</td>
+</tr>
+<tr class="row-odd"><td>401.bzip2</td>
+<td>858.00</td>
+<td>854.00</td>
+<td>1.00</td>
+<td>1010.00</td>
+<td>1.18</td>
+<td>1.18</td>
+</tr>
+<tr class="row-even"><td>403.gcc</td>
+<td>613.00</td>
+<td>617.00</td>
+<td>1.01</td>
+<td>683.00</td>
+<td>1.11</td>
+<td>1.11</td>
+</tr>
+<tr class="row-odd"><td>429.mcf</td>
+<td>605.00</td>
+<td>582.00</td>
+<td>0.96</td>
+<td>610.00</td>
+<td>1.01</td>
+<td>1.05</td>
+</tr>
+<tr class="row-even"><td>445.gobmk</td>
+<td>896.00</td>
+<td>880.00</td>
+<td>0.98</td>
+<td>1050.00</td>
+<td>1.17</td>
+<td>1.19</td>
+</tr>
+<tr class="row-odd"><td>456.hmmer</td>
+<td>892.00</td>
+<td>892.00</td>
+<td>1.00</td>
+<td>918.00</td>
+<td>1.03</td>
+<td>1.03</td>
+</tr>
+<tr class="row-even"><td>458.sjeng</td>
+<td>995.00</td>
+<td>1009.00</td>
+<td>1.01</td>
+<td>1217.00</td>
+<td>1.22</td>
+<td>1.21</td>
+</tr>
+<tr class="row-odd"><td>462.libquantum</td>
+<td>497.00</td>
+<td>492.00</td>
+<td>0.99</td>
+<td>534.00</td>
+<td>1.07</td>
+<td>1.09</td>
+</tr>
+<tr class="row-even"><td>464.h264ref</td>
+<td>1461.00</td>
+<td>1467.00</td>
+<td>1.00</td>
+<td>1543.00</td>
+<td>1.06</td>
+<td>1.05</td>
+</tr>
+<tr class="row-odd"><td>471.omnetpp</td>
+<td>575.00</td>
+<td>590.00</td>
+<td>1.03</td>
+<td>660.00</td>
+<td>1.15</td>
+<td>1.12</td>
+</tr>
+<tr class="row-even"><td>473.astar</td>
+<td>658.00</td>
+<td>652.00</td>
+<td>0.99</td>
+<td>715.00</td>
+<td>1.09</td>
+<td>1.10</td>
+</tr>
+<tr class="row-odd"><td>483.xalancbmk</td>
+<td>471.00</td>
+<td>491.00</td>
+<td>1.04</td>
+<td>582.00</td>
+<td>1.24</td>
+<td>1.19</td>
+</tr>
+<tr class="row-even"><td>433.milc</td>
+<td>616.00</td>
+<td>627.00</td>
+<td>1.02</td>
+<td>627.00</td>
+<td>1.02</td>
+<td>1.00</td>
+</tr>
+<tr class="row-odd"><td>444.namd</td>
+<td>602.00</td>
+<td>601.00</td>
+<td>1.00</td>
+<td>654.00</td>
+<td>1.09</td>
+<td>1.09</td>
+</tr>
+<tr class="row-even"><td>447.dealII</td>
+<td>630.00</td>
+<td>634.00</td>
+<td>1.01</td>
+<td>653.00</td>
+<td>1.04</td>
+<td>1.03</td>
+</tr>
+<tr class="row-odd"><td>450.soplex</td>
+<td>365.00</td>
+<td>368.00</td>
+<td>1.01</td>
+<td>395.00</td>
+<td>1.08</td>
+<td>1.07</td>
+</tr>
+<tr class="row-even"><td>453.povray</td>
+<td>427.00</td>
+<td>434.00</td>
+<td>1.02</td>
+<td>495.00</td>
+<td>1.16</td>
+<td>1.14</td>
+</tr>
+<tr class="row-odd"><td>470.lbm</td>
+<td>357.00</td>
+<td>375.00</td>
+<td>1.05</td>
+<td>370.00</td>
+<td>1.04</td>
+<td>0.99</td>
+</tr>
+<tr class="row-even"><td>482.sphinx3</td>
+<td>927.00</td>
+<td>928.00</td>
+<td>1.00</td>
+<td>1000.00</td>
+<td>1.08</td>
+<td>1.08</td>
+</tr>
+</tbody>
+</table>
+</div>
+<div class="section" id="why-another-coverage">
+<h2><a class="toc-backref" href="#id19">Why another coverage?</a><a class="headerlink" href="#why-another-coverage" title="Permalink to this headline">¶</a></h2>
+<dl class="docutils">
+<dt>Why did we implement yet another code coverage?</dt>
+<dd><ul class="first last simple">
+<li>We needed something that is lightning fast, plays well with
+AddressSanitizer, and does not significantly increase the binary size.</li>
+<li>Traditional coverage implementations based in global counters
+<a class="reference external" href="https://groups.google.com/forum/#!topic/llvm-dev/cDqYgnxNEhY">suffer from contention on counters</a>.</li>
+</ul>
+</dd>
+</dl>
+</div>
+</div>
+
+
+ </div>
+ <div class="bottomnav">
+
+ <p>
+ « <a href="LeakSanitizer.html">LeakSanitizer</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="SanitizerStats.html">SanitizerStats</a> »
+ </p>
+
+ </div>
+
+ <div class="footer">
+ © Copyright 2007-2017, The Clang Team.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/4.0.0/tools/clang/docs/SanitizerSpecialCaseList.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/4.0.0/tools/clang/docs/SanitizerSpecialCaseList.html?rev=297634&view=auto
==============================================================================
--- www-releases/trunk/4.0.0/tools/clang/docs/SanitizerSpecialCaseList.html (added)
+++ www-releases/trunk/4.0.0/tools/clang/docs/SanitizerSpecialCaseList.html Mon Mar 13 11:30:12 2017
@@ -0,0 +1,149 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>Sanitizer special case list — Clang 4 documentation</title>
+
+ <link rel="stylesheet" href="_static/haiku.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: './',
+ VERSION: '4',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+ <link rel="top" title="Clang 4 documentation" href="index.html" />
+ <link rel="next" title="Control Flow Integrity" href="ControlFlowIntegrity.html" />
+ <link rel="prev" title="SanitizerStats" href="SanitizerStats.html" />
+ </head>
+ <body>
+ <div class="header"><h1 class="heading"><a href="index.html">
+ <span>Clang 4 documentation</span></a></h1>
+ <h2 class="heading"><span>Sanitizer special case list</span></h2>
+ </div>
+ <div class="topnav">
+
+ <p>
+ « <a href="SanitizerStats.html">SanitizerStats</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="ControlFlowIntegrity.html">Control Flow Integrity</a> »
+ </p>
+
+ </div>
+ <div class="content">
+
+
+ <div class="section" id="sanitizer-special-case-list">
+<h1>Sanitizer special case list<a class="headerlink" href="#sanitizer-special-case-list" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#introduction" id="id1">Introduction</a></li>
+<li><a class="reference internal" href="#goal-and-usage" id="id2">Goal and usage</a></li>
+<li><a class="reference internal" href="#example" id="id3">Example</a></li>
+<li><a class="reference internal" href="#format" id="id4">Format</a></li>
+</ul>
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id1">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>This document describes the way to disable or alter the behavior of
+sanitizer tools for certain source-level entities by providing a special
+file at compile-time.</p>
+</div>
+<div class="section" id="goal-and-usage">
+<h2><a class="toc-backref" href="#id2">Goal and usage</a><a class="headerlink" href="#goal-and-usage" title="Permalink to this headline">¶</a></h2>
+<p>User of sanitizer tools, such as <a class="reference internal" href="AddressSanitizer.html"><em>AddressSanitizer</em></a>, <a class="reference internal" href="ThreadSanitizer.html"><em>ThreadSanitizer</em></a>
+or <a class="reference internal" href="MemorySanitizer.html"><em>MemorySanitizer</em></a> may want to disable or alter some checks for
+certain source-level entities to:</p>
+<ul class="simple">
+<li>speedup hot function, which is known to be correct;</li>
+<li>ignore a function that does some low-level magic (e.g. walks through the
+thread stack, bypassing the frame boundaries);</li>
+<li>ignore a known problem.</li>
+</ul>
+<p>To achieve this, user may create a file listing the entities they want to
+ignore, and pass it to clang at compile-time using
+<tt class="docutils literal"><span class="pre">-fsanitize-blacklist</span></tt> flag. See <a class="reference internal" href="UsersManual.html"><em>Clang Compiler User’s Manual</em></a> for details.</p>
+</div>
+<div class="section" id="example">
+<h2><a class="toc-backref" href="#id3">Example</a><a class="headerlink" href="#example" title="Permalink to this headline">¶</a></h2>
+<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>cat foo.c
+<span class="c">#include <stdlib.h></span>
+void bad_foo<span class="o">()</span> <span class="o">{</span>
+ int *a <span class="o">=</span> <span class="o">(</span>int*<span class="o">)</span>malloc<span class="o">(</span>40<span class="o">)</span>;
+ a<span class="o">[</span>10<span class="o">]</span> <span class="o">=</span> 1;
+<span class="o">}</span>
+int main<span class="o">()</span> <span class="o">{</span> bad_foo<span class="o">()</span>; <span class="o">}</span>
+<span class="nv">$ </span>cat blacklist.txt
+<span class="c"># Ignore reports from bad_foo function.</span>
+fun:bad_foo
+<span class="nv">$ </span>clang -fsanitize<span class="o">=</span>address foo.c ; ./a.out
+<span class="c"># AddressSanitizer prints an error report.</span>
+<span class="nv">$ </span>clang -fsanitize<span class="o">=</span>address -fsanitize-blacklist<span class="o">=</span>blacklist.txt foo.c ; ./a.out
+<span class="c"># No error report here.</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="format">
+<h2><a class="toc-backref" href="#id4">Format</a><a class="headerlink" href="#format" title="Permalink to this headline">¶</a></h2>
+<p>Each line contains an entity type, followed by a colon and a regular
+expression, specifying the names of the entities, optionally followed by
+an equals sign and a tool-specific category. Empty lines and lines starting
+with “#” are ignored. The meanining of <tt class="docutils literal"><span class="pre">*</span></tt> in regular expression for entity
+names is different - it is treated as in shell wildcarding. Two generic
+entity types are <tt class="docutils literal"><span class="pre">src</span></tt> and <tt class="docutils literal"><span class="pre">fun</span></tt>, which allow user to add, respectively,
+source files and functions to special case list. Some sanitizer tools may
+introduce custom entity types - refer to tool-specific docs.</p>
+<div class="highlight-bash"><div class="highlight"><pre><span class="c"># Lines starting with # are ignored.</span>
+<span class="c"># Turn off checks for the source file (use absolute path or path relative</span>
+<span class="c"># to the current working directory):</span>
+src:/path/to/source/file.c
+<span class="c"># Turn off checks for a particular functions (use mangled names):</span>
+fun:MyFooBar
+fun:_Z8MyFooBarv
+<span class="c"># Extended regular expressions are supported:</span>
+fun:bad_<span class="o">(</span>foo|bar<span class="o">)</span>
+src:bad_source<span class="o">[</span>1-9<span class="o">]</span>.c
+<span class="c"># Shell like usage of * is supported (* is treated as .*):</span>
+src:bad/sources/*
+fun:*BadFunction*
+<span class="c"># Specific sanitizer tools may introduce categories.</span>
+src:/special/path/*<span class="o">=</span>special_sources
+</pre></div>
+</div>
+</div>
+</div>
+
+
+ </div>
+ <div class="bottomnav">
+
+ <p>
+ « <a href="SanitizerStats.html">SanitizerStats</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="ControlFlowIntegrity.html">Control Flow Integrity</a> »
+ </p>
+
+ </div>
+
+ <div class="footer">
+ © Copyright 2007-2017, The Clang Team.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/4.0.0/tools/clang/docs/SanitizerStats.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/4.0.0/tools/clang/docs/SanitizerStats.html?rev=297634&view=auto
==============================================================================
--- www-releases/trunk/4.0.0/tools/clang/docs/SanitizerStats.html (added)
+++ www-releases/trunk/4.0.0/tools/clang/docs/SanitizerStats.html Mon Mar 13 11:30:12 2017
@@ -0,0 +1,130 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>SanitizerStats — Clang 4 documentation</title>
+
+ <link rel="stylesheet" href="_static/haiku.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: './',
+ VERSION: '4',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+ <link rel="top" title="Clang 4 documentation" href="index.html" />
+ <link rel="next" title="Sanitizer special case list" href="SanitizerSpecialCaseList.html" />
+ <link rel="prev" title="SanitizerCoverage" href="SanitizerCoverage.html" />
+ </head>
+ <body>
+ <div class="header"><h1 class="heading"><a href="index.html">
+ <span>Clang 4 documentation</span></a></h1>
+ <h2 class="heading"><span>SanitizerStats</span></h2>
+ </div>
+ <div class="topnav">
+
+ <p>
+ « <a href="SanitizerCoverage.html">SanitizerCoverage</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="SanitizerSpecialCaseList.html">Sanitizer special case list</a> »
+ </p>
+
+ </div>
+ <div class="content">
+
+
+ <div class="section" id="sanitizerstats">
+<h1>SanitizerStats<a class="headerlink" href="#sanitizerstats" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#introduction" id="id1">Introduction</a></li>
+<li><a class="reference internal" href="#how-to-build-and-run" id="id2">How to build and run</a></li>
+</ul>
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id1">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>The sanitizers support a simple mechanism for gathering profiling statistics
+to help understand the overhead associated with sanitizers.</p>
+</div>
+<div class="section" id="how-to-build-and-run">
+<h2><a class="toc-backref" href="#id2">How to build and run</a><a class="headerlink" href="#how-to-build-and-run" title="Permalink to this headline">¶</a></h2>
+<p>SanitizerStats can currently only be used with <a class="reference internal" href="ControlFlowIntegrity.html"><em>Control Flow Integrity</em></a>.
+In addition to <tt class="docutils literal"><span class="pre">-fsanitize=cfi*</span></tt>, pass the <tt class="docutils literal"><span class="pre">-fsanitize-stats</span></tt> flag.
+This will cause the program to count the number of times that each control
+flow integrity check in the program fires.</p>
+<p>At run time, set the <tt class="docutils literal"><span class="pre">SANITIZER_STATS_PATH</span></tt> environment variable to direct
+statistics output to a file. The file will be written on process exit.
+The following substitutions will be applied to the environment variable:</p>
+<blockquote>
+<div><ul class="simple">
+<li><tt class="docutils literal"><span class="pre">%b</span></tt> – The executable basename.</li>
+<li><tt class="docutils literal"><span class="pre">%p</span></tt> – The process ID.</li>
+</ul>
+</div></blockquote>
+<p>You can also send the <tt class="docutils literal"><span class="pre">SIGUSR2</span></tt> signal to a process to make it write
+sanitizer statistics immediately.</p>
+<p>The <tt class="docutils literal"><span class="pre">sanstats</span></tt> program can be used to dump statistics. It takes as a
+command line argument the path to a statistics file produced by a program
+compiled with <tt class="docutils literal"><span class="pre">-fsanitize-stats</span></tt>.</p>
+<p>The output of <tt class="docutils literal"><span class="pre">sanstats</span></tt> is in four columns, separated by spaces. The first
+column is the file and line number of the call site. The second column is
+the function name. The third column is the type of statistic gathered (in
+this case, the type of control flow integrity check). The fourth column is
+the call count.</p>
+<p>Example:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> cat -n vcall.cc
+<span class="go"> 1 struct A {</span>
+<span class="go"> 2 virtual void f() {}</span>
+<span class="go"> 3 };</span>
+<span class="go"> 4</span>
+<span class="go"> 5 __attribute__((noinline)) void g(A *a) {</span>
+<span class="go"> 6 a->f();</span>
+<span class="go"> 7 }</span>
+<span class="go"> 8</span>
+<span class="go"> 9 int main() {</span>
+<span class="go"> 10 A a;</span>
+<span class="go"> 11 g(&a);</span>
+<span class="go"> 12 }</span>
+<span class="gp">$</span> clang++ -fsanitize<span class="o">=</span>cfi -flto -fuse-ld<span class="o">=</span>gold vcall.cc -fsanitize-stats -g
+<span class="gp">$</span> <span class="nv">SANITIZER_STATS_PATH</span><span class="o">=</span>a.stats ./a.out
+<span class="gp">$</span> sanstats a.stats
+<span class="go">vcall.cc:6 _Z1gP1A cfi-vcall 1</span>
+</pre></div>
+</div>
+</div>
+</div>
+
+
+ </div>
+ <div class="bottomnav">
+
+ <p>
+ « <a href="SanitizerCoverage.html">SanitizerCoverage</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="SanitizerSpecialCaseList.html">Sanitizer special case list</a> »
+ </p>
+
+ </div>
+
+ <div class="footer">
+ © Copyright 2007-2017, The Clang Team.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/4.0.0/tools/clang/docs/SourceBasedCodeCoverage.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/4.0.0/tools/clang/docs/SourceBasedCodeCoverage.html?rev=297634&view=auto
==============================================================================
--- www-releases/trunk/4.0.0/tools/clang/docs/SourceBasedCodeCoverage.html (added)
+++ www-releases/trunk/4.0.0/tools/clang/docs/SourceBasedCodeCoverage.html Mon Mar 13 11:30:12 2017
@@ -0,0 +1,335 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>Source-based Code Coverage — Clang 4 documentation</title>
+
+ <link rel="stylesheet" href="_static/haiku.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: './',
+ VERSION: '4',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+ <link rel="top" title="Clang 4 documentation" href="index.html" />
+ <link rel="next" title="Modules" href="Modules.html" />
+ <link rel="prev" title="SafeStack" href="SafeStack.html" />
+ </head>
+ <body>
+ <div class="header"><h1 class="heading"><a href="index.html">
+ <span>Clang 4 documentation</span></a></h1>
+ <h2 class="heading"><span>Source-based Code Coverage</span></h2>
+ </div>
+ <div class="topnav">
+
+ <p>
+ « <a href="SafeStack.html">SafeStack</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="Modules.html">Modules</a> »
+ </p>
+
+ </div>
+ <div class="content">
+
+
+ <div class="section" id="source-based-code-coverage">
+<h1>Source-based Code Coverage<a class="headerlink" href="#source-based-code-coverage" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#introduction" id="id1">Introduction</a></li>
+<li><a class="reference internal" href="#the-code-coverage-workflow" id="id2">The code coverage workflow</a></li>
+<li><a class="reference internal" href="#compiling-with-coverage-enabled" id="id3">Compiling with coverage enabled</a></li>
+<li><a class="reference internal" href="#running-the-instrumented-program" id="id4">Running the instrumented program</a></li>
+<li><a class="reference internal" href="#creating-coverage-reports" id="id5">Creating coverage reports</a></li>
+<li><a class="reference internal" href="#exporting-coverage-data" id="id6">Exporting coverage data</a></li>
+<li><a class="reference internal" href="#interpreting-reports" id="id7">Interpreting reports</a></li>
+<li><a class="reference internal" href="#format-compatibility-guarantees" id="id8">Format compatibility guarantees</a></li>
+<li><a class="reference internal" href="#using-the-profiling-runtime-without-static-initializers" id="id9">Using the profiling runtime without static initializers</a></li>
+<li><a class="reference internal" href="#collecting-coverage-reports-for-the-llvm-project" id="id10">Collecting coverage reports for the llvm project</a></li>
+<li><a class="reference internal" href="#drawbacks-and-limitations" id="id11">Drawbacks and limitations</a></li>
+</ul>
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id1">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>This document explains how to use clang’s source-based code coverage feature.
+It’s called “source-based” because it operates on AST and preprocessor
+information directly. This allows it to generate very precise coverage data.</p>
+<p>Clang ships two other code coverage implementations:</p>
+<ul class="simple">
+<li><a class="reference internal" href="SanitizerCoverage.html"><em>SanitizerCoverage</em></a> - A low-overhead tool meant for use alongside the
+various sanitizers. It can provide up to edge-level coverage.</li>
+<li>gcov - A GCC-compatible coverage implementation which operates on DebugInfo.</li>
+</ul>
+<p>From this point onwards “code coverage” will refer to the source-based kind.</p>
+</div>
+<div class="section" id="the-code-coverage-workflow">
+<h2><a class="toc-backref" href="#id2">The code coverage workflow</a><a class="headerlink" href="#the-code-coverage-workflow" title="Permalink to this headline">¶</a></h2>
+<p>The code coverage workflow consists of three main steps:</p>
+<ul class="simple">
+<li>Compiling with coverage enabled.</li>
+<li>Running the instrumented program.</li>
+<li>Creating coverage reports.</li>
+</ul>
+<p>The next few sections work through a complete, copy-‘n-paste friendly example
+based on this program:</p>
+<div class="highlight-cpp"><div class="highlight"><pre><span class="o">%</span> <span class="n">cat</span> <span class="o"><<</span><span class="n">EOF</span> <span class="o">></span> <span class="n">foo</span><span class="p">.</span><span class="n">cc</span>
+<span class="cp">#define BAR(x) ((x) || (x))</span>
+<span class="k">template</span> <span class="o"><</span><span class="k">typename</span> <span class="n">T</span><span class="o">></span> <span class="kt">void</span> <span class="n">foo</span><span class="p">(</span><span class="n">T</span> <span class="n">x</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">for</span> <span class="p">(</span><span class="kt">unsigned</span> <span class="n">I</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="n">I</span> <span class="o"><</span> <span class="mi">10</span><span class="p">;</span> <span class="o">++</span><span class="n">I</span><span class="p">)</span> <span class="p">{</span> <span class="n">BAR</span><span class="p">(</span><span class="n">I</span><span class="p">);</span> <span class="p">}</span>
+<span class="p">}</span>
+<span class="kt">int</span> <span class="n">main</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">foo</span><span class="o"><</span><span class="kt">int</span><span class="o">></span><span class="p">(</span><span class="mi">0</span><span class="p">);</span>
+ <span class="n">foo</span><span class="o"><</span><span class="kt">float</span><span class="o">></span><span class="p">(</span><span class="mi">0</span><span class="p">);</span>
+ <span class="k">return</span> <span class="mi">0</span><span class="p">;</span>
+<span class="p">}</span>
+<span class="n">EOF</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="compiling-with-coverage-enabled">
+<h2><a class="toc-backref" href="#id3">Compiling with coverage enabled</a><a class="headerlink" href="#compiling-with-coverage-enabled" title="Permalink to this headline">¶</a></h2>
+<p>To compile code with coverage enabled, pass <tt class="docutils literal"><span class="pre">-fprofile-instr-generate</span>
+<span class="pre">-fcoverage-mapping</span></tt> to the compiler:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">#</span> Step 1: Compile with coverage enabled.
+<span class="gp">%</span> clang++ -fprofile-instr-generate -fcoverage-mapping foo.cc -o foo
+</pre></div>
+</div>
+<p>Note that linking together code with and without coverage instrumentation is
+supported. Uninstrumented code simply won’t be accounted for in reports.</p>
+</div>
+<div class="section" id="running-the-instrumented-program">
+<h2><a class="toc-backref" href="#id4">Running the instrumented program</a><a class="headerlink" href="#running-the-instrumented-program" title="Permalink to this headline">¶</a></h2>
+<p>The next step is to run the instrumented program. When the program exits it
+will write a <strong>raw profile</strong> to the path specified by the <tt class="docutils literal"><span class="pre">LLVM_PROFILE_FILE</span></tt>
+environment variable. If that variable does not exist, the profile is written
+to <tt class="docutils literal"><span class="pre">default.profraw</span></tt> in the current directory of the program. If
+<tt class="docutils literal"><span class="pre">LLVM_PROFILE_FILE</span></tt> contains a path to a non-existent directory, the missing
+directory structure will be created. Additionally, the following special
+<strong>pattern strings</strong> are rewritten:</p>
+<ul class="simple">
+<li>“%p” expands out to the process ID.</li>
+<li>“%h” expands out to the hostname of the machine running the program.</li>
+<li>“%Nm” expands out to the instrumented binary’s signature. When this pattern
+is specified, the runtime creates a pool of N raw profiles which are used for
+on-line profile merging. The runtime takes care of selecting a raw profile
+from the pool, locking it, and updating it before the program exits. If N is
+not specified (i.e the pattern is “%m”), it’s assumed that <tt class="docutils literal"><span class="pre">N</span> <span class="pre">=</span> <span class="pre">1</span></tt>. N must
+be between 1 and 9. The merge pool specifier can only occur once per filename
+pattern.</li>
+</ul>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">#</span> Step 2: Run the program.
+<span class="gp">%</span> <span class="nv">LLVM_PROFILE_FILE</span><span class="o">=</span><span class="s2">"foo.profraw"</span> ./foo
+</pre></div>
+</div>
+</div>
+<div class="section" id="creating-coverage-reports">
+<h2><a class="toc-backref" href="#id5">Creating coverage reports</a><a class="headerlink" href="#creating-coverage-reports" title="Permalink to this headline">¶</a></h2>
+<p>Raw profiles have to be <strong>indexed</strong> before they can be used to generate
+coverage reports. This is done using the “merge” tool in <tt class="docutils literal"><span class="pre">llvm-profdata</span></tt>
+(which can combine multiple raw profiles and index them at the same time):</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">#</span> Step 3<span class="o">(</span>a<span class="o">)</span>: Index the raw profile.
+<span class="gp">%</span> llvm-profdata merge -sparse foo.profraw -o foo.profdata
+</pre></div>
+</div>
+<p>There are multiple different ways to render coverage reports. The simplest
+option is to generate a line-oriented report:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">#</span> Step 3<span class="o">(</span>b<span class="o">)</span>: Create a line-oriented coverage report.
+<span class="gp">%</span> llvm-cov show ./foo -instr-profile<span class="o">=</span>foo.profdata
+</pre></div>
+</div>
+<p>This report includes a summary view as well as dedicated sub-views for
+templated functions and their instantiations. For our example program, we get
+distinct views for <tt class="docutils literal"><span class="pre">foo<int>(...)</span></tt> and <tt class="docutils literal"><span class="pre">foo<float>(...)</span></tt>. If
+<tt class="docutils literal"><span class="pre">-show-line-counts-or-regions</span></tt> is enabled, <tt class="docutils literal"><span class="pre">llvm-cov</span></tt> displays sub-line
+region counts (even in macro expansions):</p>
+<div class="highlight-none"><div class="highlight"><pre> 1| 20|#define BAR(x) ((x) || (x))
+ ^20 ^2
+ 2| 2|template <typename T> void foo(T x) {
+ 3| 22| for (unsigned I = 0; I < 10; ++I) { BAR(I); }
+ ^22 ^20 ^20^20
+ 4| 2|}
+------------------
+| void foo<int>(int):
+| 2| 1|template <typename T> void foo(T x) {
+| 3| 11| for (unsigned I = 0; I < 10; ++I) { BAR(I); }
+| ^11 ^10 ^10^10
+| 4| 1|}
+------------------
+| void foo<float>(int):
+| 2| 1|template <typename T> void foo(T x) {
+| 3| 11| for (unsigned I = 0; I < 10; ++I) { BAR(I); }
+| ^11 ^10 ^10^10
+| 4| 1|}
+------------------
+</pre></div>
+</div>
+<p>To generate a file-level summary of coverage statistics instead of a
+line-oriented report, try:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">#</span> Step 3<span class="o">(</span>c<span class="o">)</span>: Create a coverage summary.
+<span class="gp">%</span> llvm-cov report ./foo -instr-profile<span class="o">=</span>foo.profdata
+<span class="go">Filename Regions Missed Regions Cover Functions Missed Functions Executed Lines Missed Lines Cover</span>
+<span class="go">--------------------------------------------------------------------------------------------------------------------------------------</span>
+<span class="go">/tmp/foo.cc 13 0 100.00% 3 0 100.00% 13 0 100.00%</span>
+<span class="go">--------------------------------------------------------------------------------------------------------------------------------------</span>
+<span class="go">TOTAL 13 0 100.00% 3 0 100.00% 13 0 100.00%</span>
+</pre></div>
+</div>
+<p>The <tt class="docutils literal"><span class="pre">llvm-cov</span></tt> tool supports specifying a custom demangler, writing out
+reports in a directory structure, and generating html reports. For the full
+list of options, please refer to the <a class="reference external" href="http://llvm.org/docs/CommandGuide/llvm-cov.html">command guide</a>.</p>
+<p>A few final notes:</p>
+<ul>
+<li><p class="first">The <tt class="docutils literal"><span class="pre">-sparse</span></tt> flag is optional but can result in dramatically smaller
+indexed profiles. This option should not be used if the indexed profile will
+be reused for PGO.</p>
+</li>
+<li><p class="first">Raw profiles can be discarded after they are indexed. Advanced use of the
+profile runtime library allows an instrumented program to merge profiling
+information directly into an existing raw profile on disk. The details are
+out of scope.</p>
+</li>
+<li><p class="first">The <tt class="docutils literal"><span class="pre">llvm-profdata</span></tt> tool can be used to merge together multiple raw or
+indexed profiles. To combine profiling data from multiple runs of a program,
+try e.g:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> llvm-profdata merge -sparse foo1.profraw foo2.profdata -o foo3.profdata
+</pre></div>
+</div>
+</li>
+</ul>
+</div>
+<div class="section" id="exporting-coverage-data">
+<h2><a class="toc-backref" href="#id6">Exporting coverage data</a><a class="headerlink" href="#exporting-coverage-data" title="Permalink to this headline">¶</a></h2>
+<p>Coverage data can be exported into JSON using the <tt class="docutils literal"><span class="pre">llvm-cov</span> <span class="pre">export</span></tt>
+sub-command. There is a comprehensive reference which defines the structure of
+the exported data at a high level in the llvm-cov source code.</p>
+</div>
+<div class="section" id="interpreting-reports">
+<h2><a class="toc-backref" href="#id7">Interpreting reports</a><a class="headerlink" href="#interpreting-reports" title="Permalink to this headline">¶</a></h2>
+<p>There are four statistics tracked in a coverage summary:</p>
+<ul class="simple">
+<li>Function coverage is the percentage of functions which have been executed at
+least once. A function is considered to be executed if any of its
+instantiations are executed.</li>
+<li>Instantiation coverage is the percentage of function instantiations which
+have been executed at least once. Template functions and static inline
+functions from headers are two kinds of functions which may have multiple
+instantiations.</li>
+<li>Line coverage is the percentage of code lines which have been executed at
+least once. Only executable lines within function bodies are considered to be
+code lines.</li>
+<li>Region coverage is the percentage of code regions which have been executed at
+least once. A code region may span multiple lines (e.g in a large function
+body with no control flow). However, it’s also possible for a single line to
+contain multiple code regions (e.g in “return x || y && z”).</li>
+</ul>
+<p>Of these four statistics, function coverage is usually the least granular while
+region coverage is the most granular. The project-wide totals for each
+statistic are listed in the summary.</p>
+</div>
+<div class="section" id="format-compatibility-guarantees">
+<h2><a class="toc-backref" href="#id8">Format compatibility guarantees</a><a class="headerlink" href="#format-compatibility-guarantees" title="Permalink to this headline">¶</a></h2>
+<ul class="simple">
+<li>There are no backwards or forwards compatibility guarantees for the raw
+profile format. Raw profiles may be dependent on the specific compiler
+revision used to generate them. It’s inadvisable to store raw profiles for
+long periods of time.</li>
+<li>Tools must retain <strong>backwards</strong> compatibility with indexed profile formats.
+These formats are not forwards-compatible: i.e, a tool which uses format
+version X will not be able to understand format version (X+k).</li>
+<li>Tools must also retain <strong>backwards</strong> compatibility with the format of the
+coverage mappings emitted into instrumented binaries. These formats are not
+forwards-compatible.</li>
+<li>The JSON coverage export format has a (major, minor, patch) version triple.
+Only a major version increment indicates a backwards-incompatible change. A
+minor version increment is for added functionality, and patch version
+increments are for bugfixes.</li>
+</ul>
+</div>
+<div class="section" id="using-the-profiling-runtime-without-static-initializers">
+<h2><a class="toc-backref" href="#id9">Using the profiling runtime without static initializers</a><a class="headerlink" href="#using-the-profiling-runtime-without-static-initializers" title="Permalink to this headline">¶</a></h2>
+<p>By default the compiler runtime uses a static initializer to determine the
+profile output path and to register a writer function. To collect profiles
+without using static initializers, do this manually:</p>
+<ul class="simple">
+<li>Export a <tt class="docutils literal"><span class="pre">int</span> <span class="pre">__llvm_profile_runtime</span></tt> symbol from each instrumented shared
+library and executable. When the linker finds a definition of this symbol, it
+knows to skip loading the object which contains the profiling runtime’s
+static initializer.</li>
+<li>Forward-declare <tt class="docutils literal"><span class="pre">void</span> <span class="pre">__llvm_profile_initialize_file(void)</span></tt> and call it
+once from each instrumented executable. This function parses
+<tt class="docutils literal"><span class="pre">LLVM_PROFILE_FILE</span></tt>, sets the output path, and truncates any existing files
+at that path. To get the same behavior without truncating existing files,
+pass a filename pattern string to <tt class="docutils literal"><span class="pre">void</span> <span class="pre">__llvm_profile_set_filename(char</span>
+<span class="pre">*)</span></tt>. These calls can be placed anywhere so long as they precede all calls
+to <tt class="docutils literal"><span class="pre">__llvm_profile_write_file</span></tt>.</li>
+<li>Forward-declare <tt class="docutils literal"><span class="pre">int</span> <span class="pre">__llvm_profile_write_file(void)</span></tt> and call it to write
+out a profile. This function returns 0 when it succeeds, and a non-zero value
+otherwise. Calling this function multiple times appends profile data to an
+existing on-disk raw profile.</li>
+</ul>
+</div>
+<div class="section" id="collecting-coverage-reports-for-the-llvm-project">
+<h2><a class="toc-backref" href="#id10">Collecting coverage reports for the llvm project</a><a class="headerlink" href="#collecting-coverage-reports-for-the-llvm-project" title="Permalink to this headline">¶</a></h2>
+<p>To prepare a coverage report for llvm (and any of its sub-projects), add
+<tt class="docutils literal"><span class="pre">-DLLVM_BUILD_INSTRUMENTED_COVERAGE=On</span></tt> to the cmake configuration. Raw
+profiles will be written to <tt class="docutils literal"><span class="pre">$BUILD_DIR/profiles/</span></tt>. To prepare an html
+report, run <tt class="docutils literal"><span class="pre">llvm/utils/prepare-code-coverage-artifact.py</span></tt>.</p>
+<p>To specify an alternate directory for raw profiles, use
+<tt class="docutils literal"><span class="pre">-DLLVM_PROFILE_DATA_DIR</span></tt>. To change the size of the profile merge pool, use
+<tt class="docutils literal"><span class="pre">-DLLVM_PROFILE_MERGE_POOL_SIZE</span></tt>.</p>
+</div>
+<div class="section" id="drawbacks-and-limitations">
+<h2><a class="toc-backref" href="#id11">Drawbacks and limitations</a><a class="headerlink" href="#drawbacks-and-limitations" title="Permalink to this headline">¶</a></h2>
+<ul>
+<li><p class="first">Code coverage does not handle unpredictable changes in control flow or stack
+unwinding in the presence of exceptions precisely. Consider the following
+function:</p>
+<div class="highlight-cpp"><div class="highlight"><pre><span class="kt">int</span> <span class="nf">f</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">may_throw</span><span class="p">();</span>
+ <span class="k">return</span> <span class="mi">0</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>If the call to <tt class="docutils literal"><span class="pre">may_throw()</span></tt> propagates an exception into <tt class="docutils literal"><span class="pre">f</span></tt>, the code
+coverage tool may mark the <tt class="docutils literal"><span class="pre">return</span></tt> statement as executed even though it is
+not. A call to <tt class="docutils literal"><span class="pre">longjmp()</span></tt> can have similar effects.</p>
+</li>
+</ul>
+</div>
+</div>
+
+
+ </div>
+ <div class="bottomnav">
+
+ <p>
+ « <a href="SafeStack.html">SafeStack</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="Modules.html">Modules</a> »
+ </p>
+
+ </div>
+
+ <div class="footer">
+ © Copyright 2007-2017, The Clang Team.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/4.0.0/tools/clang/docs/ThinLTO.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/4.0.0/tools/clang/docs/ThinLTO.html?rev=297634&view=auto
==============================================================================
--- www-releases/trunk/4.0.0/tools/clang/docs/ThinLTO.html (added)
+++ www-releases/trunk/4.0.0/tools/clang/docs/ThinLTO.html Mon Mar 13 11:30:12 2017
@@ -0,0 +1,228 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>ThinLTO — Clang 4 documentation</title>
+
+ <link rel="stylesheet" href="_static/haiku.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: './',
+ VERSION: '4',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+ <link rel="top" title="Clang 4 documentation" href="index.html" />
+ <link rel="next" title="Clang âmanâ pages" href="CommandGuide/index.html" />
+ <link rel="prev" title="MSVC compatibility" href="MSVCCompatibility.html" />
+ </head>
+ <body>
+ <div class="header"><h1 class="heading"><a href="index.html">
+ <span>Clang 4 documentation</span></a></h1>
+ <h2 class="heading"><span>ThinLTO</span></h2>
+ </div>
+ <div class="topnav">
+
+ <p>
+ « <a href="MSVCCompatibility.html">MSVC compatibility</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="CommandGuide/index.html">Clang “man” pages</a> »
+ </p>
+
+ </div>
+ <div class="content">
+
+
+ <div class="section" id="thinlto">
+<h1>ThinLTO<a class="headerlink" href="#thinlto" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#introduction" id="id4">Introduction</a></li>
+<li><a class="reference internal" href="#current-status" id="id5">Current Status</a><ul>
+<li><a class="reference internal" href="#clang-llvm" id="id6">Clang/LLVM</a></li>
+<li><a class="reference internal" href="#linkers" id="id7">Linkers</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#usage" id="id8">Usage</a><ul>
+<li><a class="reference internal" href="#basic" id="id9">Basic</a></li>
+<li><a class="reference internal" href="#controlling-backend-parallelism" id="id10">Controlling Backend Parallelism</a></li>
+<li><a class="reference internal" href="#incremental" id="id11">Incremental</a></li>
+<li><a class="reference internal" href="#clang-bootstrap" id="id12">Clang Bootstrap</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#more-information" id="id13">More Information</a></li>
+</ul>
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id4">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p><em>ThinLTO</em> compilation is a new type of LTO that is both scalable and
+incremental. <em>LTO</em> (Link Time Optimization) achieves better
+runtime performance through whole-program analysis and cross-module
+optimization. However, monolithic LTO implements this by merging all
+input into a single module, which is not scalable
+in time or memory, and also prevents fast incremental compiles.</p>
+<p>In ThinLTO mode, as with regular LTO, clang emits LLVM bitcode after the
+compile phase. The ThinLTO bitcode is augmented with a compact summary
+of the module. During the link step, only the summaries are read and
+merged into a combined summary index, which includes an index of function
+locations for later cross-module function importing. Fast and efficient
+whole-program analysis is then performed on the combined summary index.</p>
+<p>However, all transformations, including function importing, occur
+later when the modules are optimized in fully parallel backends.
+By default, <a class="reference internal" href="#id1">linkers</a> that support ThinLTO are set up to launch
+the ThinLTO backends in threads. So the usage model is not affected
+as the distinction between the fast serial thin link step and the backends
+is transparent to the user.</p>
+<p>For more information on the ThinLTO design and current performance,
+see the LLVM blog post <a class="reference external" href="http://blog.llvm.org/2016/06/thinlto-scalable-and-incremental-lto.html">ThinLTO: Scalable and Incremental LTO</a>.
+While tuning is still in progress, results in the blog post show that
+ThinLTO already performs well compared to LTO, in many cases matching
+the performance improvement.</p>
+</div>
+<div class="section" id="current-status">
+<h2><a class="toc-backref" href="#id5">Current Status</a><a class="headerlink" href="#current-status" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="clang-llvm">
+<h3><a class="toc-backref" href="#id6">Clang/LLVM</a><a class="headerlink" href="#clang-llvm" title="Permalink to this headline">¶</a></h3>
+<p id="compiler">The 3.9 release of clang includes ThinLTO support. However, ThinLTO
+is under active development, and new features, improvements and bugfixes
+are being added for the next release. For the latest ThinLTO support,
+<a class="reference external" href="http://llvm.org/docs/CMake.html">build a recent version of clang and LLVM</a>.</p>
+</div>
+<div class="section" id="linkers">
+<h3><a class="toc-backref" href="#id7">Linkers</a><a class="headerlink" href="#linkers" title="Permalink to this headline">¶</a></h3>
+<p id="linker"><span id="id1"></span>ThinLTO is currently supported for the following linkers:</p>
+<ul class="simple">
+<li><strong>gold (via the gold-plugin)</strong>:
+Similar to monolithic LTO, this requires using
+a <a class="reference external" href="http://llvm.org/docs/GoldPlugin.html">gold linker configured with plugins enabled</a>.</li>
+<li><strong>ld64</strong>:
+Starting with <a class="reference external" href="https://developer.apple.com/xcode/">Xcode 8</a>.</li>
+<li><strong>lld</strong>:
+Starting with r284050 (ELF only).</li>
+</ul>
+</div>
+</div>
+<div class="section" id="usage">
+<h2><a class="toc-backref" href="#id8">Usage</a><a class="headerlink" href="#usage" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="basic">
+<h3><a class="toc-backref" href="#id9">Basic</a><a class="headerlink" href="#basic" title="Permalink to this headline">¶</a></h3>
+<p>To utilize ThinLTO, simply add the -flto=thin option to compile and link. E.g.</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> clang -flto<span class="o">=</span>thin -O2 file1.c file2.c -c
+<span class="gp">%</span> clang -flto<span class="o">=</span>thin -O2 file1.o file2.o -o a.out
+</pre></div>
+</div>
+<p>As mentioned earlier, by default the linkers will launch the ThinLTO backend
+threads in parallel, passing the resulting native object files back to the
+linker for the final native link. As such, the usage model the same as
+non-LTO.</p>
+<p>With gold, if you see an error during the link of the form:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="go">/usr/bin/ld: error: /path/to/clang/bin/../lib/LLVMgold.so: could not load plugin library: /path/to/clang/bin/../lib/LLVMgold.so: cannot open shared object file: No such file or directory</span>
+</pre></div>
+</div>
+<p>Then either gold was not configured with plugins enabled, or clang
+was not built with <tt class="docutils literal"><span class="pre">-DLLVM_BINUTILS_INCDIR</span></tt> set properly. See
+the instructions for the
+<a class="reference external" href="http://llvm.org/docs/GoldPlugin.html#how-to-build-it">LLVM gold plugin</a>.</p>
+</div>
+<div class="section" id="controlling-backend-parallelism">
+<h3><a class="toc-backref" href="#id10">Controlling Backend Parallelism</a><a class="headerlink" href="#controlling-backend-parallelism" title="Permalink to this headline">¶</a></h3>
+<p id="parallelism">By default, the ThinLTO link step will launch up to
+<tt class="docutils literal"><span class="pre">std::thread::hardware_concurrency</span></tt> number of threads in parallel.
+For machines with hyper-threading, this is the total number of
+virtual cores. For some applications and machine configurations this
+may be too aggressive, in which case the amount of parallelism can
+be reduced to <tt class="docutils literal"><span class="pre">N</span></tt> via:</p>
+<ul class="simple">
+<li>gold:
+<tt class="docutils literal"><span class="pre">-Wl,-plugin-opt,jobs=N</span></tt></li>
+<li>ld64:
+<tt class="docutils literal"><span class="pre">-Wl,-mllvm,-threads=N</span></tt></li>
+<li>lld:
+<tt class="docutils literal"><span class="pre">-Wl,--thinlto-jobs=N</span></tt></li>
+</ul>
+</div>
+<div class="section" id="incremental">
+<h3><a class="toc-backref" href="#id11">Incremental</a><a class="headerlink" href="#incremental" title="Permalink to this headline">¶</a></h3>
+<p id="id2">ThinLTO supports fast incremental builds through the use of a cache,
+which currently must be enabled through a linker option.</p>
+<ul class="simple">
+<li>gold (as of LLVM r279883):
+<tt class="docutils literal"><span class="pre">-Wl,-plugin-opt,cache-dir=/path/to/cache</span></tt></li>
+<li>ld64 (support in clang 3.9 and Xcode 8):
+<tt class="docutils literal"><span class="pre">-Wl,-cache_path_lto,/path/to/cache</span></tt></li>
+</ul>
+</div>
+<div class="section" id="clang-bootstrap">
+<h3><a class="toc-backref" href="#id12">Clang Bootstrap</a><a class="headerlink" href="#clang-bootstrap" title="Permalink to this headline">¶</a></h3>
+<p>To bootstrap clang/LLVM with ThinLTO, follow these steps:</p>
+<ol class="arabic simple">
+<li>The host <a class="reference internal" href="#compiler">compiler</a> must be a version of clang that supports ThinLTO.</li>
+<li>The host <a class="reference internal" href="#linker">linker</a> must support ThinLTO (and in the case of gold, must be
+<a class="reference external" href="http://llvm.org/docs/GoldPlugin.html">configured with plugins enabled</a>.</li>
+<li>Use the following additional <a class="reference external" href="http://llvm.org/docs/CMake.html#options-and-variables">CMake variables</a>
+when configuring the bootstrap compiler build:</li>
+</ol>
+<blockquote>
+<div><ul class="simple">
+<li><tt class="docutils literal"><span class="pre">-DLLVM_ENABLE_LTO=Thin</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">-DLLVM_PARALLEL_LINK_JOBS=1</span></tt>
+(since the ThinLTO link invokes parallel backend jobs)</li>
+<li><tt class="docutils literal"><span class="pre">-DCMAKE_C_COMPILER=/path/to/host/clang</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">-DCMAKE_CXX_COMPILER=/path/to/host/clang++</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">-DCMAKE_RANLIB=/path/to/host/llvm-ranlib</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">-DCMAKE_AR=/path/to/host/llvm-ar</span></tt></li>
+</ul>
+</div></blockquote>
+<ol class="arabic simple">
+<li>To use additional linker arguments for controlling the backend
+<a class="reference internal" href="#parallelism">parallelism</a> or enabling <a class="reference internal" href="#id2">incremental</a> builds of the bootstrap compiler,
+after configuring the build, modify the resulting CMakeCache.txt file in the
+build directory. Specify any additional linker options after
+<tt class="docutils literal"><span class="pre">CMAKE_EXE_LINKER_FLAGS:STRING=</span></tt>. Note the configure may fail if
+linker plugin options are instead specified directly in the previous step.</li>
+</ol>
+</div>
+</div>
+<div class="section" id="more-information">
+<h2><a class="toc-backref" href="#id13">More Information</a><a class="headerlink" href="#more-information" title="Permalink to this headline">¶</a></h2>
+<ul class="simple">
+<li>From LLVM project blog:
+<a class="reference external" href="http://blog.llvm.org/2016/06/thinlto-scalable-and-incremental-lto.html">ThinLTO: Scalable and Incremental LTO</a></li>
+</ul>
+</div>
+</div>
+
+
+ </div>
+ <div class="bottomnav">
+
+ <p>
+ « <a href="MSVCCompatibility.html">MSVC compatibility</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="CommandGuide/index.html">Clang “man” pages</a> »
+ </p>
+
+ </div>
+
+ <div class="footer">
+ © Copyright 2007-2017, The Clang Team.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/4.0.0/tools/clang/docs/ThreadSafetyAnalysis.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/4.0.0/tools/clang/docs/ThreadSafetyAnalysis.html?rev=297634&view=auto
==============================================================================
--- www-releases/trunk/4.0.0/tools/clang/docs/ThreadSafetyAnalysis.html (added)
+++ www-releases/trunk/4.0.0/tools/clang/docs/ThreadSafetyAnalysis.html Mon Mar 13 11:30:12 2017
@@ -0,0 +1,914 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>Thread Safety Analysis — Clang 4 documentation</title>
+
+ <link rel="stylesheet" href="_static/haiku.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: './',
+ VERSION: '4',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+ <link rel="top" title="Clang 4 documentation" href="index.html" />
+ <link rel="next" title="AddressSanitizer" href="AddressSanitizer.html" />
+ <link rel="prev" title="Cross-compilation using Clang" href="CrossCompilation.html" />
+ </head>
+ <body>
+ <div class="header"><h1 class="heading"><a href="index.html">
+ <span>Clang 4 documentation</span></a></h1>
+ <h2 class="heading"><span>Thread Safety Analysis</span></h2>
+ </div>
+ <div class="topnav">
+
+ <p>
+ « <a href="CrossCompilation.html">Cross-compilation using Clang</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="AddressSanitizer.html">AddressSanitizer</a> »
+ </p>
+
+ </div>
+ <div class="content">
+
+
+ <div class="section" id="thread-safety-analysis">
+<h1>Thread Safety Analysis<a class="headerlink" href="#thread-safety-analysis" title="Permalink to this headline">¶</a></h1>
+<div class="section" id="introduction">
+<h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>Clang Thread Safety Analysis is a C++ language extension which warns about
+potential race conditions in code. The analysis is completely static (i.e.
+compile-time); there is no run-time overhead. The analysis is still
+under active development, but it is mature enough to be deployed in an
+industrial setting. It is being developed by Google, in collaboration with
+CERT/SEI, and is used extensively in Google’s internal code base.</p>
+<p>Thread safety analysis works very much like a type system for multi-threaded
+programs. In addition to declaring the <em>type</em> of data (e.g. <tt class="docutils literal"><span class="pre">int</span></tt>, <tt class="docutils literal"><span class="pre">float</span></tt>,
+etc.), the programmer can (optionally) declare how access to that data is
+controlled in a multi-threaded environment. For example, if <tt class="docutils literal"><span class="pre">foo</span></tt> is
+<em>guarded by</em> the mutex <tt class="docutils literal"><span class="pre">mu</span></tt>, then the analysis will issue a warning whenever
+a piece of code reads or writes to <tt class="docutils literal"><span class="pre">foo</span></tt> without first locking <tt class="docutils literal"><span class="pre">mu</span></tt>.
+Similarly, if there are particular routines that should only be called by
+the GUI thread, then the analysis will warn if other threads call those
+routines.</p>
+<div class="section" id="getting-started">
+<h3>Getting Started<a class="headerlink" href="#getting-started" title="Permalink to this headline">¶</a></h3>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#include "mutex.h"</span>
+
+<span class="k">class</span> <span class="nc">BankAccount</span> <span class="p">{</span>
+<span class="nl">private:</span>
+ <span class="n">Mutex</span> <span class="n">mu</span><span class="p">;</span>
+ <span class="kt">int</span> <span class="n">balance</span> <span class="nf">GUARDED_BY</span><span class="p">(</span><span class="n">mu</span><span class="p">);</span>
+
+ <span class="kt">void</span> <span class="nf">depositImpl</span><span class="p">(</span><span class="kt">int</span> <span class="n">amount</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">balance</span> <span class="o">+=</span> <span class="n">amount</span><span class="p">;</span> <span class="c1">// WARNING! Cannot write balance without locking mu.</span>
+ <span class="p">}</span>
+
+ <span class="kt">void</span> <span class="nf">withdrawImpl</span><span class="p">(</span><span class="kt">int</span> <span class="n">amount</span><span class="p">)</span> <span class="n">REQUIRES</span><span class="p">(</span><span class="n">mu</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">balance</span> <span class="o">-=</span> <span class="n">amount</span><span class="p">;</span> <span class="c1">// OK. Caller must have locked mu.</span>
+ <span class="p">}</span>
+
+<span class="nl">public:</span>
+ <span class="kt">void</span> <span class="nf">withdraw</span><span class="p">(</span><span class="kt">int</span> <span class="n">amount</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">mu</span><span class="p">.</span><span class="n">Lock</span><span class="p">();</span>
+ <span class="n">withdrawImpl</span><span class="p">(</span><span class="n">amount</span><span class="p">);</span> <span class="c1">// OK. We've locked mu.</span>
+ <span class="p">}</span> <span class="c1">// WARNING! Failed to unlock mu.</span>
+
+ <span class="kt">void</span> <span class="nf">transferFrom</span><span class="p">(</span><span class="n">BankAccount</span><span class="o">&</span> <span class="n">b</span><span class="p">,</span> <span class="kt">int</span> <span class="n">amount</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">mu</span><span class="p">.</span><span class="n">Lock</span><span class="p">();</span>
+ <span class="n">b</span><span class="p">.</span><span class="n">withdrawImpl</span><span class="p">(</span><span class="n">amount</span><span class="p">);</span> <span class="c1">// WARNING! Calling withdrawImpl() requires locking b.mu.</span>
+ <span class="n">depositImpl</span><span class="p">(</span><span class="n">amount</span><span class="p">);</span> <span class="c1">// OK. depositImpl() has no requirements.</span>
+ <span class="n">mu</span><span class="p">.</span><span class="n">Unlock</span><span class="p">();</span>
+ <span class="p">}</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>This example demonstrates the basic concepts behind the analysis. The
+<tt class="docutils literal"><span class="pre">GUARDED_BY</span></tt> attribute declares that a thread must lock <tt class="docutils literal"><span class="pre">mu</span></tt> before it can
+read or write to <tt class="docutils literal"><span class="pre">balance</span></tt>, thus ensuring that the increment and decrement
+operations are atomic. Similarly, <tt class="docutils literal"><span class="pre">REQUIRES</span></tt> declares that
+the calling thread must lock <tt class="docutils literal"><span class="pre">mu</span></tt> before calling <tt class="docutils literal"><span class="pre">withdrawImpl</span></tt>.
+Because the caller is assumed to have locked <tt class="docutils literal"><span class="pre">mu</span></tt>, it is safe to modify
+<tt class="docutils literal"><span class="pre">balance</span></tt> within the body of the method.</p>
+<p>The <tt class="docutils literal"><span class="pre">depositImpl()</span></tt> method does not have <tt class="docutils literal"><span class="pre">REQUIRES</span></tt>, so the
+analysis issues a warning. Thread safety analysis is not inter-procedural, so
+caller requirements must be explicitly declared.
+There is also a warning in <tt class="docutils literal"><span class="pre">transferFrom()</span></tt>, because although the method
+locks <tt class="docutils literal"><span class="pre">this->mu</span></tt>, it does not lock <tt class="docutils literal"><span class="pre">b.mu</span></tt>. The analysis understands
+that these are two separate mutexes, in two different objects.</p>
+<p>Finally, there is a warning in the <tt class="docutils literal"><span class="pre">withdraw()</span></tt> method, because it fails to
+unlock <tt class="docutils literal"><span class="pre">mu</span></tt>. Every lock must have a corresponding unlock, and the analysis
+will detect both double locks, and double unlocks. A function is allowed to
+acquire a lock without releasing it, (or vice versa), but it must be annotated
+as such (using <tt class="docutils literal"><span class="pre">ACQUIRE</span></tt>/<tt class="docutils literal"><span class="pre">RELEASE</span></tt>).</p>
+</div>
+<div class="section" id="running-the-analysis">
+<h3>Running The Analysis<a class="headerlink" href="#running-the-analysis" title="Permalink to this headline">¶</a></h3>
+<p>To run the analysis, simply compile with the <tt class="docutils literal"><span class="pre">-Wthread-safety</span></tt> flag, e.g.</p>
+<div class="highlight-bash"><div class="highlight"><pre>clang -c -Wthread-safety example.cpp
+</pre></div>
+</div>
+<p>Note that this example assumes the presence of a suitably annotated
+<a class="reference internal" href="#mutexheader"><em>mutex.h</em></a> that declares which methods perform locking,
+unlocking, and so on.</p>
+</div>
+</div>
+<div class="section" id="basic-concepts-capabilities">
+<h2>Basic Concepts: Capabilities<a class="headerlink" href="#basic-concepts-capabilities" title="Permalink to this headline">¶</a></h2>
+<p>Thread safety analysis provides a way of protecting <em>resources</em> with
+<em>capabilities</em>. A resource is either a data member, or a function/method
+that provides access to some underlying resource. The analysis ensures that
+the calling thread cannot access the <em>resource</em> (i.e. call the function, or
+read/write the data) unless it has the <em>capability</em> to do so.</p>
+<p>Capabilities are associated with named C++ objects which declare specific
+methods to acquire and release the capability. The name of the object serves
+to identify the capability. The most common example is a mutex. For example,
+if <tt class="docutils literal"><span class="pre">mu</span></tt> is a mutex, then calling <tt class="docutils literal"><span class="pre">mu.Lock()</span></tt> causes the calling thread
+to acquire the capability to access data that is protected by <tt class="docutils literal"><span class="pre">mu</span></tt>. Similarly,
+calling <tt class="docutils literal"><span class="pre">mu.Unlock()</span></tt> releases that capability.</p>
+<p>A thread may hold a capability either <em>exclusively</em> or <em>shared</em>. An exclusive
+capability can be held by only one thread at a time, while a shared capability
+can be held by many threads at the same time. This mechanism enforces a
+multiple-reader, single-writer pattern. Write operations to protected data
+require exclusive access, while read operations require only shared access.</p>
+<p>At any given moment during program execution, a thread holds a specific set of
+capabilities (e.g. the set of mutexes that it has locked.) These act like keys
+or tokens that allow the thread to access a given resource. Just like physical
+security keys, a thread cannot make copy of a capability, nor can it destroy
+one. A thread can only release a capability to another thread, or acquire one
+from another thread. The annotations are deliberately agnostic about the
+exact mechanism used to acquire and release capabilities; it assumes that the
+underlying implementation (e.g. the Mutex implementation) does the handoff in
+an appropriate manner.</p>
+<p>The set of capabilities that are actually held by a given thread at a given
+point in program execution is a run-time concept. The static analysis works
+by calculating an approximation of that set, called the <em>capability
+environment</em>. The capability environment is calculated for every program point,
+and describes the set of capabilities that are statically known to be held, or
+not held, at that particular point. This environment is a conservative
+approximation of the full set of capabilities that will actually held by a
+thread at run-time.</p>
+</div>
+<div class="section" id="reference-guide">
+<h2>Reference Guide<a class="headerlink" href="#reference-guide" title="Permalink to this headline">¶</a></h2>
+<p>The thread safety analysis uses attributes to declare threading constraints.
+Attributes must be attached to named declarations, such as classes, methods,
+and data members. Users are <em>strongly advised</em> to define macros for the various
+attributes; example definitions can be found in <a class="reference internal" href="#mutexheader"><em>mutex.h</em></a>, below.
+The following documentation assumes the use of macros.</p>
+<p>For historical reasons, prior versions of thread safety used macro names that
+were very lock-centric. These macros have since been renamed to fit a more
+general capability model. The prior names are still in use, and will be
+mentioned under the tag <em>previously</em> where appropriate.</p>
+<div class="section" id="guarded-by-c-and-pt-guarded-by-c">
+<h3>GUARDED_BY(c) and PT_GUARDED_BY(c)<a class="headerlink" href="#guarded-by-c-and-pt-guarded-by-c" title="Permalink to this headline">¶</a></h3>
+<p><tt class="docutils literal"><span class="pre">GUARDED_BY</span></tt> is an attribute on data members, which declares that the data
+member is protected by the given capability. Read operations on the data
+require shared access, while write operations require exclusive access.</p>
+<p><tt class="docutils literal"><span class="pre">PT_GUARDED_BY</span></tt> is similar, but is intended for use on pointers and smart
+pointers. There is no constraint on the data member itself, but the <em>data that
+it points to</em> is protected by the given capability.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">Mutex</span> <span class="n">mu</span><span class="p">;</span>
+<span class="kt">int</span> <span class="o">*</span><span class="n">p1</span> <span class="nf">GUARDED_BY</span><span class="p">(</span><span class="n">mu</span><span class="p">);</span>
+<span class="kt">int</span> <span class="o">*</span><span class="n">p2</span> <span class="nf">PT_GUARDED_BY</span><span class="p">(</span><span class="n">mu</span><span class="p">);</span>
+<span class="n">unique_ptr</span><span class="o"><</span><span class="kt">int</span><span class="o">></span> <span class="n">p3</span> <span class="n">PT_GUARDED_BY</span><span class="p">(</span><span class="n">mu</span><span class="p">);</span>
+
+<span class="kt">void</span> <span class="nf">test</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">p1</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="c1">// Warning!</span>
+
+ <span class="o">*</span><span class="n">p2</span> <span class="o">=</span> <span class="mi">42</span><span class="p">;</span> <span class="c1">// Warning!</span>
+ <span class="n">p2</span> <span class="o">=</span> <span class="k">new</span> <span class="kt">int</span><span class="p">;</span> <span class="c1">// OK.</span>
+
+ <span class="o">*</span><span class="n">p3</span> <span class="o">=</span> <span class="mi">42</span><span class="p">;</span> <span class="c1">// Warning!</span>
+ <span class="n">p3</span><span class="p">.</span><span class="n">reset</span><span class="p">(</span><span class="k">new</span> <span class="kt">int</span><span class="p">);</span> <span class="c1">// OK.</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="requires-requires-shared">
+<h3>REQUIRES(...), REQUIRES_SHARED(...)<a class="headerlink" href="#requires-requires-shared" title="Permalink to this headline">¶</a></h3>
+<p><em>Previously</em>: <tt class="docutils literal"><span class="pre">EXCLUSIVE_LOCKS_REQUIRED</span></tt>, <tt class="docutils literal"><span class="pre">SHARED_LOCKS_REQUIRED</span></tt></p>
+<p><tt class="docutils literal"><span class="pre">REQUIRES</span></tt> is an attribute on functions or methods, which
+declares that the calling thread must have exclusive access to the given
+capabilities. More than one capability may be specified. The capabilities
+must be held on entry to the function, <em>and must still be held on exit</em>.</p>
+<p><tt class="docutils literal"><span class="pre">REQUIRES_SHARED</span></tt> is similar, but requires only shared access.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">Mutex</span> <span class="n">mu1</span><span class="p">,</span> <span class="n">mu2</span><span class="p">;</span>
+<span class="kt">int</span> <span class="n">a</span> <span class="nf">GUARDED_BY</span><span class="p">(</span><span class="n">mu1</span><span class="p">);</span>
+<span class="kt">int</span> <span class="n">b</span> <span class="nf">GUARDED_BY</span><span class="p">(</span><span class="n">mu2</span><span class="p">);</span>
+
+<span class="kt">void</span> <span class="nf">foo</span><span class="p">()</span> <span class="n">REQUIRES</span><span class="p">(</span><span class="n">mu1</span><span class="p">,</span> <span class="n">mu2</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">a</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
+ <span class="n">b</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
+<span class="p">}</span>
+
+<span class="kt">void</span> <span class="nf">test</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">mu1</span><span class="p">.</span><span class="n">Lock</span><span class="p">();</span>
+ <span class="n">foo</span><span class="p">();</span> <span class="c1">// Warning! Requires mu2.</span>
+ <span class="n">mu1</span><span class="p">.</span><span class="n">Unlock</span><span class="p">();</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="acquire-acquire-shared-release-release-shared">
+<h3>ACQUIRE(...), ACQUIRE_SHARED(...), RELEASE(...), RELEASE_SHARED(...)<a class="headerlink" href="#acquire-acquire-shared-release-release-shared" title="Permalink to this headline">¶</a></h3>
+<p><em>Previously</em>: <tt class="docutils literal"><span class="pre">EXCLUSIVE_LOCK_FUNCTION</span></tt>, <tt class="docutils literal"><span class="pre">SHARED_LOCK_FUNCTION</span></tt>,
+<tt class="docutils literal"><span class="pre">UNLOCK_FUNCTION</span></tt></p>
+<p><tt class="docutils literal"><span class="pre">ACQUIRE</span></tt> is an attribute on functions or methods, which
+declares that the function acquires a capability, but does not release it. The
+caller must not hold the given capability on entry, and it will hold the
+capability on exit. <tt class="docutils literal"><span class="pre">ACQUIRE_SHARED</span></tt> is similar.</p>
+<p><tt class="docutils literal"><span class="pre">RELEASE</span></tt> and <tt class="docutils literal"><span class="pre">RELEASE_SHARED</span></tt> declare that the function releases the given
+capability. The caller must hold the capability on entry, and will no longer
+hold it on exit. It does not matter whether the given capability is shared or
+exclusive.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">Mutex</span> <span class="n">mu</span><span class="p">;</span>
+<span class="n">MyClass</span> <span class="n">myObject</span> <span class="nf">GUARDED_BY</span><span class="p">(</span><span class="n">mu</span><span class="p">);</span>
+
+<span class="kt">void</span> <span class="nf">lockAndInit</span><span class="p">()</span> <span class="n">ACQUIRE</span><span class="p">(</span><span class="n">mu</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">mu</span><span class="p">.</span><span class="n">Lock</span><span class="p">();</span>
+ <span class="n">myObject</span><span class="p">.</span><span class="n">init</span><span class="p">();</span>
+<span class="p">}</span>
+
+<span class="kt">void</span> <span class="nf">cleanupAndUnlock</span><span class="p">()</span> <span class="n">RELEASE</span><span class="p">(</span><span class="n">mu</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">myObject</span><span class="p">.</span><span class="n">cleanup</span><span class="p">();</span>
+<span class="p">}</span> <span class="c1">// Warning! Need to unlock mu.</span>
+
+<span class="kt">void</span> <span class="nf">test</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">lockAndInit</span><span class="p">();</span>
+ <span class="n">myObject</span><span class="p">.</span><span class="n">doSomething</span><span class="p">();</span>
+ <span class="n">cleanupAndUnlock</span><span class="p">();</span>
+ <span class="n">myObject</span><span class="p">.</span><span class="n">doSomething</span><span class="p">();</span> <span class="c1">// Warning, mu is not locked.</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>If no argument is passed to <tt class="docutils literal"><span class="pre">ACQUIRE</span></tt> or <tt class="docutils literal"><span class="pre">RELEASE</span></tt>, then the argument is
+assumed to be <tt class="docutils literal"><span class="pre">this</span></tt>, and the analysis will not check the body of the
+function. This pattern is intended for use by classes which hide locking
+details behind an abstract interface. For example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">T</span><span class="o">></span>
+<span class="k">class</span> <span class="nc">CAPABILITY</span><span class="p">(</span><span class="s">"mutex"</span><span class="p">)</span> <span class="n">Container</span> <span class="p">{</span>
+<span class="nl">private:</span>
+ <span class="n">Mutex</span> <span class="n">mu</span><span class="p">;</span>
+ <span class="n">T</span><span class="o">*</span> <span class="n">data</span><span class="p">;</span>
+
+<span class="nl">public:</span>
+ <span class="c1">// Hide mu from public interface.</span>
+ <span class="kt">void</span> <span class="nf">Lock</span><span class="p">()</span> <span class="n">ACQUIRE</span><span class="p">()</span> <span class="p">{</span> <span class="n">mu</span><span class="p">.</span><span class="n">Lock</span><span class="p">();</span> <span class="p">}</span>
+ <span class="kt">void</span> <span class="nf">Unlock</span><span class="p">()</span> <span class="n">RELEASE</span><span class="p">()</span> <span class="p">{</span> <span class="n">mu</span><span class="p">.</span><span class="n">Unlock</span><span class="p">();</span> <span class="p">}</span>
+
+ <span class="n">T</span><span class="o">&</span> <span class="n">getElem</span><span class="p">(</span><span class="kt">int</span> <span class="n">i</span><span class="p">)</span> <span class="p">{</span> <span class="k">return</span> <span class="n">data</span><span class="p">[</span><span class="n">i</span><span class="p">];</span> <span class="p">}</span>
+<span class="p">};</span>
+
+<span class="kt">void</span> <span class="nf">test</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">Container</span><span class="o"><</span><span class="kt">int</span><span class="o">></span> <span class="n">c</span><span class="p">;</span>
+ <span class="n">c</span><span class="p">.</span><span class="n">Lock</span><span class="p">();</span>
+ <span class="kt">int</span> <span class="n">i</span> <span class="o">=</span> <span class="n">c</span><span class="p">.</span><span class="n">getElem</span><span class="p">(</span><span class="mi">0</span><span class="p">);</span>
+ <span class="n">c</span><span class="p">.</span><span class="n">Unlock</span><span class="p">();</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="excludes">
+<h3>EXCLUDES(...)<a class="headerlink" href="#excludes" title="Permalink to this headline">¶</a></h3>
+<p><em>Previously</em>: <tt class="docutils literal"><span class="pre">LOCKS_EXCLUDED</span></tt></p>
+<p><tt class="docutils literal"><span class="pre">EXCLUDES</span></tt> is an attribute on functions or methods, which declares that
+the caller must <em>not</em> hold the given capabilities. This annotation is
+used to prevent deadlock. Many mutex implementations are not re-entrant, so
+deadlock can occur if the function acquires the mutex a second time.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">Mutex</span> <span class="n">mu</span><span class="p">;</span>
+<span class="kt">int</span> <span class="n">a</span> <span class="nf">GUARDED_BY</span><span class="p">(</span><span class="n">mu</span><span class="p">);</span>
+
+<span class="kt">void</span> <span class="nf">clear</span><span class="p">()</span> <span class="n">EXCLUDES</span><span class="p">(</span><span class="n">mu</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">mu</span><span class="p">.</span><span class="n">Lock</span><span class="p">();</span>
+ <span class="n">a</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
+ <span class="n">mu</span><span class="p">.</span><span class="n">Unlock</span><span class="p">();</span>
+<span class="p">}</span>
+
+<span class="kt">void</span> <span class="nf">reset</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">mu</span><span class="p">.</span><span class="n">Lock</span><span class="p">();</span>
+ <span class="n">clear</span><span class="p">();</span> <span class="c1">// Warning! Caller cannot hold 'mu'.</span>
+ <span class="n">mu</span><span class="p">.</span><span class="n">Unlock</span><span class="p">();</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Unlike <tt class="docutils literal"><span class="pre">REQUIRES</span></tt>, <tt class="docutils literal"><span class="pre">EXCLUDES</span></tt> is optional. The analysis will not issue a
+warning if the attribute is missing, which can lead to false negatives in some
+cases. This issue is discussed further in <a class="reference internal" href="#negative"><em>Negative Capabilities</em></a>.</p>
+</div>
+<div class="section" id="no-thread-safety-analysis">
+<h3>NO_THREAD_SAFETY_ANALYSIS<a class="headerlink" href="#no-thread-safety-analysis" title="Permalink to this headline">¶</a></h3>
+<p><tt class="docutils literal"><span class="pre">NO_THREAD_SAFETY_ANALYSIS</span></tt> is an attribute on functions or methods, which
+turns off thread safety checking for that method. It provides an escape hatch
+for functions which are either (1) deliberately thread-unsafe, or (2) are
+thread-safe, but too complicated for the analysis to understand. Reasons for
+(2) will be described in the <a class="reference internal" href="#limitations"><em>Known Limitations</em></a>, below.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">class</span> <span class="nc">Counter</span> <span class="p">{</span>
+ <span class="n">Mutex</span> <span class="n">mu</span><span class="p">;</span>
+ <span class="kt">int</span> <span class="n">a</span> <span class="nf">GUARDED_BY</span><span class="p">(</span><span class="n">mu</span><span class="p">);</span>
+
+ <span class="kt">void</span> <span class="n">unsafeIncrement</span><span class="p">()</span> <span class="n">NO_THREAD_SAFETY_ANALYSIS</span> <span class="p">{</span> <span class="n">a</span><span class="o">++</span><span class="p">;</span> <span class="p">}</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>Unlike the other attributes, NO_THREAD_SAFETY_ANALYSIS is not part of the
+interface of a function, and should thus be placed on the function definition
+(in the <tt class="docutils literal"><span class="pre">.cc</span></tt> or <tt class="docutils literal"><span class="pre">.cpp</span></tt> file) rather than on the function declaration
+(in the header).</p>
+</div>
+<div class="section" id="return-capability-c">
+<h3>RETURN_CAPABILITY(c)<a class="headerlink" href="#return-capability-c" title="Permalink to this headline">¶</a></h3>
+<p><em>Previously</em>: <tt class="docutils literal"><span class="pre">LOCK_RETURNED</span></tt></p>
+<p><tt class="docutils literal"><span class="pre">RETURN_CAPABILITY</span></tt> is an attribute on functions or methods, which declares
+that the function returns a reference to the given capability. It is used to
+annotate getter methods that return mutexes.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">class</span> <span class="nc">MyClass</span> <span class="p">{</span>
+<span class="nl">private:</span>
+ <span class="n">Mutex</span> <span class="n">mu</span><span class="p">;</span>
+ <span class="kt">int</span> <span class="n">a</span> <span class="nf">GUARDED_BY</span><span class="p">(</span><span class="n">mu</span><span class="p">);</span>
+
+<span class="nl">public:</span>
+ <span class="n">Mutex</span><span class="o">*</span> <span class="nf">getMu</span><span class="p">()</span> <span class="n">RETURN_CAPABILITY</span><span class="p">(</span><span class="n">mu</span><span class="p">)</span> <span class="p">{</span> <span class="k">return</span> <span class="o">&</span><span class="n">mu</span><span class="p">;</span> <span class="p">}</span>
+
+ <span class="c1">// analysis knows that getMu() == mu</span>
+ <span class="kt">void</span> <span class="nf">clear</span><span class="p">()</span> <span class="n">REQUIRES</span><span class="p">(</span><span class="n">getMu</span><span class="p">())</span> <span class="p">{</span> <span class="n">a</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="p">}</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="acquired-before-acquired-after">
+<h3>ACQUIRED_BEFORE(...), ACQUIRED_AFTER(...)<a class="headerlink" href="#acquired-before-acquired-after" title="Permalink to this headline">¶</a></h3>
+<p><tt class="docutils literal"><span class="pre">ACQUIRED_BEFORE</span></tt> and <tt class="docutils literal"><span class="pre">ACQUIRED_AFTER</span></tt> are attributes on member
+declarations, specifically declarations of mutexes or other capabilities.
+These declarations enforce a particular order in which the mutexes must be
+acquired, in order to prevent deadlock.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">Mutex</span> <span class="n">m1</span><span class="p">;</span>
+<span class="n">Mutex</span> <span class="n">m2</span> <span class="nf">ACQUIRED_AFTER</span><span class="p">(</span><span class="n">m1</span><span class="p">);</span>
+
+<span class="c1">// Alternative declaration</span>
+<span class="c1">// Mutex m2;</span>
+<span class="c1">// Mutex m1 ACQUIRED_BEFORE(m2);</span>
+
+<span class="kt">void</span> <span class="nf">foo</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">m2</span><span class="p">.</span><span class="n">Lock</span><span class="p">();</span>
+ <span class="n">m1</span><span class="p">.</span><span class="n">Lock</span><span class="p">();</span> <span class="c1">// Warning! m2 must be acquired after m1.</span>
+ <span class="n">m1</span><span class="p">.</span><span class="n">Unlock</span><span class="p">();</span>
+ <span class="n">m2</span><span class="p">.</span><span class="n">Unlock</span><span class="p">();</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="capability-string">
+<h3>CAPABILITY(<string>)<a class="headerlink" href="#capability-string" title="Permalink to this headline">¶</a></h3>
+<p><em>Previously</em>: <tt class="docutils literal"><span class="pre">LOCKABLE</span></tt></p>
+<p><tt class="docutils literal"><span class="pre">CAPABILITY</span></tt> is an attribute on classes, which specifies that objects of the
+class can be used as a capability. The string argument specifies the kind of
+capability in error messages, e.g. <tt class="docutils literal"><span class="pre">"mutex"</span></tt>. See the <tt class="docutils literal"><span class="pre">Container</span></tt> example
+given above, or the <tt class="docutils literal"><span class="pre">Mutex</span></tt> class in <a class="reference internal" href="#mutexheader"><em>mutex.h</em></a>.</p>
+</div>
+<div class="section" id="scoped-capability">
+<h3>SCOPED_CAPABILITY<a class="headerlink" href="#scoped-capability" title="Permalink to this headline">¶</a></h3>
+<p><em>Previously</em>: <tt class="docutils literal"><span class="pre">SCOPED_LOCKABLE</span></tt></p>
+<p><tt class="docutils literal"><span class="pre">SCOPED_CAPABILITY</span></tt> is an attribute on classes that implement RAII-style
+locking, in which a capability is acquired in the constructor, and released in
+the destructor. Such classes require special handling because the constructor
+and destructor refer to the capability via different names; see the
+<tt class="docutils literal"><span class="pre">MutexLocker</span></tt> class in <a class="reference internal" href="#mutexheader"><em>mutex.h</em></a>, below.</p>
+</div>
+<div class="section" id="try-acquire-bool-try-acquire-shared-bool">
+<h3>TRY_ACQUIRE(<bool>, ...), TRY_ACQUIRE_SHARED(<bool>, ...)<a class="headerlink" href="#try-acquire-bool-try-acquire-shared-bool" title="Permalink to this headline">¶</a></h3>
+<p><em>Previously:</em> <tt class="docutils literal"><span class="pre">EXCLUSIVE_TRYLOCK_FUNCTION</span></tt>, <tt class="docutils literal"><span class="pre">SHARED_TRYLOCK_FUNCTION</span></tt></p>
+<p>These are attributes on a function or method that tries to acquire the given
+capability, and returns a boolean value indicating success or failure.
+The first argument must be <tt class="docutils literal"><span class="pre">true</span></tt> or <tt class="docutils literal"><span class="pre">false</span></tt>, to specify which return value
+indicates success, and the remaining arguments are interpreted in the same way
+as <tt class="docutils literal"><span class="pre">ACQUIRE</span></tt>. See <a class="reference internal" href="#mutexheader"><em>mutex.h</em></a>, below, for example uses.</p>
+</div>
+<div class="section" id="assert-capability-and-assert-shared-capability">
+<h3>ASSERT_CAPABILITY(...) and ASSERT_SHARED_CAPABILITY(...)<a class="headerlink" href="#assert-capability-and-assert-shared-capability" title="Permalink to this headline">¶</a></h3>
+<p><em>Previously:</em> <tt class="docutils literal"><span class="pre">ASSERT_EXCLUSIVE_LOCK</span></tt>, <tt class="docutils literal"><span class="pre">ASSERT_SHARED_LOCK</span></tt></p>
+<p>These are attributes on a function or method that does a run-time test to see
+whether the calling thread holds the given capability. The function is assumed
+to fail (no return) if the capability is not held. See <a class="reference internal" href="#mutexheader"><em>mutex.h</em></a>,
+below, for example uses.</p>
+</div>
+<div class="section" id="guarded-var-and-pt-guarded-var">
+<h3>GUARDED_VAR and PT_GUARDED_VAR<a class="headerlink" href="#guarded-var-and-pt-guarded-var" title="Permalink to this headline">¶</a></h3>
+<p>Use of these attributes has been deprecated.</p>
+</div>
+<div class="section" id="warning-flags">
+<h3>Warning flags<a class="headerlink" href="#warning-flags" title="Permalink to this headline">¶</a></h3>
+<ul>
+<li><p class="first"><tt class="docutils literal"><span class="pre">-Wthread-safety</span></tt>: Umbrella flag which turns on the following three:</p>
+<ul>
+<li><p class="first"><tt class="docutils literal"><span class="pre">-Wthread-safety-attributes</span></tt>: Sanity checks on attribute syntax.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">-Wthread-safety-analysis</span></tt>: The core analysis.</p>
+</li>
+<li><dl class="first docutils">
+<dt><tt class="docutils literal"><span class="pre">-Wthread-safety-precise</span></tt>: Requires that mutex expressions match precisely.</dt>
+<dd><p class="first last">This warning can be disabled for code which has a lot of aliases.</p>
+</dd>
+</dl>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">-Wthread-safety-reference</span></tt>: Checks when guarded members are passed by reference.</p>
+</li>
+</ul>
+</li>
+</ul>
+<p><a class="reference internal" href="#negative"><em>Negative Capabilities</em></a> are an experimental feature, which are enabled with:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">-Wthread-safety-negative</span></tt>: Negative capabilities. Off by default.</li>
+</ul>
+<p>When new features and checks are added to the analysis, they can often introduce
+additional warnings. Those warnings are initially released as <em>beta</em> warnings
+for a period of time, after which they are migrated into the standard analysis.</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">-Wthread-safety-beta</span></tt>: New features. Off by default.</li>
+</ul>
+</div>
+</div>
+<div class="section" id="negative-capabilities">
+<span id="negative"></span><h2>Negative Capabilities<a class="headerlink" href="#negative-capabilities" title="Permalink to this headline">¶</a></h2>
+<p>Thread Safety Analysis is designed to prevent both race conditions and
+deadlock. The GUARDED_BY and REQUIRES attributes prevent race conditions, by
+ensuring that a capability is held before reading or writing to guarded data,
+and the EXCLUDES attribute prevents deadlock, by making sure that a mutex is
+<em>not</em> held.</p>
+<p>However, EXCLUDES is an optional attribute, and does not provide the same
+safety guarantee as REQUIRES. In particular:</p>
+<blockquote>
+<div><ul class="simple">
+<li>A function which acquires a capability does not have to exclude it.</li>
+<li>A function which calls a function that excludes a capability does not
+have transitively exclude that capability.</li>
+</ul>
+</div></blockquote>
+<p>As a result, EXCLUDES can easily produce false negatives:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">class</span> <span class="nc">Foo</span> <span class="p">{</span>
+ <span class="n">Mutex</span> <span class="n">mu</span><span class="p">;</span>
+
+ <span class="kt">void</span> <span class="nf">foo</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">mu</span><span class="p">.</span><span class="n">Lock</span><span class="p">();</span>
+ <span class="n">bar</span><span class="p">();</span> <span class="c1">// No warning.</span>
+ <span class="n">baz</span><span class="p">();</span> <span class="c1">// No warning.</span>
+ <span class="n">mu</span><span class="p">.</span><span class="n">Unlock</span><span class="p">();</span>
+ <span class="p">}</span>
+
+ <span class="kt">void</span> <span class="nf">bar</span><span class="p">()</span> <span class="p">{</span> <span class="c1">// No warning. (Should have EXCLUDES(mu)).</span>
+ <span class="n">mu</span><span class="p">.</span><span class="n">Lock</span><span class="p">();</span>
+ <span class="c1">// ...</span>
+ <span class="n">mu</span><span class="p">.</span><span class="n">Unlock</span><span class="p">();</span>
+ <span class="p">}</span>
+
+ <span class="kt">void</span> <span class="nf">baz</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">bif</span><span class="p">();</span> <span class="c1">// No warning. (Should have EXCLUDES(mu)).</span>
+ <span class="p">}</span>
+
+ <span class="kt">void</span> <span class="nf">bif</span><span class="p">()</span> <span class="n">EXCLUDES</span><span class="p">(</span><span class="n">mu</span><span class="p">);</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>Negative requirements are an alternative EXCLUDES that provide
+a stronger safety guarantee. A negative requirement uses the REQUIRES
+attribute, in conjunction with the <tt class="docutils literal"><span class="pre">!</span></tt> operator, to indicate that a capability
+should <em>not</em> be held.</p>
+<p>For example, using <tt class="docutils literal"><span class="pre">REQUIRES(!mu)</span></tt> instead of <tt class="docutils literal"><span class="pre">EXCLUDES(mu)</span></tt> will produce
+the appropriate warnings:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">class</span> <span class="nc">FooNeg</span> <span class="p">{</span>
+ <span class="n">Mutex</span> <span class="n">mu</span><span class="p">;</span>
+
+ <span class="kt">void</span> <span class="nf">foo</span><span class="p">()</span> <span class="n">REQUIRES</span><span class="p">(</span><span class="o">!</span><span class="n">mu</span><span class="p">)</span> <span class="p">{</span> <span class="c1">// foo() now requires !mu.</span>
+ <span class="n">mu</span><span class="p">.</span><span class="n">Lock</span><span class="p">();</span>
+ <span class="n">bar</span><span class="p">();</span>
+ <span class="n">baz</span><span class="p">();</span>
+ <span class="n">mu</span><span class="p">.</span><span class="n">Unlock</span><span class="p">();</span>
+ <span class="p">}</span>
+
+ <span class="kt">void</span> <span class="nf">bar</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">mu</span><span class="p">.</span><span class="n">Lock</span><span class="p">();</span> <span class="c1">// WARNING! Missing REQUIRES(!mu).</span>
+ <span class="c1">// ...</span>
+ <span class="n">mu</span><span class="p">.</span><span class="n">Unlock</span><span class="p">();</span>
+ <span class="p">}</span>
+
+ <span class="kt">void</span> <span class="nf">baz</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">bif</span><span class="p">();</span> <span class="c1">// WARNING! Missing REQUIRES(!mu).</span>
+ <span class="p">}</span>
+
+ <span class="kt">void</span> <span class="nf">bif</span><span class="p">()</span> <span class="n">REQUIRES</span><span class="p">(</span><span class="o">!</span><span class="n">mu</span><span class="p">);</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>Negative requirements are an experimental feature which is off by default,
+because it will produce many warnings in existing code. It can be enabled
+by passing <tt class="docutils literal"><span class="pre">-Wthread-safety-negative</span></tt>.</p>
+</div>
+<div class="section" id="frequently-asked-questions">
+<span id="faq"></span><h2>Frequently Asked Questions<a class="headerlink" href="#frequently-asked-questions" title="Permalink to this headline">¶</a></h2>
+<ol class="upperalpha simple" start="17">
+<li>Should I put attributes in the header file, or in the .cc/.cpp/.cxx file?</li>
+</ol>
+<p>(A) Attributes are part of the formal interface of a function, and should
+always go in the header, where they are visible to anything that includes
+the header. Attributes in the .cpp file are not visible outside of the
+immediate translation unit, which leads to false negatives and false positives.</p>
+<ol class="upperalpha simple" start="17">
+<li>“<em>Mutex is not locked on every path through here?</em>” What does that mean?</li>
+</ol>
+<ol class="upperalpha simple">
+<li>See <a class="reference internal" href="#conditional-locks"><em>No conditionally held locks.</em></a>, below.</li>
+</ol>
+</div>
+<div class="section" id="known-limitations">
+<span id="limitations"></span><h2>Known Limitations<a class="headerlink" href="#known-limitations" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="lexical-scope">
+<h3>Lexical scope<a class="headerlink" href="#lexical-scope" title="Permalink to this headline">¶</a></h3>
+<p>Thread safety attributes contain ordinary C++ expressions, and thus follow
+ordinary C++ scoping rules. In particular, this means that mutexes and other
+capabilities must be declared before they can be used in an attribute.
+Use-before-declaration is okay within a single class, because attributes are
+parsed at the same time as method bodies. (C++ delays parsing of method bodies
+until the end of the class.) However, use-before-declaration is not allowed
+between classes, as illustrated below.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">class</span> <span class="nc">Foo</span><span class="p">;</span>
+
+<span class="k">class</span> <span class="nc">Bar</span> <span class="p">{</span>
+ <span class="kt">void</span> <span class="n">bar</span><span class="p">(</span><span class="n">Foo</span><span class="o">*</span> <span class="n">f</span><span class="p">)</span> <span class="n">REQUIRES</span><span class="p">(</span><span class="n">f</span><span class="o">-></span><span class="n">mu</span><span class="p">);</span> <span class="c1">// Error: mu undeclared.</span>
+<span class="p">};</span>
+
+<span class="k">class</span> <span class="nc">Foo</span> <span class="p">{</span>
+ <span class="n">Mutex</span> <span class="n">mu</span><span class="p">;</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="private-mutexes">
+<h3>Private Mutexes<a class="headerlink" href="#private-mutexes" title="Permalink to this headline">¶</a></h3>
+<p>Good software engineering practice dictates that mutexes should be private
+members, because the locking mechanism used by a thread-safe class is part of
+its internal implementation. However, private mutexes can sometimes leak into
+the public interface of a class.
+Thread safety attributes follow normal C++ access restrictions, so if <tt class="docutils literal"><span class="pre">mu</span></tt>
+is a private member of <tt class="docutils literal"><span class="pre">c</span></tt>, then it is an error to write <tt class="docutils literal"><span class="pre">c.mu</span></tt> in an
+attribute.</p>
+<p>One workaround is to (ab)use the <tt class="docutils literal"><span class="pre">RETURN_CAPABILITY</span></tt> attribute to provide a
+public <em>name</em> for a private mutex, without actually exposing the underlying
+mutex. For example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">class</span> <span class="nc">MyClass</span> <span class="p">{</span>
+<span class="nl">private:</span>
+ <span class="n">Mutex</span> <span class="n">mu</span><span class="p">;</span>
+
+<span class="nl">public:</span>
+ <span class="c1">// For thread safety analysis only. Does not actually return mu.</span>
+ <span class="n">Mutex</span><span class="o">*</span> <span class="nf">getMu</span><span class="p">()</span> <span class="n">RETURN_CAPABILITY</span><span class="p">(</span><span class="n">mu</span><span class="p">)</span> <span class="p">{</span> <span class="k">return</span> <span class="mi">0</span><span class="p">;</span> <span class="p">}</span>
+
+ <span class="kt">void</span> <span class="nf">doSomething</span><span class="p">()</span> <span class="n">REQUIRES</span><span class="p">(</span><span class="n">mu</span><span class="p">);</span>
+<span class="p">};</span>
+
+<span class="kt">void</span> <span class="nf">doSomethingTwice</span><span class="p">(</span><span class="n">MyClass</span><span class="o">&</span> <span class="n">c</span><span class="p">)</span> <span class="n">REQUIRES</span><span class="p">(</span><span class="n">c</span><span class="p">.</span><span class="n">getMu</span><span class="p">())</span> <span class="p">{</span>
+ <span class="c1">// The analysis thinks that c.getMu() == c.mu</span>
+ <span class="n">c</span><span class="p">.</span><span class="n">doSomething</span><span class="p">();</span>
+ <span class="n">c</span><span class="p">.</span><span class="n">doSomething</span><span class="p">();</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>In the above example, <tt class="docutils literal"><span class="pre">doSomethingTwice()</span></tt> is an external routine that
+requires <tt class="docutils literal"><span class="pre">c.mu</span></tt> to be locked, which cannot be declared directly because <tt class="docutils literal"><span class="pre">mu</span></tt>
+is private. This pattern is discouraged because it
+violates encapsulation, but it is sometimes necessary, especially when adding
+annotations to an existing code base. The workaround is to define <tt class="docutils literal"><span class="pre">getMu()</span></tt>
+as a fake getter method, which is provided only for the benefit of thread
+safety analysis.</p>
+</div>
+<div class="section" id="no-conditionally-held-locks">
+<span id="conditional-locks"></span><h3>No conditionally held locks.<a class="headerlink" href="#no-conditionally-held-locks" title="Permalink to this headline">¶</a></h3>
+<p>The analysis must be able to determine whether a lock is held, or not held, at
+every program point. Thus, sections of code where a lock <em>might be held</em> will
+generate spurious warnings (false positives). For example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="nf">foo</span><span class="p">()</span> <span class="p">{</span>
+ <span class="kt">bool</span> <span class="n">b</span> <span class="o">=</span> <span class="n">needsToLock</span><span class="p">();</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">b</span><span class="p">)</span> <span class="n">mu</span><span class="p">.</span><span class="n">Lock</span><span class="p">();</span>
+ <span class="p">...</span> <span class="c1">// Warning! Mutex 'mu' is not held on every path through here.</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">b</span><span class="p">)</span> <span class="n">mu</span><span class="p">.</span><span class="n">Unlock</span><span class="p">();</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="no-checking-inside-constructors-and-destructors">
+<h3>No checking inside constructors and destructors.<a class="headerlink" href="#no-checking-inside-constructors-and-destructors" title="Permalink to this headline">¶</a></h3>
+<p>The analysis currently does not do any checking inside constructors or
+destructors. In other words, every constructor and destructor is treated as
+if it was annotated with <tt class="docutils literal"><span class="pre">NO_THREAD_SAFETY_ANALYSIS</span></tt>.
+The reason for this is that during initialization, only one thread typically
+has access to the object which is being initialized, and it is thus safe (and
+common practice) to initialize guarded members without acquiring any locks.
+The same is true of destructors.</p>
+<p>Ideally, the analysis would allow initialization of guarded members inside the
+object being initialized or destroyed, while still enforcing the usual access
+restrictions on everything else. However, this is difficult to enforce in
+practice, because in complex pointer-based data structures, it is hard to
+determine what data is owned by the enclosing object.</p>
+</div>
+<div class="section" id="no-inlining">
+<h3>No inlining.<a class="headerlink" href="#no-inlining" title="Permalink to this headline">¶</a></h3>
+<p>Thread safety analysis is strictly intra-procedural, just like ordinary type
+checking. It relies only on the declared attributes of a function, and will
+not attempt to inline any method calls. As a result, code such as the
+following will not work:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">template</span><span class="o"><</span><span class="k">class</span> <span class="nc">T</span><span class="o">></span>
+<span class="k">class</span> <span class="nc">AutoCleanup</span> <span class="p">{</span>
+ <span class="n">T</span><span class="o">*</span> <span class="n">object</span><span class="p">;</span>
+ <span class="kt">void</span> <span class="p">(</span><span class="n">T</span><span class="o">::*</span><span class="n">mp</span><span class="p">)();</span>
+
+<span class="nl">public:</span>
+ <span class="n">AutoCleanup</span><span class="p">(</span><span class="n">T</span><span class="o">*</span> <span class="n">obj</span><span class="p">,</span> <span class="kt">void</span> <span class="p">(</span><span class="n">T</span><span class="o">::*</span><span class="n">imp</span><span class="p">)())</span> <span class="o">:</span> <span class="n">object</span><span class="p">(</span><span class="n">obj</span><span class="p">),</span> <span class="n">mp</span><span class="p">(</span><span class="n">imp</span><span class="p">)</span> <span class="p">{</span> <span class="p">}</span>
+ <span class="o">~</span><span class="n">AutoCleanup</span><span class="p">()</span> <span class="p">{</span> <span class="p">(</span><span class="n">object</span><span class="o">->*</span><span class="n">mp</span><span class="p">)();</span> <span class="p">}</span>
+<span class="p">};</span>
+
+<span class="n">Mutex</span> <span class="n">mu</span><span class="p">;</span>
+<span class="kt">void</span> <span class="nf">foo</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">mu</span><span class="p">.</span><span class="n">Lock</span><span class="p">();</span>
+ <span class="n">AutoCleanup</span><span class="o"><</span><span class="n">Mutex</span><span class="o">></span><span class="p">(</span><span class="o">&</span><span class="n">mu</span><span class="p">,</span> <span class="o">&</span><span class="n">Mutex</span><span class="o">::</span><span class="n">Unlock</span><span class="p">);</span>
+ <span class="c1">// ...</span>
+<span class="p">}</span> <span class="c1">// Warning, mu is not unlocked.</span>
+</pre></div>
+</div>
+<p>In this case, the destructor of <tt class="docutils literal"><span class="pre">Autocleanup</span></tt> calls <tt class="docutils literal"><span class="pre">mu.Unlock()</span></tt>, so
+the warning is bogus. However,
+thread safety analysis cannot see the unlock, because it does not attempt to
+inline the destructor. Moreover, there is no way to annotate the destructor,
+because the destructor is calling a function that is not statically known.
+This pattern is simply not supported.</p>
+</div>
+<div class="section" id="no-alias-analysis">
+<h3>No alias analysis.<a class="headerlink" href="#no-alias-analysis" title="Permalink to this headline">¶</a></h3>
+<p>The analysis currently does not track pointer aliases. Thus, there can be
+false positives if two pointers both point to the same mutex.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">class</span> <span class="nc">MutexUnlocker</span> <span class="p">{</span>
+ <span class="n">Mutex</span><span class="o">*</span> <span class="n">mu</span><span class="p">;</span>
+
+<span class="nl">public:</span>
+ <span class="n">MutexUnlocker</span><span class="p">(</span><span class="n">Mutex</span><span class="o">*</span> <span class="n">m</span><span class="p">)</span> <span class="n">RELEASE</span><span class="p">(</span><span class="n">m</span><span class="p">)</span> <span class="o">:</span> <span class="n">mu</span><span class="p">(</span><span class="n">m</span><span class="p">)</span> <span class="p">{</span> <span class="n">mu</span><span class="o">-></span><span class="n">Unlock</span><span class="p">();</span> <span class="p">}</span>
+ <span class="o">~</span><span class="n">MutexUnlocker</span><span class="p">()</span> <span class="n">ACQUIRE</span><span class="p">(</span><span class="n">mu</span><span class="p">)</span> <span class="p">{</span> <span class="n">mu</span><span class="o">-></span><span class="n">Lock</span><span class="p">();</span> <span class="p">}</span>
+<span class="p">};</span>
+
+<span class="n">Mutex</span> <span class="n">mutex</span><span class="p">;</span>
+<span class="kt">void</span> <span class="nf">test</span><span class="p">()</span> <span class="n">REQUIRES</span><span class="p">(</span><span class="n">mutex</span><span class="p">)</span> <span class="p">{</span>
+ <span class="p">{</span>
+ <span class="n">MutexUnlocker</span> <span class="n">munl</span><span class="p">(</span><span class="o">&</span><span class="n">mutex</span><span class="p">);</span> <span class="c1">// unlocks mutex</span>
+ <span class="n">doSomeIO</span><span class="p">();</span>
+ <span class="p">}</span> <span class="c1">// Warning: locks munl.mu</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>The MutexUnlocker class is intended to be the dual of the MutexLocker class,
+defined in <a class="reference internal" href="#mutexheader"><em>mutex.h</em></a>. However, it doesn’t work because the analysis
+doesn’t know that munl.mu == mutex. The SCOPED_CAPABILITY attribute handles
+aliasing for MutexLocker, but does so only for that particular pattern.</p>
+</div>
+<div class="section" id="acquired-before-and-acquired-after-are-currently-unimplemented">
+<h3>ACQUIRED_BEFORE(...) and ACQUIRED_AFTER(...) are currently unimplemented.<a class="headerlink" href="#acquired-before-and-acquired-after-are-currently-unimplemented" title="Permalink to this headline">¶</a></h3>
+<p>To be fixed in a future update.</p>
+</div>
+</div>
+<div class="section" id="mutex-h">
+<span id="mutexheader"></span><h2>mutex.h<a class="headerlink" href="#mutex-h" title="Permalink to this headline">¶</a></h2>
+<p>Thread safety analysis can be used with any threading library, but it does
+require that the threading API be wrapped in classes and methods which have the
+appropriate annotations. The following code provides <tt class="docutils literal"><span class="pre">mutex.h</span></tt> as an example;
+these methods should be filled in to call the appropriate underlying
+implementation.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#ifndef THREAD_SAFETY_ANALYSIS_MUTEX_H</span>
+<span class="cp">#define THREAD_SAFETY_ANALYSIS_MUTEX_H</span>
+
+<span class="c1">// Enable thread safety attributes only with clang.</span>
+<span class="c1">// The attributes can be safely erased when compiling with other compilers.</span>
+<span class="cp">#if defined(__clang__) && (!defined(SWIG))</span>
+<span class="cp">#define THREAD_ANNOTATION_ATTRIBUTE__(x) __attribute__((x))</span>
+<span class="cp">#else</span>
+<span class="cp">#define THREAD_ANNOTATION_ATTRIBUTE__(x) </span><span class="c1">// no-op</span>
+<span class="cp">#endif</span>
+
+<span class="cp">#define THREAD_ANNOTATION_ATTRIBUTE__(x) __attribute__((x))</span>
+
+<span class="cp">#define CAPABILITY(x) \</span>
+<span class="cp"> THREAD_ANNOTATION_ATTRIBUTE__(capability(x))</span>
+
+<span class="cp">#define SCOPED_CAPABILITY \</span>
+<span class="cp"> THREAD_ANNOTATION_ATTRIBUTE__(scoped_lockable)</span>
+
+<span class="cp">#define GUARDED_BY(x) \</span>
+<span class="cp"> THREAD_ANNOTATION_ATTRIBUTE__(guarded_by(x))</span>
+
+<span class="cp">#define PT_GUARDED_BY(x) \</span>
+<span class="cp"> THREAD_ANNOTATION_ATTRIBUTE__(pt_guarded_by(x))</span>
+
+<span class="cp">#define ACQUIRED_BEFORE(...) \</span>
+<span class="cp"> THREAD_ANNOTATION_ATTRIBUTE__(acquired_before(__VA_ARGS__))</span>
+
+<span class="cp">#define ACQUIRED_AFTER(...) \</span>
+<span class="cp"> THREAD_ANNOTATION_ATTRIBUTE__(acquired_after(__VA_ARGS__))</span>
+
+<span class="cp">#define REQUIRES(...) \</span>
+<span class="cp"> THREAD_ANNOTATION_ATTRIBUTE__(requires_capability(__VA_ARGS__))</span>
+
+<span class="cp">#define REQUIRES_SHARED(...) \</span>
+<span class="cp"> THREAD_ANNOTATION_ATTRIBUTE__(requires_shared_capability(__VA_ARGS__))</span>
+
+<span class="cp">#define ACQUIRE(...) \</span>
+<span class="cp"> THREAD_ANNOTATION_ATTRIBUTE__(acquire_capability(__VA_ARGS__))</span>
+
+<span class="cp">#define ACQUIRE_SHARED(...) \</span>
+<span class="cp"> THREAD_ANNOTATION_ATTRIBUTE__(acquire_shared_capability(__VA_ARGS__))</span>
+
+<span class="cp">#define RELEASE(...) \</span>
+<span class="cp"> THREAD_ANNOTATION_ATTRIBUTE__(release_capability(__VA_ARGS__))</span>
+
+<span class="cp">#define RELEASE_SHARED(...) \</span>
+<span class="cp"> THREAD_ANNOTATION_ATTRIBUTE__(release_shared_capability(__VA_ARGS__))</span>
+
+<span class="cp">#define TRY_ACQUIRE(...) \</span>
+<span class="cp"> THREAD_ANNOTATION_ATTRIBUTE__(try_acquire_capability(__VA_ARGS__))</span>
+
+<span class="cp">#define TRY_ACQUIRE_SHARED(...) \</span>
+<span class="cp"> THREAD_ANNOTATION_ATTRIBUTE__(try_acquire_shared_capability(__VA_ARGS__))</span>
+
+<span class="cp">#define EXCLUDES(...) \</span>
+<span class="cp"> THREAD_ANNOTATION_ATTRIBUTE__(locks_excluded(__VA_ARGS__))</span>
+
+<span class="cp">#define ASSERT_CAPABILITY(x) \</span>
+<span class="cp"> THREAD_ANNOTATION_ATTRIBUTE__(assert_capability(x))</span>
+
+<span class="cp">#define ASSERT_SHARED_CAPABILITY(x) \</span>
+<span class="cp"> THREAD_ANNOTATION_ATTRIBUTE__(assert_shared_capability(x))</span>
+
+<span class="cp">#define RETURN_CAPABILITY(x) \</span>
+<span class="cp"> THREAD_ANNOTATION_ATTRIBUTE__(lock_returned(x))</span>
+
+<span class="cp">#define NO_THREAD_SAFETY_ANALYSIS \</span>
+<span class="cp"> THREAD_ANNOTATION_ATTRIBUTE__(no_thread_safety_analysis)</span>
+
+
+<span class="c1">// Defines an annotated interface for mutexes.</span>
+<span class="c1">// These methods can be implemented to use any internal mutex implementation.</span>
+<span class="k">class</span> <span class="nf">CAPABILITY</span><span class="p">(</span><span class="s">"mutex"</span><span class="p">)</span> <span class="n">Mutex</span> <span class="p">{</span>
+<span class="nl">public:</span>
+ <span class="c1">// Acquire/lock this mutex exclusively. Only one thread can have exclusive</span>
+ <span class="c1">// access at any one time. Write operations to guarded data require an</span>
+ <span class="c1">// exclusive lock.</span>
+ <span class="kt">void</span> <span class="n">Lock</span><span class="p">()</span> <span class="n">ACQUIRE</span><span class="p">();</span>
+
+ <span class="c1">// Acquire/lock this mutex for read operations, which require only a shared</span>
+ <span class="c1">// lock. This assumes a multiple-reader, single writer semantics. Multiple</span>
+ <span class="c1">// threads may acquire the mutex simultaneously as readers, but a writer</span>
+ <span class="c1">// must wait for all of them to release the mutex before it can acquire it</span>
+ <span class="c1">// exclusively.</span>
+ <span class="kt">void</span> <span class="nf">ReaderLock</span><span class="p">()</span> <span class="n">ACQUIRE_SHARED</span><span class="p">();</span>
+
+ <span class="c1">// Release/unlock an exclusive mutex.</span>
+ <span class="kt">void</span> <span class="nf">Unlock</span><span class="p">()</span> <span class="n">RELEASE</span><span class="p">();</span>
+
+ <span class="c1">// Release/unlock a shared mutex.</span>
+ <span class="kt">void</span> <span class="nf">ReaderUnlock</span><span class="p">()</span> <span class="n">RELEASE_SHARED</span><span class="p">();</span>
+
+ <span class="c1">// Try to acquire the mutex. Returns true on success, and false on failure.</span>
+ <span class="kt">bool</span> <span class="nf">TryLock</span><span class="p">()</span> <span class="n">TRY_ACQUIRE</span><span class="p">(</span><span class="nb">true</span><span class="p">);</span>
+
+ <span class="c1">// Try to acquire the mutex for read operations.</span>
+ <span class="kt">bool</span> <span class="nf">ReaderTryLock</span><span class="p">()</span> <span class="n">TRY_ACQUIRE_SHARED</span><span class="p">(</span><span class="nb">true</span><span class="p">);</span>
+
+ <span class="c1">// Assert that this mutex is currently held by the calling thread.</span>
+ <span class="kt">void</span> <span class="nf">AssertHeld</span><span class="p">()</span> <span class="n">ASSERT_CAPABILITY</span><span class="p">(</span><span class="k">this</span><span class="p">);</span>
+
+ <span class="c1">// Assert that is mutex is currently held for read operations.</span>
+ <span class="kt">void</span> <span class="nf">AssertReaderHeld</span><span class="p">()</span> <span class="n">ASSERT_SHARED_CAPABILITY</span><span class="p">(</span><span class="k">this</span><span class="p">);</span>
+
+ <span class="c1">// For negative capabilities.</span>
+ <span class="k">const</span> <span class="n">Mutex</span><span class="o">&</span> <span class="k">operator</span><span class="o">!</span><span class="p">()</span> <span class="k">const</span> <span class="p">{</span> <span class="k">return</span> <span class="o">*</span><span class="k">this</span><span class="p">;</span> <span class="p">}</span>
+<span class="p">};</span>
+
+
+<span class="c1">// MutexLocker is an RAII class that acquires a mutex in its constructor, and</span>
+<span class="c1">// releases it in its destructor.</span>
+<span class="k">class</span> <span class="nc">SCOPED_CAPABILITY</span> <span class="n">MutexLocker</span> <span class="p">{</span>
+<span class="nl">private:</span>
+ <span class="n">Mutex</span><span class="o">*</span> <span class="n">mut</span><span class="p">;</span>
+
+<span class="nl">public:</span>
+ <span class="n">MutexLocker</span><span class="p">(</span><span class="n">Mutex</span> <span class="o">*</span><span class="n">mu</span><span class="p">)</span> <span class="n">ACQUIRE</span><span class="p">(</span><span class="n">mu</span><span class="p">)</span> <span class="o">:</span> <span class="n">mut</span><span class="p">(</span><span class="n">mu</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">mu</span><span class="o">-></span><span class="n">Lock</span><span class="p">();</span>
+ <span class="p">}</span>
+ <span class="o">~</span><span class="n">MutexLocker</span><span class="p">()</span> <span class="n">RELEASE</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">mut</span><span class="o">-></span><span class="n">Unlock</span><span class="p">();</span>
+ <span class="p">}</span>
+<span class="p">};</span>
+
+
+<span class="cp">#ifdef USE_LOCK_STYLE_THREAD_SAFETY_ATTRIBUTES</span>
+<span class="c1">// The original version of thread safety analysis the following attribute</span>
+<span class="c1">// definitions. These use a lock-based terminology. They are still in use</span>
+<span class="c1">// by existing thread safety code, and will continue to be supported.</span>
+
+<span class="c1">// Deprecated.</span>
+<span class="cp">#define PT_GUARDED_VAR \</span>
+<span class="cp"> THREAD_ANNOTATION_ATTRIBUTE__(pt_guarded)</span>
+
+<span class="c1">// Deprecated.</span>
+<span class="cp">#define GUARDED_VAR \</span>
+<span class="cp"> THREAD_ANNOTATION_ATTRIBUTE__(guarded)</span>
+
+<span class="c1">// Replaced by REQUIRES</span>
+<span class="cp">#define EXCLUSIVE_LOCKS_REQUIRED(...) \</span>
+<span class="cp"> THREAD_ANNOTATION_ATTRIBUTE__(exclusive_locks_required(__VA_ARGS__))</span>
+
+<span class="c1">// Replaced by REQUIRES_SHARED</span>
+<span class="cp">#define SHARED_LOCKS_REQUIRED(...) \</span>
+<span class="cp"> THREAD_ANNOTATION_ATTRIBUTE__(shared_locks_required(__VA_ARGS__))</span>
+
+<span class="c1">// Replaced by CAPABILITY</span>
+<span class="cp">#define LOCKABLE \</span>
+<span class="cp"> THREAD_ANNOTATION_ATTRIBUTE__(lockable)</span>
+
+<span class="c1">// Replaced by SCOPED_CAPABILITY</span>
+<span class="cp">#define SCOPED_LOCKABLE \</span>
+<span class="cp"> THREAD_ANNOTATION_ATTRIBUTE__(scoped_lockable)</span>
+
+<span class="c1">// Replaced by ACQUIRE</span>
+<span class="cp">#define EXCLUSIVE_LOCK_FUNCTION(...) \</span>
+<span class="cp"> THREAD_ANNOTATION_ATTRIBUTE__(exclusive_lock_function(__VA_ARGS__))</span>
+
+<span class="c1">// Replaced by ACQUIRE_SHARED</span>
+<span class="cp">#define SHARED_LOCK_FUNCTION(...) \</span>
+<span class="cp"> THREAD_ANNOTATION_ATTRIBUTE__(shared_lock_function(__VA_ARGS__))</span>
+
+<span class="c1">// Replaced by RELEASE and RELEASE_SHARED</span>
+<span class="cp">#define UNLOCK_FUNCTION(...) \</span>
+<span class="cp"> THREAD_ANNOTATION_ATTRIBUTE__(unlock_function(__VA_ARGS__))</span>
+
+<span class="c1">// Replaced by TRY_ACQUIRE</span>
+<span class="cp">#define EXCLUSIVE_TRYLOCK_FUNCTION(...) \</span>
+<span class="cp"> THREAD_ANNOTATION_ATTRIBUTE__(exclusive_trylock_function(__VA_ARGS__))</span>
+
+<span class="c1">// Replaced by TRY_ACQUIRE_SHARED</span>
+<span class="cp">#define SHARED_TRYLOCK_FUNCTION(...) \</span>
+<span class="cp"> THREAD_ANNOTATION_ATTRIBUTE__(shared_trylock_function(__VA_ARGS__))</span>
+
+<span class="c1">// Replaced by ASSERT_CAPABILITY</span>
+<span class="cp">#define ASSERT_EXCLUSIVE_LOCK(...) \</span>
+<span class="cp"> THREAD_ANNOTATION_ATTRIBUTE__(assert_exclusive_lock(__VA_ARGS__))</span>
+
+<span class="c1">// Replaced by ASSERT_SHARED_CAPABILITY</span>
+<span class="cp">#define ASSERT_SHARED_LOCK(...) \</span>
+<span class="cp"> THREAD_ANNOTATION_ATTRIBUTE__(assert_shared_lock(__VA_ARGS__))</span>
+
+<span class="c1">// Replaced by EXCLUDE_CAPABILITY.</span>
+<span class="cp">#define LOCKS_EXCLUDED(...) \</span>
+<span class="cp"> THREAD_ANNOTATION_ATTRIBUTE__(locks_excluded(__VA_ARGS__))</span>
+
+<span class="c1">// Replaced by RETURN_CAPABILITY</span>
+<span class="cp">#define LOCK_RETURNED(x) \</span>
+<span class="cp"> THREAD_ANNOTATION_ATTRIBUTE__(lock_returned(x))</span>
+
+<span class="cp">#endif </span><span class="c1">// USE_LOCK_STYLE_THREAD_SAFETY_ATTRIBUTES</span>
+
+<span class="cp">#endif </span><span class="c1">// THREAD_SAFETY_ANALYSIS_MUTEX_H</span>
+</pre></div>
+</div>
+</div>
+</div>
+
+
+ </div>
+ <div class="bottomnav">
+
+ <p>
+ « <a href="CrossCompilation.html">Cross-compilation using Clang</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="AddressSanitizer.html">AddressSanitizer</a> »
+ </p>
+
+ </div>
+
+ <div class="footer">
+ © Copyright 2007-2017, The Clang Team.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/4.0.0/tools/clang/docs/ThreadSanitizer.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/4.0.0/tools/clang/docs/ThreadSanitizer.html?rev=297634&view=auto
==============================================================================
--- www-releases/trunk/4.0.0/tools/clang/docs/ThreadSanitizer.html (added)
+++ www-releases/trunk/4.0.0/tools/clang/docs/ThreadSanitizer.html Mon Mar 13 11:30:12 2017
@@ -0,0 +1,192 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>ThreadSanitizer — Clang 4 documentation</title>
+
+ <link rel="stylesheet" href="_static/haiku.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: './',
+ VERSION: '4',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+ <link rel="top" title="Clang 4 documentation" href="index.html" />
+ <link rel="next" title="MemorySanitizer" href="MemorySanitizer.html" />
+ <link rel="prev" title="AddressSanitizer" href="AddressSanitizer.html" />
+ </head>
+ <body>
+ <div class="header"><h1 class="heading"><a href="index.html">
+ <span>Clang 4 documentation</span></a></h1>
+ <h2 class="heading"><span>ThreadSanitizer</span></h2>
+ </div>
+ <div class="topnav">
+
+ <p>
+ « <a href="AddressSanitizer.html">AddressSanitizer</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="MemorySanitizer.html">MemorySanitizer</a> »
+ </p>
+
+ </div>
+ <div class="content">
+
+
+ <div class="section" id="threadsanitizer">
+<h1>ThreadSanitizer<a class="headerlink" href="#threadsanitizer" title="Permalink to this headline">¶</a></h1>
+<div class="section" id="introduction">
+<h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>ThreadSanitizer is a tool that detects data races. It consists of a compiler
+instrumentation module and a run-time library. Typical slowdown introduced by
+ThreadSanitizer is about <strong>5x-15x</strong>. Typical memory overhead introduced by
+ThreadSanitizer is about <strong>5x-10x</strong>.</p>
+</div>
+<div class="section" id="how-to-build">
+<h2>How to build<a class="headerlink" href="#how-to-build" title="Permalink to this headline">¶</a></h2>
+<p>Build LLVM/Clang with <a class="reference external" href="http://llvm.org/docs/CMake.html">CMake</a>.</p>
+</div>
+<div class="section" id="supported-platforms">
+<h2>Supported Platforms<a class="headerlink" href="#supported-platforms" title="Permalink to this headline">¶</a></h2>
+<p>ThreadSanitizer is supported on Linux x86_64 (tested on Ubuntu 12.04).
+Support for other 64-bit architectures is possible, contributions are welcome.
+Support for 32-bit platforms is problematic and is not planned.</p>
+</div>
+<div class="section" id="usage">
+<h2>Usage<a class="headerlink" href="#usage" title="Permalink to this headline">¶</a></h2>
+<p>Simply compile and link your program with <tt class="docutils literal"><span class="pre">-fsanitize=thread</span></tt>. To get a
+reasonable performance add <tt class="docutils literal"><span class="pre">-O1</span></tt> or higher. Use <tt class="docutils literal"><span class="pre">-g</span></tt> to get file names
+and line numbers in the warning messages.</p>
+<p>Example:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> cat projects/compiler-rt/lib/tsan/lit_tests/tiny_race.c
+<span class="gp">#</span>include <pthread.h>
+<span class="go">int Global;</span>
+<span class="go">void *Thread1(void *x) {</span>
+<span class="go"> Global = 42;</span>
+<span class="go"> return x;</span>
+<span class="go">}</span>
+<span class="go">int main() {</span>
+<span class="go"> pthread_t t;</span>
+<span class="go"> pthread_create(&t, NULL, Thread1, NULL);</span>
+<span class="go"> Global = 43;</span>
+<span class="go"> pthread_join(t, NULL);</span>
+<span class="go"> return Global;</span>
+<span class="go">}</span>
+
+<span class="gp">$</span> clang -fsanitize<span class="o">=</span>thread -g -O1 tiny_race.c
+</pre></div>
+</div>
+<p>If a bug is detected, the program will print an error message to stderr.
+Currently, ThreadSanitizer symbolizes its output using an external
+<tt class="docutils literal"><span class="pre">addr2line</span></tt> process (this will be fixed in future).</p>
+<div class="highlight-bash"><div class="highlight"><pre>% ./a.out
+WARNING: ThreadSanitizer: data race <span class="o">(</span><span class="nv">pid</span><span class="o">=</span>19219<span class="o">)</span>
+ Write of size 4 at 0x7fcf47b21bc0 by thread T1:
+ <span class="c">#0 Thread1 tiny_race.c:4 (exe+0x00000000a360)</span>
+
+ Previous write of size 4 at 0x7fcf47b21bc0 by main thread:
+ <span class="c">#0 main tiny_race.c:10 (exe+0x00000000a3b4)</span>
+
+ Thread T1 <span class="o">(</span>running<span class="o">)</span> created at:
+ <span class="c">#0 pthread_create tsan_interceptors.cc:705 (exe+0x00000000c790)</span>
+ <span class="c">#1 main tiny_race.c:9 (exe+0x00000000a3a4)</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="has-feature-thread-sanitizer">
+<h2><tt class="docutils literal"><span class="pre">__has_feature(thread_sanitizer)</span></tt><a class="headerlink" href="#has-feature-thread-sanitizer" title="Permalink to this headline">¶</a></h2>
+<p>In some cases one may need to execute different code depending on whether
+ThreadSanitizer is enabled.
+<a class="reference internal" href="LanguageExtensions.html#langext-has-feature-has-extension"><em>__has_feature</em></a> can be used for
+this purpose.</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="cp">#if defined(__has_feature)</span>
+<span class="cp"># if __has_feature(thread_sanitizer)</span>
+<span class="c1">// code that builds only under ThreadSanitizer</span>
+<span class="cp"># endif</span>
+<span class="cp">#endif</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="attribute-no-sanitize-thread">
+<h2><tt class="docutils literal"><span class="pre">__attribute__((no_sanitize("thread")))</span></tt><a class="headerlink" href="#attribute-no-sanitize-thread" title="Permalink to this headline">¶</a></h2>
+<p>Some code should not be instrumented by ThreadSanitizer. One may use the
+function attribute <tt class="docutils literal"><span class="pre">no_sanitize("thread")</span></tt> to disable instrumentation of plain
+(non-atomic) loads/stores in a particular function. ThreadSanitizer still
+instruments such functions to avoid false positives and provide meaningful stack
+traces. This attribute may not be supported by other compilers, so we suggest
+to use it together with <tt class="docutils literal"><span class="pre">__has_feature(thread_sanitizer)</span></tt>.</p>
+</div>
+<div class="section" id="blacklist">
+<h2>Blacklist<a class="headerlink" href="#blacklist" title="Permalink to this headline">¶</a></h2>
+<p>ThreadSanitizer supports <tt class="docutils literal"><span class="pre">src</span></tt> and <tt class="docutils literal"><span class="pre">fun</span></tt> entity types in
+<a class="reference internal" href="SanitizerSpecialCaseList.html"><em>Sanitizer special case list</em></a>, that can be used to suppress data race reports
+in the specified source files or functions. Unlike functions marked with
+<tt class="docutils literal"><span class="pre">no_sanitize("thread")</span></tt> attribute, blacklisted functions are not instrumented
+at all. This can lead to false positives due to missed synchronization via
+atomic operations and missed stack frames in reports.</p>
+</div>
+<div class="section" id="limitations">
+<h2>Limitations<a class="headerlink" href="#limitations" title="Permalink to this headline">¶</a></h2>
+<ul class="simple">
+<li>ThreadSanitizer uses more real memory than a native run. At the default
+settings the memory overhead is 5x plus 1Mb per each thread. Settings with 3x
+(less accurate analysis) and 9x (more accurate analysis) overhead are also
+available.</li>
+<li>ThreadSanitizer maps (but does not reserve) a lot of virtual address space.
+This means that tools like <tt class="docutils literal"><span class="pre">ulimit</span></tt> may not work as usually expected.</li>
+<li>Libc/libstdc++ static linking is not supported.</li>
+<li>Non-position-independent executables are not supported. Therefore, the
+<tt class="docutils literal"><span class="pre">fsanitize=thread</span></tt> flag will cause Clang to act as though the <tt class="docutils literal"><span class="pre">-fPIE</span></tt>
+flag had been supplied if compiling without <tt class="docutils literal"><span class="pre">-fPIC</span></tt>, and as though the
+<tt class="docutils literal"><span class="pre">-pie</span></tt> flag had been supplied if linking an executable.</li>
+</ul>
+</div>
+<div class="section" id="current-status">
+<h2>Current Status<a class="headerlink" href="#current-status" title="Permalink to this headline">¶</a></h2>
+<p>ThreadSanitizer is in beta stage. It is known to work on large C++ programs
+using pthreads, but we do not promise anything (yet). C++11 threading is
+supported with llvm libc++. The test suite is integrated into CMake build
+and can be run with <tt class="docutils literal"><span class="pre">make</span> <span class="pre">check-tsan</span></tt> command.</p>
+<p>We are actively working on enhancing the tool — stay tuned. Any help,
+especially in the form of minimized standalone tests is more than welcome.</p>
+</div>
+<div class="section" id="more-information">
+<h2>More Information<a class="headerlink" href="#more-information" title="Permalink to this headline">¶</a></h2>
+<p><a class="reference external" href="https://github.com/google/sanitizers/wiki/ThreadSanitizerCppManual">https://github.com/google/sanitizers/wiki/ThreadSanitizerCppManual</a></p>
+</div>
+</div>
+
+
+ </div>
+ <div class="bottomnav">
+
+ <p>
+ « <a href="AddressSanitizer.html">AddressSanitizer</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="MemorySanitizer.html">MemorySanitizer</a> »
+ </p>
+
+ </div>
+
+ <div class="footer">
+ © Copyright 2007-2017, The Clang Team.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/4.0.0/tools/clang/docs/Toolchain.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/4.0.0/tools/clang/docs/Toolchain.html?rev=297634&view=auto
==============================================================================
--- www-releases/trunk/4.0.0/tools/clang/docs/Toolchain.html (added)
+++ www-releases/trunk/4.0.0/tools/clang/docs/Toolchain.html Mon Mar 13 11:30:12 2017
@@ -0,0 +1,385 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>Assembling a Complete Toolchain — Clang 4 documentation</title>
+
+ <link rel="stylesheet" href="_static/haiku.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: './',
+ VERSION: '4',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+ <link rel="top" title="Clang 4 documentation" href="index.html" />
+ <link rel="next" title="Clang Language Extensions" href="LanguageExtensions.html" />
+ <link rel="prev" title="Clang Compiler Userâs Manual" href="UsersManual.html" />
+ </head>
+ <body>
+ <div class="header"><h1 class="heading"><a href="index.html">
+ <span>Clang 4 documentation</span></a></h1>
+ <h2 class="heading"><span>Assembling a Complete Toolchain</span></h2>
+ </div>
+ <div class="topnav">
+
+ <p>
+ « <a href="UsersManual.html">Clang Compiler User’s Manual</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="LanguageExtensions.html">Clang Language Extensions</a> »
+ </p>
+
+ </div>
+ <div class="content">
+
+
+ <div class="section" id="assembling-a-complete-toolchain">
+<h1>Assembling a Complete Toolchain<a class="headerlink" href="#assembling-a-complete-toolchain" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#introduction" id="id8">Introduction</a></li>
+<li><a class="reference internal" href="#tools" id="id9">Tools</a><ul>
+<li><a class="reference internal" href="#clang-frontend" id="id10">Clang frontend</a></li>
+<li><a class="reference internal" href="#language-frontends-for-other-languages" id="id11">Language frontends for other languages</a></li>
+<li><a class="reference internal" href="#assember" id="id12">Assember</a></li>
+<li><a class="reference internal" href="#linker" id="id13">Linker</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#runtime-libraries" id="id14">Runtime libraries</a><ul>
+<li><a class="reference internal" href="#compiler-runtime" id="id15">Compiler runtime</a></li>
+<li><a class="reference internal" href="#atomics-library" id="id16">Atomics library</a></li>
+<li><a class="reference internal" href="#unwind-library" id="id17">Unwind library</a></li>
+<li><a class="reference internal" href="#sanitizer-runtime" id="id18">Sanitizer runtime</a></li>
+<li><a class="reference internal" href="#c-standard-library" id="id19">C standard library</a></li>
+<li><a class="reference internal" href="#c-abi-library" id="id20">C++ ABI library</a></li>
+<li><a class="reference internal" href="#id6" id="id21">C++ standard library</a></li>
+</ul>
+</li>
+</ul>
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id8">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>Clang is only one component in a complete tool chain for C family
+programming languages. In order to assemble a complete toolchain,
+additional tools and runtime libraries are required. Clang is designed
+to interoperate with existing tools and libraries for its target
+platforms, and the LLVM project provides alternatives for a number
+of these components.</p>
+<p>This document describes the required and optional components in a
+complete toolchain, where to find them, and the supported versions
+and limitations of each option.</p>
+<div class="admonition warning">
+<p class="first admonition-title">Warning</p>
+<p class="last">This document currently describes Clang configurations on POSIX-like
+operating systems with the GCC-compatible <tt class="docutils literal"><span class="pre">clang</span></tt> driver. When
+targeting Windows with the MSVC-compatible <tt class="docutils literal"><span class="pre">clang-cl</span></tt> driver, some
+of the details are different.</p>
+</div>
+</div>
+<div class="section" id="tools">
+<h2><a class="toc-backref" href="#id9">Tools</a><a class="headerlink" href="#tools" title="Permalink to this headline">¶</a></h2>
+<p>A complete compilation of C family programming languages typically
+involves the following pipeline of tools, some of which are omitted
+in some compilations:</p>
+<ul class="simple">
+<li><strong>Preprocessor</strong>: This performs the actions of the C preprocessor:
+expanding #includes and #defines.
+The <tt class="docutils literal"><span class="pre">-E</span></tt> flag instructs Clang to stop after this step.</li>
+<li><strong>Parsing</strong>: This parses and semantically analyzes the source language and
+builds a source-level intermediate representation (“AST”), producing a
+<a class="reference internal" href="UsersManual.html#usersmanual-precompiled-headers"><em>precompiled header (PCH)</em></a>,
+preamble, or
+<a class="reference internal" href="Modules.html"><em>precompiled module file (PCM)</em></a>,
+depending on the input.
+The <tt class="docutils literal"><span class="pre">-precompile</span></tt> flag instructs Clang to stop after this step. This is
+the default when the input is a header file.</li>
+<li><strong>IR generation</strong>: This converts the source-level intermediate representation
+into an optimizer-specific intermediate representation (IR); for Clang, this
+is LLVM IR.
+The <tt class="docutils literal"><span class="pre">-emit-llvm</span></tt> flag instructs Clang to stop after this step. If combined
+with <tt class="docutils literal"><span class="pre">-S</span></tt>, Clang will produce textual LLVM IR; otherwise, it will produce
+LLVM IR bitcode.</li>
+<li><strong>Compiler backend</strong>: This converts the intermediate representation
+into target-specific assembly code.
+The <tt class="docutils literal"><span class="pre">-S</span></tt> flag instructs Clang to stop after this step.</li>
+<li><strong>Assembler</strong>: This converts target-specific assembly code into
+target-specific machine code object files.
+The <tt class="docutils literal"><span class="pre">-c</span></tt> flag instructs Clang to stop after this step.</li>
+<li><strong>Linker</strong>: This combines multiple object files into a single image
+(either a shared object or an executable).</li>
+</ul>
+<p>Clang provides all of these pieces other than the linker. When multiple
+steps are performed by the same tool, it is common for the steps to be
+fused together to avoid creating intermediate files.</p>
+<p>When given an output of one of the above steps as an input, earlier steps
+are skipped (for instance, a <tt class="docutils literal"><span class="pre">.s</span></tt> file input will be assembled and linked).</p>
+<p>The Clang driver can be invoked with the <tt class="docutils literal"><span class="pre">-###</span></tt> flag (this argument will need
+to be escaped under most shells) to see which commands it would run for the
+above steps, without running them. The <tt class="docutils literal"><span class="pre">-v</span></tt> (verbose) flag will print the
+commands in addition to running them.</p>
+<div class="section" id="clang-frontend">
+<h3><a class="toc-backref" href="#id10">Clang frontend</a><a class="headerlink" href="#clang-frontend" title="Permalink to this headline">¶</a></h3>
+<p>The Clang frontend (<tt class="docutils literal"><span class="pre">clang</span> <span class="pre">-cc1</span></tt>) is used to compile C family languages. The
+command-line interface of the frontend is considered to be an implementation
+detail, intentionally has no external documentation, and is subject to change
+without notice.</p>
+</div>
+<div class="section" id="language-frontends-for-other-languages">
+<h3><a class="toc-backref" href="#id11">Language frontends for other languages</a><a class="headerlink" href="#language-frontends-for-other-languages" title="Permalink to this headline">¶</a></h3>
+<p>Clang can be provided with inputs written in non-C-family languages. In such
+cases, an external tool will be used to compile the input. The
+currently-supported languages are:</p>
+<ul class="simple">
+<li>Ada (<tt class="docutils literal"><span class="pre">-x</span> <span class="pre">ada</span></tt>, <tt class="docutils literal"><span class="pre">.ad[bs]</span></tt>)</li>
+<li>Fortran (<tt class="docutils literal"><span class="pre">-x</span> <span class="pre">f95</span></tt>, <tt class="docutils literal"><span class="pre">.f</span></tt>, <tt class="docutils literal"><span class="pre">.f9[05]</span></tt>, <tt class="docutils literal"><span class="pre">.for</span></tt>, <tt class="docutils literal"><span class="pre">.fpp</span></tt>, case-insensitive)</li>
+<li>Java (<tt class="docutils literal"><span class="pre">-x</span> <span class="pre">java</span></tt>)</li>
+</ul>
+<p>In each case, GCC will be invoked to compile the input.</p>
+</div>
+<div class="section" id="assember">
+<h3><a class="toc-backref" href="#id12">Assember</a><a class="headerlink" href="#assember" title="Permalink to this headline">¶</a></h3>
+<p>Clang can either use LLVM’s integrated assembler or an external system-specific
+tool (for instance, the GNU Assembler on GNU OSes) to produce machine code from
+assembly.
+By default, Clang uses LLVM’s integrataed assembler on all targets where it is
+supported. If you wish to use the system assember instead, use the
+<tt class="docutils literal"><span class="pre">-fno-integrated-as</span></tt> option.</p>
+</div>
+<div class="section" id="linker">
+<h3><a class="toc-backref" href="#id13">Linker</a><a class="headerlink" href="#linker" title="Permalink to this headline">¶</a></h3>
+<p>Clang can be configured to use one of several different linkers:</p>
+<ul class="simple">
+<li>GNU ld</li>
+<li>GNU gold</li>
+<li>LLVM’s <a class="reference external" href="http://lld.llvm.org">lld</a></li>
+<li>MSVC’s link.exe</li>
+</ul>
+<p>Link-time optimization is natively supported by lld, and supported via
+a <a class="reference external" href="http://llvm.org/docs/GoldPlugin.html">linker plugin</a> when using gold.</p>
+<p>The default linker varies between targets, and can be overridden via the
+<tt class="docutils literal"><span class="pre">-fuse-ld=<linker</span> <span class="pre">name></span></tt> flag.</p>
+</div>
+</div>
+<div class="section" id="runtime-libraries">
+<h2><a class="toc-backref" href="#id14">Runtime libraries</a><a class="headerlink" href="#runtime-libraries" title="Permalink to this headline">¶</a></h2>
+<p>A number of different runtime libraries are required to provide different
+layers of support for C family programs. Clang will implicitly link an
+appropriate implementation of each runtime library, selected based on
+target defaults or explicitly selected by the <tt class="docutils literal"><span class="pre">--rtlib=</span></tt> and <tt class="docutils literal"><span class="pre">--stdlib=</span></tt>
+flags.</p>
+<p>The set of implicitly-linked libraries depend on the language mode. As a
+consequence, you should use <tt class="docutils literal"><span class="pre">clang++</span></tt> when linking C++ programs in order
+to ensure the C++ runtimes are provided.</p>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">There may exist other implementations for these components not described
+below. Please let us know how well those other implementations work with
+Clang so they can be added to this list!</p>
+</div>
+<div class="section" id="compiler-runtime">
+<h3><a class="toc-backref" href="#id15">Compiler runtime</a><a class="headerlink" href="#compiler-runtime" title="Permalink to this headline">¶</a></h3>
+<p>The compiler runtime library provides definitions of functions implicitly
+invoked by the compiler to support operations not natively supported by
+the underlying hardware (for instance, 128-bit integer multiplications),
+and where inline expansion of the operation is deemed unsuitable.</p>
+<p>The default runtime library is target-specific. For targets where GCC is
+the dominant compiler, Clang currently defaults to using libgcc_s. On most
+other targets, compiler-rt is used by default.</p>
+<div class="section" id="compiler-rt-llvm">
+<h4>compiler-rt (LLVM)<a class="headerlink" href="#compiler-rt-llvm" title="Permalink to this headline">¶</a></h4>
+<p><a class="reference external" href="http://compiler-rt.llvm.org/">LLVM’s compiler runtime library</a> provides a
+complete set of runtime library functions containing all functions that
+Clang will implicitly call, in <tt class="docutils literal"><span class="pre">libclang_rt.builtins.<arch>.a</span></tt>.</p>
+<p>You can instruct Clang to use compiler-rt with the <tt class="docutils literal"><span class="pre">--rtlib=compiler-rt</span></tt> flag.
+This is not supported on every platform.</p>
+<p>If using libc++ and/or libc++abi, you may need to configure them to use
+compiler-rt rather than libgcc_s by passing <tt class="docutils literal"><span class="pre">-DLIBCXX_USE_COMPILER_RT=YES</span></tt>
+and/or <tt class="docutils literal"><span class="pre">-DLIBCXXABI_USE_COMPILER_RT=YES</span></tt> to <tt class="docutils literal"><span class="pre">cmake</span></tt>. Otherwise, you
+may end up with both runtime libraries linked into your program (this is
+typically harmless, but wasteful).</p>
+</div>
+<div class="section" id="libgcc-s-gnu">
+<h4>libgcc_s (GNU)<a class="headerlink" href="#libgcc-s-gnu" title="Permalink to this headline">¶</a></h4>
+<p><a class="reference external" href="https://gcc.gnu.org/onlinedocs/gccint/Libgcc.html">GCC’s runtime library</a>
+can be used in place of compiler-rt. However, it lacks several functions
+that LLVM may emit references to, particularly when using Clang’s
+<tt class="docutils literal"><span class="pre">__builtin_*_overflow</span></tt> family of intrinsics.</p>
+<p>You can instruct Clang to use libgcc_s with the <tt class="docutils literal"><span class="pre">--rtlib=libgcc</span></tt> flag.
+This is not supported on every platform.</p>
+</div>
+</div>
+<div class="section" id="atomics-library">
+<h3><a class="toc-backref" href="#id16">Atomics library</a><a class="headerlink" href="#atomics-library" title="Permalink to this headline">¶</a></h3>
+<p>If your program makes use of atomic operations and the compiler is not able
+to lower them all directly to machine instructions (because there either is
+no known suitable machine instruction or the operand is not known to be
+suitably aligned), a call to a runtime library <tt class="docutils literal"><span class="pre">__atomic_*</span></tt> function
+will be generated. A runtime library containing these atomics functions is
+necessary for such programs.</p>
+<div class="section" id="id1">
+<h4>compiler-rt (LLVM)<a class="headerlink" href="#id1" title="Permalink to this headline">¶</a></h4>
+<p>compiler-rt contains an implementation of an atomics library.</p>
+</div>
+<div class="section" id="libatomic-gnu">
+<h4>libatomic (GNU)<a class="headerlink" href="#libatomic-gnu" title="Permalink to this headline">¶</a></h4>
+<p>libgcc_s does not provide an implementation of an atomics library. Instead,
+<a class="reference external" href="https://gcc.gnu.org/wiki/Atomic/GCCMM">GCC’s libatomic library</a> can be
+used to supply these when using libgcc_s.</p>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">Clang does not currently automatically link against libatomic when using
+libgcc_s. You may need to manually add <tt class="docutils literal"><span class="pre">-latomic</span></tt> to support this
+configuration when using non-native atomic operations (if you see link errors
+referring to <tt class="docutils literal"><span class="pre">__atomic_*</span></tt> functions).</p>
+</div>
+</div>
+</div>
+<div class="section" id="unwind-library">
+<h3><a class="toc-backref" href="#id17">Unwind library</a><a class="headerlink" href="#unwind-library" title="Permalink to this headline">¶</a></h3>
+<p>The unwind library provides a family of <tt class="docutils literal"><span class="pre">_Unwind_*</span></tt> functions implementing
+the language-neutral stack unwinding portion of the Itanium C++ ABI
+(<a class="reference external" href="http://mentorembedded.github.io/cxx-abi/abi-eh.html#base-abi">Level I</a>).
+It is a dependency of the C++ ABI library, and sometimes is a dependency
+of other runtimes.</p>
+<div class="section" id="libunwind-llvm">
+<h4>libunwind (LLVM)<a class="headerlink" href="#libunwind-llvm" title="Permalink to this headline">¶</a></h4>
+<p>LLVM’s unwinder library can be obtained from subversion:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="go">llvm-src$ svn co http://llvm.org/svn/llvm-project/libunwind/trunk projects/libunwind</span>
+</pre></div>
+</div>
+<p>When checked out into projects/libunwind within an LLVM checkout,
+it should be automatically picked up by the LLVM build system.</p>
+<p>If using libc++abi, you may need to configure it to use libunwind
+rather than libgcc_s by passing <tt class="docutils literal"><span class="pre">-DLIBCXXABI_USE_LLVM_UNWINDER=YES</span></tt>
+to <tt class="docutils literal"><span class="pre">cmake</span></tt>. If libc++abi is configured to use some version of
+libunwind, that library will be implicitly linked into binaries that
+link to libc++abi.</p>
+</div>
+<div class="section" id="id2">
+<h4>libgcc_s (GNU)<a class="headerlink" href="#id2" title="Permalink to this headline">¶</a></h4>
+<p>libgcc_s has an integrated unwinder, and does not need an external unwind
+library to be provided.</p>
+</div>
+<div class="section" id="libunwind-nongnu-org">
+<h4>libunwind (nongnu.org)<a class="headerlink" href="#libunwind-nongnu-org" title="Permalink to this headline">¶</a></h4>
+<p>This is another implementation of the libunwind specification.
+See <a class="reference external" href="http://www.nongnu.org/libunwind">libunwind (nongnu.org)</a>.</p>
+</div>
+<div class="section" id="libunwind-pathscale">
+<h4>libunwind (PathScale)<a class="headerlink" href="#libunwind-pathscale" title="Permalink to this headline">¶</a></h4>
+<p>This is another implementation of the libunwind specification.
+See <a class="reference external" href="https://github.com/pathscale/libunwind">libunwind (pathscale)</a>.</p>
+</div>
+</div>
+<div class="section" id="sanitizer-runtime">
+<h3><a class="toc-backref" href="#id18">Sanitizer runtime</a><a class="headerlink" href="#sanitizer-runtime" title="Permalink to this headline">¶</a></h3>
+<p>The instrumentation added by Clang’s sanitizers (<tt class="docutils literal"><span class="pre">-fsanitize=...</span></tt>) implicitly
+makes calls to a runtime library, in order to maintain side state about the
+execution of the program and to issue diagnostic messages when a problem is
+detected.</p>
+<p>The only supported implementation of these runtimes is provided by LLVM’s
+compiler-rt, and the relevant portion of that library
+(<tt class="docutils literal"><span class="pre">libclang_rt.<sanitizer>.<arch>.a</span></tt>)
+will be implicitly linked when linking with a <tt class="docutils literal"><span class="pre">-fsanitize=...</span></tt> flag.</p>
+</div>
+<div class="section" id="c-standard-library">
+<h3><a class="toc-backref" href="#id19">C standard library</a><a class="headerlink" href="#c-standard-library" title="Permalink to this headline">¶</a></h3>
+<p>Clang supports a wide variety of
+<a class="reference external" href="http://en.cppreference.com/w/c">C standard library</a>
+implementations.</p>
+</div>
+<div class="section" id="c-abi-library">
+<h3><a class="toc-backref" href="#id20">C++ ABI library</a><a class="headerlink" href="#c-abi-library" title="Permalink to this headline">¶</a></h3>
+<p>The C++ ABI library provides an implementation of the library portion of
+the Itanium C++ ABI, covering both the
+<a class="reference external" href="http://mentorembedded.github.io/cxx-abi/abi.html">support functionality in the main Itanium C++ ABI document</a> and
+<a class="reference external" href="http://mentorembedded.github.io/cxx-abi/abi-eh.html#cxx-abi">Level II of the exception handling support</a>.
+References to the functions and objects in this library are implicitly
+generated by Clang when compiling C++ code.</p>
+<p>While it is possible to link C++ code using libstdc++ and code using libc++
+together into the same program (so long as you do not attempt to pass C++
+standard library objects across the boundary), it is not generally possible
+to have more than one C++ ABI library in a program.</p>
+<p>The version of the C++ ABI library used by Clang will be the one that the
+chosen C++ standard library was linked against. Several implementations are
+available:</p>
+<div class="section" id="libc-abi-llvm">
+<h4>libc++abi (LLVM)<a class="headerlink" href="#libc-abi-llvm" title="Permalink to this headline">¶</a></h4>
+<p><a class="reference external" href="http://libcxxabi.llvm.org/">libc++abi</a> is LLVM’s implementation of this
+specification.</p>
+</div>
+<div class="section" id="libsupc-gnu">
+<h4>libsupc++ (GNU)<a class="headerlink" href="#libsupc-gnu" title="Permalink to this headline">¶</a></h4>
+<p>libsupc++ is GCC’s implementation of this specification. However, this
+library is only used when libstdc++ is linked statically. The dynamic
+library version of libstdc++ contains a copy of libsupc++.</p>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">Clang does not currently automatically link against libatomic when statically
+linking libstdc++. You may need to manually add <tt class="docutils literal"><span class="pre">-lsupc++</span></tt> to support this
+configuration when using <tt class="docutils literal"><span class="pre">-static</span></tt> or <tt class="docutils literal"><span class="pre">-static-libstdc++</span></tt>.</p>
+</div>
+</div>
+<div class="section" id="libcxxrt-pathscale">
+<h4>libcxxrt (PathScale)<a class="headerlink" href="#libcxxrt-pathscale" title="Permalink to this headline">¶</a></h4>
+<p>This is another implementation of the Itanium C++ ABI specification.
+See <a class="reference external" href="https://github.com/pathscale/libcxxrt">libcxxrt</a>.</p>
+</div>
+</div>
+<div class="section" id="id6">
+<h3><a class="toc-backref" href="#id21">C++ standard library</a><a class="headerlink" href="#id6" title="Permalink to this headline">¶</a></h3>
+<p>Clang supports use of either LLVM’s libc++ or GCC’s libstdc++ implementation
+of the <a class="reference external" href="http://en.cppreference.com/w/cpp">C++ standard library</a>.</p>
+<div class="section" id="libc-llvm">
+<h4>libc++ (LLVM)<a class="headerlink" href="#libc-llvm" title="Permalink to this headline">¶</a></h4>
+<p><a class="reference external" href="http://libcxx.llvm.org/">libc++</a> is LLVM’s implementation of the C++
+standard library, aimed at being a complete implementation of the C++
+standards from C++11 onwards.</p>
+<p>You can instruct Clang to use libc++ with the <tt class="docutils literal"><span class="pre">-stdlib=libc++</span></tt> flag.</p>
+</div>
+<div class="section" id="libstdc-gnu">
+<h4>libstdc++ (GNU)<a class="headerlink" href="#libstdc-gnu" title="Permalink to this headline">¶</a></h4>
+<p><a class="reference external" href="https://gcc.gnu.org/onlinedocs/libstdc++/">libstdc++</a> is GCC’s implementation
+of the C++ standard library. Clang supports a wide range of versions of
+libstdc++, from around version 4.2 onwards, and will implicitly work around
+some bugs in older versions of libstdc++.</p>
+<p>You can instruct Clang to use libstdc++ with the <tt class="docutils literal"><span class="pre">-stdlib=libstdc++</span></tt> flag.</p>
+</div>
+</div>
+</div>
+</div>
+
+
+ </div>
+ <div class="bottomnav">
+
+ <p>
+ « <a href="UsersManual.html">Clang Compiler User’s Manual</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="LanguageExtensions.html">Clang Language Extensions</a> »
+ </p>
+
+ </div>
+
+ <div class="footer">
+ © Copyright 2007-2017, The Clang Team.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/4.0.0/tools/clang/docs/Tooling.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/4.0.0/tools/clang/docs/Tooling.html?rev=297634&view=auto
==============================================================================
--- www-releases/trunk/4.0.0/tools/clang/docs/Tooling.html (added)
+++ www-releases/trunk/4.0.0/tools/clang/docs/Tooling.html Mon Mar 13 11:30:12 2017
@@ -0,0 +1,162 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>Choosing the Right Interface for Your Application — Clang 4 documentation</title>
+
+ <link rel="stylesheet" href="_static/haiku.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: './',
+ VERSION: '4',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+ <link rel="top" title="Clang 4 documentation" href="index.html" />
+ <link rel="next" title="External Clang Examples" href="ExternalClangExamples.html" />
+ <link rel="prev" title="Frequently Asked Questions (FAQ)" href="FAQ.html" />
+ </head>
+ <body>
+ <div class="header"><h1 class="heading"><a href="index.html">
+ <span>Clang 4 documentation</span></a></h1>
+ <h2 class="heading"><span>Choosing the Right Interface for Your Application</span></h2>
+ </div>
+ <div class="topnav">
+
+ <p>
+ « <a href="FAQ.html">Frequently Asked Questions (FAQ)</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="ExternalClangExamples.html">External Clang Examples</a> »
+ </p>
+
+ </div>
+ <div class="content">
+
+
+ <div class="section" id="choosing-the-right-interface-for-your-application">
+<h1>Choosing the Right Interface for Your Application<a class="headerlink" href="#choosing-the-right-interface-for-your-application" title="Permalink to this headline">¶</a></h1>
+<p>Clang provides infrastructure to write tools that need syntactic and semantic
+information about a program. This document will give a short introduction of
+the different ways to write clang tools, and their pros and cons.</p>
+<div class="section" id="libclang">
+<h2>LibClang<a class="headerlink" href="#libclang" title="Permalink to this headline">¶</a></h2>
+<p><a class="reference external" href="http://clang.llvm.org/doxygen/group__CINDEX.html">LibClang</a> is a stable high
+level C interface to clang. When in doubt LibClang is probably the interface
+you want to use. Consider the other interfaces only when you have a good
+reason not to use LibClang.</p>
+<p>Canonical examples of when to use LibClang:</p>
+<ul class="simple">
+<li>Xcode</li>
+<li>Clang Python Bindings</li>
+</ul>
+<p>Use LibClang when you...:</p>
+<ul class="simple">
+<li>want to interface with clang from other languages than C++</li>
+<li>need a stable interface that takes care to be backwards compatible</li>
+<li>want powerful high-level abstractions, like iterating through an AST with a
+cursor, and don’t want to learn all the nitty gritty details of Clang’s AST.</li>
+</ul>
+<p>Do not use LibClang when you...:</p>
+<ul class="simple">
+<li>want full control over the Clang AST</li>
+</ul>
+</div>
+<div class="section" id="clang-plugins">
+<h2>Clang Plugins<a class="headerlink" href="#clang-plugins" title="Permalink to this headline">¶</a></h2>
+<p><a class="reference internal" href="ClangPlugins.html"><em>Clang Plugins</em></a> allow you to run additional actions on the
+AST as part of a compilation. Plugins are dynamic libraries that are loaded at
+runtime by the compiler, and they’re easy to integrate into your build
+environment.</p>
+<p>Canonical examples of when to use Clang Plugins:</p>
+<ul class="simple">
+<li>special lint-style warnings or errors for your project</li>
+<li>creating additional build artifacts from a single compile step</li>
+</ul>
+<p>Use Clang Plugins when you...:</p>
+<ul class="simple">
+<li>need your tool to rerun if any of the dependencies change</li>
+<li>want your tool to make or break a build</li>
+<li>need full control over the Clang AST</li>
+</ul>
+<p>Do not use Clang Plugins when you...:</p>
+<ul class="simple">
+<li>want to run tools outside of your build environment</li>
+<li>want full control on how Clang is set up, including mapping of in-memory
+virtual files</li>
+<li>need to run over a specific subset of files in your project which is not
+necessarily related to any changes which would trigger rebuilds</li>
+</ul>
+</div>
+<div class="section" id="libtooling">
+<h2>LibTooling<a class="headerlink" href="#libtooling" title="Permalink to this headline">¶</a></h2>
+<p><a class="reference internal" href="LibTooling.html"><em>LibTooling</em></a> is a C++ interface aimed at writing standalone
+tools, as well as integrating into services that run clang tools. Canonical
+examples of when to use LibTooling:</p>
+<ul class="simple">
+<li>a simple syntax checker</li>
+<li>refactoring tools</li>
+</ul>
+<p>Use LibTooling when you...:</p>
+<ul class="simple">
+<li>want to run tools over a single file, or a specific subset of files,
+independently of the build system</li>
+<li>want full control over the Clang AST</li>
+<li>want to share code with Clang Plugins</li>
+</ul>
+<p>Do not use LibTooling when you...:</p>
+<ul class="simple">
+<li>want to run as part of the build triggered by dependency changes</li>
+<li>want a stable interface so you don’t need to change your code when the AST API
+changes</li>
+<li>want high level abstractions like cursors and code completion out of the box</li>
+<li>do not want to write your tools in C++</li>
+</ul>
+<p><a class="reference internal" href="ClangTools.html"><em>Clang tools</em></a> are a collection of specific developer tools
+built on top of the LibTooling infrastructure as part of the Clang project.
+They are targeted at automating and improving core development activities of
+C/C++ developers.</p>
+<p>Examples of tools we are building or planning as part of the Clang project:</p>
+<ul class="simple">
+<li>Syntax checking (<strong class="program">clang-check</strong>)</li>
+<li>Automatic fixing of compile errors (<strong class="program">clang-fixit</strong>)</li>
+<li>Automatic code formatting (<strong class="program">clang-format</strong>)</li>
+<li>Migration tools for new features in new language standards</li>
+<li>Core refactoring tools</li>
+</ul>
+</div>
+</div>
+
+
+ </div>
+ <div class="bottomnav">
+
+ <p>
+ « <a href="FAQ.html">Frequently Asked Questions (FAQ)</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="ExternalClangExamples.html">External Clang Examples</a> »
+ </p>
+
+ </div>
+
+ <div class="footer">
+ © Copyright 2007-2017, The Clang Team.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/4.0.0/tools/clang/docs/UndefinedBehaviorSanitizer.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/4.0.0/tools/clang/docs/UndefinedBehaviorSanitizer.html?rev=297634&view=auto
==============================================================================
--- www-releases/trunk/4.0.0/tools/clang/docs/UndefinedBehaviorSanitizer.html (added)
+++ www-releases/trunk/4.0.0/tools/clang/docs/UndefinedBehaviorSanitizer.html Mon Mar 13 11:30:12 2017
@@ -0,0 +1,333 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>UndefinedBehaviorSanitizer — Clang 4 documentation</title>
+
+ <link rel="stylesheet" href="_static/haiku.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: './',
+ VERSION: '4',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+ <link rel="top" title="Clang 4 documentation" href="index.html" />
+ <link rel="next" title="DataFlowSanitizer" href="DataFlowSanitizer.html" />
+ <link rel="prev" title="MemorySanitizer" href="MemorySanitizer.html" />
+ </head>
+ <body>
+ <div class="header"><h1 class="heading"><a href="index.html">
+ <span>Clang 4 documentation</span></a></h1>
+ <h2 class="heading"><span>UndefinedBehaviorSanitizer</span></h2>
+ </div>
+ <div class="topnav">
+
+ <p>
+ « <a href="MemorySanitizer.html">MemorySanitizer</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="DataFlowSanitizer.html">DataFlowSanitizer</a> »
+ </p>
+
+ </div>
+ <div class="content">
+
+
+ <div class="section" id="undefinedbehaviorsanitizer">
+<h1>UndefinedBehaviorSanitizer<a class="headerlink" href="#undefinedbehaviorsanitizer" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#introduction" id="id1">Introduction</a></li>
+<li><a class="reference internal" href="#how-to-build" id="id2">How to build</a></li>
+<li><a class="reference internal" href="#usage" id="id3">Usage</a></li>
+<li><a class="reference internal" href="#available-checks" id="id4">Available checks</a></li>
+<li><a class="reference internal" href="#stack-traces-and-report-symbolization" id="id5">Stack traces and report symbolization</a></li>
+<li><a class="reference internal" href="#issue-suppression" id="id6">Issue Suppression</a><ul>
+<li><a class="reference internal" href="#disabling-instrumentation-with-attribute-no-sanitize-undefined" id="id7">Disabling Instrumentation with <tt class="docutils literal"><span class="pre">__attribute__((no_sanitize("undefined")))</span></tt></a></li>
+<li><a class="reference internal" href="#suppressing-errors-in-recompiled-code-blacklist" id="id8">Suppressing Errors in Recompiled Code (Blacklist)</a></li>
+<li><a class="reference internal" href="#runtime-suppressions" id="id9">Runtime suppressions</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#supported-platforms" id="id10">Supported Platforms</a></li>
+<li><a class="reference internal" href="#current-status" id="id11">Current Status</a></li>
+<li><a class="reference internal" href="#additional-configuration" id="id12">Additional Configuration</a><ul>
+<li><a class="reference internal" href="#example" id="id13">Example</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#more-information" id="id14">More Information</a></li>
+</ul>
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id1">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>UndefinedBehaviorSanitizer (UBSan) is a fast undefined behavior detector.
+UBSan modifies the program at compile-time to catch various kinds of undefined
+behavior during program execution, for example:</p>
+<ul class="simple">
+<li>Using misaligned or null pointer</li>
+<li>Signed integer overflow</li>
+<li>Conversion to, from, or between floating-point types which would
+overflow the destination</li>
+</ul>
+<p>See the full list of available <a class="reference internal" href="#ubsan-checks"><em>checks</em></a> below.</p>
+<p>UBSan has an optional run-time library which provides better error reporting.
+The checks have small runtime cost and no impact on address space layout or ABI.</p>
+</div>
+<div class="section" id="how-to-build">
+<h2><a class="toc-backref" href="#id2">How to build</a><a class="headerlink" href="#how-to-build" title="Permalink to this headline">¶</a></h2>
+<p>Build LLVM/Clang with <a class="reference external" href="http://llvm.org/docs/CMake.html">CMake</a>.</p>
+</div>
+<div class="section" id="usage">
+<h2><a class="toc-backref" href="#id3">Usage</a><a class="headerlink" href="#usage" title="Permalink to this headline">¶</a></h2>
+<p>Use <tt class="docutils literal"><span class="pre">clang++</span></tt> to compile and link your program with <tt class="docutils literal"><span class="pre">-fsanitize=undefined</span></tt>
+flag. Make sure to use <tt class="docutils literal"><span class="pre">clang++</span></tt> (not <tt class="docutils literal"><span class="pre">ld</span></tt>) as a linker, so that your
+executable is linked with proper UBSan runtime libraries. You can use <tt class="docutils literal"><span class="pre">clang</span></tt>
+instead of <tt class="docutils literal"><span class="pre">clang++</span></tt> if you’re compiling/linking C code.</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> cat test.cc
+<span class="go">int main(int argc, char **argv) {</span>
+<span class="go"> int k = 0x7fffffff;</span>
+<span class="go"> k += argc;</span>
+<span class="go"> return 0;</span>
+<span class="go">}</span>
+<span class="gp">%</span> clang++ -fsanitize<span class="o">=</span>undefined test.cc
+<span class="gp">%</span> ./a.out
+<span class="go">test.cc:3:5: runtime error: signed integer overflow: 2147483647 + 1 cannot be represented in type 'int'</span>
+</pre></div>
+</div>
+<p>You can enable only a subset of <a class="reference internal" href="#ubsan-checks"><em>checks</em></a> offered by UBSan,
+and define the desired behavior for each kind of check:</p>
+<ul class="simple">
+<li>print a verbose error report and continue execution (default);</li>
+<li>print a verbose error report and exit the program;</li>
+<li>execute a trap instruction (doesn’t require UBSan run-time support).</li>
+</ul>
+<p>For example if you compile/link your program as:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> clang++ -fsanitize<span class="o">=</span>signed-integer-overflow,null,alignment -fno-sanitize-recover<span class="o">=</span>null -fsanitize-trap<span class="o">=</span>alignment
+</pre></div>
+</div>
+<p>the program will continue execution after signed integer overflows, exit after
+the first invalid use of a null pointer, and trap after the first use of misaligned
+pointer.</p>
+</div>
+<div class="section" id="available-checks">
+<span id="ubsan-checks"></span><h2><a class="toc-backref" href="#id4">Available checks</a><a class="headerlink" href="#available-checks" title="Permalink to this headline">¶</a></h2>
+<p>Available checks are:</p>
+<blockquote>
+<div><ul class="simple">
+<li><tt class="docutils literal"><span class="pre">-fsanitize=alignment</span></tt>: Use of a misaligned pointer or creation
+of a misaligned reference.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=bool</span></tt>: Load of a <tt class="docutils literal"><span class="pre">bool</span></tt> value which is neither
+<tt class="docutils literal"><span class="pre">true</span></tt> nor <tt class="docutils literal"><span class="pre">false</span></tt>.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=bounds</span></tt>: Out of bounds array indexing, in cases
+where the array bound can be statically determined.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=enum</span></tt>: Load of a value of an enumerated type which
+is not in the range of representable values for that enumerated
+type.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=float-cast-overflow</span></tt>: Conversion to, from, or
+between floating-point types which would overflow the
+destination.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=float-divide-by-zero</span></tt>: Floating point division by
+zero.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=function</span></tt>: Indirect call of a function through a
+function pointer of the wrong type (Linux, C++ and x86/x86_64 only).</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=integer-divide-by-zero</span></tt>: Integer division by zero.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=nonnull-attribute</span></tt>: Passing null pointer as a function
+parameter which is declared to never be null.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=null</span></tt>: Use of a null pointer or creation of a null
+reference.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=object-size</span></tt>: An attempt to potentially use bytes which
+the optimizer can determine are not part of the object being accessed.
+This will also detect some types of undefined behavior that may not
+directly access memory, but are provably incorrect given the size of
+the objects involved, such as invalid downcasts and calling methods on
+invalid pointers. These checks are made in terms of
+<tt class="docutils literal"><span class="pre">__builtin_object_size</span></tt>, and consequently may be able to detect more
+problems at higher optimization levels.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=return</span></tt>: In C++, reaching the end of a
+value-returning function without returning a value.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=returns-nonnull-attribute</span></tt>: Returning null pointer
+from a function which is declared to never return null.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=shift</span></tt>: Shift operators where the amount shifted is
+greater or equal to the promoted bit-width of the left hand side
+or less than zero, or where the left hand side is negative. For a
+signed left shift, also checks for signed overflow in C, and for
+unsigned overflow in C++. You can use <tt class="docutils literal"><span class="pre">-fsanitize=shift-base</span></tt> or
+<tt class="docutils literal"><span class="pre">-fsanitize=shift-exponent</span></tt> to check only left-hand side or
+right-hand side of shift operation, respectively.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=signed-integer-overflow</span></tt>: Signed integer overflow,
+including all the checks added by <tt class="docutils literal"><span class="pre">-ftrapv</span></tt>, and checking for
+overflow in signed division (<tt class="docutils literal"><span class="pre">INT_MIN</span> <span class="pre">/</span> <span class="pre">-1</span></tt>).</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=unreachable</span></tt>: If control flow reaches
+<tt class="docutils literal"><span class="pre">__builtin_unreachable</span></tt>.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=unsigned-integer-overflow</span></tt>: Unsigned integer
+overflows.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=vla-bound</span></tt>: A variable-length array whose bound
+does not evaluate to a positive value.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=vptr</span></tt>: Use of an object whose vptr indicates that
+it is of the wrong dynamic type, or that its lifetime has not
+begun or has ended. Incompatible with <tt class="docutils literal"><span class="pre">-fno-rtti</span></tt>. Link must
+be performed by <tt class="docutils literal"><span class="pre">clang++</span></tt>, not <tt class="docutils literal"><span class="pre">clang</span></tt>, to make sure C++-specific
+parts of the runtime library and C++ standard libraries are present.</li>
+</ul>
+</div></blockquote>
+<dl class="docutils">
+<dt>You can also use the following check groups:</dt>
+<dd><ul class="first last simple">
+<li><tt class="docutils literal"><span class="pre">-fsanitize=undefined</span></tt>: All of the checks listed above other than
+<tt class="docutils literal"><span class="pre">unsigned-integer-overflow</span></tt>.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=undefined-trap</span></tt>: Deprecated alias of
+<tt class="docutils literal"><span class="pre">-fsanitize=undefined</span></tt>.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=integer</span></tt>: Checks for undefined or suspicious integer
+behavior (e.g. unsigned integer overflow).</li>
+</ul>
+</dd>
+</dl>
+</div>
+<div class="section" id="stack-traces-and-report-symbolization">
+<h2><a class="toc-backref" href="#id5">Stack traces and report symbolization</a><a class="headerlink" href="#stack-traces-and-report-symbolization" title="Permalink to this headline">¶</a></h2>
+<p>If you want UBSan to print symbolized stack trace for each error report, you
+will need to:</p>
+<ol class="arabic simple">
+<li>Compile with <tt class="docutils literal"><span class="pre">-g</span></tt> and <tt class="docutils literal"><span class="pre">-fno-omit-frame-pointer</span></tt> to get proper debug
+information in your binary.</li>
+<li>Run your program with environment variable
+<tt class="docutils literal"><span class="pre">UBSAN_OPTIONS=print_stacktrace=1</span></tt>.</li>
+<li>Make sure <tt class="docutils literal"><span class="pre">llvm-symbolizer</span></tt> binary is in <tt class="docutils literal"><span class="pre">PATH</span></tt>.</li>
+</ol>
+</div>
+<div class="section" id="issue-suppression">
+<h2><a class="toc-backref" href="#id6">Issue Suppression</a><a class="headerlink" href="#issue-suppression" title="Permalink to this headline">¶</a></h2>
+<p>UndefinedBehaviorSanitizer is not expected to produce false positives.
+If you see one, look again; most likely it is a true positive!</p>
+<div class="section" id="disabling-instrumentation-with-attribute-no-sanitize-undefined">
+<h3><a class="toc-backref" href="#id7">Disabling Instrumentation with <tt class="docutils literal"><span class="pre">__attribute__((no_sanitize("undefined")))</span></tt></a><a class="headerlink" href="#disabling-instrumentation-with-attribute-no-sanitize-undefined" title="Permalink to this headline">¶</a></h3>
+<p>You disable UBSan checks for particular functions with
+<tt class="docutils literal"><span class="pre">__attribute__((no_sanitize("undefined")))</span></tt>. You can use all values of
+<tt class="docutils literal"><span class="pre">-fsanitize=</span></tt> flag in this attribute, e.g. if your function deliberately
+contains possible signed integer overflow, you can use
+<tt class="docutils literal"><span class="pre">__attribute__((no_sanitize("signed-integer-overflow")))</span></tt>.</p>
+<p>This attribute may not be
+supported by other compilers, so consider using it together with
+<tt class="docutils literal"><span class="pre">#if</span> <span class="pre">defined(__clang__)</span></tt>.</p>
+</div>
+<div class="section" id="suppressing-errors-in-recompiled-code-blacklist">
+<h3><a class="toc-backref" href="#id8">Suppressing Errors in Recompiled Code (Blacklist)</a><a class="headerlink" href="#suppressing-errors-in-recompiled-code-blacklist" title="Permalink to this headline">¶</a></h3>
+<p>UndefinedBehaviorSanitizer supports <tt class="docutils literal"><span class="pre">src</span></tt> and <tt class="docutils literal"><span class="pre">fun</span></tt> entity types in
+<a class="reference internal" href="SanitizerSpecialCaseList.html"><em>Sanitizer special case list</em></a>, that can be used to suppress error reports
+in the specified source files or functions.</p>
+</div>
+<div class="section" id="runtime-suppressions">
+<h3><a class="toc-backref" href="#id9">Runtime suppressions</a><a class="headerlink" href="#runtime-suppressions" title="Permalink to this headline">¶</a></h3>
+<p>Sometimes you can suppress UBSan error reports for specific files, functions,
+or libraries without recompiling the code. You need to pass a path to
+suppression file in a <tt class="docutils literal"><span class="pre">UBSAN_OPTIONS</span></tt> environment variable.</p>
+<div class="highlight-bash"><div class="highlight"><pre><span class="nv">UBSAN_OPTIONS</span><span class="o">=</span><span class="nv">suppressions</span><span class="o">=</span>MyUBSan.supp
+</pre></div>
+</div>
+<p>You need to specify a <a class="reference internal" href="#ubsan-checks"><em>check</em></a> you are suppressing and the
+bug location. For example:</p>
+<div class="highlight-bash"><div class="highlight"><pre>signed-integer-overflow:file-with-known-overflow.cpp
+alignment:function_doing_unaligned_access
+vptr:shared_object_with_vptr_failures.so
+</pre></div>
+</div>
+<p>There are several limitations:</p>
+<ul class="simple">
+<li>Sometimes your binary must have enough debug info and/or symbol table, so
+that the runtime could figure out source file or function name to match
+against the suppression.</li>
+<li>It is only possible to suppress recoverable checks. For the example above,
+you can additionally pass
+<tt class="docutils literal"><span class="pre">-fsanitize-recover=signed-integer-overflow,alignment,vptr</span></tt>, although
+most of UBSan checks are recoverable by default.</li>
+<li>Check groups (like <tt class="docutils literal"><span class="pre">undefined</span></tt>) can’t be used in suppressions file, only
+fine-grained checks are supported.</li>
+</ul>
+</div>
+</div>
+<div class="section" id="supported-platforms">
+<h2><a class="toc-backref" href="#id10">Supported Platforms</a><a class="headerlink" href="#supported-platforms" title="Permalink to this headline">¶</a></h2>
+<p>UndefinedBehaviorSanitizer is supported on the following OS:</p>
+<ul class="simple">
+<li>Android</li>
+<li>Linux</li>
+<li>FreeBSD</li>
+<li>OS X 10.6 onwards</li>
+</ul>
+<p>and for the following architectures:</p>
+<ul class="simple">
+<li>i386/x86_64</li>
+<li>ARM</li>
+<li>AArch64</li>
+<li>PowerPC64</li>
+<li>MIPS/MIPS64</li>
+</ul>
+</div>
+<div class="section" id="current-status">
+<h2><a class="toc-backref" href="#id11">Current Status</a><a class="headerlink" href="#current-status" title="Permalink to this headline">¶</a></h2>
+<p>UndefinedBehaviorSanitizer is available on selected platforms starting from LLVM
+3.3. The test suite is integrated into the CMake build and can be run with
+<tt class="docutils literal"><span class="pre">check-ubsan</span></tt> command.</p>
+</div>
+<div class="section" id="additional-configuration">
+<h2><a class="toc-backref" href="#id12">Additional Configuration</a><a class="headerlink" href="#additional-configuration" title="Permalink to this headline">¶</a></h2>
+<p>UndefinedBehaviorSanitizer adds static check data for each check unless it is
+in trap mode. This check data includes the full file name. The option
+<tt class="docutils literal"><span class="pre">-fsanitize-undefined-strip-path-components=N</span></tt> can be used to trim this
+information. If <tt class="docutils literal"><span class="pre">N</span></tt> is positive, file information emitted by
+UndefinedBehaviorSanitizer will drop the first <tt class="docutils literal"><span class="pre">N</span></tt> components from the file
+path. If <tt class="docutils literal"><span class="pre">N</span></tt> is negative, the last <tt class="docutils literal"><span class="pre">N</span></tt> components will be kept.</p>
+<div class="section" id="example">
+<h3><a class="toc-backref" href="#id13">Example</a><a class="headerlink" href="#example" title="Permalink to this headline">¶</a></h3>
+<p>For a file called <tt class="docutils literal"><span class="pre">/code/library/file.cpp</span></tt>, here is what would be emitted:
+* Default (No flag, or <tt class="docutils literal"><span class="pre">-fsanitize-undefined-strip-path-components=0</span></tt>): <tt class="docutils literal"><span class="pre">/code/library/file.cpp</span></tt>
+* <tt class="docutils literal"><span class="pre">-fsanitize-undefined-strip-path-components=1</span></tt>: <tt class="docutils literal"><span class="pre">code/library/file.cpp</span></tt>
+* <tt class="docutils literal"><span class="pre">-fsanitize-undefined-strip-path-components=2</span></tt>: <tt class="docutils literal"><span class="pre">library/file.cpp</span></tt>
+* <tt class="docutils literal"><span class="pre">-fsanitize-undefined-strip-path-components=-1</span></tt>: <tt class="docutils literal"><span class="pre">file.cpp</span></tt>
+* <tt class="docutils literal"><span class="pre">-fsanitize-undefined-strip-path-components=-2</span></tt>: <tt class="docutils literal"><span class="pre">library/file.cpp</span></tt></p>
+</div>
+</div>
+<div class="section" id="more-information">
+<h2><a class="toc-backref" href="#id14">More Information</a><a class="headerlink" href="#more-information" title="Permalink to this headline">¶</a></h2>
+<ul class="simple">
+<li>From LLVM project blog:
+<a class="reference external" href="http://blog.llvm.org/2011/05/what-every-c-programmer-should-know.html">What Every C Programmer Should Know About Undefined Behavior</a></li>
+<li>From John Regehr’s <em>Embedded in Academia</em> blog:
+<a class="reference external" href="http://blog.regehr.org/archives/213">A Guide to Undefined Behavior in C and C++</a></li>
+</ul>
+</div>
+</div>
+
+
+ </div>
+ <div class="bottomnav">
+
+ <p>
+ « <a href="MemorySanitizer.html">MemorySanitizer</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="DataFlowSanitizer.html">DataFlowSanitizer</a> »
+ </p>
+
+ </div>
+
+ <div class="footer">
+ © Copyright 2007-2017, The Clang Team.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/4.0.0/tools/clang/docs/UsersManual.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/4.0.0/tools/clang/docs/UsersManual.html?rev=297634&view=auto
==============================================================================
--- www-releases/trunk/4.0.0/tools/clang/docs/UsersManual.html (added)
+++ www-releases/trunk/4.0.0/tools/clang/docs/UsersManual.html Mon Mar 13 11:30:12 2017
@@ -0,0 +1,2704 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>Clang Compiler Userâs Manual — Clang 4 documentation</title>
+
+ <link rel="stylesheet" href="_static/haiku.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: './',
+ VERSION: '4',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+ <link rel="top" title="Clang 4 documentation" href="index.html" />
+ <link rel="next" title="Assembling a Complete Toolchain" href="Toolchain.html" />
+ <link rel="prev" title="Clang 4.0.0 Release Notes" href="ReleaseNotes.html" />
+ </head>
+ <body>
+ <div class="header"><h1 class="heading"><a href="index.html">
+ <span>Clang 4 documentation</span></a></h1>
+ <h2 class="heading"><span>Clang Compiler Userâs Manual</span></h2>
+ </div>
+ <div class="topnav">
+
+ <p>
+ « <a href="ReleaseNotes.html">Clang 4.0.0 Release Notes</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="Toolchain.html">Assembling a Complete Toolchain</a> »
+ </p>
+
+ </div>
+ <div class="content">
+
+
+ <div class="section" id="clang-compiler-user-s-manual">
+<h1>Clang Compiler User’s Manual<a class="headerlink" href="#clang-compiler-user-s-manual" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#introduction" id="id9">Introduction</a><ul>
+<li><a class="reference internal" href="#terminology" id="id10">Terminology</a></li>
+<li><a class="reference internal" href="#basic-usage" id="id11">Basic Usage</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#command-line-options" id="id12">Command Line Options</a><ul>
+<li><a class="reference internal" href="#options-to-control-error-and-warning-messages" id="id13">Options to Control Error and Warning Messages</a><ul>
+<li><a class="reference internal" href="#formatting-of-diagnostics" id="id14">Formatting of Diagnostics</a></li>
+<li><a class="reference internal" href="#individual-warning-groups" id="id15">Individual Warning Groups</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#options-to-control-clang-crash-diagnostics" id="id16">Options to Control Clang Crash Diagnostics</a></li>
+<li><a class="reference internal" href="#options-to-emit-optimization-reports" id="id17">Options to Emit Optimization Reports</a><ul>
+<li><a class="reference internal" href="#current-limitations" id="id18">Current limitations</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#other-options" id="id19">Other Options</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#language-and-target-independent-features" id="id20">Language and Target-Independent Features</a><ul>
+<li><a class="reference internal" href="#controlling-errors-and-warnings" id="id21">Controlling Errors and Warnings</a><ul>
+<li><a class="reference internal" href="#controlling-how-clang-displays-diagnostics" id="id22">Controlling How Clang Displays Diagnostics</a></li>
+<li><a class="reference internal" href="#diagnostic-mappings" id="id23">Diagnostic Mappings</a></li>
+<li><a class="reference internal" href="#diagnostic-categories" id="id24">Diagnostic Categories</a></li>
+<li><a class="reference internal" href="#controlling-diagnostics-via-command-line-flags" id="id25">Controlling Diagnostics via Command Line Flags</a></li>
+<li><a class="reference internal" href="#controlling-diagnostics-via-pragmas" id="id26">Controlling Diagnostics via Pragmas</a></li>
+<li><a class="reference internal" href="#controlling-diagnostics-in-system-headers" id="id27">Controlling Diagnostics in System Headers</a></li>
+<li><a class="reference internal" href="#enabling-all-diagnostics" id="id28">Enabling All Diagnostics</a></li>
+<li><a class="reference internal" href="#controlling-static-analyzer-diagnostics" id="id29">Controlling Static Analyzer Diagnostics</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#precompiled-headers" id="id30">Precompiled Headers</a><ul>
+<li><a class="reference internal" href="#generating-a-pch-file" id="id31">Generating a PCH File</a></li>
+<li><a class="reference internal" href="#using-a-pch-file" id="id32">Using a PCH File</a></li>
+<li><a class="reference internal" href="#relocatable-pch-files" id="id33">Relocatable PCH Files</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#controlling-code-generation" id="id34">Controlling Code Generation</a></li>
+<li><a class="reference internal" href="#profile-guided-optimization" id="id35">Profile Guided Optimization</a><ul>
+<li><a class="reference internal" href="#differences-between-sampling-and-instrumentation" id="id36">Differences Between Sampling and Instrumentation</a></li>
+<li><a class="reference internal" href="#using-sampling-profilers" id="id37">Using Sampling Profilers</a><ul>
+<li><a class="reference internal" href="#sample-profile-formats" id="id38">Sample Profile Formats</a></li>
+<li><a class="reference internal" href="#sample-profile-text-format" id="id39">Sample Profile Text Format</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#profiling-with-instrumentation" id="id40">Profiling with Instrumentation</a></li>
+<li><a class="reference internal" href="#disabling-instrumentation" id="id41">Disabling Instrumentation</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#controlling-debug-information" id="id42">Controlling Debug Information</a><ul>
+<li><a class="reference internal" href="#controlling-size-of-debug-information" id="id43">Controlling Size of Debug Information</a></li>
+<li><a class="reference internal" href="#controlling-debugger-tuning" id="id44">Controlling Debugger “Tuning”</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#comment-parsing-options" id="id45">Comment Parsing Options</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#c-language-features" id="id46">C Language Features</a><ul>
+<li><a class="reference internal" href="#extensions-supported-by-clang" id="id47">Extensions supported by clang</a></li>
+<li><a class="reference internal" href="#differences-between-various-standard-modes" id="id48">Differences between various standard modes</a></li>
+<li><a class="reference internal" href="#gcc-extensions-not-implemented-yet" id="id49">GCC extensions not implemented yet</a></li>
+<li><a class="reference internal" href="#intentionally-unsupported-gcc-extensions" id="id50">Intentionally unsupported GCC extensions</a></li>
+<li><a class="reference internal" href="#microsoft-extensions" id="id51">Microsoft extensions</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#cxx" id="id52">C++ Language Features</a><ul>
+<li><a class="reference internal" href="#controlling-implementation-limits" id="id53">Controlling implementation limits</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#objective-c-language-features" id="id54">Objective-C Language Features</a></li>
+<li><a class="reference internal" href="#objcxx" id="id55">Objective-C++ Language Features</a></li>
+<li><a class="reference internal" href="#openmp-features" id="id56">OpenMP Features</a><ul>
+<li><a class="reference internal" href="#id5" id="id57">Controlling implementation limits</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#opencl-features" id="id58">OpenCL Features</a><ul>
+<li><a class="reference internal" href="#opencl-specific-options" id="id59">OpenCL Specific Options</a></li>
+<li><a class="reference internal" href="#opencl-targets" id="id60">OpenCL Targets</a><ul>
+<li><a class="reference internal" href="#specific-targets" id="id61">Specific Targets</a></li>
+<li><a class="reference internal" href="#generic-targets" id="id62">Generic Targets</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#opencl-header" id="id63">OpenCL Header</a></li>
+<li><a class="reference internal" href="#opencl-extensions" id="id64">OpenCL Extensions</a></li>
+<li><a class="reference internal" href="#opencl-metadata" id="id65">OpenCL Metadata</a></li>
+<li><a class="reference internal" href="#opencl-specific-attributes" id="id66">OpenCL-Specific Attributes</a><ul>
+<li><a class="reference internal" href="#nosvm" id="id67">nosvm</a></li>
+<li><a class="reference internal" href="#opencl-unroll-hint" id="id68">opencl_unroll_hint</a></li>
+<li><a class="reference internal" href="#convergent" id="id69">convergent</a></li>
+<li><a class="reference internal" href="#noduplicate" id="id70">noduplicate</a></li>
+<li><a class="reference internal" href="#address-space" id="id71">address_space</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#opencl-builtins" id="id72">OpenCL builtins</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#target-specific-features-and-limitations" id="id73">Target-Specific Features and Limitations</a><ul>
+<li><a class="reference internal" href="#cpu-architectures-features-and-limitations" id="id74">CPU Architectures Features and Limitations</a><ul>
+<li><a class="reference internal" href="#x86" id="id75">X86</a></li>
+<li><a class="reference internal" href="#arm" id="id76">ARM</a></li>
+<li><a class="reference internal" href="#powerpc" id="id77">PowerPC</a></li>
+<li><a class="reference internal" href="#other-platforms" id="id78">Other platforms</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#operating-system-features-and-limitations" id="id79">Operating System Features and Limitations</a><ul>
+<li><a class="reference internal" href="#darwin-mac-os-x" id="id80">Darwin (Mac OS X)</a></li>
+<li><a class="reference internal" href="#windows" id="id81">Windows</a><ul>
+<li><a class="reference internal" href="#cygwin" id="id82">Cygwin</a></li>
+<li><a class="reference internal" href="#mingw32" id="id83">MinGW32</a></li>
+<li><a class="reference internal" href="#mingw-w64" id="id84">MinGW-w64</a></li>
+</ul>
+</li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#clang-cl" id="id85">clang-cl</a><ul>
+<li><a class="reference internal" href="#id8" id="id86">Command-Line Options</a><ul>
+<li><a class="reference internal" href="#the-fallback-option" id="id87">The /fallback Option</a></li>
+</ul>
+</li>
+</ul>
+</li>
+</ul>
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id9">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>The Clang Compiler is an open-source compiler for the C family of
+programming languages, aiming to be the best in class implementation of
+these languages. Clang builds on the LLVM optimizer and code generator,
+allowing it to provide high-quality optimization and code generation
+support for many targets. For more general information, please see the
+<a class="reference external" href="http://clang.llvm.org">Clang Web Site</a> or the <a class="reference external" href="http://llvm.org">LLVM Web
+Site</a>.</p>
+<p>This document describes important notes about using Clang as a compiler
+for an end-user, documenting the supported features, command line
+options, etc. If you are interested in using Clang to build a tool that
+processes code, please see <a class="reference internal" href="InternalsManual.html"><em>“Clang” CFE Internals Manual</em></a>. If you are interested in the
+<a class="reference external" href="http://clang-analyzer.llvm.org">Clang Static Analyzer</a>, please see its web
+page.</p>
+<p>Clang is one component in a complete toolchain for C family languages.
+A separate document describes the other pieces necessary to
+<a class="reference internal" href="Toolchain.html"><em>assemble a complete toolchain</em></a>.</p>
+<p>Clang is designed to support the C family of programming languages,
+which includes <a class="reference internal" href="#c"><em>C</em></a>, <a class="reference internal" href="#objc"><em>Objective-C</em></a>, <a class="reference internal" href="#cxx"><em>C++</em></a>, and
+<a class="reference internal" href="#objcxx"><em>Objective-C++</em></a> as well as many dialects of those. For
+language-specific information, please see the corresponding language
+specific section:</p>
+<ul class="simple">
+<li><a class="reference internal" href="#c"><em>C Language</em></a>: K&R C, ANSI C89, ISO C90, ISO C94 (C89+AMD1), ISO
+C99 (+TC1, TC2, TC3).</li>
+<li><a class="reference internal" href="#objc"><em>Objective-C Language</em></a>: ObjC 1, ObjC 2, ObjC 2.1, plus
+variants depending on base language.</li>
+<li><a class="reference internal" href="#cxx"><em>C++ Language</em></a></li>
+<li><a class="reference internal" href="#objcxx"><em>Objective C++ Language</em></a></li>
+<li><a class="reference internal" href="#opencl"><em>OpenCL C Language</em></a>: v1.0, v1.1, v1.2, v2.0.</li>
+</ul>
+<p>In addition to these base languages and their dialects, Clang supports a
+broad variety of language extensions, which are documented in the
+corresponding language section. These extensions are provided to be
+compatible with the GCC, Microsoft, and other popular compilers as well
+as to improve functionality through Clang-specific features. The Clang
+driver and language features are intentionally designed to be as
+compatible with the GNU GCC compiler as reasonably possible, easing
+migration from GCC to Clang. In most cases, code “just works”.
+Clang also provides an alternative driver, <a class="reference internal" href="#clang-cl"><em>clang-cl</em></a>, that is designed
+to be compatible with the Visual C++ compiler, cl.exe.</p>
+<p>In addition to language specific features, Clang has a variety of
+features that depend on what CPU architecture or operating system is
+being compiled for. Please see the <a class="reference internal" href="#target-features"><em>Target-Specific Features and
+Limitations</em></a> section for more details.</p>
+<p>The rest of the introduction introduces some basic <a class="reference internal" href="#terminology"><em>compiler
+terminology</em></a> that is used throughout this manual and
+contains a basic <a class="reference internal" href="#basicusage"><em>introduction to using Clang</em></a> as a
+command line compiler.</p>
+<div class="section" id="terminology">
+<span id="id1"></span><h3><a class="toc-backref" href="#id10">Terminology</a><a class="headerlink" href="#terminology" title="Permalink to this headline">¶</a></h3>
+<p>Front end, parser, backend, preprocessor, undefined behavior,
+diagnostic, optimizer</p>
+</div>
+<div class="section" id="basic-usage">
+<span id="basicusage"></span><h3><a class="toc-backref" href="#id11">Basic Usage</a><a class="headerlink" href="#basic-usage" title="Permalink to this headline">¶</a></h3>
+<p>Intro to how to use a C compiler for newbies.</p>
+<p>compile + link compile then link debug info enabling optimizations
+picking a language to use, defaults to C11 by default. Autosenses based
+on extension. using a makefile</p>
+</div>
+</div>
+<div class="section" id="command-line-options">
+<h2><a class="toc-backref" href="#id12">Command Line Options</a><a class="headerlink" href="#command-line-options" title="Permalink to this headline">¶</a></h2>
+<p>This section is generally an index into other sections. It does not go
+into depth on the ones that are covered by other sections. However, the
+first part introduces the language selection and other high level
+options like <a class="reference internal" href="CommandGuide/clang.html#cmdoption-c"><em class="xref std std-option">-c</em></a>, <a class="reference internal" href="#cmdoption-g"><em class="xref std std-option">-g</em></a>, etc.</p>
+<div class="section" id="options-to-control-error-and-warning-messages">
+<h3><a class="toc-backref" href="#id13">Options to Control Error and Warning Messages</a><a class="headerlink" href="#options-to-control-error-and-warning-messages" title="Permalink to this headline">¶</a></h3>
+<dl class="option">
+<dt id="cmdoption-Werror">
+<tt class="descname">-Werror</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-Werror" title="Permalink to this definition">¶</a></dt>
+<dd><p>Turn warnings into errors.</p>
+</dd></dl>
+
+<p><tt class="docutils literal"><span class="pre">-Werror=foo</span></tt></p>
+<blockquote>
+<div>Turn warning “foo” into an error.</div></blockquote>
+<dl class="option">
+<dt id="cmdoption-Wno-error">
+<tt class="descname">-Wno-error</tt><tt class="descclassname">=foo</tt><a class="headerlink" href="#cmdoption-Wno-error" title="Permalink to this definition">¶</a></dt>
+<dd><p>Turn warning “foo” into an warning even if <a class="reference internal" href="#cmdoption-Werror"><em class="xref std std-option">-Werror</em></a> is specified.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-Wfoo">
+<tt class="descname">-Wfoo</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-Wfoo" title="Permalink to this definition">¶</a></dt>
+<dd><p>Enable warning “foo”.
+See the <a class="reference internal" href="DiagnosticsReference.html"><em>diagnostics reference</em></a> for a complete
+list of the warning flags that can be specified in this way.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-Wno-foo">
+<tt class="descname">-Wno-foo</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-Wno-foo" title="Permalink to this definition">¶</a></dt>
+<dd><p>Disable warning “foo”.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-w">
+<tt class="descname">-w</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-w" title="Permalink to this definition">¶</a></dt>
+<dd><p>Disable all diagnostics.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-Weverything">
+<tt class="descname">-Weverything</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-Weverything" title="Permalink to this definition">¶</a></dt>
+<dd><p><a class="reference internal" href="#diagnostics-enable-everything"><em>Enable all diagnostics.</em></a></p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-pedantic">
+<tt class="descname">-pedantic</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-pedantic" title="Permalink to this definition">¶</a></dt>
+<dd><p>Warn on language extensions.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-pedantic-errors">
+<tt class="descname">-pedantic-errors</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-pedantic-errors" title="Permalink to this definition">¶</a></dt>
+<dd><p>Error on language extensions.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-Wsystem-headers">
+<tt class="descname">-Wsystem-headers</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-Wsystem-headers" title="Permalink to this definition">¶</a></dt>
+<dd><p>Enable warnings from system headers.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-ferror-limit">
+<tt class="descname">-ferror-limit</tt><tt class="descclassname">=123</tt><a class="headerlink" href="#cmdoption-ferror-limit" title="Permalink to this definition">¶</a></dt>
+<dd><p>Stop emitting diagnostics after 123 errors have been produced. The default is
+20, and the error limit can be disabled with <cite>-ferror-limit=0</cite>.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-ftemplate-backtrace-limit">
+<tt class="descname">-ftemplate-backtrace-limit</tt><tt class="descclassname">=123</tt><a class="headerlink" href="#cmdoption-ftemplate-backtrace-limit" title="Permalink to this definition">¶</a></dt>
+<dd><p>Only emit up to 123 template instantiation notes within the template
+instantiation backtrace for a single warning or error. The default is 10, and
+the limit can be disabled with <cite>-ftemplate-backtrace-limit=0</cite>.</p>
+</dd></dl>
+
+<div class="section" id="formatting-of-diagnostics">
+<span id="cl-diag-formatting"></span><h4><a class="toc-backref" href="#id14">Formatting of Diagnostics</a><a class="headerlink" href="#formatting-of-diagnostics" title="Permalink to this headline">¶</a></h4>
+<p>Clang aims to produce beautiful diagnostics by default, particularly for
+new users that first come to Clang. However, different people have
+different preferences, and sometimes Clang is driven not by a human,
+but by a program that wants consistent and easily parsable output. For
+these cases, Clang provides a wide range of options to control the exact
+output format of the diagnostics that it generates.</p>
+<dl class="docutils" id="opt-fshow-column">
+<dt><strong>-f[no-]show-column</strong></dt>
+<dd><p class="first">Print column number in diagnostic.</p>
+<p>This option, which defaults to on, controls whether or not Clang
+prints the column number of a diagnostic. For example, when this is
+enabled, Clang will print something like:</p>
+<div class="highlight-python"><div class="highlight"><pre>test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
+#endif bad
+ ^
+ //
+</pre></div>
+</div>
+<p>When this is disabled, Clang will print “test.c:28: warning...” with
+no column number.</p>
+<p class="last">The printed column numbers count bytes from the beginning of the
+line; take care if your source contains multibyte characters.</p>
+</dd>
+</dl>
+<dl class="docutils" id="opt-fshow-source-location">
+<dt><strong>-f[no-]show-source-location</strong></dt>
+<dd><p class="first">Print source file/line/column information in diagnostic.</p>
+<p>This option, which defaults to on, controls whether or not Clang
+prints the filename, line number and column number of a diagnostic.
+For example, when this is enabled, Clang will print something like:</p>
+<div class="highlight-python"><div class="highlight"><pre>test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
+#endif bad
+ ^
+ //
+</pre></div>
+</div>
+<p class="last">When this is disabled, Clang will not print the “test.c:28:8: ”
+part.</p>
+</dd>
+</dl>
+<dl class="docutils" id="opt-fcaret-diagnostics">
+<dt><strong>-f[no-]caret-diagnostics</strong></dt>
+<dd><p class="first">Print source line and ranges from source code in diagnostic.
+This option, which defaults to on, controls whether or not Clang
+prints the source line, source ranges, and caret when emitting a
+diagnostic. For example, when this is enabled, Clang will print
+something like:</p>
+<div class="last highlight-python"><div class="highlight"><pre>test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
+#endif bad
+ ^
+ //
+</pre></div>
+</div>
+</dd>
+<dt><strong>-f[no-]color-diagnostics</strong></dt>
+<dd><p class="first">This option, which defaults to on when a color-capable terminal is
+detected, controls whether or not Clang prints diagnostics in color.</p>
+<p>When this option is enabled, Clang will use colors to highlight
+specific parts of the diagnostic, e.g.,</p>
+<pre>
+ <b><span style="color:black">test.c:28:8: <span style="color:magenta">warning</span>: extra tokens at end of #endif directive [-Wextra-tokens]</span></b>
+ #endif bad
+ <span style="color:green">^</span>
+ <span style="color:green">//</span>
+</pre><p>When this is disabled, Clang will just print:</p>
+<div class="last highlight-python"><div class="highlight"><pre>test.c:2:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
+#endif bad
+ ^
+ //
+</pre></div>
+</div>
+</dd>
+<dt><strong>-fansi-escape-codes</strong></dt>
+<dd>Controls whether ANSI escape codes are used instead of the Windows Console
+API to output colored diagnostics. This option is only used on Windows and
+defaults to off.</dd>
+</dl>
+<dl class="option">
+<dt id="cmdoption-fdiagnostics-format">
+<tt class="descname">-fdiagnostics-format</tt><tt class="descclassname">=clang/msvc/vi</tt><a class="headerlink" href="#cmdoption-fdiagnostics-format" title="Permalink to this definition">¶</a></dt>
+<dd><p>Changes diagnostic output format to better match IDEs and command line tools.</p>
+<p>This option controls the output format of the filename, line number,
+and column printed in diagnostic messages. The options, and their
+affect on formatting a simple conversion diagnostic, follow:</p>
+<dl class="docutils">
+<dt><strong>clang</strong> (default)</dt>
+<dd><div class="first last highlight-python"><div class="highlight"><pre>t.c:3:11: warning: conversion specifies type 'char *' but the argument has type 'int'
+</pre></div>
+</div>
+</dd>
+<dt><strong>msvc</strong></dt>
+<dd><div class="first last highlight-python"><div class="highlight"><pre>t.c(3,11) : warning: conversion specifies type 'char *' but the argument has type 'int'
+</pre></div>
+</div>
+</dd>
+<dt><strong>vi</strong></dt>
+<dd><div class="first last highlight-python"><div class="highlight"><pre>t.c +3:11: warning: conversion specifies type 'char *' but the argument has type 'int'
+</pre></div>
+</div>
+</dd>
+</dl>
+</dd></dl>
+
+<dl class="docutils" id="opt-fdiagnostics-show-option">
+<dt><strong>-f[no-]diagnostics-show-option</strong></dt>
+<dd><p class="first">Enable <tt class="docutils literal"><span class="pre">[-Woption]</span></tt> information in diagnostic line.</p>
+<p>This option, which defaults to on, controls whether or not Clang
+prints the associated <a class="reference internal" href="#cl-diag-warning-groups"><em>warning group</em></a>
+option name when outputting a warning diagnostic. For example, in
+this output:</p>
+<div class="highlight-python"><div class="highlight"><pre>test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
+#endif bad
+ ^
+ //
+</pre></div>
+</div>
+<p class="last">Passing <strong>-fno-diagnostics-show-option</strong> will prevent Clang from
+printing the [<a class="reference internal" href="#opt-wextra-tokens"><em>-Wextra-tokens</em></a>] information in
+the diagnostic. This information tells you the flag needed to enable
+or disable the diagnostic, either from the command line or through
+<a class="reference internal" href="#pragma-gcc-diagnostic"><em>#pragma GCC diagnostic</em></a>.</p>
+</dd>
+</dl>
+<span class="target" id="opt-fdiagnostics-show-category"></span><dl class="option">
+<dt id="cmdoption-fdiagnostics-show-category">
+<tt class="descname">-fdiagnostics-show-category</tt><tt class="descclassname">=none/id/name</tt><a class="headerlink" href="#cmdoption-fdiagnostics-show-category" title="Permalink to this definition">¶</a></dt>
+<dd><p>Enable printing category information in diagnostic line.</p>
+<p>This option, which defaults to “none”, controls whether or not Clang
+prints the category associated with a diagnostic when emitting it.
+Each diagnostic may or many not have an associated category, if it
+has one, it is listed in the diagnostic categorization field of the
+diagnostic line (in the []’s).</p>
+<p>For example, a format string warning will produce these three
+renditions based on the setting of this option:</p>
+<div class="highlight-python"><div class="highlight"><pre>t.c:3:11: warning: conversion specifies type 'char *' but the argument has type 'int' [-Wformat]
+t.c:3:11: warning: conversion specifies type 'char *' but the argument has type 'int' [-Wformat,1]
+t.c:3:11: warning: conversion specifies type 'char *' but the argument has type 'int' [-Wformat,Format String]
+</pre></div>
+</div>
+<p>This category can be used by clients that want to group diagnostics
+by category, so it should be a high level category. We want dozens
+of these, not hundreds or thousands of them.</p>
+</dd></dl>
+
+<dl class="docutils" id="opt-fdiagnostics-show-hotness">
+<dt><strong>-f[no-]diagnostics-show-hotness</strong></dt>
+<dd><p class="first">Enable profile hotness information in diagnostic line.</p>
+<p>This option, which defaults to off, controls whether Clang prints the
+profile hotness associated with a diagnostics in the presence of
+profile-guided optimization information. This is currently supported with
+optimization remarks (see <a class="reference internal" href="#rpass"><em>Options to Emit Optimization Reports</em></a>). The hotness information allows users to focus on the hot
+optimization remarks that are likely to be more relevant for run-time
+performance.</p>
+<p>For example, in this output, the block containing the callsite of <cite>foo</cite> was
+executed 3000 times according to the profile data:</p>
+<div class="last highlight-python"><div class="highlight"><pre>s.c:7:10: remark: foo inlined into bar (hotness: 3000) [-Rpass-analysis=inline]
+ sum += foo(x, x - 2);
+ ^
+</pre></div>
+</div>
+</dd>
+</dl>
+<dl class="docutils" id="opt-fdiagnostics-fixit-info">
+<dt><strong>-f[no-]diagnostics-fixit-info</strong></dt>
+<dd><p class="first">Enable “FixIt” information in the diagnostics output.</p>
+<p>This option, which defaults to on, controls whether or not Clang
+prints the information on how to fix a specific diagnostic
+underneath it when it knows. For example, in this output:</p>
+<div class="highlight-python"><div class="highlight"><pre>test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
+#endif bad
+ ^
+ //
+</pre></div>
+</div>
+<p class="last">Passing <strong>-fno-diagnostics-fixit-info</strong> will prevent Clang from
+printing the “//” line at the end of the message. This information
+is useful for users who may not understand what is wrong, but can be
+confusing for machine parsing.</p>
+</dd>
+</dl>
+<dl class="docutils" id="opt-fdiagnostics-print-source-range-info">
+<dt><strong>-fdiagnostics-print-source-range-info</strong></dt>
+<dd><p class="first">Print machine parsable information about source ranges.
+This option makes Clang print information about source ranges in a machine
+parsable format after the file/line/column number information. The
+information is a simple sequence of brace enclosed ranges, where each range
+lists the start and end line/column locations. For example, in this output:</p>
+<div class="highlight-python"><div class="highlight"><pre>exprs.c:47:15:{47:8-47:14}{47:17-47:24}: error: invalid operands to binary expression ('int *' and '_Complex float')
+ P = (P-42) + Gamma*4;
+ ~~~~~~ ^ ~~~~~~~
+</pre></div>
+</div>
+<p>The {}’s are generated by -fdiagnostics-print-source-range-info.</p>
+<p class="last">The printed column numbers count bytes from the beginning of the
+line; take care if your source contains multibyte characters.</p>
+</dd>
+</dl>
+<dl class="option">
+<dt id="cmdoption-fdiagnostics-parseable-fixits">
+<tt class="descname">-fdiagnostics-parseable-fixits</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-fdiagnostics-parseable-fixits" title="Permalink to this definition">¶</a></dt>
+<dd><p>Print Fix-Its in a machine parseable form.</p>
+<p>This option makes Clang print available Fix-Its in a machine
+parseable format at the end of diagnostics. The following example
+illustrates the format:</p>
+<div class="highlight-python"><div class="highlight"><pre>fix-it:"t.cpp":{7:25-7:29}:"Gamma"
+</pre></div>
+</div>
+<p>The range printed is a half-open range, so in this example the
+characters at column 25 up to but not including column 29 on line 7
+in t.cpp should be replaced with the string “Gamma”. Either the
+range or the replacement string may be empty (representing strict
+insertions and strict erasures, respectively). Both the file name
+and the insertion string escape backslash (as “\\”), tabs (as
+“\t”), newlines (as “\n”), double quotes(as “\””) and
+non-printable characters (as octal “\xxx”).</p>
+<p>The printed column numbers count bytes from the beginning of the
+line; take care if your source contains multibyte characters.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fno-elide-type">
+<tt class="descname">-fno-elide-type</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-fno-elide-type" title="Permalink to this definition">¶</a></dt>
+<dd><p>Turns off elision in template type printing.</p>
+<p>The default for template type printing is to elide as many template
+arguments as possible, removing those which are the same in both
+template types, leaving only the differences. Adding this flag will
+print all the template arguments. If supported by the terminal,
+highlighting will still appear on differing arguments.</p>
+<p>Default:</p>
+<div class="highlight-python"><div class="highlight"><pre>t.cc:4:5: note: candidate function not viable: no known conversion from 'vector<map<[...], map<float, [...]>>>' to 'vector<map<[...], map<double, [...]>>>' for 1st argument;
+</pre></div>
+</div>
+<p>-fno-elide-type:</p>
+<div class="highlight-python"><div class="highlight"><pre>t.cc:4:5: note: candidate function not viable: no known conversion from 'vector<map<int, map<float, int>>>' to 'vector<map<int, map<double, int>>>' for 1st argument;
+</pre></div>
+</div>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fdiagnostics-show-template-tree">
+<tt class="descname">-fdiagnostics-show-template-tree</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-fdiagnostics-show-template-tree" title="Permalink to this definition">¶</a></dt>
+<dd><p>Template type diffing prints a text tree.</p>
+<p>For diffing large templated types, this option will cause Clang to
+display the templates as an indented text tree, one argument per
+line, with differences marked inline. This is compatible with
+-fno-elide-type.</p>
+<p>Default:</p>
+<div class="highlight-python"><div class="highlight"><pre>t.cc:4:5: note: candidate function not viable: no known conversion from 'vector<map<[...], map<float, [...]>>>' to 'vector<map<[...], map<double, [...]>>>' for 1st argument;
+</pre></div>
+</div>
+<p>With <a class="reference internal" href="#cmdoption-fdiagnostics-show-template-tree"><em class="xref std std-option">-fdiagnostics-show-template-tree</em></a>:</p>
+<div class="highlight-python"><div class="highlight"><pre>t.cc:4:5: note: candidate function not viable: no known conversion for 1st argument;
+ vector<
+ map<
+ [...],
+ map<
+ [float != double],
+ [...]>>>
+</pre></div>
+</div>
+</dd></dl>
+
+</div>
+<div class="section" id="individual-warning-groups">
+<span id="cl-diag-warning-groups"></span><h4><a class="toc-backref" href="#id15">Individual Warning Groups</a><a class="headerlink" href="#individual-warning-groups" title="Permalink to this headline">¶</a></h4>
+<p>TODO: Generate this from tblgen. Define one anchor per warning group.</p>
+<span class="target" id="opt-wextra-tokens"></span><dl class="option">
+<dt id="cmdoption-Wextra-tokens">
+<tt class="descname">-Wextra-tokens</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-Wextra-tokens" title="Permalink to this definition">¶</a></dt>
+<dd><p>Warn about excess tokens at the end of a preprocessor directive.</p>
+<p>This option, which defaults to on, enables warnings about extra
+tokens at the end of preprocessor directives. For example:</p>
+<div class="highlight-python"><div class="highlight"><pre>test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
+#endif bad
+ ^
+</pre></div>
+</div>
+<p>These extra tokens are not strictly conforming, and are usually best
+handled by commenting them out.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-Wambiguous-member-template">
+<tt class="descname">-Wambiguous-member-template</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-Wambiguous-member-template" title="Permalink to this definition">¶</a></dt>
+<dd><p>Warn about unqualified uses of a member template whose name resolves to
+another template at the location of the use.</p>
+<p>This option, which defaults to on, enables a warning in the
+following code:</p>
+<div class="highlight-python"><div class="highlight"><pre>template<typename T> struct set{};
+template<typename T> struct trait { typedef const T& type; };
+struct Value {
+ template<typename T> void set(typename trait<T>::type value) {}
+};
+void foo() {
+ Value v;
+ v.set<double>(3.2);
+}
+</pre></div>
+</div>
+<p>C++ [basic.lookup.classref] requires this to be an error, but,
+because it’s hard to work around, Clang downgrades it to a warning
+as an extension.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-Wbind-to-temporary-copy">
+<tt class="descname">-Wbind-to-temporary-copy</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-Wbind-to-temporary-copy" title="Permalink to this definition">¶</a></dt>
+<dd><p>Warn about an unusable copy constructor when binding a reference to a
+temporary.</p>
+<p>This option enables warnings about binding a
+reference to a temporary when the temporary doesn’t have a usable
+copy constructor. For example:</p>
+<div class="highlight-python"><div class="highlight"><pre>struct NonCopyable {
+ NonCopyable();
+private:
+ NonCopyable(const NonCopyable&);
+};
+void foo(const NonCopyable&);
+void bar() {
+ foo(NonCopyable()); // Disallowed in C++98; allowed in C++11.
+}
+</pre></div>
+</div>
+<div class="highlight-python"><div class="highlight"><pre>struct NonCopyable2 {
+ NonCopyable2();
+ NonCopyable2(NonCopyable2&);
+};
+void foo(const NonCopyable2&);
+void bar() {
+ foo(NonCopyable2()); // Disallowed in C++98; allowed in C++11.
+}
+</pre></div>
+</div>
+<p>Note that if <tt class="docutils literal"><span class="pre">NonCopyable2::NonCopyable2()</span></tt> has a default argument
+whose instantiation produces a compile error, that error will still
+be a hard error in C++98 mode even if this warning is turned off.</p>
+</dd></dl>
+
+</div>
+</div>
+<div class="section" id="options-to-control-clang-crash-diagnostics">
+<h3><a class="toc-backref" href="#id16">Options to Control Clang Crash Diagnostics</a><a class="headerlink" href="#options-to-control-clang-crash-diagnostics" title="Permalink to this headline">¶</a></h3>
+<p>As unbelievable as it may sound, Clang does crash from time to time.
+Generally, this only occurs to those living on the <a class="reference external" href="http://llvm.org/releases/download.html#svn">bleeding
+edge</a>. Clang goes to great
+lengths to assist you in filing a bug report. Specifically, Clang
+generates preprocessed source file(s) and associated run script(s) upon
+a crash. These files should be attached to a bug report to ease
+reproducibility of the failure. Below are the command line options to
+control the crash diagnostics.</p>
+<dl class="option">
+<dt id="cmdoption-fno-crash-diagnostics">
+<tt class="descname">-fno-crash-diagnostics</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-fno-crash-diagnostics" title="Permalink to this definition">¶</a></dt>
+<dd><p>Disable auto-generation of preprocessed source files during a clang crash.</p>
+</dd></dl>
+
+<p>The -fno-crash-diagnostics flag can be helpful for speeding the process
+of generating a delta reduced test case.</p>
+</div>
+<div class="section" id="options-to-emit-optimization-reports">
+<span id="rpass"></span><h3><a class="toc-backref" href="#id17">Options to Emit Optimization Reports</a><a class="headerlink" href="#options-to-emit-optimization-reports" title="Permalink to this headline">¶</a></h3>
+<p>Optimization reports trace, at a high-level, all the major decisions
+done by compiler transformations. For instance, when the inliner
+decides to inline function <tt class="docutils literal"><span class="pre">foo()</span></tt> into <tt class="docutils literal"><span class="pre">bar()</span></tt>, or the loop unroller
+decides to unroll a loop N times, or the vectorizer decides to
+vectorize a loop body.</p>
+<p>Clang offers a family of flags which the optimizers can use to emit
+a diagnostic in three cases:</p>
+<ol class="arabic simple">
+<li>When the pass makes a transformation (<cite>-Rpass</cite>).</li>
+<li>When the pass fails to make a transformation (<cite>-Rpass-missed</cite>).</li>
+<li>When the pass determines whether or not to make a transformation
+(<cite>-Rpass-analysis</cite>).</li>
+</ol>
+<p>NOTE: Although the discussion below focuses on <cite>-Rpass</cite>, the exact
+same options apply to <cite>-Rpass-missed</cite> and <cite>-Rpass-analysis</cite>.</p>
+<p>Since there are dozens of passes inside the compiler, each of these flags
+take a regular expression that identifies the name of the pass which should
+emit the associated diagnostic. For example, to get a report from the inliner,
+compile the code with:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> clang -O2 -Rpass<span class="o">=</span>inline code.cc -o code
+<span class="go">code.cc:4:25: remark: foo inlined into bar [-Rpass=inline]</span>
+<span class="go">int bar(int j) { return foo(j, j - 2); }</span>
+<span class="go"> ^</span>
+</pre></div>
+</div>
+<p>Note that remarks from the inliner are identified with <cite>[-Rpass=inline]</cite>.
+To request a report from every optimization pass, you should use
+<cite>-Rpass=.*</cite> (in fact, you can use any valid POSIX regular
+expression). However, do not expect a report from every transformation
+made by the compiler. Optimization remarks do not really make sense
+outside of the major transformations (e.g., inlining, vectorization,
+loop optimizations) and not every optimization pass supports this
+feature.</p>
+<p>Note that when using profile-guided optimization information, profile hotness
+information can be included in the remarks (see
+<a class="reference internal" href="#opt-fdiagnostics-show-hotness"><em>-fdiagnostics-show-hotness</em></a>).</p>
+<div class="section" id="current-limitations">
+<h4><a class="toc-backref" href="#id18">Current limitations</a><a class="headerlink" href="#current-limitations" title="Permalink to this headline">¶</a></h4>
+<ol class="arabic simple">
+<li>Optimization remarks that refer to function names will display the
+mangled name of the function. Since these remarks are emitted by the
+back end of the compiler, it does not know anything about the input
+language, nor its mangling rules.</li>
+<li>Some source locations are not displayed correctly. The front end has
+a more detailed source location tracking than the locations included
+in the debug info (e.g., the front end can locate code inside macro
+expansions). However, the locations used by <cite>-Rpass</cite> are
+translated from debug annotations. That translation can be lossy,
+which results in some remarks having no location information.</li>
+</ol>
+</div>
+</div>
+<div class="section" id="other-options">
+<h3><a class="toc-backref" href="#id19">Other Options</a><a class="headerlink" href="#other-options" title="Permalink to this headline">¶</a></h3>
+<p>Clang options that that don’t fit neatly into other categories.</p>
+<dl class="option">
+<dt id="cmdoption-MV">
+<tt class="descname">-MV</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-MV" title="Permalink to this definition">¶</a></dt>
+<dd><p>When emitting a dependency file, use formatting conventions appropriate
+for NMake or Jom. Ignored unless another option causes Clang to emit a
+dependency file.</p>
+</dd></dl>
+
+<p>When Clang emits a dependency file (e.g., you supplied the -M option)
+most filenames can be written to the file without any special formatting.
+Different Make tools will treat different sets of characters as “special”
+and use different conventions for telling the Make tool that the character
+is actually part of the filename. Normally Clang uses backslash to “escape”
+a special character, which is the convention used by GNU Make. The -MV
+option tells Clang to put double-quotes around the entire filename, which
+is the convention used by NMake and Jom.</p>
+</div>
+</div>
+<div class="section" id="language-and-target-independent-features">
+<h2><a class="toc-backref" href="#id20">Language and Target-Independent Features</a><a class="headerlink" href="#language-and-target-independent-features" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="controlling-errors-and-warnings">
+<h3><a class="toc-backref" href="#id21">Controlling Errors and Warnings</a><a class="headerlink" href="#controlling-errors-and-warnings" title="Permalink to this headline">¶</a></h3>
+<p>Clang provides a number of ways to control which code constructs cause
+it to emit errors and warning messages, and how they are displayed to
+the console.</p>
+<div class="section" id="controlling-how-clang-displays-diagnostics">
+<h4><a class="toc-backref" href="#id22">Controlling How Clang Displays Diagnostics</a><a class="headerlink" href="#controlling-how-clang-displays-diagnostics" title="Permalink to this headline">¶</a></h4>
+<p>When Clang emits a diagnostic, it includes rich information in the
+output, and gives you fine-grain control over which information is
+printed. Clang has the ability to print this information, and these are
+the options that control it:</p>
+<ol class="arabic simple">
+<li>A file/line/column indicator that shows exactly where the diagnostic
+occurs in your code [<a class="reference internal" href="#opt-fshow-column"><em>-fshow-column</em></a>,
+<a class="reference internal" href="#opt-fshow-source-location"><em>-fshow-source-location</em></a>].</li>
+<li>A categorization of the diagnostic as a note, warning, error, or
+fatal error.</li>
+<li>A text string that describes what the problem is.</li>
+<li>An option that indicates how to control the diagnostic (for
+diagnostics that support it)
+[<a class="reference internal" href="#opt-fdiagnostics-show-option"><em>-fdiagnostics-show-option</em></a>].</li>
+<li>A <a class="reference internal" href="#diagnostics-categories"><em>high-level category</em></a> for the diagnostic
+for clients that want to group diagnostics by class (for diagnostics
+that support it)
+[<a class="reference internal" href="#opt-fdiagnostics-show-category"><em>-fdiagnostics-show-category</em></a>].</li>
+<li>The line of source code that the issue occurs on, along with a caret
+and ranges that indicate the important locations
+[<a class="reference internal" href="#opt-fcaret-diagnostics"><em>-fcaret-diagnostics</em></a>].</li>
+<li>“FixIt” information, which is a concise explanation of how to fix the
+problem (when Clang is certain it knows)
+[<a class="reference internal" href="#opt-fdiagnostics-fixit-info"><em>-fdiagnostics-fixit-info</em></a>].</li>
+<li>A machine-parsable representation of the ranges involved (off by
+default)
+[<a class="reference internal" href="#opt-fdiagnostics-print-source-range-info"><em>-fdiagnostics-print-source-range-info</em></a>].</li>
+</ol>
+<p>For more information please see <a class="reference internal" href="#cl-diag-formatting"><em>Formatting of
+Diagnostics</em></a>.</p>
+</div>
+<div class="section" id="diagnostic-mappings">
+<h4><a class="toc-backref" href="#id23">Diagnostic Mappings</a><a class="headerlink" href="#diagnostic-mappings" title="Permalink to this headline">¶</a></h4>
+<p>All diagnostics are mapped into one of these 6 classes:</p>
+<ul class="simple">
+<li>Ignored</li>
+<li>Note</li>
+<li>Remark</li>
+<li>Warning</li>
+<li>Error</li>
+<li>Fatal</li>
+</ul>
+</div>
+<div class="section" id="diagnostic-categories">
+<span id="diagnostics-categories"></span><h4><a class="toc-backref" href="#id24">Diagnostic Categories</a><a class="headerlink" href="#diagnostic-categories" title="Permalink to this headline">¶</a></h4>
+<p>Though not shown by default, diagnostics may each be associated with a
+high-level category. This category is intended to make it possible to
+triage builds that produce a large number of errors or warnings in a
+grouped way.</p>
+<p>Categories are not shown by default, but they can be turned on with the
+<a class="reference internal" href="#opt-fdiagnostics-show-category"><em>-fdiagnostics-show-category</em></a> option.
+When set to “<tt class="docutils literal"><span class="pre">name</span></tt>”, the category is printed textually in the
+diagnostic output. When it is set to “<tt class="docutils literal"><span class="pre">id</span></tt>”, a category number is
+printed. The mapping of category names to category id’s can be obtained
+by running ‘<tt class="docutils literal"><span class="pre">clang</span> <span class="pre">--print-diagnostic-categories</span></tt>‘.</p>
+</div>
+<div class="section" id="controlling-diagnostics-via-command-line-flags">
+<h4><a class="toc-backref" href="#id25">Controlling Diagnostics via Command Line Flags</a><a class="headerlink" href="#controlling-diagnostics-via-command-line-flags" title="Permalink to this headline">¶</a></h4>
+<p>TODO: -W flags, -pedantic, etc</p>
+</div>
+<div class="section" id="controlling-diagnostics-via-pragmas">
+<span id="pragma-gcc-diagnostic"></span><h4><a class="toc-backref" href="#id26">Controlling Diagnostics via Pragmas</a><a class="headerlink" href="#controlling-diagnostics-via-pragmas" title="Permalink to this headline">¶</a></h4>
+<p>Clang can also control what diagnostics are enabled through the use of
+pragmas in the source code. This is useful for turning off specific
+warnings in a section of source code. Clang supports GCC’s pragma for
+compatibility with existing source code, as well as several extensions.</p>
+<p>The pragma may control any warning that can be used from the command
+line. Warnings may be set to ignored, warning, error, or fatal. The
+following example code will tell Clang or GCC to ignore the -Wall
+warnings:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="cp">#pragma GCC diagnostic ignored "-Wall"</span>
+</pre></div>
+</div>
+<p>In addition to all of the functionality provided by GCC’s pragma, Clang
+also allows you to push and pop the current warning state. This is
+particularly useful when writing a header file that will be compiled by
+other people, because you don’t know what warning flags they build with.</p>
+<p>In the below example <a class="reference internal" href="#cmdoption-Wextra-tokens"><em class="xref std std-option">-Wextra-tokens</em></a> is ignored for only a single line
+of code, after which the diagnostics return to whatever state had previously
+existed.</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="cp">#if foo</span>
+<span class="cp">#endif foo </span><span class="c1">// warning: extra tokens at end of #endif directive</span>
+
+<span class="cp">#pragma clang diagnostic ignored "-Wextra-tokens"</span>
+
+<span class="cp">#if foo</span>
+<span class="cp">#endif foo </span><span class="c1">// no warning</span>
+
+<span class="cp">#pragma clang diagnostic pop</span>
+</pre></div>
+</div>
+<p>The push and pop pragmas will save and restore the full diagnostic state
+of the compiler, regardless of how it was set. That means that it is
+possible to use push and pop around GCC compatible diagnostics and Clang
+will push and pop them appropriately, while GCC will ignore the pushes
+and pops as unknown pragmas. It should be noted that while Clang
+supports the GCC pragma, Clang and GCC do not support the exact same set
+of warnings, so even when using GCC compatible #pragmas there is no
+guarantee that they will have identical behaviour on both compilers.</p>
+<p>In addition to controlling warnings and errors generated by the compiler, it is
+possible to generate custom warning and error messages through the following
+pragmas:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="c1">// The following will produce warning messages</span>
+<span class="cp">#pragma message "some diagnostic message"</span>
+<span class="cp">#pragma GCC warning "TODO: replace deprecated feature"</span>
+
+<span class="c1">// The following will produce an error message</span>
+<span class="cp">#pragma GCC error "Not supported"</span>
+</pre></div>
+</div>
+<p>These pragmas operate similarly to the <tt class="docutils literal"><span class="pre">#warning</span></tt> and <tt class="docutils literal"><span class="pre">#error</span></tt> preprocessor
+directives, except that they may also be embedded into preprocessor macros via
+the C99 <tt class="docutils literal"><span class="pre">_Pragma</span></tt> operator, for example:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="cp">#define STR(X) #X</span>
+<span class="cp">#define DEFER(M,...) M(__VA_ARGS__)</span>
+<span class="cp">#define CUSTOM_ERROR(X) _Pragma(STR(GCC error(X " at line " DEFER(STR,__LINE__))))</span>
+
+<span class="n">CUSTOM_ERROR</span><span class="p">(</span><span class="s">"Feature not available"</span><span class="p">);</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="controlling-diagnostics-in-system-headers">
+<h4><a class="toc-backref" href="#id27">Controlling Diagnostics in System Headers</a><a class="headerlink" href="#controlling-diagnostics-in-system-headers" title="Permalink to this headline">¶</a></h4>
+<p>Warnings are suppressed when they occur in system headers. By default,
+an included file is treated as a system header if it is found in an
+include path specified by <tt class="docutils literal"><span class="pre">-isystem</span></tt>, but this can be overridden in
+several ways.</p>
+<p>The <tt class="docutils literal"><span class="pre">system_header</span></tt> pragma can be used to mark the current file as
+being a system header. No warnings will be produced from the location of
+the pragma onwards within the same file.</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="cp">#if foo</span>
+<span class="cp">#endif foo </span><span class="c1">// warning: extra tokens at end of #endif directive</span>
+
+<span class="cp">#pragma clang system_header</span>
+
+<span class="cp">#if foo</span>
+<span class="cp">#endif foo </span><span class="c1">// no warning</span>
+</pre></div>
+</div>
+<p>The <cite>–system-header-prefix=</cite> and <cite>–no-system-header-prefix=</cite>
+command-line arguments can be used to override whether subsets of an include
+path are treated as system headers. When the name in a <tt class="docutils literal"><span class="pre">#include</span></tt> directive
+is found within a header search path and starts with a system prefix, the
+header is treated as a system header. The last prefix on the
+command-line which matches the specified header name takes precedence.
+For instance:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> clang -Ifoo -isystem bar --system-header-prefix<span class="o">=</span>x/ <span class="se">\</span>
+<span class="go"> --no-system-header-prefix=x/y/</span>
+</pre></div>
+</div>
+<p>Here, <tt class="docutils literal"><span class="pre">#include</span> <span class="pre">"x/a.h"</span></tt> is treated as including a system header, even
+if the header is found in <tt class="docutils literal"><span class="pre">foo</span></tt>, and <tt class="docutils literal"><span class="pre">#include</span> <span class="pre">"x/y/b.h"</span></tt> is treated
+as not including a system header, even if the header is found in
+<tt class="docutils literal"><span class="pre">bar</span></tt>.</p>
+<p>A <tt class="docutils literal"><span class="pre">#include</span></tt> directive which finds a file relative to the current
+directory is treated as including a system header if the including file
+is treated as a system header.</p>
+</div>
+<div class="section" id="enabling-all-diagnostics">
+<span id="diagnostics-enable-everything"></span><h4><a class="toc-backref" href="#id28">Enabling All Diagnostics</a><a class="headerlink" href="#enabling-all-diagnostics" title="Permalink to this headline">¶</a></h4>
+<p>In addition to the traditional <tt class="docutils literal"><span class="pre">-W</span></tt> flags, one can enable <strong>all</strong>
+diagnostics by passing <a class="reference internal" href="#cmdoption-Weverything"><em class="xref std std-option">-Weverything</em></a>. This works as expected
+with
+<a class="reference internal" href="#cmdoption-Werror"><em class="xref std std-option">-Werror</em></a>, and also includes the warnings from <a class="reference internal" href="#cmdoption-pedantic"><em class="xref std std-option">-pedantic</em></a>.</p>
+<p>Note that when combined with <a class="reference internal" href="#cmdoption-w"><em class="xref std std-option">-w</em></a> (which disables all warnings), that
+flag wins.</p>
+</div>
+<div class="section" id="controlling-static-analyzer-diagnostics">
+<h4><a class="toc-backref" href="#id29">Controlling Static Analyzer Diagnostics</a><a class="headerlink" href="#controlling-static-analyzer-diagnostics" title="Permalink to this headline">¶</a></h4>
+<p>While not strictly part of the compiler, the diagnostics from Clang’s
+<a class="reference external" href="http://clang-analyzer.llvm.org">static analyzer</a> can also be
+influenced by the user via changes to the source code. See the available
+<a class="reference external" href="http://clang-analyzer.llvm.org/annotations.html">annotations</a> and the
+analyzer’s <a class="reference external" href="http://clang-analyzer.llvm.org/faq.html#exclude_code">FAQ
+page</a> for more
+information.</p>
+</div>
+</div>
+<div class="section" id="precompiled-headers">
+<span id="usersmanual-precompiled-headers"></span><h3><a class="toc-backref" href="#id30">Precompiled Headers</a><a class="headerlink" href="#precompiled-headers" title="Permalink to this headline">¶</a></h3>
+<p><a class="reference external" href="http://en.wikipedia.org/wiki/Precompiled_header">Precompiled headers</a>
+are a general approach employed by many compilers to reduce compilation
+time. The underlying motivation of the approach is that it is common for
+the same (and often large) header files to be included by multiple
+source files. Consequently, compile times can often be greatly improved
+by caching some of the (redundant) work done by a compiler to process
+headers. Precompiled header files, which represent one of many ways to
+implement this optimization, are literally files that represent an
+on-disk cache that contains the vital information necessary to reduce
+some of the work needed to process a corresponding header file. While
+details of precompiled headers vary between compilers, precompiled
+headers have been shown to be highly effective at speeding up program
+compilation on systems with very large system headers (e.g., Mac OS X).</p>
+<div class="section" id="generating-a-pch-file">
+<h4><a class="toc-backref" href="#id31">Generating a PCH File</a><a class="headerlink" href="#generating-a-pch-file" title="Permalink to this headline">¶</a></h4>
+<p>To generate a PCH file using Clang, one invokes Clang with the
+<cite>-x <language>-header</cite> option. This mirrors the interface in GCC
+for generating PCH files:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> gcc -x c-header test.h -o test.h.gch
+<span class="gp">$</span> clang -x c-header test.h -o test.h.pch
+</pre></div>
+</div>
+</div>
+<div class="section" id="using-a-pch-file">
+<h4><a class="toc-backref" href="#id32">Using a PCH File</a><a class="headerlink" href="#using-a-pch-file" title="Permalink to this headline">¶</a></h4>
+<p>A PCH file can then be used as a prefix header when a <a class="reference internal" href="CommandGuide/clang.html#cmdoption-include"><em class="xref std std-option">-include</em></a>
+option is passed to <tt class="docutils literal"><span class="pre">clang</span></tt>:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> clang -include test.h test.c -o <span class="nb">test</span>
+</pre></div>
+</div>
+<p>The <tt class="docutils literal"><span class="pre">clang</span></tt> driver will first check if a PCH file for <tt class="docutils literal"><span class="pre">test.h</span></tt> is
+available; if so, the contents of <tt class="docutils literal"><span class="pre">test.h</span></tt> (and the files it includes)
+will be processed from the PCH file. Otherwise, Clang falls back to
+directly processing the content of <tt class="docutils literal"><span class="pre">test.h</span></tt>. This mirrors the behavior
+of GCC.</p>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p>Clang does <em>not</em> automatically use PCH files for headers that are directly
+included within a source file. For example:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> clang -x c-header test.h -o test.h.pch
+<span class="gp">$</span> cat test.c
+<span class="gp">#</span>include <span class="s2">"test.h"</span>
+<span class="gp">$</span> clang test.c -o <span class="nb">test</span>
+</pre></div>
+</div>
+<p class="last">In this example, <tt class="docutils literal"><span class="pre">clang</span></tt> will not automatically use the PCH file for
+<tt class="docutils literal"><span class="pre">test.h</span></tt> since <tt class="docutils literal"><span class="pre">test.h</span></tt> was included directly in the source file and not
+specified on the command line using <a class="reference internal" href="CommandGuide/clang.html#cmdoption-include"><em class="xref std std-option">-include</em></a>.</p>
+</div>
+</div>
+<div class="section" id="relocatable-pch-files">
+<h4><a class="toc-backref" href="#id33">Relocatable PCH Files</a><a class="headerlink" href="#relocatable-pch-files" title="Permalink to this headline">¶</a></h4>
+<p>It is sometimes necessary to build a precompiled header from headers
+that are not yet in their final, installed locations. For example, one
+might build a precompiled header within the build tree that is then
+meant to be installed alongside the headers. Clang permits the creation
+of “relocatable” precompiled headers, which are built with a given path
+(into the build directory) and can later be used from an installed
+location.</p>
+<p>To build a relocatable precompiled header, place your headers into a
+subdirectory whose structure mimics the installed location. For example,
+if you want to build a precompiled header for the header <tt class="docutils literal"><span class="pre">mylib.h</span></tt>
+that will be installed into <tt class="docutils literal"><span class="pre">/usr/include</span></tt>, create a subdirectory
+<tt class="docutils literal"><span class="pre">build/usr/include</span></tt> and place the header <tt class="docutils literal"><span class="pre">mylib.h</span></tt> into that
+subdirectory. If <tt class="docutils literal"><span class="pre">mylib.h</span></tt> depends on other headers, then they can be
+stored within <tt class="docutils literal"><span class="pre">build/usr/include</span></tt> in a way that mimics the installed
+location.</p>
+<p>Building a relocatable precompiled header requires two additional
+arguments. First, pass the <tt class="docutils literal"><span class="pre">--relocatable-pch</span></tt> flag to indicate that
+the resulting PCH file should be relocatable. Second, pass
+<cite>-isysroot /path/to/build</cite>, which makes all includes for your library
+relative to the build directory. For example:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">#</span> clang -x c-header --relocatable-pch -isysroot /path/to/build /path/to/build/mylib.h mylib.h.pch
+</pre></div>
+</div>
+<p>When loading the relocatable PCH file, the various headers used in the
+PCH file are found from the system header root. For example, <tt class="docutils literal"><span class="pre">mylib.h</span></tt>
+can be found in <tt class="docutils literal"><span class="pre">/usr/include/mylib.h</span></tt>. If the headers are installed
+in some other system root, the <cite>-isysroot</cite> option can be used provide
+a different system root from which the headers will be based. For
+example, <cite>-isysroot /Developer/SDKs/MacOSX10.4u.sdk</cite> will look for
+<tt class="docutils literal"><span class="pre">mylib.h</span></tt> in <tt class="docutils literal"><span class="pre">/Developer/SDKs/MacOSX10.4u.sdk/usr/include/mylib.h</span></tt>.</p>
+<p>Relocatable precompiled headers are intended to be used in a limited
+number of cases where the compilation environment is tightly controlled
+and the precompiled header cannot be generated after headers have been
+installed.</p>
+</div>
+</div>
+<div class="section" id="controlling-code-generation">
+<span id="id2"></span><h3><a class="toc-backref" href="#id34">Controlling Code Generation</a><a class="headerlink" href="#controlling-code-generation" title="Permalink to this headline">¶</a></h3>
+<p>Clang provides a number of ways to control code generation. The options
+are listed below.</p>
+<dl class="docutils">
+<dt><strong>-f[no-]sanitize=check1,check2,...</strong></dt>
+<dd><p class="first">Turn on runtime checks for various forms of undefined or suspicious
+behavior.</p>
+<p>This option controls whether Clang adds runtime checks for various
+forms of undefined or suspicious behavior, and is disabled by
+default. If a check fails, a diagnostic message is produced at
+runtime explaining the problem. The main checks are:</p>
+<ul class="simple">
+<li><p id="opt-fsanitize-address"><tt class="docutils literal"><span class="pre">-fsanitize=address</span></tt>:
+<a class="reference internal" href="AddressSanitizer.html"><em>AddressSanitizer</em></a>, a memory error
+detector.</p>
+</li>
+<li><p id="opt-fsanitize-thread"><tt class="docutils literal"><span class="pre">-fsanitize=thread</span></tt>: <a class="reference internal" href="ThreadSanitizer.html"><em>ThreadSanitizer</em></a>, a data race detector.</p>
+</li>
+<li><p id="opt-fsanitize-memory"><tt class="docutils literal"><span class="pre">-fsanitize=memory</span></tt>: <a class="reference internal" href="MemorySanitizer.html"><em>MemorySanitizer</em></a>,
+a detector of uninitialized reads. Requires instrumentation of all
+program code.</p>
+</li>
+<li><p id="opt-fsanitize-undefined"><tt class="docutils literal"><span class="pre">-fsanitize=undefined</span></tt>: <a class="reference internal" href="UndefinedBehaviorSanitizer.html"><em>UndefinedBehaviorSanitizer</em></a>,
+a fast and compatible undefined behavior checker.</p>
+</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=dataflow</span></tt>: <a class="reference internal" href="DataFlowSanitizer.html"><em>DataFlowSanitizer</em></a>, a general data
+flow analysis.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=cfi</span></tt>: <a class="reference internal" href="ControlFlowIntegrity.html"><em>control flow integrity</em></a>
+checks. Requires <tt class="docutils literal"><span class="pre">-flto</span></tt>.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=safe-stack</span></tt>: <a class="reference internal" href="SafeStack.html"><em>safe stack</em></a>
+protection against stack-based memory corruption errors.</li>
+</ul>
+<p>There are more fine-grained checks available: see
+the <a class="reference internal" href="UndefinedBehaviorSanitizer.html#ubsan-checks"><em>list</em></a> of specific kinds of
+undefined behavior that can be detected and the <a class="reference internal" href="ControlFlowIntegrity.html#cfi-schemes"><em>list</em></a>
+of control flow integrity schemes.</p>
+<p>The <tt class="docutils literal"><span class="pre">-fsanitize=</span></tt> argument must also be provided when linking, in
+order to link to the appropriate runtime library.</p>
+<p class="last">It is not possible to combine more than one of the <tt class="docutils literal"><span class="pre">-fsanitize=address</span></tt>,
+<tt class="docutils literal"><span class="pre">-fsanitize=thread</span></tt>, and <tt class="docutils literal"><span class="pre">-fsanitize=memory</span></tt> checkers in the same
+program.</p>
+</dd>
+</dl>
+<p><strong>-f[no-]sanitize-recover=check1,check2,...</strong></p>
+<p><strong>-f[no-]sanitize-recover=all</strong></p>
+<blockquote>
+<div><p>Controls which checks enabled by <tt class="docutils literal"><span class="pre">-fsanitize=</span></tt> flag are non-fatal.
+If the check is fatal, program will halt after the first error
+of this kind is detected and error report is printed.</p>
+<p>By default, non-fatal checks are those enabled by
+<a class="reference internal" href="UndefinedBehaviorSanitizer.html"><em>UndefinedBehaviorSanitizer</em></a>,
+except for <tt class="docutils literal"><span class="pre">-fsanitize=return</span></tt> and <tt class="docutils literal"><span class="pre">-fsanitize=unreachable</span></tt>. Some
+sanitizers may not support recovery (or not support it by default
+e.g. <a class="reference internal" href="AddressSanitizer.html"><em>AddressSanitizer</em></a>), and always crash the program after the issue
+is detected.</p>
+<p>Note that the <tt class="docutils literal"><span class="pre">-fsanitize-trap</span></tt> flag has precedence over this flag.
+This means that if a check has been configured to trap elsewhere on the
+command line, or if the check traps by default, this flag will not have
+any effect unless that sanitizer’s trapping behavior is disabled with
+<tt class="docutils literal"><span class="pre">-fno-sanitize-trap</span></tt>.</p>
+<p>For example, if a command line contains the flags <tt class="docutils literal"><span class="pre">-fsanitize=undefined</span>
+<span class="pre">-fsanitize-trap=undefined</span></tt>, the flag <tt class="docutils literal"><span class="pre">-fsanitize-recover=alignment</span></tt>
+will have no effect on its own; it will need to be accompanied by
+<tt class="docutils literal"><span class="pre">-fno-sanitize-trap=alignment</span></tt>.</p>
+</div></blockquote>
+<p><strong>-f[no-]sanitize-trap=check1,check2,...</strong></p>
+<blockquote>
+<div><p>Controls which checks enabled by the <tt class="docutils literal"><span class="pre">-fsanitize=</span></tt> flag trap. This
+option is intended for use in cases where the sanitizer runtime cannot
+be used (for instance, when building libc or a kernel module), or where
+the binary size increase caused by the sanitizer runtime is a concern.</p>
+<p>This flag is only compatible with <a class="reference internal" href="ControlFlowIntegrity.html"><em>control flow integrity</em></a> schemes and <a class="reference internal" href="UndefinedBehaviorSanitizer.html"><em>UndefinedBehaviorSanitizer</em></a>
+checks other than <tt class="docutils literal"><span class="pre">vptr</span></tt>. If this flag
+is supplied together with <tt class="docutils literal"><span class="pre">-fsanitize=undefined</span></tt>, the <tt class="docutils literal"><span class="pre">vptr</span></tt> sanitizer
+will be implicitly disabled.</p>
+<p>This flag is enabled by default for sanitizers in the <tt class="docutils literal"><span class="pre">cfi</span></tt> group.</p>
+</div></blockquote>
+<dl class="option">
+<dt id="cmdoption-fsanitize-blacklist">
+<tt class="descname">-fsanitize-blacklist</tt><tt class="descclassname">=/path/to/blacklist/file</tt><a class="headerlink" href="#cmdoption-fsanitize-blacklist" title="Permalink to this definition">¶</a></dt>
+<dd><p>Disable or modify sanitizer checks for objects (source files, functions,
+variables, types) listed in the file. See
+<a class="reference internal" href="SanitizerSpecialCaseList.html"><em>Sanitizer special case list</em></a> for file format description.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fno-sanitize-blacklist">
+<tt class="descname">-fno-sanitize-blacklist</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-fno-sanitize-blacklist" title="Permalink to this definition">¶</a></dt>
+<dd><p>Don’t use blacklist file, if it was specified earlier in the command line.</p>
+</dd></dl>
+
+<p><strong>-f[no-]sanitize-coverage=[type,features,...]</strong></p>
+<blockquote>
+<div>Enable simple code coverage in addition to certain sanitizers.
+See <a class="reference internal" href="SanitizerCoverage.html"><em>SanitizerCoverage</em></a> for more details.</div></blockquote>
+<p><strong>-f[no-]sanitize-stats</strong></p>
+<blockquote>
+<div>Enable simple statistics gathering for the enabled sanitizers.
+See <a class="reference internal" href="SanitizerStats.html"><em>SanitizerStats</em></a> for more details.</div></blockquote>
+<dl class="option">
+<dt id="cmdoption-fsanitize-undefined-trap-on-error">
+<tt class="descname">-fsanitize-undefined-trap-on-error</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-fsanitize-undefined-trap-on-error" title="Permalink to this definition">¶</a></dt>
+<dd><p>Deprecated alias for <tt class="docutils literal"><span class="pre">-fsanitize-trap=undefined</span></tt>.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fsanitize-cfi-cross-dso">
+<tt class="descname">-fsanitize-cfi-cross-dso</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-fsanitize-cfi-cross-dso" title="Permalink to this definition">¶</a></dt>
+<dd><p>Enable cross-DSO control flow integrity checks. This flag modifies
+the behavior of sanitizers in the <tt class="docutils literal"><span class="pre">cfi</span></tt> group to allow checking
+of cross-DSO virtual and indirect calls.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fstrict-vtable-pointers">
+<tt class="descname">-fstrict-vtable-pointers</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-fstrict-vtable-pointers" title="Permalink to this definition">¶</a></dt>
+<dd><p>Enable optimizations based on the strict rules for overwriting polymorphic
+C++ objects, i.e. the vptr is invariant during an object’s lifetime.
+This enables better devirtualization. Turned off by default, because it is
+still experimental.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-ffast-math">
+<tt class="descname">-ffast-math</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-ffast-math" title="Permalink to this definition">¶</a></dt>
+<dd><p>Enable fast-math mode. This defines the <tt class="docutils literal"><span class="pre">__FAST_MATH__</span></tt> preprocessor
+macro, and lets the compiler make aggressive, potentially-lossy assumptions
+about floating-point math. These include:</p>
+<ul class="simple">
+<li>Floating-point math obeys regular algebraic rules for real numbers (e.g.
+<tt class="docutils literal"><span class="pre">+</span></tt> and <tt class="docutils literal"><span class="pre">*</span></tt> are associative, <tt class="docutils literal"><span class="pre">x/y</span> <span class="pre">==</span> <span class="pre">x</span> <span class="pre">*</span> <span class="pre">(1/y)</span></tt>, and
+<tt class="docutils literal"><span class="pre">(a</span> <span class="pre">+</span> <span class="pre">b)</span> <span class="pre">*</span> <span class="pre">c</span> <span class="pre">==</span> <span class="pre">a</span> <span class="pre">*</span> <span class="pre">c</span> <span class="pre">+</span> <span class="pre">b</span> <span class="pre">*</span> <span class="pre">c</span></tt>),</li>
+<li>operands to floating-point operations are not equal to <tt class="docutils literal"><span class="pre">NaN</span></tt> and
+<tt class="docutils literal"><span class="pre">Inf</span></tt>, and</li>
+<li><tt class="docutils literal"><span class="pre">+0</span></tt> and <tt class="docutils literal"><span class="pre">-0</span></tt> are interchangeable.</li>
+</ul>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fdenormal-fp-math">
+<tt class="descname">-fdenormal-fp-math</tt><tt class="descclassname">=[values]</tt><a class="headerlink" href="#cmdoption-fdenormal-fp-math" title="Permalink to this definition">¶</a></dt>
+<dd><p>Select which denormal numbers the code is permitted to require.</p>
+<p>Valid values are: <tt class="docutils literal"><span class="pre">ieee</span></tt>, <tt class="docutils literal"><span class="pre">preserve-sign</span></tt>, and <tt class="docutils literal"><span class="pre">positive-zero</span></tt>,
+which correspond to IEEE 754 denormal numbers, the sign of a
+flushed-to-zero number is preserved in the sign of 0, denormals are
+flushed to positive zero, respectively.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fwhole-program-vtables">
+<tt class="descname">-fwhole-program-vtables</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-fwhole-program-vtables" title="Permalink to this definition">¶</a></dt>
+<dd><p>Enable whole-program vtable optimizations, such as single-implementation
+devirtualization and virtual constant propagation, for classes with
+<a class="reference internal" href="LTOVisibility.html"><em>hidden LTO visibility</em></a>. Requires <tt class="docutils literal"><span class="pre">-flto</span></tt>.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fno-assume-sane-operator-new">
+<tt class="descname">-fno-assume-sane-operator-new</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-fno-assume-sane-operator-new" title="Permalink to this definition">¶</a></dt>
+<dd><p>Don’t assume that the C++’s new operator is sane.</p>
+<p>This option tells the compiler to do not assume that C++’s global
+new operator will always return a pointer that does not alias any
+other pointer when the function returns.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-ftrap-function">
+<tt class="descname">-ftrap-function</tt><tt class="descclassname">=[name]</tt><a class="headerlink" href="#cmdoption-ftrap-function" title="Permalink to this definition">¶</a></dt>
+<dd><p>Instruct code generator to emit a function call to the specified
+function name for <tt class="docutils literal"><span class="pre">__builtin_trap()</span></tt>.</p>
+<p>LLVM code generator translates <tt class="docutils literal"><span class="pre">__builtin_trap()</span></tt> to a trap
+instruction if it is supported by the target ISA. Otherwise, the
+builtin is translated into a call to <tt class="docutils literal"><span class="pre">abort</span></tt>. If this option is
+set, then the code generator will always lower the builtin to a call
+to the specified function regardless of whether the target ISA has a
+trap instruction. This option is useful for environments (e.g.
+deeply embedded) where a trap cannot be properly handled, or when
+some custom behavior is desired.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-ftls-model">
+<tt class="descname">-ftls-model</tt><tt class="descclassname">=[model]</tt><a class="headerlink" href="#cmdoption-ftls-model" title="Permalink to this definition">¶</a></dt>
+<dd><p>Select which TLS model to use.</p>
+<p>Valid values are: <tt class="docutils literal"><span class="pre">global-dynamic</span></tt>, <tt class="docutils literal"><span class="pre">local-dynamic</span></tt>,
+<tt class="docutils literal"><span class="pre">initial-exec</span></tt> and <tt class="docutils literal"><span class="pre">local-exec</span></tt>. The default value is
+<tt class="docutils literal"><span class="pre">global-dynamic</span></tt>. The compiler may use a different model if the
+selected model is not supported by the target, or if a more
+efficient model can be used. The TLS model can be overridden per
+variable using the <tt class="docutils literal"><span class="pre">tls_model</span></tt> attribute.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-femulated-tls">
+<tt class="descname">-femulated-tls</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-femulated-tls" title="Permalink to this definition">¶</a></dt>
+<dd><p>Select emulated TLS model, which overrides all -ftls-model choices.</p>
+<p>In emulated TLS mode, all access to TLS variables are converted to
+calls to __emutls_get_address in the runtime library.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-mhwdiv">
+<tt class="descname">-mhwdiv</tt><tt class="descclassname">=[values]</tt><a class="headerlink" href="#cmdoption-mhwdiv" title="Permalink to this definition">¶</a></dt>
+<dd><p>Select the ARM modes (arm or thumb) that support hardware division
+instructions.</p>
+<p>Valid values are: <tt class="docutils literal"><span class="pre">arm</span></tt>, <tt class="docutils literal"><span class="pre">thumb</span></tt> and <tt class="docutils literal"><span class="pre">arm,thumb</span></tt>.
+This option is used to indicate which mode (arm or thumb) supports
+hardware division instructions. This only applies to the ARM
+architecture.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-m">
+<tt class="descname">-m</tt><tt class="descclassname">[no-]crc</tt><a class="headerlink" href="#cmdoption-m" title="Permalink to this definition">¶</a></dt>
+<dd><p>Enable or disable CRC instructions.</p>
+<p>This option is used to indicate whether CRC instructions are to
+be generated. This only applies to the ARM architecture.</p>
+<p>CRC instructions are enabled by default on ARMv8.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-mgeneral-regs-only">
+<tt class="descname">-mgeneral-regs-only</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-mgeneral-regs-only" title="Permalink to this definition">¶</a></dt>
+<dd><p>Generate code which only uses the general purpose registers.</p>
+<p>This option restricts the generated code to use general registers
+only. This only applies to the AArch64 architecture.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-mcompact-branches">
+<tt class="descname">-mcompact-branches</tt><tt class="descclassname">=[values]</tt><a class="headerlink" href="#cmdoption-mcompact-branches" title="Permalink to this definition">¶</a></dt>
+<dd><p>Control the usage of compact branches for MIPSR6.</p>
+<p>Valid values are: <tt class="docutils literal"><span class="pre">never</span></tt>, <tt class="docutils literal"><span class="pre">optimal</span></tt> and <tt class="docutils literal"><span class="pre">always</span></tt>.
+The default value is <tt class="docutils literal"><span class="pre">optimal</span></tt> which generates compact branches
+when a delay slot cannot be filled. <tt class="docutils literal"><span class="pre">never</span></tt> disables the usage of
+compact branches and <tt class="docutils literal"><span class="pre">always</span></tt> generates compact branches whenever
+possible.</p>
+</dd></dl>
+
+<dl class="docutils">
+<dt><strong>-f[no-]max-type-align=[number]</strong></dt>
+<dd><p class="first">Instruct the code generator to not enforce a higher alignment than the given
+number (of bytes) when accessing memory via an opaque pointer or reference.
+This cap is ignored when directly accessing a variable or when the pointee
+type has an explicit âalignedâ attribute.</p>
+<p>The value should usually be determined by the properties of the system allocator.
+Some builtin types, especially vector types, have very high natural alignments;
+when working with values of those types, Clang usually wants to use instructions
+that take advantage of that alignment. However, many system allocators do
+not promise to return memory that is more than 8-byte or 16-byte-aligned. Use
+this option to limit the alignment that the compiler can assume for an arbitrary
+pointer, which may point onto the heap.</p>
+<p>This option does not affect the ABI alignment of types; the layout of structs and
+unions and the value returned by the alignof operator remain the same.</p>
+<p>This option can be overridden on a case-by-case basis by putting an explicit
+âalignedâ alignment on a struct, union, or typedef. For example:</p>
+<div class="last highlight-console"><div class="highlight"><pre><span class="gp">#</span>include <immintrin.h>
+<span class="go">// Make an aligned typedef of the AVX-512 16-int vector type.</span>
+<span class="go">typedef __v16si __aligned_v16si __attribute__((aligned(64)));</span>
+
+<span class="go">void initialize_vector(__aligned_v16si *v) {</span>
+<span class="go"> // The compiler may assume that âvâ is 64-byte aligned, regardless of the</span>
+<span class="go"> // value of -fmax-type-align.</span>
+<span class="go">}</span>
+</pre></div>
+</div>
+</dd>
+</dl>
+</div>
+<div class="section" id="profile-guided-optimization">
+<h3><a class="toc-backref" href="#id35">Profile Guided Optimization</a><a class="headerlink" href="#profile-guided-optimization" title="Permalink to this headline">¶</a></h3>
+<p>Profile information enables better optimization. For example, knowing that a
+branch is taken very frequently helps the compiler make better decisions when
+ordering basic blocks. Knowing that a function <tt class="docutils literal"><span class="pre">foo</span></tt> is called more
+frequently than another function <tt class="docutils literal"><span class="pre">bar</span></tt> helps the inliner.</p>
+<p>Clang supports profile guided optimization with two different kinds of
+profiling. A sampling profiler can generate a profile with very low runtime
+overhead, or you can build an instrumented version of the code that collects
+more detailed profile information. Both kinds of profiles can provide execution
+counts for instructions in the code and information on branches taken and
+function invocation.</p>
+<p>Regardless of which kind of profiling you use, be careful to collect profiles
+by running your code with inputs that are representative of the typical
+behavior. Code that is not exercised in the profile will be optimized as if it
+is unimportant, and the compiler may make poor optimization choices for code
+that is disproportionately used while profiling.</p>
+<div class="section" id="differences-between-sampling-and-instrumentation">
+<h4><a class="toc-backref" href="#id36">Differences Between Sampling and Instrumentation</a><a class="headerlink" href="#differences-between-sampling-and-instrumentation" title="Permalink to this headline">¶</a></h4>
+<p>Although both techniques are used for similar purposes, there are important
+differences between the two:</p>
+<ol class="arabic simple">
+<li>Profile data generated with one cannot be used by the other, and there is no
+conversion tool that can convert one to the other. So, a profile generated
+via <tt class="docutils literal"><span class="pre">-fprofile-instr-generate</span></tt> must be used with <tt class="docutils literal"><span class="pre">-fprofile-instr-use</span></tt>.
+Similarly, sampling profiles generated by external profilers must be
+converted and used with <tt class="docutils literal"><span class="pre">-fprofile-sample-use</span></tt>.</li>
+<li>Instrumentation profile data can be used for code coverage analysis and
+optimization.</li>
+<li>Sampling profiles can only be used for optimization. They cannot be used for
+code coverage analysis. Although it would be technically possible to use
+sampling profiles for code coverage, sample-based profiles are too
+coarse-grained for code coverage purposes; it would yield poor results.</li>
+<li>Sampling profiles must be generated by an external tool. The profile
+generated by that tool must then be converted into a format that can be read
+by LLVM. The section on sampling profilers describes one of the supported
+sampling profile formats.</li>
+</ol>
+</div>
+<div class="section" id="using-sampling-profilers">
+<h4><a class="toc-backref" href="#id37">Using Sampling Profilers</a><a class="headerlink" href="#using-sampling-profilers" title="Permalink to this headline">¶</a></h4>
+<p>Sampling profilers are used to collect runtime information, such as
+hardware counters, while your application executes. They are typically
+very efficient and do not incur a large runtime overhead. The
+sample data collected by the profiler can be used during compilation
+to determine what the most executed areas of the code are.</p>
+<p>Using the data from a sample profiler requires some changes in the way
+a program is built. Before the compiler can use profiling information,
+the code needs to execute under the profiler. The following is the
+usual build cycle when using sample profilers for optimization:</p>
+<ol class="arabic">
+<li><p class="first">Build the code with source line table information. You can use all the
+usual build flags that you always build your application with. The only
+requirement is that you add <tt class="docutils literal"><span class="pre">-gline-tables-only</span></tt> or <tt class="docutils literal"><span class="pre">-g</span></tt> to the
+command line. This is important for the profiler to be able to map
+instructions back to source line locations.</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> clang++ -O2 -gline-tables-only code.cc -o code
+</pre></div>
+</div>
+</li>
+<li><p class="first">Run the executable under a sampling profiler. The specific profiler
+you use does not really matter, as long as its output can be converted
+into the format that the LLVM optimizer understands. Currently, there
+exists a conversion tool for the Linux Perf profiler
+(<a class="reference external" href="https://perf.wiki.kernel.org/">https://perf.wiki.kernel.org/</a>), so these examples assume that you
+are using Linux Perf to profile your code.</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> perf record -b ./code
+</pre></div>
+</div>
+<p>Note the use of the <tt class="docutils literal"><span class="pre">-b</span></tt> flag. This tells Perf to use the Last Branch
+Record (LBR) to record call chains. While this is not strictly required,
+it provides better call information, which improves the accuracy of
+the profile data.</p>
+</li>
+<li><p class="first">Convert the collected profile data to LLVM’s sample profile format.
+This is currently supported via the AutoFDO converter <tt class="docutils literal"><span class="pre">create_llvm_prof</span></tt>.
+It is available at <a class="reference external" href="http://github.com/google/autofdo">http://github.com/google/autofdo</a>. Once built and
+installed, you can convert the <tt class="docutils literal"><span class="pre">perf.data</span></tt> file to LLVM using
+the command:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> create_llvm_prof --binary<span class="o">=</span>./code --out<span class="o">=</span>code.prof
+</pre></div>
+</div>
+<p>This will read <tt class="docutils literal"><span class="pre">perf.data</span></tt> and the binary file <tt class="docutils literal"><span class="pre">./code</span></tt> and emit
+the profile data in <tt class="docutils literal"><span class="pre">code.prof</span></tt>. Note that if you ran <tt class="docutils literal"><span class="pre">perf</span></tt>
+without the <tt class="docutils literal"><span class="pre">-b</span></tt> flag, you need to use <tt class="docutils literal"><span class="pre">--use_lbr=false</span></tt> when
+calling <tt class="docutils literal"><span class="pre">create_llvm_prof</span></tt>.</p>
+</li>
+<li><p class="first">Build the code again using the collected profile. This step feeds
+the profile back to the optimizers. This should result in a binary
+that executes faster than the original one. Note that you are not
+required to build the code with the exact same arguments that you
+used in the first step. The only requirement is that you build the code
+with <tt class="docutils literal"><span class="pre">-gline-tables-only</span></tt> and <tt class="docutils literal"><span class="pre">-fprofile-sample-use</span></tt>.</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> clang++ -O2 -gline-tables-only -fprofile-sample-use<span class="o">=</span>code.prof code.cc -o code
+</pre></div>
+</div>
+</li>
+</ol>
+<div class="section" id="sample-profile-formats">
+<h5><a class="toc-backref" href="#id38">Sample Profile Formats</a><a class="headerlink" href="#sample-profile-formats" title="Permalink to this headline">¶</a></h5>
+<p>Since external profilers generate profile data in a variety of custom formats,
+the data generated by the profiler must be converted into a format that can be
+read by the backend. LLVM supports three different sample profile formats:</p>
+<ol class="arabic simple">
+<li>ASCII text. This is the easiest one to generate. The file is divided into
+sections, which correspond to each of the functions with profile
+information. The format is described below. It can also be generated from
+the binary or gcov formats using the <tt class="docutils literal"><span class="pre">llvm-profdata</span></tt> tool.</li>
+<li>Binary encoding. This uses a more efficient encoding that yields smaller
+profile files. This is the format generated by the <tt class="docutils literal"><span class="pre">create_llvm_prof</span></tt> tool
+in <a class="reference external" href="http://github.com/google/autofdo">http://github.com/google/autofdo</a>.</li>
+<li>GCC encoding. This is based on the gcov format, which is accepted by GCC. It
+is only interesting in environments where GCC and Clang co-exist. This
+encoding is only generated by the <tt class="docutils literal"><span class="pre">create_gcov</span></tt> tool in
+<a class="reference external" href="http://github.com/google/autofdo">http://github.com/google/autofdo</a>. It can be read by LLVM and
+<tt class="docutils literal"><span class="pre">llvm-profdata</span></tt>, but it cannot be generated by either.</li>
+</ol>
+<p>If you are using Linux Perf to generate sampling profiles, you can use the
+conversion tool <tt class="docutils literal"><span class="pre">create_llvm_prof</span></tt> described in the previous section.
+Otherwise, you will need to write a conversion tool that converts your
+profiler’s native format into one of these three.</p>
+</div>
+<div class="section" id="sample-profile-text-format">
+<h5><a class="toc-backref" href="#id39">Sample Profile Text Format</a><a class="headerlink" href="#sample-profile-text-format" title="Permalink to this headline">¶</a></h5>
+<p>This section describes the ASCII text format for sampling profiles. It is,
+arguably, the easiest one to generate. If you are interested in generating any
+of the other two, consult the <tt class="docutils literal"><span class="pre">ProfileData</span></tt> library in in LLVM’s source tree
+(specifically, <tt class="docutils literal"><span class="pre">include/llvm/ProfileData/SampleProfReader.h</span></tt>).</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="go">function1:total_samples:total_head_samples</span>
+<span class="go"> offset1[.discriminator]: number_of_samples [fn1:num fn2:num ... ]</span>
+<span class="go"> offset2[.discriminator]: number_of_samples [fn3:num fn4:num ... ]</span>
+<span class="go"> ...</span>
+<span class="go"> offsetN[.discriminator]: number_of_samples [fn5:num fn6:num ... ]</span>
+<span class="go"> offsetA[.discriminator]: fnA:num_of_total_samples</span>
+<span class="go"> offsetA1[.discriminator]: number_of_samples [fn7:num fn8:num ... ]</span>
+<span class="go"> offsetA1[.discriminator]: number_of_samples [fn9:num fn10:num ... ]</span>
+<span class="go"> offsetB[.discriminator]: fnB:num_of_total_samples</span>
+<span class="go"> offsetB1[.discriminator]: number_of_samples [fn11:num fn12:num ... ]</span>
+</pre></div>
+</div>
+<p>This is a nested tree in which the identation represents the nesting level
+of the inline stack. There are no blank lines in the file. And the spacing
+within a single line is fixed. Additional spaces will result in an error
+while reading the file.</p>
+<p>Any line starting with the ‘#’ character is completely ignored.</p>
+<p>Inlined calls are represented with indentation. The Inline stack is a
+stack of source locations in which the top of the stack represents the
+leaf function, and the bottom of the stack represents the actual
+symbol to which the instruction belongs.</p>
+<p>Function names must be mangled in order for the profile loader to
+match them in the current translation unit. The two numbers in the
+function header specify how many total samples were accumulated in the
+function (first number), and the total number of samples accumulated
+in the prologue of the function (second number). This head sample
+count provides an indicator of how frequently the function is invoked.</p>
+<p>There are two types of lines in the function body.</p>
+<ul class="simple">
+<li>Sampled line represents the profile information of a source location.
+<tt class="docutils literal"><span class="pre">offsetN[.discriminator]:</span> <span class="pre">number_of_samples</span> <span class="pre">[fn5:num</span> <span class="pre">fn6:num</span> <span class="pre">...</span> <span class="pre">]</span></tt></li>
+<li>Callsite line represents the profile information of an inlined callsite.
+<tt class="docutils literal"><span class="pre">offsetA[.discriminator]:</span> <span class="pre">fnA:num_of_total_samples</span></tt></li>
+</ul>
+<p>Each sampled line may contain several items. Some are optional (marked
+below):</p>
+<ol class="loweralpha">
+<li><p class="first">Source line offset. This number represents the line number
+in the function where the sample was collected. The line number is
+always relative to the line where symbol of the function is
+defined. So, if the function has its header at line 280, the offset
+13 is at line 293 in the file.</p>
+<p>Note that this offset should never be a negative number. This could
+happen in cases like macros. The debug machinery will register the
+line number at the point of macro expansion. So, if the macro was
+expanded in a line before the start of the function, the profile
+converter should emit a 0 as the offset (this means that the optimizers
+will not be able to associate a meaningful weight to the instructions
+in the macro).</p>
+</li>
+<li><p class="first">[OPTIONAL] Discriminator. This is used if the sampled program
+was compiled with DWARF discriminator support
+(<a class="reference external" href="http://wiki.dwarfstd.org/index.php?title=Path_Discriminators">http://wiki.dwarfstd.org/index.php?title=Path_Discriminators</a>).
+DWARF discriminators are unsigned integer values that allow the
+compiler to distinguish between multiple execution paths on the
+same source line location.</p>
+<p>For example, consider the line of code <tt class="docutils literal"><span class="pre">if</span> <span class="pre">(cond)</span> <span class="pre">foo();</span> <span class="pre">else</span> <span class="pre">bar();</span></tt>.
+If the predicate <tt class="docutils literal"><span class="pre">cond</span></tt> is true 80% of the time, then the edge
+into function <tt class="docutils literal"><span class="pre">foo</span></tt> should be considered to be taken most of the
+time. But both calls to <tt class="docutils literal"><span class="pre">foo</span></tt> and <tt class="docutils literal"><span class="pre">bar</span></tt> are at the same source
+line, so a sample count at that line is not sufficient. The
+compiler needs to know which part of that line is taken more
+frequently.</p>
+<p>This is what discriminators provide. In this case, the calls to
+<tt class="docutils literal"><span class="pre">foo</span></tt> and <tt class="docutils literal"><span class="pre">bar</span></tt> will be at the same line, but will have
+different discriminator values. This allows the compiler to correctly
+set edge weights into <tt class="docutils literal"><span class="pre">foo</span></tt> and <tt class="docutils literal"><span class="pre">bar</span></tt>.</p>
+</li>
+<li><p class="first">Number of samples. This is an integer quantity representing the
+number of samples collected by the profiler at this source
+location.</p>
+</li>
+<li><p class="first">[OPTIONAL] Potential call targets and samples. If present, this
+line contains a call instruction. This models both direct and
+number of samples. For example,</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="go">130: 7 foo:3 bar:2 baz:7</span>
+</pre></div>
+</div>
+<p>The above means that at relative line offset 130 there is a call
+instruction that calls one of <tt class="docutils literal"><span class="pre">foo()</span></tt>, <tt class="docutils literal"><span class="pre">bar()</span></tt> and <tt class="docutils literal"><span class="pre">baz()</span></tt>,
+with <tt class="docutils literal"><span class="pre">baz()</span></tt> being the relatively more frequently called target.</p>
+</li>
+</ol>
+<p>As an example, consider a program with the call chain <tt class="docutils literal"><span class="pre">main</span> <span class="pre">-></span> <span class="pre">foo</span> <span class="pre">-></span> <span class="pre">bar</span></tt>.
+When built with optimizations enabled, the compiler may inline the
+calls to <tt class="docutils literal"><span class="pre">bar</span></tt> and <tt class="docutils literal"><span class="pre">foo</span></tt> inside <tt class="docutils literal"><span class="pre">main</span></tt>. The generated profile
+could then be something like this:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="go">main:35504:0</span>
+<span class="go">1: _Z3foov:35504</span>
+<span class="go"> 2: _Z32bari:31977</span>
+<span class="go"> 1.1: 31977</span>
+<span class="go">2: 0</span>
+</pre></div>
+</div>
+<p>This profile indicates that there were a total of 35,504 samples
+collected in main. All of those were at line 1 (the call to <tt class="docutils literal"><span class="pre">foo</span></tt>).
+Of those, 31,977 were spent inside the body of <tt class="docutils literal"><span class="pre">bar</span></tt>. The last line
+of the profile (<tt class="docutils literal"><span class="pre">2:</span> <span class="pre">0</span></tt>) corresponds to line 2 inside <tt class="docutils literal"><span class="pre">main</span></tt>. No
+samples were collected there.</p>
+</div>
+</div>
+<div class="section" id="profiling-with-instrumentation">
+<h4><a class="toc-backref" href="#id40">Profiling with Instrumentation</a><a class="headerlink" href="#profiling-with-instrumentation" title="Permalink to this headline">¶</a></h4>
+<p>Clang also supports profiling via instrumentation. This requires building a
+special instrumented version of the code and has some runtime
+overhead during the profiling, but it provides more detailed results than a
+sampling profiler. It also provides reproducible results, at least to the
+extent that the code behaves consistently across runs.</p>
+<p>Here are the steps for using profile guided optimization with
+instrumentation:</p>
+<ol class="arabic">
+<li><p class="first">Build an instrumented version of the code by compiling and linking with the
+<tt class="docutils literal"><span class="pre">-fprofile-instr-generate</span></tt> option.</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> clang++ -O2 -fprofile-instr-generate code.cc -o code
+</pre></div>
+</div>
+</li>
+<li><p class="first">Run the instrumented executable with inputs that reflect the typical usage.
+By default, the profile data will be written to a <tt class="docutils literal"><span class="pre">default.profraw</span></tt> file
+in the current directory. You can override that default by using option
+<tt class="docutils literal"><span class="pre">-fprofile-instr-generate=</span></tt> or by setting the <tt class="docutils literal"><span class="pre">LLVM_PROFILE_FILE</span></tt>
+environment variable to specify an alternate file. If non-default file name
+is specified by both the environment variable and the command line option,
+the environment variable takes precedence. The file name pattern specified
+can include different modifiers: <tt class="docutils literal"><span class="pre">%p</span></tt>, <tt class="docutils literal"><span class="pre">%h</span></tt>, and <tt class="docutils literal"><span class="pre">%m</span></tt>.</p>
+<p>Any instance of <tt class="docutils literal"><span class="pre">%p</span></tt> in that file name will be replaced by the process
+ID, so that you can easily distinguish the profile output from multiple
+runs.</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> <span class="nv">LLVM_PROFILE_FILE</span><span class="o">=</span><span class="s2">"code-%p.profraw"</span> ./code
+</pre></div>
+</div>
+<p>The modifier <tt class="docutils literal"><span class="pre">%h</span></tt> can be used in scenarios where the same instrumented
+binary is run in multiple different host machines dumping profile data
+to a shared network based storage. The <tt class="docutils literal"><span class="pre">%h</span></tt> specifier will be substituted
+with the hostname so that profiles collected from different hosts do not
+clobber each other.</p>
+<p>While the use of <tt class="docutils literal"><span class="pre">%p</span></tt> specifier can reduce the likelihood for the profiles
+dumped from different processes to clobber each other, such clobbering can still
+happen because of the <tt class="docutils literal"><span class="pre">pid</span></tt> re-use by the OS. Another side-effect of using
+<tt class="docutils literal"><span class="pre">%p</span></tt> is that the storage requirement for raw profile data files is greatly
+increased. To avoid issues like this, the <tt class="docutils literal"><span class="pre">%m</span></tt> specifier can used in the profile
+name. When this specifier is used, the profiler runtime will substitute <tt class="docutils literal"><span class="pre">%m</span></tt>
+with a unique integer identifier associated with the instrumented binary. Additionally,
+multiple raw profiles dumped from different processes that share a file system (can be
+on different hosts) will be automatically merged by the profiler runtime during the
+dumping. If the program links in multiple instrumented shared libraries, each library
+will dump the profile data into its own profile data file (with its unique integer
+id embedded in the profile name). Note that the merging enabled by <tt class="docutils literal"><span class="pre">%m</span></tt> is for raw
+profile data generated by profiler runtime. The resulting merged “raw” profile data
+file still needs to be converted to a different format expected by the compiler (
+see step 3 below).</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> <span class="nv">LLVM_PROFILE_FILE</span><span class="o">=</span><span class="s2">"code-%m.profraw"</span> ./code
+</pre></div>
+</div>
+</li>
+<li><p class="first">Combine profiles from multiple runs and convert the “raw” profile format to
+the input expected by clang. Use the <tt class="docutils literal"><span class="pre">merge</span></tt> command of the
+<tt class="docutils literal"><span class="pre">llvm-profdata</span></tt> tool to do this.</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> llvm-profdata merge -output<span class="o">=</span>code.profdata code-*.profraw
+</pre></div>
+</div>
+<p>Note that this step is necessary even when there is only one “raw” profile,
+since the merge operation also changes the file format.</p>
+</li>
+<li><p class="first">Build the code again using the <tt class="docutils literal"><span class="pre">-fprofile-instr-use</span></tt> option to specify the
+collected profile data.</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> clang++ -O2 -fprofile-instr-use<span class="o">=</span>code.profdata code.cc -o code
+</pre></div>
+</div>
+<p>You can repeat step 4 as often as you like without regenerating the
+profile. As you make changes to your code, clang may no longer be able to
+use the profile data. It will warn you when this happens.</p>
+</li>
+</ol>
+<p>Profile generation using an alternative instrumentation method can be
+controlled by the GCC-compatible flags <tt class="docutils literal"><span class="pre">-fprofile-generate</span></tt> and
+<tt class="docutils literal"><span class="pre">-fprofile-use</span></tt>. Although these flags are semantically equivalent to
+their GCC counterparts, they <em>do not</em> handle GCC-compatible profiles.
+They are only meant to implement GCC’s semantics with respect to
+profile creation and use.</p>
+<dl class="option">
+<dt id="cmdoption-fprofile-generate">
+<tt class="descname">-fprofile-generate</tt><tt class="descclassname">[=<dirname>]</tt><a class="headerlink" href="#cmdoption-fprofile-generate" title="Permalink to this definition">¶</a></dt>
+<dd><blockquote>
+<div><p>The <tt class="docutils literal"><span class="pre">-fprofile-generate</span></tt> and <tt class="docutils literal"><span class="pre">-fprofile-generate=</span></tt> flags will use
+an alterantive instrumentation method for profile generation. When
+given a directory name, it generates the profile file
+<tt class="docutils literal"><span class="pre">default_%m.profraw</span></tt> in the directory named <tt class="docutils literal"><span class="pre">dirname</span></tt> if specified.
+If <tt class="docutils literal"><span class="pre">dirname</span></tt> does not exist, it will be created at runtime. <tt class="docutils literal"><span class="pre">%m</span></tt> specifier
+will be substibuted with a unique id documented in step 2 above. In other words,
+with <tt class="docutils literal"><span class="pre">-fprofile-generate[=<dirname>]</span></tt> option, the “raw” profile data automatic
+merging is turned on by default, so there will no longer any risk of profile
+clobbering from different running processes. For example,</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> clang++ -O2 -fprofile-generate<span class="o">=</span>yyy/zzz code.cc -o code
+</pre></div>
+</div>
+<p>When <tt class="docutils literal"><span class="pre">code</span></tt> is executed, the profile will be written to the file
+<tt class="docutils literal"><span class="pre">yyy/zzz/default_xxxx.profraw</span></tt>.</p>
+<p>To generate the profile data file with the compiler readable format, the
+<tt class="docutils literal"><span class="pre">llvm-profdata</span></tt> tool can be used with the profile directory as the input:</p>
+<blockquote>
+<div><div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> llvm-profdata merge -output<span class="o">=</span>code.profdata yyy/zzz/
+</pre></div>
+</div>
+</div></blockquote>
+</div></blockquote>
+<p>If the user wants to turn off the auto-merging feature, or simply override the
+the profile dumping path specified at command line, the environment variable
+<tt class="docutils literal"><span class="pre">LLVM_PROFILE_FILE</span></tt> can still be used to override
+the directory and filename for the profile file at runtime.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fprofile-use">
+<tt class="descname">-fprofile-use</tt><tt class="descclassname">[=<pathname>]</tt><a class="headerlink" href="#cmdoption-fprofile-use" title="Permalink to this definition">¶</a></dt>
+<dd><p>Without any other arguments, <tt class="docutils literal"><span class="pre">-fprofile-use</span></tt> behaves identically to
+<tt class="docutils literal"><span class="pre">-fprofile-instr-use</span></tt>. Otherwise, if <tt class="docutils literal"><span class="pre">pathname</span></tt> is the full path to a
+profile file, it reads from that file. If <tt class="docutils literal"><span class="pre">pathname</span></tt> is a directory name,
+it reads from <tt class="docutils literal"><span class="pre">pathname/default.profdata</span></tt>.</p>
+</dd></dl>
+
+</div>
+<div class="section" id="disabling-instrumentation">
+<h4><a class="toc-backref" href="#id41">Disabling Instrumentation</a><a class="headerlink" href="#disabling-instrumentation" title="Permalink to this headline">¶</a></h4>
+<p>In certain situations, it may be useful to disable profile generation or use
+for specific files in a build, without affecting the main compilation flags
+used for the other files in the project.</p>
+<p>In these cases, you can use the flag <tt class="docutils literal"><span class="pre">-fno-profile-instr-generate</span></tt> (or
+<tt class="docutils literal"><span class="pre">-fno-profile-generate</span></tt>) to disable profile generation, and
+<tt class="docutils literal"><span class="pre">-fno-profile-instr-use</span></tt> (or <tt class="docutils literal"><span class="pre">-fno-profile-use</span></tt>) to disable profile use.</p>
+<p>Note that these flags should appear after the corresponding profile
+flags to have an effect.</p>
+</div>
+</div>
+<div class="section" id="controlling-debug-information">
+<h3><a class="toc-backref" href="#id42">Controlling Debug Information</a><a class="headerlink" href="#controlling-debug-information" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="controlling-size-of-debug-information">
+<h4><a class="toc-backref" href="#id43">Controlling Size of Debug Information</a><a class="headerlink" href="#controlling-size-of-debug-information" title="Permalink to this headline">¶</a></h4>
+<p>Debug info kind generated by Clang can be set by one of the flags listed
+below. If multiple flags are present, the last one is used.</p>
+<dl class="option">
+<dt id="cmdoption-g0">
+<tt class="descname">-g0</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-g0" title="Permalink to this definition">¶</a></dt>
+<dd><p>Don’t generate any debug info (default).</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-gline-tables-only">
+<tt class="descname">-gline-tables-only</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-gline-tables-only" title="Permalink to this definition">¶</a></dt>
+<dd><p>Generate line number tables only.</p>
+<p>This kind of debug info allows to obtain stack traces with function names,
+file names and line numbers (by such tools as <tt class="docutils literal"><span class="pre">gdb</span></tt> or <tt class="docutils literal"><span class="pre">addr2line</span></tt>). It
+doesn’t contain any other data (e.g. description of local variables or
+function parameters).</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fstandalone-debug">
+<tt class="descname">-fstandalone-debug</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-fstandalone-debug" title="Permalink to this definition">¶</a></dt>
+<dd><p>Clang supports a number of optimizations to reduce the size of debug
+information in the binary. They work based on the assumption that
+the debug type information can be spread out over multiple
+compilation units. For instance, Clang will not emit type
+definitions for types that are not needed by a module and could be
+replaced with a forward declaration. Further, Clang will only emit
+type info for a dynamic C++ class in the module that contains the
+vtable for the class.</p>
+<p>The <strong>-fstandalone-debug</strong> option turns off these optimizations.
+This is useful when working with 3rd-party libraries that don’t come
+with debug information. Note that Clang will never emit type
+information for types that are not referenced at all by the program.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fno-standalone-debug">
+<tt class="descname">-fno-standalone-debug</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-fno-standalone-debug" title="Permalink to this definition">¶</a></dt>
+<dd><p>On Darwin <strong>-fstandalone-debug</strong> is enabled by default. The
+<strong>-fno-standalone-debug</strong> option can be used to get to turn on the
+vtable-based optimization described above.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-g">
+<tt class="descname">-g</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-g" title="Permalink to this definition">¶</a></dt>
+<dd><p>Generate complete debug info.</p>
+</dd></dl>
+
+</div>
+<div class="section" id="controlling-debugger-tuning">
+<h4><a class="toc-backref" href="#id44">Controlling Debugger “Tuning”</a><a class="headerlink" href="#controlling-debugger-tuning" title="Permalink to this headline">¶</a></h4>
+<p>While Clang generally emits standard DWARF debug info (<a class="reference external" href="http://dwarfstd.org">http://dwarfstd.org</a>),
+different debuggers may know how to take advantage of different specific DWARF
+features. You can “tune” the debug info for one of several different debuggers.</p>
+<dl class="option">
+<dt id="cmdoption-ggdb">
+<span id="cmdoption-glldb"></span><span id="cmdoption-gsce"></span><tt class="descname">-ggdb</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">-glldb</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">-gsce</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-ggdb" title="Permalink to this definition">¶</a></dt>
+<dd><p>Tune the debug info for the <tt class="docutils literal"><span class="pre">gdb</span></tt>, <tt class="docutils literal"><span class="pre">lldb</span></tt>, or Sony PlayStation®
+debugger, respectively. Each of these options implies <strong>-g</strong>. (Therefore, if
+you want both <strong>-gline-tables-only</strong> and debugger tuning, the tuning option
+must come first.)</p>
+</dd></dl>
+
+</div>
+</div>
+<div class="section" id="comment-parsing-options">
+<h3><a class="toc-backref" href="#id45">Comment Parsing Options</a><a class="headerlink" href="#comment-parsing-options" title="Permalink to this headline">¶</a></h3>
+<p>Clang parses Doxygen and non-Doxygen style documentation comments and attaches
+them to the appropriate declaration nodes. By default, it only parses
+Doxygen-style comments and ignores ordinary comments starting with <tt class="docutils literal"><span class="pre">//</span></tt> and
+<tt class="docutils literal"><span class="pre">/*</span></tt>.</p>
+<dl class="option">
+<dt id="cmdoption-Wdocumentation">
+<tt class="descname">-Wdocumentation</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-Wdocumentation" title="Permalink to this definition">¶</a></dt>
+<dd><p>Emit warnings about use of documentation comments. This warning group is off
+by default.</p>
+<p>This includes checking that <tt class="docutils literal"><span class="pre">\param</span></tt> commands name parameters that actually
+present in the function signature, checking that <tt class="docutils literal"><span class="pre">\returns</span></tt> is used only on
+functions that actually return a value etc.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-Wno-documentation-unknown-command">
+<tt class="descname">-Wno-documentation-unknown-command</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-Wno-documentation-unknown-command" title="Permalink to this definition">¶</a></dt>
+<dd><p>Don’t warn when encountering an unknown Doxygen command.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fparse-all-comments">
+<tt class="descname">-fparse-all-comments</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-fparse-all-comments" title="Permalink to this definition">¶</a></dt>
+<dd><p>Parse all comments as documentation comments (including ordinary comments
+starting with <tt class="docutils literal"><span class="pre">//</span></tt> and <tt class="docutils literal"><span class="pre">/*</span></tt>).</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fcomment-block-commands">
+<tt class="descname">-fcomment-block-commands</tt><tt class="descclassname">=[commands]</tt><a class="headerlink" href="#cmdoption-fcomment-block-commands" title="Permalink to this definition">¶</a></dt>
+<dd><p>Define custom documentation commands as block commands. This allows Clang to
+construct the correct AST for these custom commands, and silences warnings
+about unknown commands. Several commands must be separated by a comma
+<em>without trailing space</em>; e.g. <tt class="docutils literal"><span class="pre">-fcomment-block-commands=foo,bar</span></tt> defines
+custom commands <tt class="docutils literal"><span class="pre">\foo</span></tt> and <tt class="docutils literal"><span class="pre">\bar</span></tt>.</p>
+<p>It is also possible to use <tt class="docutils literal"><span class="pre">-fcomment-block-commands</span></tt> several times; e.g.
+<tt class="docutils literal"><span class="pre">-fcomment-block-commands=foo</span> <span class="pre">-fcomment-block-commands=bar</span></tt> does the same
+as above.</p>
+</dd></dl>
+
+</div>
+</div>
+<div class="section" id="c-language-features">
+<span id="c"></span><h2><a class="toc-backref" href="#id46">C Language Features</a><a class="headerlink" href="#c-language-features" title="Permalink to this headline">¶</a></h2>
+<p>The support for standard C in clang is feature-complete except for the
+C99 floating-point pragmas.</p>
+<div class="section" id="extensions-supported-by-clang">
+<h3><a class="toc-backref" href="#id47">Extensions supported by clang</a><a class="headerlink" href="#extensions-supported-by-clang" title="Permalink to this headline">¶</a></h3>
+<p>See <a class="reference internal" href="LanguageExtensions.html"><em>Clang Language Extensions</em></a>.</p>
+</div>
+<div class="section" id="differences-between-various-standard-modes">
+<h3><a class="toc-backref" href="#id48">Differences between various standard modes</a><a class="headerlink" href="#differences-between-various-standard-modes" title="Permalink to this headline">¶</a></h3>
+<p>clang supports the -std option, which changes what language mode clang
+uses. The supported modes for C are c89, gnu89, c94, c99, gnu99, c11,
+gnu11, and various aliases for those modes. If no -std option is
+specified, clang defaults to gnu11 mode. Many C99 and C11 features are
+supported in earlier modes as a conforming extension, with a warning. Use
+<tt class="docutils literal"><span class="pre">-pedantic-errors</span></tt> to request an error if a feature from a later standard
+revision is used in an earlier mode.</p>
+<p>Differences between all <tt class="docutils literal"><span class="pre">c*</span></tt> and <tt class="docutils literal"><span class="pre">gnu*</span></tt> modes:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">c*</span></tt> modes define “<tt class="docutils literal"><span class="pre">__STRICT_ANSI__</span></tt>”.</li>
+<li>Target-specific defines not prefixed by underscores, like “linux”,
+are defined in <tt class="docutils literal"><span class="pre">gnu*</span></tt> modes.</li>
+<li>Trigraphs default to being off in <tt class="docutils literal"><span class="pre">gnu*</span></tt> modes; they can be enabled by
+the -trigraphs option.</li>
+<li>The parser recognizes “asm” and “typeof” as keywords in <tt class="docutils literal"><span class="pre">gnu*</span></tt> modes;
+the variants “<tt class="docutils literal"><span class="pre">__asm__</span></tt>” and “<tt class="docutils literal"><span class="pre">__typeof__</span></tt>” are recognized in all
+modes.</li>
+<li>The Apple “blocks” extension is recognized by default in <tt class="docutils literal"><span class="pre">gnu*</span></tt> modes
+on some platforms; it can be enabled in any mode with the “-fblocks”
+option.</li>
+<li>Arrays that are VLA’s according to the standard, but which can be
+constant folded by the frontend are treated as fixed size arrays.
+This occurs for things like “int X[(1, 2)];”, which is technically a
+VLA. <tt class="docutils literal"><span class="pre">c*</span></tt> modes are strictly compliant and treat these as VLAs.</li>
+</ul>
+<p>Differences between <tt class="docutils literal"><span class="pre">*89</span></tt> and <tt class="docutils literal"><span class="pre">*99</span></tt> modes:</p>
+<ul class="simple">
+<li>The <tt class="docutils literal"><span class="pre">*99</span></tt> modes default to implementing “inline” as specified in C99,
+while the <tt class="docutils literal"><span class="pre">*89</span></tt> modes implement the GNU version. This can be
+overridden for individual functions with the <tt class="docutils literal"><span class="pre">__gnu_inline__</span></tt>
+attribute.</li>
+<li>Digraphs are not recognized in c89 mode.</li>
+<li>The scope of names defined inside a “for”, “if”, “switch”, “while”,
+or “do” statement is different. (example: “<tt class="docutils literal"><span class="pre">if</span> <span class="pre">((struct</span> <span class="pre">x</span> <span class="pre">{int</span>
+<span class="pre">x;}*)0)</span> <span class="pre">{}</span></tt>”.)</li>
+<li><tt class="docutils literal"><span class="pre">__STDC_VERSION__</span></tt> is not defined in <tt class="docutils literal"><span class="pre">*89</span></tt> modes.</li>
+<li>“inline” is not recognized as a keyword in c89 mode.</li>
+<li>“restrict” is not recognized as a keyword in <tt class="docutils literal"><span class="pre">*89</span></tt> modes.</li>
+<li>Commas are allowed in integer constant expressions in <tt class="docutils literal"><span class="pre">*99</span></tt> modes.</li>
+<li>Arrays which are not lvalues are not implicitly promoted to pointers
+in <tt class="docutils literal"><span class="pre">*89</span></tt> modes.</li>
+<li>Some warnings are different.</li>
+</ul>
+<p>Differences between <tt class="docutils literal"><span class="pre">*99</span></tt> and <tt class="docutils literal"><span class="pre">*11</span></tt> modes:</p>
+<ul class="simple">
+<li>Warnings for use of C11 features are disabled.</li>
+<li><tt class="docutils literal"><span class="pre">__STDC_VERSION__</span></tt> is defined to <tt class="docutils literal"><span class="pre">201112L</span></tt> rather than <tt class="docutils literal"><span class="pre">199901L</span></tt>.</li>
+</ul>
+<p>c94 mode is identical to c89 mode except that digraphs are enabled in
+c94 mode (FIXME: And <tt class="docutils literal"><span class="pre">__STDC_VERSION__</span></tt> should be defined!).</p>
+</div>
+<div class="section" id="gcc-extensions-not-implemented-yet">
+<h3><a class="toc-backref" href="#id49">GCC extensions not implemented yet</a><a class="headerlink" href="#gcc-extensions-not-implemented-yet" title="Permalink to this headline">¶</a></h3>
+<p>clang tries to be compatible with gcc as much as possible, but some gcc
+extensions are not implemented yet:</p>
+<ul>
+<li><p class="first">clang does not support decimal floating point types (<tt class="docutils literal"><span class="pre">_Decimal32</span></tt> and
+friends) or fixed-point types (<tt class="docutils literal"><span class="pre">_Fract</span></tt> and friends); nobody has
+expressed interest in these features yet, so it’s hard to say when
+they will be implemented.</p>
+</li>
+<li><p class="first">clang does not support nested functions; this is a complex feature
+which is infrequently used, so it is unlikely to be implemented
+anytime soon. In C++11 it can be emulated by assigning lambda
+functions to local variables, e.g:</p>
+<div class="highlight-cpp"><div class="highlight"><pre><span class="k">auto</span> <span class="k">const</span> <span class="n">local_function</span> <span class="o">=</span> <span class="p">[</span><span class="o">&</span><span class="p">](</span><span class="kt">int</span> <span class="n">parameter</span><span class="p">)</span> <span class="p">{</span>
+ <span class="c1">// Do something</span>
+<span class="p">};</span>
+<span class="p">...</span>
+<span class="n">local_function</span><span class="p">(</span><span class="mi">1</span><span class="p">);</span>
+</pre></div>
+</div>
+</li>
+<li><p class="first">clang only supports global register variables when the register specified
+is non-allocatable (e.g. the stack pointer). Support for general global
+register variables is unlikely to be implemented soon because it requires
+additional LLVM backend support.</p>
+</li>
+<li><p class="first">clang does not support static initialization of flexible array
+members. This appears to be a rarely used extension, but could be
+implemented pending user demand.</p>
+</li>
+<li><p class="first">clang does not support
+<tt class="docutils literal"><span class="pre">__builtin_va_arg_pack</span></tt>/<tt class="docutils literal"><span class="pre">__builtin_va_arg_pack_len</span></tt>. This is
+used rarely, but in some potentially interesting places, like the
+glibc headers, so it may be implemented pending user demand. Note
+that because clang pretends to be like GCC 4.2, and this extension
+was introduced in 4.3, the glibc headers will not try to use this
+extension with clang at the moment.</p>
+</li>
+<li><p class="first">clang does not support the gcc extension for forward-declaring
+function parameters; this has not shown up in any real-world code
+yet, though, so it might never be implemented.</p>
+</li>
+</ul>
+<p>This is not a complete list; if you find an unsupported extension
+missing from this list, please send an e-mail to cfe-dev. This list
+currently excludes C++; see <a class="reference internal" href="#cxx"><em>C++ Language Features</em></a>. Also, this
+list does not include bugs in mostly-implemented features; please see
+the <a class="reference external" href="http://llvm.org/bugs/buglist.cgi?quicksearch=product%3Aclang+component%3A-New%2BBugs%2CAST%2CBasic%2CDriver%2CHeaders%2CLLVM%2BCodeGen%2Cparser%2Cpreprocessor%2CSemantic%2BAnalyzer">bug
+tracker</a>
+for known existing bugs (FIXME: Is there a section for bug-reporting
+guidelines somewhere?).</p>
+</div>
+<div class="section" id="intentionally-unsupported-gcc-extensions">
+<h3><a class="toc-backref" href="#id50">Intentionally unsupported GCC extensions</a><a class="headerlink" href="#intentionally-unsupported-gcc-extensions" title="Permalink to this headline">¶</a></h3>
+<ul class="simple">
+<li>clang does not support the gcc extension that allows variable-length
+arrays in structures. This is for a few reasons: one, it is tricky to
+implement, two, the extension is completely undocumented, and three,
+the extension appears to be rarely used. Note that clang <em>does</em>
+support flexible array members (arrays with a zero or unspecified
+size at the end of a structure).</li>
+<li>clang does not have an equivalent to gcc’s “fold”; this means that
+clang doesn’t accept some constructs gcc might accept in contexts
+where a constant expression is required, like “x-x” where x is a
+variable.</li>
+<li>clang does not support <tt class="docutils literal"><span class="pre">__builtin_apply</span></tt> and friends; this extension
+is extremely obscure and difficult to implement reliably.</li>
+</ul>
+</div>
+<div class="section" id="microsoft-extensions">
+<span id="c-ms"></span><h3><a class="toc-backref" href="#id51">Microsoft extensions</a><a class="headerlink" href="#microsoft-extensions" title="Permalink to this headline">¶</a></h3>
+<p>clang has support for many extensions from Microsoft Visual C++. To enable these
+extensions, use the <tt class="docutils literal"><span class="pre">-fms-extensions</span></tt> command-line option. This is the default
+for Windows targets. Clang does not implement every pragma or declspec provided
+by MSVC, but the popular ones, such as <tt class="docutils literal"><span class="pre">__declspec(dllexport)</span></tt> and <tt class="docutils literal"><span class="pre">#pragma</span>
+<span class="pre">comment(lib)</span></tt> are well supported.</p>
+<p>clang has a <tt class="docutils literal"><span class="pre">-fms-compatibility</span></tt> flag that makes clang accept enough
+invalid C++ to be able to parse most Microsoft headers. For example, it
+allows <a class="reference external" href="http://clang.llvm.org/compatibility.html#dep_lookup_bases">unqualified lookup of dependent base class members</a>, which is
+a common compatibility issue with clang. This flag is enabled by default
+for Windows targets.</p>
+<p><tt class="docutils literal"><span class="pre">-fdelayed-template-parsing</span></tt> lets clang delay parsing of function template
+definitions until the end of a translation unit. This flag is enabled by
+default for Windows targets.</p>
+<p>For compatibility with existing code that compiles with MSVC, clang defines the
+<tt class="docutils literal"><span class="pre">_MSC_VER</span></tt> and <tt class="docutils literal"><span class="pre">_MSC_FULL_VER</span></tt> macros. These default to the values of 1800
+and 180000000 respectively, making clang look like an early release of Visual
+C++ 2013. The <tt class="docutils literal"><span class="pre">-fms-compatibility-version=</span></tt> flag overrides these values. It
+accepts a dotted version tuple, such as 19.00.23506. Changing the MSVC
+compatibility version makes clang behave more like that version of MSVC. For
+example, <tt class="docutils literal"><span class="pre">-fms-compatibility-version=19</span></tt> will enable C++14 features and define
+<tt class="docutils literal"><span class="pre">char16_t</span></tt> and <tt class="docutils literal"><span class="pre">char32_t</span></tt> as builtin types.</p>
+</div>
+</div>
+<div class="section" id="cxx">
+<span id="id3"></span><h2><a class="toc-backref" href="#id52">C++ Language Features</a><a class="headerlink" href="#cxx" title="Permalink to this headline">¶</a></h2>
+<p>clang fully implements all of standard C++98 except for exported
+templates (which were removed in C++11), and all of standard C++11
+and the current draft standard for C++1y.</p>
+<div class="section" id="controlling-implementation-limits">
+<h3><a class="toc-backref" href="#id53">Controlling implementation limits</a><a class="headerlink" href="#controlling-implementation-limits" title="Permalink to this headline">¶</a></h3>
+<dl class="option">
+<dt id="cmdoption-fbracket-depth">
+<tt class="descname">-fbracket-depth</tt><tt class="descclassname">=N</tt><a class="headerlink" href="#cmdoption-fbracket-depth" title="Permalink to this definition">¶</a></dt>
+<dd><p>Sets the limit for nested parentheses, brackets, and braces to N. The
+default is 256.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fconstexpr-depth">
+<tt class="descname">-fconstexpr-depth</tt><tt class="descclassname">=N</tt><a class="headerlink" href="#cmdoption-fconstexpr-depth" title="Permalink to this definition">¶</a></dt>
+<dd><p>Sets the limit for recursive constexpr function invocations to N. The
+default is 512.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-ftemplate-depth">
+<tt class="descname">-ftemplate-depth</tt><tt class="descclassname">=N</tt><a class="headerlink" href="#cmdoption-ftemplate-depth" title="Permalink to this definition">¶</a></dt>
+<dd><p>Sets the limit for recursively nested template instantiations to N. The
+default is 256.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-foperator-arrow-depth">
+<tt class="descname">-foperator-arrow-depth</tt><tt class="descclassname">=N</tt><a class="headerlink" href="#cmdoption-foperator-arrow-depth" title="Permalink to this definition">¶</a></dt>
+<dd><p>Sets the limit for iterative calls to ‘operator->’ functions to N. The
+default is 256.</p>
+</dd></dl>
+
+</div>
+</div>
+<div class="section" id="objective-c-language-features">
+<span id="objc"></span><h2><a class="toc-backref" href="#id54">Objective-C Language Features</a><a class="headerlink" href="#objective-c-language-features" title="Permalink to this headline">¶</a></h2>
+</div>
+<div class="section" id="objcxx">
+<span id="id4"></span><h2><a class="toc-backref" href="#id55">Objective-C++ Language Features</a><a class="headerlink" href="#objcxx" title="Permalink to this headline">¶</a></h2>
+</div>
+<div class="section" id="openmp-features">
+<span id="openmp"></span><h2><a class="toc-backref" href="#id56">OpenMP Features</a><a class="headerlink" href="#openmp-features" title="Permalink to this headline">¶</a></h2>
+<p>Clang supports all OpenMP 3.1 directives and clauses. In addition, some
+features of OpenMP 4.0 are supported. For example, <tt class="docutils literal"><span class="pre">#pragma</span> <span class="pre">omp</span> <span class="pre">simd</span></tt>,
+<tt class="docutils literal"><span class="pre">#pragma</span> <span class="pre">omp</span> <span class="pre">for</span> <span class="pre">simd</span></tt>, <tt class="docutils literal"><span class="pre">#pragma</span> <span class="pre">omp</span> <span class="pre">parallel</span> <span class="pre">for</span> <span class="pre">simd</span></tt> directives, extended
+set of atomic constructs, <tt class="docutils literal"><span class="pre">proc_bind</span></tt> clause for all parallel-based
+directives, <tt class="docutils literal"><span class="pre">depend</span></tt> clause for <tt class="docutils literal"><span class="pre">#pragma</span> <span class="pre">omp</span> <span class="pre">task</span></tt> directive (except for
+array sections), <tt class="docutils literal"><span class="pre">#pragma</span> <span class="pre">omp</span> <span class="pre">cancel</span></tt> and <tt class="docutils literal"><span class="pre">#pragma</span> <span class="pre">omp</span> <span class="pre">cancellation</span> <span class="pre">point</span></tt>
+directives, and <tt class="docutils literal"><span class="pre">#pragma</span> <span class="pre">omp</span> <span class="pre">taskgroup</span></tt> directive.</p>
+<p>Use <cite>-fopenmp</cite> to enable OpenMP. Support for OpenMP can be disabled with
+<cite>-fno-openmp</cite>.</p>
+<div class="section" id="id5">
+<h3><a class="toc-backref" href="#id57">Controlling implementation limits</a><a class="headerlink" href="#id5" title="Permalink to this headline">¶</a></h3>
+<dl class="option">
+<dt id="cmdoption-fopenmp-use-tls">
+<tt class="descname">-fopenmp-use-tls</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-fopenmp-use-tls" title="Permalink to this definition">¶</a></dt>
+<dd><p>Controls code generation for OpenMP threadprivate variables. In presence of
+this option all threadprivate variables are generated the same way as thread
+local variables, using TLS support. If <cite>-fno-openmp-use-tls</cite>
+is provided or target does not support TLS, code generation for threadprivate
+variables relies on OpenMP runtime library.</p>
+</dd></dl>
+
+</div>
+</div>
+<div class="section" id="opencl-features">
+<span id="opencl"></span><h2><a class="toc-backref" href="#id58">OpenCL Features</a><a class="headerlink" href="#opencl-features" title="Permalink to this headline">¶</a></h2>
+<p>Clang can be used to compile OpenCL kernels for execution on a device
+(e.g. GPU). It is possible to compile the kernel into a binary (e.g. for AMD or
+Nvidia targets) that can be uploaded to run directly on a device (e.g. using
+<a class="reference external" href="https://www.khronos.org/registry/OpenCL/specs/opencl-1.1.pdf#111">clCreateProgramWithBinary</a>) or
+into generic bitcode files loadable into other toolchains.</p>
+<p>Compiling to a binary using the default target from the installation can be done
+as follows:</p>
+<blockquote>
+<div><div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> <span class="nb">echo</span> <span class="s2">"kernel void k(){}"</span> > test.cl
+<span class="gp">$</span> clang test.cl
+</pre></div>
+</div>
+</div></blockquote>
+<p>Compiling for a specific target can be done by specifying the triple corresponding
+to the target, for example:</p>
+<blockquote>
+<div><div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> clang -target nvptx64-unknown-unknown test.cl
+<span class="gp">$</span> clang -target amdgcn-amd-amdhsa-opencl test.cl
+</pre></div>
+</div>
+</div></blockquote>
+<p>Compiling to bitcode can be done as follows:</p>
+<blockquote>
+<div><div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> clang -c -emit-llvm test.cl
+</pre></div>
+</div>
+</div></blockquote>
+<p>This will produce a generic test.bc file that can be used in vendor toolchains
+to perform machine code generation.</p>
+<p>Clang currently supports OpenCL C language standards up to v2.0.</p>
+<div class="section" id="opencl-specific-options">
+<h3><a class="toc-backref" href="#id59">OpenCL Specific Options</a><a class="headerlink" href="#opencl-specific-options" title="Permalink to this headline">¶</a></h3>
+<p>Most of the OpenCL build options from <a class="reference external" href="https://www.khronos.org/registry/cl/specs/opencl-2.0.pdf#200">the specification v2.0 section 5.8.4</a> are available.</p>
+<p>Examples:</p>
+<blockquote>
+<div><div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> clang -cl-std<span class="o">=</span>CL2.0 -cl-single-precision-constant test.cl
+</pre></div>
+</div>
+</div></blockquote>
+<p>Some extra options are available to support special OpenCL features.</p>
+<dl class="option">
+<dt id="cmdoption-finclude-default-header">
+<tt class="descname">-finclude-default-header</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-finclude-default-header" title="Permalink to this definition">¶</a></dt>
+<dd></dd></dl>
+
+<p>Loads standard includes during compilations. By default OpenCL headers are not
+loaded and therefore standard library includes are not available. To load them
+automatically a flag has been added to the frontend (see also <a class="reference internal" href="#opencl-header"><em>the section
+on the OpenCL Header</em></a>):</p>
+<blockquote>
+<div><div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> clang -Xclang -finclude-default-header test.cl
+</pre></div>
+</div>
+</div></blockquote>
+<p>Alternatively <tt class="docutils literal"><span class="pre">-include</span></tt> or <tt class="docutils literal"><span class="pre">-I</span></tt> followed by the path to the header location
+can be given manually.</p>
+<blockquote>
+<div><div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> clang -I<path to clang>/lib/Headers/opencl-c.h test.cl
+</pre></div>
+</div>
+</div></blockquote>
+<p>In this case the kernel code should contain <tt class="docutils literal"><span class="pre">#include</span> <span class="pre"><opencl-c.h></span></tt> just as a
+regular C include.</p>
+<span class="target" id="opencl-cl-ext"></span><dl class="option">
+<dt id="cmdoption-cl-ext">
+<tt class="descname">-cl-ext</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-cl-ext" title="Permalink to this definition">¶</a></dt>
+<dd></dd></dl>
+
+<p>Disables support of OpenCL extensions. All OpenCL targets provide a list
+of extensions that they support. Clang allows to amend this using the <tt class="docutils literal"><span class="pre">-cl-ext</span></tt>
+flag with a comma-separated list of extensions prefixed with <tt class="docutils literal"><span class="pre">'+'</span></tt> or <tt class="docutils literal"><span class="pre">'-'</span></tt>.
+The syntax: <tt class="docutils literal"><span class="pre">-cl-ext=<(['-'|'+']<extension>[,])+></span></tt>, where extensions
+can be either one of <a class="reference external" href="https://www.khronos.org/registry/cl/sdk/2.0/docs/man/xhtml/EXTENSION.html">the OpenCL specification extensions</a>
+or any known vendor extension. Alternatively, <tt class="docutils literal"><span class="pre">'all'</span></tt> can be used to enable
+or disable all known extensions.
+Example disabling double support for the 64-bit SPIR target:</p>
+<blockquote>
+<div><div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> clang -cc1 -triple spir64-unknown-unknown -cl-ext<span class="o">=</span>-cl_khr_fp64 test.cl
+</pre></div>
+</div>
+</div></blockquote>
+<p>Enabling all extensions except double support in R600 AMD GPU can be done using:</p>
+<blockquote>
+<div><div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> clang -cc1 -triple r600-unknown-unknown -cl-ext<span class="o">=</span>-all,+cl_khr_fp16 test.cl
+</pre></div>
+</div>
+</div></blockquote>
+<span class="target" id="opencl-fake-address-space-map"></span><dl class="option">
+<dt id="cmdoption-ffake-address-space-map">
+<tt class="descname">-ffake-address-space-map</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-ffake-address-space-map" title="Permalink to this definition">¶</a></dt>
+<dd></dd></dl>
+
+<p>Overrides the target address space map with a fake map.
+This allows adding explicit address space IDs to the bitcode for non-segmented
+memory architectures that don’t have separate IDs for each of the OpenCL
+logical address spaces by default. Passing <tt class="docutils literal"><span class="pre">-ffake-address-space-map</span></tt> will
+add/override address spaces of the target compiled for with the following values:
+<tt class="docutils literal"><span class="pre">1-global</span></tt>, <tt class="docutils literal"><span class="pre">2-constant</span></tt>, <tt class="docutils literal"><span class="pre">3-local</span></tt>, <tt class="docutils literal"><span class="pre">4-generic</span></tt>. The private address
+space is represented by the absence of an address space attribute in the IR (see
+also <a class="reference internal" href="#opencl-addrsp"><em>the section on the address space attribute</em></a>).</p>
+<blockquote>
+<div><div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> clang -ffake-address-space-map test.cl
+</pre></div>
+</div>
+</div></blockquote>
+<p>Some other flags used for the compilation for C can also be passed while
+compiling for OpenCL, examples: <tt class="docutils literal"><span class="pre">-c</span></tt>, <tt class="docutils literal"><span class="pre">-O<1-4|s></span></tt>, <tt class="docutils literal"><span class="pre">-o</span></tt>, <tt class="docutils literal"><span class="pre">-emit-llvm</span></tt>, etc.</p>
+</div>
+<div class="section" id="opencl-targets">
+<h3><a class="toc-backref" href="#id60">OpenCL Targets</a><a class="headerlink" href="#opencl-targets" title="Permalink to this headline">¶</a></h3>
+<p>OpenCL targets are derived from the regular Clang target classes. The OpenCL
+specific parts of the target representation provide address space mapping as
+well as a set of supported extensions.</p>
+<div class="section" id="specific-targets">
+<h4><a class="toc-backref" href="#id61">Specific Targets</a><a class="headerlink" href="#specific-targets" title="Permalink to this headline">¶</a></h4>
+<p>There is a set of concrete HW architectures that OpenCL can be compiled for.</p>
+<ul>
+<li><p class="first">For AMD target:</p>
+<blockquote>
+<div><div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> clang -target amdgcn-amd-amdhsa-opencl test.cl
+</pre></div>
+</div>
+</div></blockquote>
+</li>
+<li><p class="first">For Nvidia architectures:</p>
+<blockquote>
+<div><div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> clang -target nvptx64-unknown-unknown test.cl
+</pre></div>
+</div>
+</div></blockquote>
+</li>
+</ul>
+</div>
+<div class="section" id="generic-targets">
+<h4><a class="toc-backref" href="#id62">Generic Targets</a><a class="headerlink" href="#generic-targets" title="Permalink to this headline">¶</a></h4>
+<ul>
+<li><p class="first">SPIR is available as a generic target to allow portable bitcode to be produced
+that can be used across GPU toolchains. The implementation follows <a class="reference external" href="https://www.khronos.org/spir">the SPIR
+specification</a>. There are two flavors
+available for 32 and 64 bits.</p>
+<blockquote>
+<div><div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> clang -target spir-unknown-unknown test.cl
+<span class="gp">$</span> clang -target spir64-unknown-unknown test.cl
+</pre></div>
+</div>
+</div></blockquote>
+<p>All known OpenCL extensions are supported in the SPIR targets. Clang will
+generate SPIR v1.2 compatible IR for OpenCL versions up to 2.0 and SPIR v2.0
+for OpenCL v2.0.</p>
+</li>
+<li><p class="first">x86 is used by some implementations that are x86 compatible and currently
+remains for backwards compatibility (with older implementations prior to
+SPIR target support). For “non-SPMD” targets which cannot spawn multiple
+work-items on the fly using hardware, which covers practically all non-GPU
+devices such as CPUs and DSPs, additional processing is needed for the kernels
+to support multiple work-item execution. For this, a 3rd party toolchain,
+such as for example <a class="reference external" href="http://portablecl.org/">POCL</a>, can be used.</p>
+<p>This target does not support multiple memory segments and, therefore, the fake
+address space map can be added using the <a class="reference internal" href="#opencl-fake-address-space-map"><em>-ffake-address-space-map</em></a> flag.</p>
+</li>
+</ul>
+</div>
+</div>
+<div class="section" id="opencl-header">
+<span id="id6"></span><h3><a class="toc-backref" href="#id63">OpenCL Header</a><a class="headerlink" href="#opencl-header" title="Permalink to this headline">¶</a></h3>
+<p>By default Clang will not include standard headers and therefore OpenCL builtin
+functions and some types (i.e. vectors) are unknown. The default CL header is,
+however, provided in the Clang installation and can be enabled by passing the
+<tt class="docutils literal"><span class="pre">-finclude-default-header</span></tt> flag to the Clang frontend.</p>
+<blockquote>
+<div><div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> <span class="nb">echo</span> <span class="s2">"bool is_wg_uniform(int i){return get_enqueued_local_size(i)==get_local_size(i);}"</span> > test.cl
+<span class="gp">$</span> clang -Xclang -finclude-default-header -cl-std<span class="o">=</span>CL2.0 test.cl
+</pre></div>
+</div>
+</div></blockquote>
+<p>Because the header is very large and long to parse, PCH (<a class="reference internal" href="PCHInternals.html"><em>Precompiled Header and Modules Internals</em></a>)
+and modules (<a class="reference internal" href="Modules.html"><em>Modules</em></a>) are used internally to improve the compilation
+speed.</p>
+<p>To enable modules for OpenCL:</p>
+<blockquote>
+<div><div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> clang -target spir-unknown-unknown -c -emit-llvm -Xclang -finclude-default-header -fmodules -fimplicit-module-maps -fmodules-cache-path<span class="o">=</span><path to the generated module> test.cl
+</pre></div>
+</div>
+</div></blockquote>
+</div>
+<div class="section" id="opencl-extensions">
+<h3><a class="toc-backref" href="#id64">OpenCL Extensions</a><a class="headerlink" href="#opencl-extensions" title="Permalink to this headline">¶</a></h3>
+<p>All of the <tt class="docutils literal"><span class="pre">cl_khr_*</span></tt> extensions from <a class="reference external" href="https://www.khronos.org/registry/OpenCL/sdk/2.0/docs/man/xhtml/EXTENSION.html">the official OpenCL specification</a>
+up to and including version 2.0 are available and set per target depending on the
+support available in the specific architecture.</p>
+<p>It is possible to alter the default extensions setting per target using
+<tt class="docutils literal"><span class="pre">-cl-ext</span></tt> flag. (See <a class="reference internal" href="#opencl-cl-ext"><em>flags description</em></a> for more details).</p>
+<p>Vendor extensions can be added flexibly by declaring the list of types and
+functions associated with each extensions enclosed within the following
+compiler pragma directives:</p>
+<blockquote>
+<div><div class="highlight-c"><div class="highlight"><pre><span class="cp">#pragma OPENCL EXTENSION the_new_extension_name : begin</span>
+<span class="c1">// declare types and functions associated with the extension here</span>
+<span class="cp">#pragma OPENCL EXTENSION the_new_extension_name : end</span>
+</pre></div>
+</div>
+</div></blockquote>
+<p>For example, parsing the following code adds <tt class="docutils literal"><span class="pre">my_t</span></tt> type and <tt class="docutils literal"><span class="pre">my_func</span></tt>
+function to the custom <tt class="docutils literal"><span class="pre">my_ext</span></tt> extension.</p>
+<blockquote>
+<div><div class="highlight-c"><div class="highlight"><pre><span class="cp">#pragma OPENCL EXTENSION my_ext : begin</span>
+<span class="k">typedef</span> <span class="k">struct</span><span class="p">{</span>
+ <span class="kt">int</span> <span class="n">a</span><span class="p">;</span>
+<span class="p">}</span><span class="kt">my_t</span><span class="p">;</span>
+<span class="kt">void</span> <span class="nf">my_func</span><span class="p">(</span><span class="kt">my_t</span><span class="p">);</span>
+<span class="cp">#pragma OPENCL EXTENSION my_ext : end</span>
+</pre></div>
+</div>
+</div></blockquote>
+<p>Declaring the same types in different vendor extensions is disallowed.</p>
+</div>
+<div class="section" id="opencl-metadata">
+<h3><a class="toc-backref" href="#id65">OpenCL Metadata</a><a class="headerlink" href="#opencl-metadata" title="Permalink to this headline">¶</a></h3>
+<p>Clang uses metadata to provide additional OpenCL semantics in IR needed for
+backends and OpenCL runtime.</p>
+<p>Each kernel will have function metadata attached to it, specifying the arguments.
+Kernel argument metadata is used to provide source level information for querying
+at runtime, for example using the <a class="reference external" href="https://www.khronos.org/registry/OpenCL/specs/opencl-1.2.pdf#167">clGetKernelArgInfo</a>
+call.</p>
+<p>Note that <tt class="docutils literal"><span class="pre">-cl-kernel-arg-info</span></tt> enables more information about the original CL
+code to be added e.g. kernel parameter names will appear in the OpenCL metadata
+along with other information.</p>
+<p>The IDs used to encode the OpenCL’s logical address spaces in the argument info
+metadata follows the SPIR address space mapping as defined in the SPIR
+specification <a class="reference external" href="https://www.khronos.org/registry/spir/specs/spir_spec-2.0.pdf#18">section 2.2</a></p>
+</div>
+<div class="section" id="opencl-specific-attributes">
+<h3><a class="toc-backref" href="#id66">OpenCL-Specific Attributes</a><a class="headerlink" href="#opencl-specific-attributes" title="Permalink to this headline">¶</a></h3>
+<p>OpenCL support in Clang contains a set of attribute taken directly from the
+specification as well as additional attributes.</p>
+<p>See also <a class="reference internal" href="AttributeReference.html"><em>Attributes in Clang</em></a>.</p>
+<div class="section" id="nosvm">
+<h4><a class="toc-backref" href="#id67">nosvm</a><a class="headerlink" href="#nosvm" title="Permalink to this headline">¶</a></h4>
+<p>Clang supports this attribute to comply to OpenCL v2.0 conformance, but it
+does not have any effect on the IR. For more details reffer to the specification
+<a class="reference external" href="https://www.khronos.org/registry/cl/specs/opencl-2.0-openclc.pdf#49">section 6.7.2</a></p>
+</div>
+<div class="section" id="opencl-unroll-hint">
+<h4><a class="toc-backref" href="#id68">opencl_unroll_hint</a><a class="headerlink" href="#opencl-unroll-hint" title="Permalink to this headline">¶</a></h4>
+<p>The implementation of this feature mirrors the unroll hint for C.
+More details on the syntax can be found in the specification
+<a class="reference external" href="https://www.khronos.org/registry/cl/specs/opencl-2.0-openclc.pdf#61">section 6.11.5</a></p>
+</div>
+<div class="section" id="convergent">
+<h4><a class="toc-backref" href="#id69">convergent</a><a class="headerlink" href="#convergent" title="Permalink to this headline">¶</a></h4>
+<p>To make sure no invalid optimizations occur for single program multiple data
+(SPMD) / single instruction multiple thread (SIMT) Clang provides attributes that
+can be used for special functions that have cross work item semantics.
+An example is the subgroup operations such as <a class="reference external" href="https://www.khronos.org/registry/cl/extensions/intel/cl_intel_subgroups.txt">intel_sub_group_shuffle</a></p>
+<blockquote>
+<div><div class="highlight-c"><div class="highlight"><pre>// Define custom my_sub_group_shuffle(data, c)
+// that makes use of intel_sub_group_shuffle
+r1 = â¦
+if (r0) r1 = computeA();
+// Shuffle data from r1 into r3
+// of threads id r2.
+r3 = my_sub_group_shuffle(r1, r2);
+if (r0) r3 = computeB();
+</pre></div>
+</div>
+</div></blockquote>
+<p>with non-SPMD semantics this is optimized to the following equivalent code:</p>
+<blockquote>
+<div><div class="highlight-c"><div class="highlight"><pre>r1 = â¦
+if (!r0)
+ // Incorrect functionality! The data in r1
+ // have not been computed by all threads yet.
+ r3 = my_sub_group_shuffle(r1, r2);
+else {
+ r1 = computeA();
+ r3 = my_sub_group_shuffle(r1, r2);
+ r3 = computeB();
+}
+</pre></div>
+</div>
+</div></blockquote>
+<p>Declaring the function <tt class="docutils literal"><span class="pre">my_sub_group_shuffle</span></tt> with the convergent attribute
+would prevent this:</p>
+<blockquote>
+<div><div class="highlight-c"><div class="highlight"><pre><span class="n">my_sub_group_shuffle</span><span class="p">()</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">convergent</span><span class="p">));</span>
+</pre></div>
+</div>
+</div></blockquote>
+<p>Using <tt class="docutils literal"><span class="pre">convergent</span></tt> guarantees correct execution by keeping CFG equivalence
+wrt operations marked as <tt class="docutils literal"><span class="pre">convergent</span></tt>. CFG <tt class="docutils literal"><span class="pre">G´</span></tt> is equivalent to <tt class="docutils literal"><span class="pre">G</span></tt> wrt
+node <tt class="docutils literal"><span class="pre">Ni</span></tt> : <tt class="docutils literal"><span class="pre">iff</span> <span class="pre">â</span> <span class="pre">Nj</span> <span class="pre">(iâ j)</span></tt> domination and post-domination relations with
+respect to <tt class="docutils literal"><span class="pre">Ni</span></tt> remain the same in both <tt class="docutils literal"><span class="pre">G</span></tt> and <tt class="docutils literal"><span class="pre">G´</span></tt>.</p>
+</div>
+<div class="section" id="noduplicate">
+<h4><a class="toc-backref" href="#id70">noduplicate</a><a class="headerlink" href="#noduplicate" title="Permalink to this headline">¶</a></h4>
+<p><tt class="docutils literal"><span class="pre">noduplicate</span></tt> is more restrictive with respect to optimizations than
+<tt class="docutils literal"><span class="pre">convergent</span></tt> because a convergent function only preserves CFG equivalence.
+This allows some optimizations to happen as long as the control flow remains
+unmodified.</p>
+<blockquote>
+<div><div class="highlight-c"><div class="highlight"><pre><span class="k">for</span> <span class="p">(</span><span class="kt">int</span> <span class="n">i</span><span class="o">=</span><span class="mi">0</span><span class="p">;</span> <span class="n">i</span><span class="o"><</span><span class="mi">4</span><span class="p">;</span> <span class="n">i</span><span class="o">++</span><span class="p">)</span>
+ <span class="n">my_sub_group_shuffle</span><span class="p">()</span>
+</pre></div>
+</div>
+</div></blockquote>
+<p>can be modified to:</p>
+<blockquote>
+<div><div class="highlight-c"><div class="highlight"><pre><span class="n">my_sub_group_shuffle</span><span class="p">();</span>
+<span class="n">my_sub_group_shuffle</span><span class="p">();</span>
+<span class="n">my_sub_group_shuffle</span><span class="p">();</span>
+<span class="n">my_sub_group_shuffle</span><span class="p">();</span>
+</pre></div>
+</div>
+</div></blockquote>
+<p>while using <tt class="docutils literal"><span class="pre">noduplicate</span></tt> would disallow this. Also <tt class="docutils literal"><span class="pre">noduplicate</span></tt> doesn’t
+have the same safe semantics of CFG as <tt class="docutils literal"><span class="pre">convergent</span></tt> and can cause changes in
+CFG that modify semantics of the original program.</p>
+<p><tt class="docutils literal"><span class="pre">noduplicate</span></tt> is kept for backwards compatibility only and it considered to be
+deprecated for future uses.</p>
+</div>
+<div class="section" id="address-space">
+<span id="opencl-addrsp"></span><h4><a class="toc-backref" href="#id71">address_space</a><a class="headerlink" href="#address-space" title="Permalink to this headline">¶</a></h4>
+<p>Clang has arbitrary address space support using the <tt class="docutils literal"><span class="pre">address_space(N)</span></tt>
+attribute, where <tt class="docutils literal"><span class="pre">N</span></tt> is an integer number in the range <tt class="docutils literal"><span class="pre">0</span></tt> to <tt class="docutils literal"><span class="pre">16777215</span></tt>
+(<tt class="docutils literal"><span class="pre">0xffffffu</span></tt>).</p>
+<p>An OpenCL implementation provides a list of standard address spaces using
+keywords: <tt class="docutils literal"><span class="pre">private</span></tt>, <tt class="docutils literal"><span class="pre">local</span></tt>, <tt class="docutils literal"><span class="pre">global</span></tt>, and <tt class="docutils literal"><span class="pre">generic</span></tt>. In the AST and
+in the IR local, global, or generic will be represented by the address space
+attribute with the corresponding unique number. Note that private does not have
+any corresponding attribute added and, therefore, is represented by the absence
+of an address space number. The specific IDs for an address space do not have to
+match between the AST and the IR. Typically in the AST address space numbers
+represent logical segments while in the IR they represent physical segments.
+Therefore, machines with flat memory segments can map all AST address space
+numbers to the same physical segment ID or skip address space attribute
+completely while generating the IR. However, if the address space information
+is needed by the IR passes e.g. to improve alias analysis, it is recommended
+to keep it and only lower to reflect physical memory segments in the late
+machine passes.</p>
+</div>
+</div>
+<div class="section" id="opencl-builtins">
+<h3><a class="toc-backref" href="#id72">OpenCL builtins</a><a class="headerlink" href="#opencl-builtins" title="Permalink to this headline">¶</a></h3>
+<p>There are some standard OpenCL functions that are implemented as Clang builtins:</p>
+<ul class="simple">
+<li>All pipe functions from <a class="reference external" href="https://www.khronos.org/registry/cl/specs/opencl-2.0-openclc.pdf#160">section 6.13.16.2/6.13.16.3</a> of
+the OpenCL v2.0 kernel language specification. `</li>
+<li>Address space qualifier conversion functions <tt class="docutils literal"><span class="pre">to_global</span></tt>/<tt class="docutils literal"><span class="pre">to_local</span></tt>/<tt class="docutils literal"><span class="pre">to_private</span></tt>
+from <a class="reference external" href="https://www.khronos.org/registry/cl/specs/opencl-2.0-openclc.pdf#101">section 6.13.9</a>.</li>
+<li>All the <tt class="docutils literal"><span class="pre">enqueue_kernel</span></tt> functions from <a class="reference external" href="https://www.khronos.org/registry/cl/specs/opencl-2.0-openclc.pdf#164">section 6.13.17.1</a> and
+enqueue query functions from <a class="reference external" href="https://www.khronos.org/registry/cl/specs/opencl-2.0-openclc.pdf#171">section 6.13.17.5</a>.</li>
+</ul>
+</div>
+</div>
+<div class="section" id="target-specific-features-and-limitations">
+<span id="target-features"></span><h2><a class="toc-backref" href="#id73">Target-Specific Features and Limitations</a><a class="headerlink" href="#target-specific-features-and-limitations" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="cpu-architectures-features-and-limitations">
+<h3><a class="toc-backref" href="#id74">CPU Architectures Features and Limitations</a><a class="headerlink" href="#cpu-architectures-features-and-limitations" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="x86">
+<h4><a class="toc-backref" href="#id75">X86</a><a class="headerlink" href="#x86" title="Permalink to this headline">¶</a></h4>
+<p>The support for X86 (both 32-bit and 64-bit) is considered stable on
+Darwin (Mac OS X), Linux, FreeBSD, and Dragonfly BSD: it has been tested
+to correctly compile many large C, C++, Objective-C, and Objective-C++
+codebases.</p>
+<p>On <tt class="docutils literal"><span class="pre">x86_64-mingw32</span></tt>, passing i128(by value) is incompatible with the
+Microsoft x64 calling convention. You might need to tweak
+<tt class="docutils literal"><span class="pre">WinX86_64ABIInfo::classify()</span></tt> in lib/CodeGen/TargetInfo.cpp.</p>
+<p>For the X86 target, clang supports the <cite>-m16</cite> command line
+argument which enables 16-bit code output. This is broadly similar to
+using <tt class="docutils literal"><span class="pre">asm(".code16gcc")</span></tt> with the GNU toolchain. The generated code
+and the ABI remains 32-bit but the assembler emits instructions
+appropriate for a CPU running in 16-bit mode, with address-size and
+operand-size prefixes to enable 32-bit addressing and operations.</p>
+</div>
+<div class="section" id="arm">
+<h4><a class="toc-backref" href="#id76">ARM</a><a class="headerlink" href="#arm" title="Permalink to this headline">¶</a></h4>
+<p>The support for ARM (specifically ARMv6 and ARMv7) is considered stable
+on Darwin (iOS): it has been tested to correctly compile many large C,
+C++, Objective-C, and Objective-C++ codebases. Clang only supports a
+limited number of ARM architectures. It does not yet fully support
+ARMv5, for example.</p>
+</div>
+<div class="section" id="powerpc">
+<h4><a class="toc-backref" href="#id77">PowerPC</a><a class="headerlink" href="#powerpc" title="Permalink to this headline">¶</a></h4>
+<p>The support for PowerPC (especially PowerPC64) is considered stable
+on Linux and FreeBSD: it has been tested to correctly compile many
+large C and C++ codebases. PowerPC (32bit) is still missing certain
+features (e.g. PIC code on ELF platforms).</p>
+</div>
+<div class="section" id="other-platforms">
+<h4><a class="toc-backref" href="#id78">Other platforms</a><a class="headerlink" href="#other-platforms" title="Permalink to this headline">¶</a></h4>
+<p>clang currently contains some support for other architectures (e.g. Sparc);
+however, significant pieces of code generation are still missing, and they
+haven’t undergone significant testing.</p>
+<p>clang contains limited support for the MSP430 embedded processor, but
+both the clang support and the LLVM backend support are highly
+experimental.</p>
+<p>Other platforms are completely unsupported at the moment. Adding the
+minimal support needed for parsing and semantic analysis on a new
+platform is quite easy; see <tt class="docutils literal"><span class="pre">lib/Basic/Targets.cpp</span></tt> in the clang source
+tree. This level of support is also sufficient for conversion to LLVM IR
+for simple programs. Proper support for conversion to LLVM IR requires
+adding code to <tt class="docutils literal"><span class="pre">lib/CodeGen/CGCall.cpp</span></tt> at the moment; this is likely to
+change soon, though. Generating assembly requires a suitable LLVM
+backend.</p>
+</div>
+</div>
+<div class="section" id="operating-system-features-and-limitations">
+<h3><a class="toc-backref" href="#id79">Operating System Features and Limitations</a><a class="headerlink" href="#operating-system-features-and-limitations" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="darwin-mac-os-x">
+<h4><a class="toc-backref" href="#id80">Darwin (Mac OS X)</a><a class="headerlink" href="#darwin-mac-os-x" title="Permalink to this headline">¶</a></h4>
+<p>Thread Sanitizer is not supported.</p>
+</div>
+<div class="section" id="windows">
+<h4><a class="toc-backref" href="#id81">Windows</a><a class="headerlink" href="#windows" title="Permalink to this headline">¶</a></h4>
+<p>Clang has experimental support for targeting “Cygming” (Cygwin / MinGW)
+platforms.</p>
+<p>See also <a class="reference internal" href="#c-ms"><em>Microsoft Extensions</em></a>.</p>
+<div class="section" id="cygwin">
+<h5><a class="toc-backref" href="#id82">Cygwin</a><a class="headerlink" href="#cygwin" title="Permalink to this headline">¶</a></h5>
+<p>Clang works on Cygwin-1.7.</p>
+</div>
+<div class="section" id="mingw32">
+<h5><a class="toc-backref" href="#id83">MinGW32</a><a class="headerlink" href="#mingw32" title="Permalink to this headline">¶</a></h5>
+<p>Clang works on some mingw32 distributions. Clang assumes directories as
+below;</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">C:/mingw/include</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">C:/mingw/lib</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">C:/mingw/lib/gcc/mingw32/4.[3-5].0/include/c++</span></tt></li>
+</ul>
+<p>On MSYS, a few tests might fail.</p>
+</div>
+<div class="section" id="mingw-w64">
+<h5><a class="toc-backref" href="#id84">MinGW-w64</a><a class="headerlink" href="#mingw-w64" title="Permalink to this headline">¶</a></h5>
+<p>For 32-bit (i686-w64-mingw32), and 64-bit (x86_64-w64-mingw32), Clang
+assumes as below;</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">GCC</span> <span class="pre">versions</span> <span class="pre">4.5.0</span> <span class="pre">to</span> <span class="pre">4.5.3,</span> <span class="pre">4.6.0</span> <span class="pre">to</span> <span class="pre">4.6.2,</span> <span class="pre">or</span> <span class="pre">4.7.0</span> <span class="pre">(for</span> <span class="pre">the</span> <span class="pre">C++</span> <span class="pre">header</span> <span class="pre">search</span> <span class="pre">path)</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">some_directory/bin/gcc.exe</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">some_directory/bin/clang.exe</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">some_directory/bin/clang++.exe</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">some_directory/bin/../include/c++/GCC_version</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">some_directory/bin/../include/c++/GCC_version/x86_64-w64-mingw32</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">some_directory/bin/../include/c++/GCC_version/i686-w64-mingw32</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">some_directory/bin/../include/c++/GCC_version/backward</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">some_directory/bin/../x86_64-w64-mingw32/include</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">some_directory/bin/../i686-w64-mingw32/include</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">some_directory/bin/../include</span></tt></li>
+</ul>
+<p>This directory layout is standard for any toolchain you will find on the
+official <a class="reference external" href="http://mingw-w64.sourceforge.net">MinGW-w64 website</a>.</p>
+<p>Clang expects the GCC executable “gcc.exe” compiled for
+<tt class="docutils literal"><span class="pre">i686-w64-mingw32</span></tt> (or <tt class="docutils literal"><span class="pre">x86_64-w64-mingw32</span></tt>) to be present on PATH.</p>
+<p><a class="reference external" href="http://llvm.org/bugs/show_bug.cgi?id=9072">Some tests might fail</a> on
+<tt class="docutils literal"><span class="pre">x86_64-w64-mingw32</span></tt>.</p>
+</div>
+</div>
+</div>
+</div>
+<div class="section" id="clang-cl">
+<span id="id7"></span><h2><a class="toc-backref" href="#id85">clang-cl</a><a class="headerlink" href="#clang-cl" title="Permalink to this headline">¶</a></h2>
+<p>clang-cl is an alternative command-line interface to Clang, designed for
+compatibility with the Visual C++ compiler, cl.exe.</p>
+<p>To enable clang-cl to find system headers, libraries, and the linker when run
+from the command-line, it should be executed inside a Visual Studio Native Tools
+Command Prompt or a regular Command Prompt where the environment has been set
+up using e.g. <a class="reference external" href="http://msdn.microsoft.com/en-us/library/f2ccy3wt.aspx">vcvars32.bat</a>.</p>
+<p>clang-cl can also be used from inside Visual Studio by using an LLVM Platform
+Toolset.</p>
+<div class="section" id="id8">
+<h3><a class="toc-backref" href="#id86">Command-Line Options</a><a class="headerlink" href="#id8" title="Permalink to this headline">¶</a></h3>
+<p>To be compatible with cl.exe, clang-cl supports most of the same command-line
+options. Those options can start with either <tt class="docutils literal"><span class="pre">/</span></tt> or <tt class="docutils literal"><span class="pre">-</span></tt>. It also supports
+some of Clang’s core options, such as the <tt class="docutils literal"><span class="pre">-W</span></tt> options.</p>
+<p>Options that are known to clang-cl, but not currently supported, are ignored
+with a warning. For example:</p>
+<blockquote>
+<div><div class="highlight-python"><div class="highlight"><pre>clang-cl.exe: warning: argument unused during compilation: '/AI'
+</pre></div>
+</div>
+</div></blockquote>
+<p>To suppress warnings about unused arguments, use the <tt class="docutils literal"><span class="pre">-Qunused-arguments</span></tt> option.</p>
+<p>Options that are not known to clang-cl will be ignored by default. Use the
+<tt class="docutils literal"><span class="pre">-Werror=unknown-argument</span></tt> option in order to treat them as errors. If these
+options are spelled with a leading <tt class="docutils literal"><span class="pre">/</span></tt>, they will be mistaken for a filename:</p>
+<blockquote>
+<div><div class="highlight-python"><div class="highlight"><pre>clang-cl.exe: error: no such file or directory: '/foobar'
+</pre></div>
+</div>
+</div></blockquote>
+<p>Please <a class="reference external" href="http://llvm.org/bugs/enter_bug.cgi?product=clang&component=Driver">file a bug</a>
+for any valid cl.exe flags that clang-cl does not understand.</p>
+<p>Execute <tt class="docutils literal"><span class="pre">clang-cl</span> <span class="pre">/?</span></tt> to see a list of supported options:</p>
+<blockquote>
+<div><div class="highlight-python"><div class="highlight"><pre>CL.EXE COMPATIBILITY OPTIONS:
+ /? Display available options
+ /arch:<value> Set architecture for code generation
+ /Brepro- Emit an object file which cannot be reproduced over time
+ /Brepro Emit an object file which can be reproduced over time
+ /C Don't discard comments when preprocessing
+ /c Compile only
+ /D <macro[=value]> Define macro
+ /EH<value> Exception handling model
+ /EP Disable linemarker output and preprocess to stdout
+ /execution-charset:<value>
+ Runtime encoding, supports only UTF-8
+ /E Preprocess to stdout
+ /fallback Fall back to cl.exe if clang-cl fails to compile
+ /FA Output assembly code file during compilation
+ /Fa<file or directory> Output assembly code to this file during compilation (with /FA)
+ /Fe<file or directory> Set output executable file or directory (ends in / or \)
+ /FI <value> Include file before parsing
+ /Fi<file> Set preprocess output file name (with /P)
+ /Fo<file or directory> Set output object file, or directory (ends in / or \) (with /c)
+ /fp:except-
+ /fp:except
+ /fp:fast
+ /fp:precise
+ /fp:strict
+ /Fp<filename> Set pch filename (with /Yc and /Yu)
+ /GA Assume thread-local variables are defined in the executable
+ /Gd Set __cdecl as a default calling convention
+ /GF- Disable string pooling
+ /GR- Disable emission of RTTI data
+ /GR Enable emission of RTTI data
+ /Gr Set __fastcall as a default calling convention
+ /GS- Disable buffer security check
+ /GS Enable buffer security check
+ /Gs<value> Set stack probe size
+ /Gv Set __vectorcall as a default calling convention
+ /Gw- Don't put each data item in its own section
+ /Gw Put each data item in its own section
+ /GX- Enable exception handling
+ /GX Enable exception handling
+ /Gy- Don't put each function in its own section
+ /Gy Put each function in its own section
+ /Gz Set __stdcall as a default calling convention
+ /help Display available options
+ /imsvc <dir> Add directory to system include search path, as if part of %INCLUDE%
+ /I <dir> Add directory to include search path
+ /J Make char type unsigned
+ /LDd Create debug DLL
+ /LD Create DLL
+ /link <options> Forward options to the linker
+ /MDd Use DLL debug run-time
+ /MD Use DLL run-time
+ /MTd Use static debug run-time
+ /MT Use static run-time
+ /Od Disable optimization
+ /Oi- Disable use of builtin functions
+ /Oi Enable use of builtin functions
+ /Os Optimize for size
+ /Ot Optimize for speed
+ /O<value> Optimization level
+ /o <file or directory> Set output file or directory (ends in / or \)
+ /P Preprocess to file
+ /Qvec- Disable the loop vectorization passes
+ /Qvec Enable the loop vectorization passes
+ /showIncludes Print info about included files to stderr
+ /source-charset:<value> Source encoding, supports only UTF-8
+ /std:<value> Language standard to compile for
+ /TC Treat all source files as C
+ /Tc <filename> Specify a C source file
+ /TP Treat all source files as C++
+ /Tp <filename> Specify a C++ source file
+ /utf-8 Set source and runtime encoding to UTF-8 (default)
+ /U <macro> Undefine macro
+ /vd<value> Control vtordisp placement
+ /vmb Use a best-case representation method for member pointers
+ /vmg Use a most-general representation for member pointers
+ /vmm Set the default most-general representation to multiple inheritance
+ /vms Set the default most-general representation to single inheritance
+ /vmv Set the default most-general representation to virtual inheritance
+ /volatile:iso Volatile loads and stores have standard semantics
+ /volatile:ms Volatile loads and stores have acquire and release semantics
+ /W0 Disable all warnings
+ /W1 Enable -Wall
+ /W2 Enable -Wall
+ /W3 Enable -Wall
+ /W4 Enable -Wall and -Wextra
+ /Wall Enable -Wall and -Wextra
+ /WX- Do not treat warnings as errors
+ /WX Treat warnings as errors
+ /w Disable all warnings
+ /Y- Disable precompiled headers, overrides /Yc and /Yu
+ /Yc<filename> Generate a pch file for all code up to and including <filename>
+ /Yu<filename> Load a pch file and use it instead of all code up to and including <filename>
+ /Z7 Enable CodeView debug information in object files
+ /Zc:sizedDealloc- Disable C++14 sized global deallocation functions
+ /Zc:sizedDealloc Enable C++14 sized global deallocation functions
+ /Zc:strictStrings Treat string literals as const
+ /Zc:threadSafeInit- Disable thread-safe initialization of static variables
+ /Zc:threadSafeInit Enable thread-safe initialization of static variables
+ /Zc:trigraphs- Disable trigraphs (default)
+ /Zc:trigraphs Enable trigraphs
+ /Zd Emit debug line number tables only
+ /Zi Alias for /Z7. Does not produce PDBs.
+ /Zl Don't mention any default libraries in the object file
+ /Zp Set the default maximum struct packing alignment to 1
+ /Zp<value> Specify the default maximum struct packing alignment
+ /Zs Syntax-check only
+
+OPTIONS:
+ -### Print (but do not run) the commands to run for this compilation
+ --analyze Run the static analyzer
+ -fansi-escape-codes Use ANSI escape codes for diagnostics
+ -fcolor-diagnostics Use colors in diagnostics
+ -fdelayed-template-parsing
+ Parse templated function definitions at the end of the translation unit
+ -fdiagnostics-absolute-paths
+ Print absolute paths in diagnostics
+ -fdiagnostics-parseable-fixits
+ Print fix-its in machine parseable form
+ -flto Enable LTO in 'full' mode
+ -fms-compatibility-version=<value>
+ Dot-separated value representing the Microsoft compiler version
+ number to report in _MSC_VER (0 = don't define it (default))
+ -fms-compatibility Enable full Microsoft Visual C++ compatibility
+ -fms-extensions Accept some non-standard constructs supported by the Microsoft compiler
+ -fmsc-version=<value> Microsoft compiler version number to report in _MSC_VER
+ (0 = don't define it (default))
+ -fno-delayed-template-parsing
+ Disable delayed template parsing
+ -fno-sanitize-coverage=<value>
+ Disable specified features of coverage instrumentation for Sanitizers
+ -fno-sanitize-recover=<value>
+ Disable recovery for specified sanitizers
+ -fno-sanitize-trap=<value>
+ Disable trapping for specified sanitizers
+ -fno-standalone-debug Limit debug information produced to reduce size of debug binary
+ -fprofile-instr-generate=<file>
+ Generate instrumented code to collect execution counts into <file>
+ (overridden by LLVM_PROFILE_FILE env var)
+ -fprofile-instr-generate
+ Generate instrumented code to collect execution counts into default.profraw file
+ (overridden by '=' form of option or LLVM_PROFILE_FILE env var)
+ -fprofile-instr-use=<value>
+ Use instrumentation data for profile-guided optimization
+ -fsanitize-blacklist=<value>
+ Path to blacklist file for sanitizers
+ -fsanitize-coverage=<value>
+ Specify the type of coverage instrumentation for Sanitizers
+ -fsanitize-recover=<value>
+ Enable recovery for specified sanitizers
+ -fsanitize-trap=<value> Enable trapping for specified sanitizers
+ -fsanitize=<check> Turn on runtime checks for various forms of undefined or suspicious
+ behavior. See user manual for available checks
+ -fstandalone-debug Emit full debug info for all types used by the program
+ -gcodeview Generate CodeView debug information
+ -gline-tables-only Emit debug line number tables only
+ -miamcu Use Intel MCU ABI
+ -mllvm <value> Additional arguments to forward to LLVM's option processing
+ -Qunused-arguments Don't emit warning for unused driver arguments
+ -R<remark> Enable the specified remark
+ --target=<value> Generate code for the given target
+ -v Show commands to run and use verbose output
+ -W<warning> Enable the specified warning
+ -Xclang <arg> Pass <arg> to the clang compiler
+</pre></div>
+</div>
+</div></blockquote>
+<div class="section" id="the-fallback-option">
+<h4><a class="toc-backref" href="#id87">The /fallback Option</a><a class="headerlink" href="#the-fallback-option" title="Permalink to this headline">¶</a></h4>
+<p>When clang-cl is run with the <tt class="docutils literal"><span class="pre">/fallback</span></tt> option, it will first try to
+compile files itself. For any file that it fails to compile, it will fall back
+and try to compile the file by invoking cl.exe.</p>
+<p>This option is intended to be used as a temporary means to build projects where
+clang-cl cannot successfully compile all the files. clang-cl may fail to compile
+a file either because it cannot generate code for some C++ feature, or because
+it cannot parse some Microsoft language extension.</p>
+</div>
+</div>
+</div>
+</div>
+
+
+ </div>
+ <div class="bottomnav">
+
+ <p>
+ « <a href="ReleaseNotes.html">Clang 4.0.0 Release Notes</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="Toolchain.html">Assembling a Complete Toolchain</a> »
+ </p>
+
+ </div>
+
+ <div class="footer">
+ © Copyright 2007-2017, The Clang Team.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/4.0.0/tools/clang/docs/_images/DriverArchitecture.png
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/4.0.0/tools/clang/docs/_images/DriverArchitecture.png?rev=297634&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/4.0.0/tools/clang/docs/_images/DriverArchitecture.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: www-releases/trunk/4.0.0/tools/clang/docs/_images/PCHLayout.png
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/4.0.0/tools/clang/docs/_images/PCHLayout.png?rev=297634&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/4.0.0/tools/clang/docs/_images/PCHLayout.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: www-releases/trunk/4.0.0/tools/clang/docs/_sources/AddressSanitizer.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/4.0.0/tools/clang/docs/_sources/AddressSanitizer.txt?rev=297634&view=auto
==============================================================================
--- www-releases/trunk/4.0.0/tools/clang/docs/_sources/AddressSanitizer.txt (added)
+++ www-releases/trunk/4.0.0/tools/clang/docs/_sources/AddressSanitizer.txt Mon Mar 13 11:30:12 2017
@@ -0,0 +1,288 @@
+================
+AddressSanitizer
+================
+
+.. contents::
+ :local:
+
+Introduction
+============
+
+AddressSanitizer is a fast memory error detector. It consists of a compiler
+instrumentation module and a run-time library. The tool can detect the
+following types of bugs:
+
+* Out-of-bounds accesses to heap, stack and globals
+* Use-after-free
+* Use-after-return (runtime flag `ASAN_OPTIONS=detect_stack_use_after_return=1`)
+* Use-after-scope (clang flag `-fsanitize-address-use-after-scope`)
+* Double-free, invalid free
+* Memory leaks (experimental)
+
+Typical slowdown introduced by AddressSanitizer is **2x**.
+
+How to build
+============
+
+Build LLVM/Clang with `CMake <http://llvm.org/docs/CMake.html>`_.
+
+Usage
+=====
+
+Simply compile and link your program with ``-fsanitize=address`` flag. The
+AddressSanitizer run-time library should be linked to the final executable, so
+make sure to use ``clang`` (not ``ld``) for the final link step. When linking
+shared libraries, the AddressSanitizer run-time is not linked, so
+``-Wl,-z,defs`` may cause link errors (don't use it with AddressSanitizer). To
+get a reasonable performance add ``-O1`` or higher. To get nicer stack traces
+in error messages add ``-fno-omit-frame-pointer``. To get perfect stack traces
+you may need to disable inlining (just use ``-O1``) and tail call elimination
+(``-fno-optimize-sibling-calls``).
+
+.. code-block:: console
+
+ % cat example_UseAfterFree.cc
+ int main(int argc, char **argv) {
+ int *array = new int[100];
+ delete [] array;
+ return array[argc]; // BOOM
+ }
+
+ # Compile and link
+ % clang++ -O1 -g -fsanitize=address -fno-omit-frame-pointer example_UseAfterFree.cc
+
+or:
+
+.. code-block:: console
+
+ # Compile
+ % clang++ -O1 -g -fsanitize=address -fno-omit-frame-pointer -c example_UseAfterFree.cc
+ # Link
+ % clang++ -g -fsanitize=address example_UseAfterFree.o
+
+If a bug is detected, the program will print an error message to stderr and
+exit with a non-zero exit code. AddressSanitizer exits on the first detected error.
+This is by design:
+
+* This approach allows AddressSanitizer to produce faster and smaller generated code
+ (both by ~5%).
+* Fixing bugs becomes unavoidable. AddressSanitizer does not produce
+ false alarms. Once a memory corruption occurs, the program is in an inconsistent
+ state, which could lead to confusing results and potentially misleading
+ subsequent reports.
+
+If your process is sandboxed and you are running on OS X 10.10 or earlier, you
+will need to set ``DYLD_INSERT_LIBRARIES`` environment variable and point it to
+the ASan library that is packaged with the compiler used to build the
+executable. (You can find the library by searching for dynamic libraries with
+``asan`` in their name.) If the environment variable is not set, the process will
+try to re-exec. Also keep in mind that when moving the executable to another machine,
+the ASan library will also need to be copied over.
+
+Symbolizing the Reports
+=========================
+
+To make AddressSanitizer symbolize its output
+you need to set the ``ASAN_SYMBOLIZER_PATH`` environment variable to point to
+the ``llvm-symbolizer`` binary (or make sure ``llvm-symbolizer`` is in your
+``$PATH``):
+
+.. code-block:: console
+
+ % ASAN_SYMBOLIZER_PATH=/usr/local/bin/llvm-symbolizer ./a.out
+ ==9442== ERROR: AddressSanitizer heap-use-after-free on address 0x7f7ddab8c084 at pc 0x403c8c bp 0x7fff87fb82d0 sp 0x7fff87fb82c8
+ READ of size 4 at 0x7f7ddab8c084 thread T0
+ #0 0x403c8c in main example_UseAfterFree.cc:4
+ #1 0x7f7ddabcac4d in __libc_start_main ??:0
+ 0x7f7ddab8c084 is located 4 bytes inside of 400-byte region [0x7f7ddab8c080,0x7f7ddab8c210)
+ freed by thread T0 here:
+ #0 0x404704 in operator delete[](void*) ??:0
+ #1 0x403c53 in main example_UseAfterFree.cc:4
+ #2 0x7f7ddabcac4d in __libc_start_main ??:0
+ previously allocated by thread T0 here:
+ #0 0x404544 in operator new[](unsigned long) ??:0
+ #1 0x403c43 in main example_UseAfterFree.cc:2
+ #2 0x7f7ddabcac4d in __libc_start_main ??:0
+ ==9442== ABORTING
+
+If that does not work for you (e.g. your process is sandboxed), you can use a
+separate script to symbolize the result offline (online symbolization can be
+force disabled by setting ``ASAN_OPTIONS=symbolize=0``):
+
+.. code-block:: console
+
+ % ASAN_OPTIONS=symbolize=0 ./a.out 2> log
+ % projects/compiler-rt/lib/asan/scripts/asan_symbolize.py / < log | c++filt
+ ==9442== ERROR: AddressSanitizer heap-use-after-free on address 0x7f7ddab8c084 at pc 0x403c8c bp 0x7fff87fb82d0 sp 0x7fff87fb82c8
+ READ of size 4 at 0x7f7ddab8c084 thread T0
+ #0 0x403c8c in main example_UseAfterFree.cc:4
+ #1 0x7f7ddabcac4d in __libc_start_main ??:0
+ ...
+
+Note that on OS X you may need to run ``dsymutil`` on your binary to have the
+file\:line info in the AddressSanitizer reports.
+
+Additional Checks
+=================
+
+Initialization order checking
+-----------------------------
+
+AddressSanitizer can optionally detect dynamic initialization order problems,
+when initialization of globals defined in one translation unit uses
+globals defined in another translation unit. To enable this check at runtime,
+you should set environment variable
+``ASAN_OPTIONS=check_initialization_order=1``.
+
+Note that this option is not supported on OS X.
+
+Memory leak detection
+---------------------
+
+For more information on leak detector in AddressSanitizer, see
+:doc:`LeakSanitizer`. The leak detection is turned on by default on Linux;
+however, it is not yet supported on other platforms.
+
+Issue Suppression
+=================
+
+AddressSanitizer is not expected to produce false positives. If you see one,
+look again; most likely it is a true positive!
+
+Suppressing Reports in External Libraries
+-----------------------------------------
+Runtime interposition allows AddressSanitizer to find bugs in code that is
+not being recompiled. If you run into an issue in external libraries, we
+recommend immediately reporting it to the library maintainer so that it
+gets addressed. However, you can use the following suppression mechanism
+to unblock yourself and continue on with the testing. This suppression
+mechanism should only be used for suppressing issues in external code; it
+does not work on code recompiled with AddressSanitizer. To suppress errors
+in external libraries, set the ``ASAN_OPTIONS`` environment variable to point
+to a suppression file. You can either specify the full path to the file or the
+path of the file relative to the location of your executable.
+
+.. code-block:: bash
+
+ ASAN_OPTIONS=suppressions=MyASan.supp
+
+Use the following format to specify the names of the functions or libraries
+you want to suppress. You can see these in the error report. Remember that
+the narrower the scope of the suppression, the more bugs you will be able to
+catch.
+
+.. code-block:: bash
+
+ interceptor_via_fun:NameOfCFunctionToSuppress
+ interceptor_via_fun:-[ClassName objCMethodToSuppress:]
+ interceptor_via_lib:NameOfTheLibraryToSuppress
+
+Conditional Compilation with ``__has_feature(address_sanitizer)``
+-----------------------------------------------------------------
+
+In some cases one may need to execute different code depending on whether
+AddressSanitizer is enabled.
+:ref:`\_\_has\_feature <langext-__has_feature-__has_extension>` can be used for
+this purpose.
+
+.. code-block:: c
+
+ #if defined(__has_feature)
+ # if __has_feature(address_sanitizer)
+ // code that builds only under AddressSanitizer
+ # endif
+ #endif
+
+Disabling Instrumentation with ``__attribute__((no_sanitize("address")))``
+--------------------------------------------------------------------------
+
+Some code should not be instrumented by AddressSanitizer. One may use the
+function attribute ``__attribute__((no_sanitize("address")))`` (which has
+deprecated synonyms `no_sanitize_address` and `no_address_safety_analysis`) to
+disable instrumentation of a particular function. This attribute may not be
+supported by other compilers, so we suggest to use it together with
+``__has_feature(address_sanitizer)``.
+
+Suppressing Errors in Recompiled Code (Blacklist)
+-------------------------------------------------
+
+AddressSanitizer supports ``src`` and ``fun`` entity types in
+:doc:`SanitizerSpecialCaseList`, that can be used to suppress error reports
+in the specified source files or functions. Additionally, AddressSanitizer
+introduces ``global`` and ``type`` entity types that can be used to
+suppress error reports for out-of-bound access to globals with certain
+names and types (you may only specify class or struct types).
+
+You may use an ``init`` category to suppress reports about initialization-order
+problems happening in certain source files or with certain global variables.
+
+.. code-block:: bash
+
+ # Suppress error reports for code in a file or in a function:
+ src:bad_file.cpp
+ # Ignore all functions with names containing MyFooBar:
+ fun:*MyFooBar*
+ # Disable out-of-bound checks for global:
+ global:bad_array
+ # Disable out-of-bound checks for global instances of a given class ...
+ type:Namespace::BadClassName
+ # ... or a given struct. Use wildcard to deal with anonymous namespace.
+ type:Namespace2::*::BadStructName
+ # Disable initialization-order checks for globals:
+ global:bad_init_global=init
+ type:*BadInitClassSubstring*=init
+ src:bad/init/files/*=init
+
+Suppressing memory leaks
+------------------------
+
+Memory leak reports produced by :doc:`LeakSanitizer` (if it is run as a part
+of AddressSanitizer) can be suppressed by a separate file passed as
+
+.. code-block:: bash
+
+ LSAN_OPTIONS=suppressions=MyLSan.supp
+
+which contains lines of the form `leak:<pattern>`. Memory leak will be
+suppressed if pattern matches any function name, source file name, or
+library name in the symbolized stack trace of the leak report. See
+`full documentation
+<https://github.com/google/sanitizers/wiki/AddressSanitizerLeakSanitizer#suppressions>`_
+for more details.
+
+Limitations
+===========
+
+* AddressSanitizer uses more real memory than a native run. Exact overhead
+ depends on the allocations sizes. The smaller the allocations you make the
+ bigger the overhead is.
+* AddressSanitizer uses more stack memory. We have seen up to 3x increase.
+* On 64-bit platforms AddressSanitizer maps (but not reserves) 16+ Terabytes of
+ virtual address space. This means that tools like ``ulimit`` may not work as
+ usually expected.
+* Static linking is not supported.
+
+Supported Platforms
+===================
+
+AddressSanitizer is supported on:
+
+* Linux i386/x86\_64 (tested on Ubuntu 12.04)
+* OS X 10.7 - 10.11 (i386/x86\_64)
+* iOS Simulator
+* Android ARM
+* FreeBSD i386/x86\_64 (tested on FreeBSD 11-current)
+
+Ports to various other platforms are in progress.
+
+Current Status
+==============
+
+AddressSanitizer is fully functional on supported platforms starting from LLVM
+3.1. The test suite is integrated into CMake build and can be run with ``make
+check-asan`` command.
+
+More Information
+================
+
+`<https://github.com/google/sanitizers/wiki/AddressSanitizer>`_
Added: www-releases/trunk/4.0.0/tools/clang/docs/_sources/AttributeReference.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/4.0.0/tools/clang/docs/_sources/AttributeReference.txt?rev=297634&view=auto
==============================================================================
--- www-releases/trunk/4.0.0/tools/clang/docs/_sources/AttributeReference.txt (added)
+++ www-releases/trunk/4.0.0/tools/clang/docs/_sources/AttributeReference.txt Mon Mar 13 11:30:12 2017
@@ -0,0 +1,3119 @@
+..
+ -------------------------------------------------------------------
+ NOTE: This file is automatically generated by running clang-tblgen
+ -gen-attr-docs. Do not edit this file by hand!!
+ -------------------------------------------------------------------
+
+===================
+Attributes in Clang
+===================
+.. contents::
+ :local:
+
+Introduction
+============
+
+This page lists the attributes currently supported by Clang.
+
+Function Attributes
+===================
+
+
+interrupt
+---------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "X","","","", ""
+
+Clang supports the GNU style ``__attribute__((interrupt("TYPE")))`` attribute on
+ARM targets. This attribute may be attached to a function definition and
+instructs the backend to generate appropriate function entry/exit code so that
+it can be used directly as an interrupt service routine.
+
+The parameter passed to the interrupt attribute is optional, but if
+provided it must be a string literal with one of the following values: "IRQ",
+"FIQ", "SWI", "ABORT", "UNDEF".
+
+The semantics are as follows:
+
+- If the function is AAPCS, Clang instructs the backend to realign the stack to
+ 8 bytes on entry. This is a general requirement of the AAPCS at public
+ interfaces, but may not hold when an exception is taken. Doing this allows
+ other AAPCS functions to be called.
+- If the CPU is M-class this is all that needs to be done since the architecture
+ itself is designed in such a way that functions obeying the normal AAPCS ABI
+ constraints are valid exception handlers.
+- If the CPU is not M-class, the prologue and epilogue are modified to save all
+ non-banked registers that are used, so that upon return the user-mode state
+ will not be corrupted. Note that to avoid unnecessary overhead, only
+ general-purpose (integer) registers are saved in this way. If VFP operations
+ are needed, that state must be saved manually.
+
+ Specifically, interrupt kinds other than "FIQ" will save all core registers
+ except "lr" and "sp". "FIQ" interrupts will save r0-r7.
+- If the CPU is not M-class, the return instruction is changed to one of the
+ canonical sequences permitted by the architecture for exception return. Where
+ possible the function itself will make the necessary "lr" adjustments so that
+ the "preferred return address" is selected.
+
+ Unfortunately the compiler is unable to make this guarantee for an "UNDEF"
+ handler, where the offset from "lr" to the preferred return address depends on
+ the execution state of the code which generated the exception. In this case
+ a sequence equivalent to "movs pc, lr" will be used.
+
+
+abi_tag (gnu::abi_tag)
+----------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "X","X","","", ""
+
+The ``abi_tag`` attribute can be applied to a function, variable, class or
+inline namespace declaration to modify the mangled name of the entity. It gives
+the ability to distinguish between different versions of the same entity but
+with different ABI versions supported. For example, a newer version of a class
+could have a different set of data members and thus have a different size. Using
+the ``abi_tag`` attribute, it is possible to have different mangled names for
+a global variable of the class type. Therefor, the old code could keep using
+the old manged name and the new code will use the new mangled name with tags.
+
+
+acquire_capability (acquire_shared_capability, clang::acquire_capability, clang::acquire_shared_capability)
+-----------------------------------------------------------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "X","X","","", ""
+
+Marks a function as acquiring a capability.
+
+
+alloc_size (gnu::alloc_size)
+----------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "X","X","","", ""
+
+The ``alloc_size`` attribute can be placed on functions that return pointers in
+order to hint to the compiler how many bytes of memory will be available at the
+returned poiner. ``alloc_size`` takes one or two arguments.
+
+- ``alloc_size(N)`` implies that argument number N equals the number of
+ available bytes at the returned pointer.
+- ``alloc_size(N, M)`` implies that the product of argument number N and
+ argument number M equals the number of available bytes at the returned
+ pointer.
+
+Argument numbers are 1-based.
+
+An example of how to use ``alloc_size``
+
+.. code-block:: c
+
+ void *my_malloc(int a) __attribute__((alloc_size(1)));
+ void *my_calloc(int a, int b) __attribute__((alloc_size(1, 2)));
+
+ int main() {
+ void *const p = my_malloc(100);
+ assert(__builtin_object_size(p, 0) == 100);
+ void *const a = my_calloc(20, 5);
+ assert(__builtin_object_size(a, 0) == 100);
+ }
+
+.. Note:: This attribute works differently in clang than it does in GCC.
+ Specifically, clang will only trace ``const`` pointers (as above); we give up
+ on pointers that are not marked as ``const``. In the vast majority of cases,
+ this is unimportant, because LLVM has support for the ``alloc_size``
+ attribute. However, this may cause mildly unintuitive behavior when used with
+ other attributes, such as ``enable_if``.
+
+
+interrupt
+---------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "X","","","", ""
+
+Clang supports the GNU style ``__attribute__((interrupt))`` attribute on
+x86/x86-64 targets.The compiler generates function entry and exit sequences
+suitable for use in an interrupt handler when this attribute is present.
+The 'IRET' instruction, instead of the 'RET' instruction, is used to return
+from interrupt or exception handlers. All registers, except for the EFLAGS
+register which is restored by the 'IRET' instruction, are preserved by the
+compiler.
+
+Any interruptible-without-stack-switch code must be compiled with
+-mno-red-zone since interrupt handlers can and will, because of the
+hardware design, touch the red zone.
+
+1. interrupt handler must be declared with a mandatory pointer argument:
+
+ .. code-block:: c
+
+ struct interrupt_frame
+ {
+ uword_t ip;
+ uword_t cs;
+ uword_t flags;
+ uword_t sp;
+ uword_t ss;
+ };
+
+ __attribute__ ((interrupt))
+ void f (struct interrupt_frame *frame) {
+ ...
+ }
+
+2. exception handler:
+
+ The exception handler is very similar to the interrupt handler with
+ a different mandatory function signature:
+
+ .. code-block:: c
+
+ __attribute__ ((interrupt))
+ void f (struct interrupt_frame *frame, uword_t error_code) {
+ ...
+ }
+
+ and compiler pops 'ERROR_CODE' off stack before the 'IRET' instruction.
+
+ The exception handler should only be used for exceptions which push an
+ error code and all other exceptions must use the interrupt handler.
+ The system will crash if the wrong handler is used.
+
+
+assert_capability (assert_shared_capability, clang::assert_capability, clang::assert_shared_capability)
+-------------------------------------------------------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "X","X","","", ""
+
+Marks a function that dynamically tests whether a capability is held, and halts
+the program if it is not held.
+
+
+assume_aligned (gnu::assume_aligned)
+------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "X","X","","", ""
+
+Use ``__attribute__((assume_aligned(<alignment>[,<offset>]))`` on a function
+declaration to specify that the return value of the function (which must be a
+pointer type) has the specified offset, in bytes, from an address with the
+specified alignment. The offset is taken to be zero if omitted.
+
+.. code-block:: c++
+
+ // The returned pointer value has 32-byte alignment.
+ void *a() __attribute__((assume_aligned (32)));
+
+ // The returned pointer value is 4 bytes greater than an address having
+ // 32-byte alignment.
+ void *b() __attribute__((assume_aligned (32, 4)));
+
+Note that this attribute provides information to the compiler regarding a
+condition that the code already ensures is true. It does not cause the compiler
+to enforce the provided alignment assumption.
+
+
+availability
+------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "X","","","", ""
+
+The ``availability`` attribute can be placed on declarations to describe the
+lifecycle of that declaration relative to operating system versions. Consider
+the function declaration for a hypothetical function ``f``:
+
+.. code-block:: c++
+
+ void f(void) __attribute__((availability(macos,introduced=10.4,deprecated=10.6,obsoleted=10.7)));
+
+The availability attribute states that ``f`` was introduced in Mac OS X 10.4,
+deprecated in Mac OS X 10.6, and obsoleted in Mac OS X 10.7. This information
+is used by Clang to determine when it is safe to use ``f``: for example, if
+Clang is instructed to compile code for Mac OS X 10.5, a call to ``f()``
+succeeds. If Clang is instructed to compile code for Mac OS X 10.6, the call
+succeeds but Clang emits a warning specifying that the function is deprecated.
+Finally, if Clang is instructed to compile code for Mac OS X 10.7, the call
+fails because ``f()`` is no longer available.
+
+The availability attribute is a comma-separated list starting with the
+platform name and then including clauses specifying important milestones in the
+declaration's lifetime (in any order) along with additional information. Those
+clauses can be:
+
+introduced=\ *version*
+ The first version in which this declaration was introduced.
+
+deprecated=\ *version*
+ The first version in which this declaration was deprecated, meaning that
+ users should migrate away from this API.
+
+obsoleted=\ *version*
+ The first version in which this declaration was obsoleted, meaning that it
+ was removed completely and can no longer be used.
+
+unavailable
+ This declaration is never available on this platform.
+
+message=\ *string-literal*
+ Additional message text that Clang will provide when emitting a warning or
+ error about use of a deprecated or obsoleted declaration. Useful to direct
+ users to replacement APIs.
+
+replacement=\ *string-literal*
+ Additional message text that Clang will use to provide Fix-It when emitting
+ a warning about use of a deprecated declaration. The Fix-It will replace
+ the deprecated declaration with the new declaration specified.
+
+Multiple availability attributes can be placed on a declaration, which may
+correspond to different platforms. Only the availability attribute with the
+platform corresponding to the target platform will be used; any others will be
+ignored. If no availability attribute specifies availability for the current
+target platform, the availability attributes are ignored. Supported platforms
+are:
+
+``ios``
+ Apple's iOS operating system. The minimum deployment target is specified by
+ the ``-mios-version-min=*version*`` or ``-miphoneos-version-min=*version*``
+ command-line arguments.
+
+``macos``
+ Apple's Mac OS X operating system. The minimum deployment target is
+ specified by the ``-mmacosx-version-min=*version*`` command-line argument.
+ ``macosx`` is supported for backward-compatibility reasons, but it is
+ deprecated.
+
+``tvos``
+ Apple's tvOS operating system. The minimum deployment target is specified by
+ the ``-mtvos-version-min=*version*`` command-line argument.
+
+``watchos``
+ Apple's watchOS operating system. The minimum deployment target is specified by
+ the ``-mwatchos-version-min=*version*`` command-line argument.
+
+A declaration can typically be used even when deploying back to a platform
+version prior to when the declaration was introduced. When this happens, the
+declaration is `weakly linked
+<https://developer.apple.com/library/mac/#documentation/MacOSX/Conceptual/BPFrameworks/Concepts/WeakLinking.html>`_,
+as if the ``weak_import`` attribute were added to the declaration. A
+weakly-linked declaration may or may not be present a run-time, and a program
+can determine whether the declaration is present by checking whether the
+address of that declaration is non-NULL.
+
+The flag ``strict`` disallows using API when deploying back to a
+platform version prior to when the declaration was introduced. An
+attempt to use such API before its introduction causes a hard error.
+Weakly-linking is almost always a better API choice, since it allows
+users to query availability at runtime.
+
+If there are multiple declarations of the same entity, the availability
+attributes must either match on a per-platform basis or later
+declarations must not have availability attributes for that
+platform. For example:
+
+.. code-block:: c
+
+ void g(void) __attribute__((availability(macos,introduced=10.4)));
+ void g(void) __attribute__((availability(macos,introduced=10.4))); // okay, matches
+ void g(void) __attribute__((availability(ios,introduced=4.0))); // okay, adds a new platform
+ void g(void); // okay, inherits both macos and ios availability from above.
+ void g(void) __attribute__((availability(macos,introduced=10.5))); // error: mismatch
+
+When one method overrides another, the overriding method can be more widely available than the overridden method, e.g.,:
+
+.. code-block:: objc
+
+ @interface A
+ - (id)method __attribute__((availability(macos,introduced=10.4)));
+ - (id)method2 __attribute__((availability(macos,introduced=10.4)));
+ @end
+
+ @interface B : A
+ - (id)method __attribute__((availability(macos,introduced=10.3))); // okay: method moved into base class later
+ - (id)method __attribute__((availability(macos,introduced=10.5))); // error: this method was available via the base class in 10.4
+ @end
+
+
+_Noreturn
+---------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "","","","X", ""
+
+A function declared as ``_Noreturn`` shall not return to its caller. The
+compiler will generate a diagnostic for a function declared as ``_Noreturn``
+that appears to be capable of returning to its caller.
+
+
+noreturn
+--------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "","X","","", ""
+
+A function declared as ``[[noreturn]]`` shall not return to its caller. The
+compiler will generate a diagnostic for a function declared as ``[[noreturn]]``
+that appears to be capable of returning to its caller.
+
+
+carries_dependency
+------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "X","X","","", ""
+
+The ``carries_dependency`` attribute specifies dependency propagation into and
+out of functions.
+
+When specified on a function or Objective-C method, the ``carries_dependency``
+attribute means that the return value carries a dependency out of the function,
+so that the implementation need not constrain ordering upon return from that
+function. Implementations of the function and its caller may choose to preserve
+dependencies instead of emitting memory ordering instructions such as fences.
+
+Note, this attribute does not change the meaning of the program, but may result
+in generation of more efficient code.
+
+
+convergent (clang::convergent)
+------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "X","X","","", ""
+
+The ``convergent`` attribute can be placed on a function declaration. It is
+translated into the LLVM ``convergent`` attribute, which indicates that the call
+instructions of a function with this attribute cannot be made control-dependent
+on any additional values.
+
+In languages designed for SPMD/SIMT programming model, e.g. OpenCL or CUDA,
+the call instructions of a function with this attribute must be executed by
+all work items or threads in a work group or sub group.
+
+This attribute is different from ``noduplicate`` because it allows duplicating
+function calls if it can be proved that the duplicated function calls are
+not made control-dependent on any additional values, e.g., unrolling a loop
+executed by all work items.
+
+Sample usage:
+.. code-block:: c
+
+ void convfunc(void) __attribute__((convergent));
+ // Setting it as a C++11 attribute is also valid in a C++ program.
+ // void convfunc(void) [[clang::convergent]];
+
+
+deprecated (gnu::deprecated)
+----------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "X","X","X","", ""
+
+The ``deprecated`` attribute can be applied to a function, a variable, or a
+type. This is useful when identifying functions, variables, or types that are
+expected to be removed in a future version of a program.
+
+Consider the function declaration for a hypothetical function ``f``:
+
+.. code-block:: c++
+
+ void f(void) __attribute__((deprecated("message", "replacement")));
+
+When spelled as `__attribute__((deprecated))`, the deprecated attribute can have
+two optional string arguments. The first one is the message to display when
+emitting the warning; the second one enables the compiler to provide a Fix-It
+to replace the deprecated name with a new name. Otherwise, when spelled as
+`[[gnu::deprecated]] or [[deprecated]]`, the attribute can have one optional
+string argument which is the message to display when emitting the warning.
+
+
+diagnose_if
+-----------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "X","","","", ""
+
+The ``diagnose_if`` attribute can be placed on function declarations to emit
+warnings or errors at compile-time if calls to the attributed function meet
+certain user-defined criteria. For example:
+
+.. code-block:: c
+
+ void abs(int a)
+ __attribute__((diagnose_if(a >= 0, "Redundant abs call", "warning")));
+ void must_abs(int a)
+ __attribute__((diagnose_if(a >= 0, "Redundant abs call", "error")));
+
+ int val = abs(1); // warning: Redundant abs call
+ int val2 = must_abs(1); // error: Redundant abs call
+ int val3 = abs(val);
+ int val4 = must_abs(val); // Because run-time checks are not emitted for
+ // diagnose_if attributes, this executes without
+ // issue.
+
+
+``diagnose_if`` is closely related to ``enable_if``, with a few key differences:
+
+* Overload resolution is not aware of ``diagnose_if`` attributes: they're
+ considered only after we select the best candidate from a given candidate set.
+* Function declarations that differ only in their ``diagnose_if`` attributes are
+ considered to be redeclarations of the same function (not overloads).
+* If the condition provided to ``diagnose_if`` cannot be evaluated, no
+ diagnostic will be emitted.
+
+Otherwise, ``diagnose_if`` is essentially the logical negation of ``enable_if``.
+
+As a result of bullet number two, ``diagnose_if`` attributes will stack on the
+same function. For example:
+
+.. code-block:: c
+
+ int foo() __attribute__((diagnose_if(1, "diag1", "warning")));
+ int foo() __attribute__((diagnose_if(1, "diag2", "warning")));
+
+ int bar = foo(); // warning: diag1
+ // warning: diag2
+ int (*fooptr)(void) = foo; // warning: diag1
+ // warning: diag2
+
+ constexpr int supportsAPILevel(int N) { return N < 5; }
+ int baz(int a)
+ __attribute__((diagnose_if(!supportsAPILevel(10),
+ "Upgrade to API level 10 to use baz", "error")));
+ int baz(int a)
+ __attribute__((diagnose_if(!a, "0 is not recommended.", "warning")));
+
+ int (*bazptr)(int) = baz; // error: Upgrade to API level 10 to use baz
+ int v = baz(0); // error: Upgrade to API level 10 to use baz
+
+Query for this feature with ``__has_attribute(diagnose_if)``.
+
+
+disable_tail_calls (clang::disable_tail_calls)
+----------------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "X","X","","", ""
+
+The ``disable_tail_calls`` attribute instructs the backend to not perform tail call optimization inside the marked function.
+
+For example:
+
+ .. code-block:: c
+
+ int callee(int);
+
+ int foo(int a) __attribute__((disable_tail_calls)) {
+ return callee(a); // This call is not tail-call optimized.
+ }
+
+Marking virtual functions as ``disable_tail_calls`` is legal.
+
+ .. code-block:: c++
+
+ int callee(int);
+
+ class Base {
+ public:
+ [[clang::disable_tail_calls]] virtual int foo1() {
+ return callee(); // This call is not tail-call optimized.
+ }
+ };
+
+ class Derived1 : public Base {
+ public:
+ int foo1() override {
+ return callee(); // This call is tail-call optimized.
+ }
+ };
+
+
+enable_if
+---------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "X","","","", ""
+
+.. Note:: Some features of this attribute are experimental. The meaning of
+ multiple enable_if attributes on a single declaration is subject to change in
+ a future version of clang. Also, the ABI is not standardized and the name
+ mangling may change in future versions. To avoid that, use asm labels.
+
+The ``enable_if`` attribute can be placed on function declarations to control
+which overload is selected based on the values of the function's arguments.
+When combined with the ``overloadable`` attribute, this feature is also
+available in C.
+
+.. code-block:: c++
+
+ int isdigit(int c);
+ int isdigit(int c) __attribute__((enable_if(c <= -1 || c > 255, "chosen when 'c' is out of range"))) __attribute__((unavailable("'c' must have the value of an unsigned char or EOF")));
+
+ void foo(char c) {
+ isdigit(c);
+ isdigit(10);
+ isdigit(-10); // results in a compile-time error.
+ }
+
+The enable_if attribute takes two arguments, the first is an expression written
+in terms of the function parameters, the second is a string explaining why this
+overload candidate could not be selected to be displayed in diagnostics. The
+expression is part of the function signature for the purposes of determining
+whether it is a redeclaration (following the rules used when determining
+whether a C++ template specialization is ODR-equivalent), but is not part of
+the type.
+
+The enable_if expression is evaluated as if it were the body of a
+bool-returning constexpr function declared with the arguments of the function
+it is being applied to, then called with the parameters at the call site. If the
+result is false or could not be determined through constant expression
+evaluation, then this overload will not be chosen and the provided string may
+be used in a diagnostic if the compile fails as a result.
+
+Because the enable_if expression is an unevaluated context, there are no global
+state changes, nor the ability to pass information from the enable_if
+expression to the function body. For example, suppose we want calls to
+strnlen(strbuf, maxlen) to resolve to strnlen_chk(strbuf, maxlen, size of
+strbuf) only if the size of strbuf can be determined:
+
+.. code-block:: c++
+
+ __attribute__((always_inline))
+ static inline size_t strnlen(const char *s, size_t maxlen)
+ __attribute__((overloadable))
+ __attribute__((enable_if(__builtin_object_size(s, 0) != -1))),
+ "chosen when the buffer size is known but 'maxlen' is not")))
+ {
+ return strnlen_chk(s, maxlen, __builtin_object_size(s, 0));
+ }
+
+Multiple enable_if attributes may be applied to a single declaration. In this
+case, the enable_if expressions are evaluated from left to right in the
+following manner. First, the candidates whose enable_if expressions evaluate to
+false or cannot be evaluated are discarded. If the remaining candidates do not
+share ODR-equivalent enable_if expressions, the overload resolution is
+ambiguous. Otherwise, enable_if overload resolution continues with the next
+enable_if attribute on the candidates that have not been discarded and have
+remaining enable_if attributes. In this way, we pick the most specific
+overload out of a number of viable overloads using enable_if.
+
+.. code-block:: c++
+
+ void f() __attribute__((enable_if(true, ""))); // #1
+ void f() __attribute__((enable_if(true, ""))) __attribute__((enable_if(true, ""))); // #2
+
+ void g(int i, int j) __attribute__((enable_if(i, ""))); // #1
+ void g(int i, int j) __attribute__((enable_if(j, ""))) __attribute__((enable_if(true))); // #2
+
+In this example, a call to f() is always resolved to #2, as the first enable_if
+expression is ODR-equivalent for both declarations, but #1 does not have another
+enable_if expression to continue evaluating, so the next round of evaluation has
+only a single candidate. In a call to g(1, 1), the call is ambiguous even though
+#2 has more enable_if attributes, because the first enable_if expressions are
+not ODR-equivalent.
+
+Query for this feature with ``__has_attribute(enable_if)``.
+
+Note that functions with one or more ``enable_if`` attributes may not have
+their address taken, unless all of the conditions specified by said
+``enable_if`` are constants that evaluate to ``true``. For example:
+
+.. code-block:: c
+
+ const int TrueConstant = 1;
+ const int FalseConstant = 0;
+ int f(int a) __attribute__((enable_if(a > 0, "")));
+ int g(int a) __attribute__((enable_if(a == 0 || a != 0, "")));
+ int h(int a) __attribute__((enable_if(1, "")));
+ int i(int a) __attribute__((enable_if(TrueConstant, "")));
+ int j(int a) __attribute__((enable_if(FalseConstant, "")));
+
+ void fn() {
+ int (*ptr)(int);
+ ptr = &f; // error: 'a > 0' is not always true
+ ptr = &g; // error: 'a == 0 || a != 0' is not a truthy constant
+ ptr = &h; // OK: 1 is a truthy constant
+ ptr = &i; // OK: 'TrueConstant' is a truthy constant
+ ptr = &j; // error: 'FalseConstant' is a constant, but not truthy
+ }
+
+Because ``enable_if`` evaluation happens during overload resolution,
+``enable_if`` may give unintuitive results when used with templates, depending
+on when overloads are resolved. In the example below, clang will emit a
+diagnostic about no viable overloads for ``foo`` in ``bar``, but not in ``baz``:
+
+.. code-block:: c++
+
+ double foo(int i) __attribute__((enable_if(i > 0, "")));
+ void *foo(int i) __attribute__((enable_if(i <= 0, "")));
+ template <int I>
+ auto bar() { return foo(I); }
+
+ template <typename T>
+ auto baz() { return foo(T::number); }
+
+ struct WithNumber { constexpr static int number = 1; };
+ void callThem() {
+ bar<sizeof(WithNumber)>();
+ baz<WithNumber>();
+ }
+
+This is because, in ``bar``, ``foo`` is resolved prior to template
+instantiation, so the value for ``I`` isn't known (thus, both ``enable_if``
+conditions for ``foo`` fail). However, in ``baz``, ``foo`` is resolved during
+template instantiation, so the value for ``T::number`` is known.
+
+
+flatten (gnu::flatten)
+----------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "X","X","","", ""
+
+The ``flatten`` attribute causes calls within the attributed function to
+be inlined unless it is impossible to do so, for example if the body of the
+callee is unavailable or if the callee has the ``noinline`` attribute.
+
+
+format (gnu::format)
+--------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "X","X","","", ""
+
+Clang supports the ``format`` attribute, which indicates that the function
+accepts a ``printf`` or ``scanf``-like format string and corresponding
+arguments or a ``va_list`` that contains these arguments.
+
+Please see `GCC documentation about format attribute
+<http://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html>`_ to find details
+about attribute syntax.
+
+Clang implements two kinds of checks with this attribute.
+
+#. Clang checks that the function with the ``format`` attribute is called with
+ a format string that uses format specifiers that are allowed, and that
+ arguments match the format string. This is the ``-Wformat`` warning, it is
+ on by default.
+
+#. Clang checks that the format string argument is a literal string. This is
+ the ``-Wformat-nonliteral`` warning, it is off by default.
+
+ Clang implements this mostly the same way as GCC, but there is a difference
+ for functions that accept a ``va_list`` argument (for example, ``vprintf``).
+ GCC does not emit ``-Wformat-nonliteral`` warning for calls to such
+ functions. Clang does not warn if the format string comes from a function
+ parameter, where the function is annotated with a compatible attribute,
+ otherwise it warns. For example:
+
+ .. code-block:: c
+
+ __attribute__((__format__ (__scanf__, 1, 3)))
+ void foo(const char* s, char *buf, ...) {
+ va_list ap;
+ va_start(ap, buf);
+
+ vprintf(s, ap); // warning: format string is not a string literal
+ }
+
+ In this case we warn because ``s`` contains a format string for a
+ ``scanf``-like function, but it is passed to a ``printf``-like function.
+
+ If the attribute is removed, clang still warns, because the format string is
+ not a string literal.
+
+ Another example:
+
+ .. code-block:: c
+
+ __attribute__((__format__ (__printf__, 1, 3)))
+ void foo(const char* s, char *buf, ...) {
+ va_list ap;
+ va_start(ap, buf);
+
+ vprintf(s, ap); // warning
+ }
+
+ In this case Clang does not warn because the format string ``s`` and
+ the corresponding arguments are annotated. If the arguments are
+ incorrect, the caller of ``foo`` will receive a warning.
+
+
+ifunc (gnu::ifunc)
+------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "X","X","","", ""
+
+``__attribute__((ifunc("resolver")))`` is used to mark that the address of a declaration should be resolved at runtime by calling a resolver function.
+
+The symbol name of the resolver function is given in quotes. A function with this name (after mangling) must be defined in the current translation unit; it may be ``static``. The resolver function should take no arguments and return a pointer.
+
+The ``ifunc`` attribute may only be used on a function declaration. A function declaration with an ``ifunc`` attribute is considered to be a definition of the declared entity. The entity must not have weak linkage; for example, in C++, it cannot be applied to a declaration if a definition at that location would be considered inline.
+
+Not all targets support this attribute. ELF targets support this attribute when using binutils v2.20.1 or higher and glibc v2.11.1 or higher. Non-ELF targets currently do not support this attribute.
+
+
+internal_linkage (clang::internal_linkage)
+------------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "X","X","","", ""
+
+The ``internal_linkage`` attribute changes the linkage type of the declaration to internal.
+This is similar to C-style ``static``, but can be used on classes and class methods. When applied to a class definition,
+this attribute affects all methods and static data members of that class.
+This can be used to contain the ABI of a C++ library by excluding unwanted class methods from the export tables.
+
+
+interrupt
+---------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "X","","","", ""
+
+Clang supports the GNU style ``__attribute__((interrupt("ARGUMENT")))`` attribute on
+MIPS targets. This attribute may be attached to a function definition and instructs
+the backend to generate appropriate function entry/exit code so that it can be used
+directly as an interrupt service routine.
+
+By default, the compiler will produce a function prologue and epilogue suitable for
+an interrupt service routine that handles an External Interrupt Controller (eic)
+generated interrupt. This behaviour can be explicitly requested with the "eic"
+argument.
+
+Otherwise, for use with vectored interrupt mode, the argument passed should be
+of the form "vector=LEVEL" where LEVEL is one of the following values:
+"sw0", "sw1", "hw0", "hw1", "hw2", "hw3", "hw4", "hw5". The compiler will
+then set the interrupt mask to the corresponding level which will mask all
+interrupts up to and including the argument.
+
+The semantics are as follows:
+
+- The prologue is modified so that the Exception Program Counter (EPC) and
+ Status coprocessor registers are saved to the stack. The interrupt mask is
+ set so that the function can only be interrupted by a higher priority
+ interrupt. The epilogue will restore the previous values of EPC and Status.
+
+- The prologue and epilogue are modified to save and restore all non-kernel
+ registers as necessary.
+
+- The FPU is disabled in the prologue, as the floating pointer registers are not
+ spilled to the stack.
+
+- The function return sequence is changed to use an exception return instruction.
+
+- The parameter sets the interrupt mask for the function corresponding to the
+ interrupt level specified. If no mask is specified the interrupt mask
+ defaults to "eic".
+
+
+noalias
+-------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "","","X","", ""
+
+The ``noalias`` attribute indicates that the only memory accesses inside
+function are loads and stores from objects pointed to by its pointer-typed
+arguments, with arbitrary offsets.
+
+
+noduplicate (clang::noduplicate)
+--------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "X","X","","", ""
+
+The ``noduplicate`` attribute can be placed on function declarations to control
+whether function calls to this function can be duplicated or not as a result of
+optimizations. This is required for the implementation of functions with
+certain special requirements, like the OpenCL "barrier" function, that might
+need to be run concurrently by all the threads that are executing in lockstep
+on the hardware. For example this attribute applied on the function
+"nodupfunc" in the code below avoids that:
+
+.. code-block:: c
+
+ void nodupfunc() __attribute__((noduplicate));
+ // Setting it as a C++11 attribute is also valid
+ // void nodupfunc() [[clang::noduplicate]];
+ void foo();
+ void bar();
+
+ nodupfunc();
+ if (a > n) {
+ foo();
+ } else {
+ bar();
+ }
+
+gets possibly modified by some optimizations into code similar to this:
+
+.. code-block:: c
+
+ if (a > n) {
+ nodupfunc();
+ foo();
+ } else {
+ nodupfunc();
+ bar();
+ }
+
+where the call to "nodupfunc" is duplicated and sunk into the two branches
+of the condition.
+
+
+no_sanitize (clang::no_sanitize)
+--------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "X","X","","", ""
+
+Use the ``no_sanitize`` attribute on a function declaration to specify
+that a particular instrumentation or set of instrumentations should not be
+applied to that function. The attribute takes a list of string literals,
+which have the same meaning as values accepted by the ``-fno-sanitize=``
+flag. For example, ``__attribute__((no_sanitize("address", "thread")))``
+specifies that AddressSanitizer and ThreadSanitizer should not be applied
+to the function.
+
+See :ref:`Controlling Code Generation <controlling-code-generation>` for a
+full list of supported sanitizer flags.
+
+
+no_sanitize_address (no_address_safety_analysis, gnu::no_address_safety_analysis, gnu::no_sanitize_address)
+-----------------------------------------------------------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "X","X","","", ""
+
+.. _langext-address_sanitizer:
+
+Use ``__attribute__((no_sanitize_address))`` on a function declaration to
+specify that address safety instrumentation (e.g. AddressSanitizer) should
+not be applied to that function.
+
+
+no_sanitize_thread
+------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "X","X","","", ""
+
+.. _langext-thread_sanitizer:
+
+Use ``__attribute__((no_sanitize_thread))`` on a function declaration to
+specify that checks for data races on plain (non-atomic) memory accesses should
+not be inserted by ThreadSanitizer. The function is still instrumented by the
+tool to avoid false positives and provide meaningful stack traces.
+
+
+no_sanitize_memory
+------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "X","X","","", ""
+
+.. _langext-memory_sanitizer:
+
+Use ``__attribute__((no_sanitize_memory))`` on a function declaration to
+specify that checks for uninitialized memory should not be inserted
+(e.g. by MemorySanitizer). The function may still be instrumented by the tool
+to avoid false positives in other places.
+
+
+no_split_stack (gnu::no_split_stack)
+------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "X","X","","", ""
+
+The ``no_split_stack`` attribute disables the emission of the split stack
+preamble for a particular function. It has no effect if ``-fsplit-stack``
+is not specified.
+
+
+not_tail_called (clang::not_tail_called)
+----------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "X","X","","", ""
+
+The ``not_tail_called`` attribute prevents tail-call optimization on statically bound calls. It has no effect on indirect calls. Virtual functions, objective-c methods, and functions marked as ``always_inline`` cannot be marked as ``not_tail_called``.
+
+For example, it prevents tail-call optimization in the following case:
+
+ .. code-block:: c
+
+ int __attribute__((not_tail_called)) foo1(int);
+
+ int foo2(int a) {
+ return foo1(a); // No tail-call optimization on direct calls.
+ }
+
+However, it doesn't prevent tail-call optimization in this case:
+
+ .. code-block:: c
+
+ int __attribute__((not_tail_called)) foo1(int);
+
+ int foo2(int a) {
+ int (*fn)(int) = &foo1;
+
+ // not_tail_called has no effect on an indirect call even if the call can be
+ // resolved at compile time.
+ return (*fn)(a);
+ }
+
+Marking virtual functions as ``not_tail_called`` is an error:
+
+ .. code-block:: c++
+
+ class Base {
+ public:
+ // not_tail_called on a virtual function is an error.
+ [[clang::not_tail_called]] virtual int foo1();
+
+ virtual int foo2();
+
+ // Non-virtual functions can be marked ``not_tail_called``.
+ [[clang::not_tail_called]] int foo3();
+ };
+
+ class Derived1 : public Base {
+ public:
+ int foo1() override;
+
+ // not_tail_called on a virtual function is an error.
+ [[clang::not_tail_called]] int foo2() override;
+ };
+
+
+#pragma omp declare simd
+------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "","","","", "X"
+
+The `declare simd` construct can be applied to a function to enable the creation
+of one or more versions that can process multiple arguments using SIMD
+instructions from a single invocation in a SIMD loop. The `declare simd`
+directive is a declarative directive. There may be multiple `declare simd`
+directives for a function. The use of a `declare simd` construct on a function
+enables the creation of SIMD versions of the associated function that can be
+used to process multiple arguments from a single invocation from a SIMD loop
+concurrently.
+The syntax of the `declare simd` construct is as follows:
+
+ .. code-block:: c
+
+ #pragma omp declare simd [clause[[,] clause] ...] new-line
+ [#pragma omp declare simd [clause[[,] clause] ...] new-line]
+ [...]
+ function definition or declaration
+
+where clause is one of the following:
+
+ .. code-block:: c
+
+ simdlen(length)
+ linear(argument-list[:constant-linear-step])
+ aligned(argument-list[:alignment])
+ uniform(argument-list)
+ inbranch
+ notinbranch
+
+
+#pragma omp declare target
+--------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "","","","", "X"
+
+The `declare target` directive specifies that variables and functions are mapped
+to a device for OpenMP offload mechanism.
+
+The syntax of the declare target directive is as follows:
+
+ .. code-block:: c
+
+ #pragma omp declare target new-line
+ declarations-definition-seq
+ #pragma omp end declare target new-line
+
+
+objc_boxable
+------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "X","","","", ""
+
+Structs and unions marked with the ``objc_boxable`` attribute can be used
+with the Objective-C boxed expression syntax, ``@(...)``.
+
+**Usage**: ``__attribute__((objc_boxable))``. This attribute
+can only be placed on a declaration of a trivially-copyable struct or union:
+
+.. code-block:: objc
+
+ struct __attribute__((objc_boxable)) some_struct {
+ int i;
+ };
+ union __attribute__((objc_boxable)) some_union {
+ int i;
+ float f;
+ };
+ typedef struct __attribute__((objc_boxable)) _some_struct some_struct;
+
+ // ...
+
+ some_struct ss;
+ NSValue *boxed = @(ss);
+
+
+objc_method_family
+------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "X","","","", ""
+
+Many methods in Objective-C have conventional meanings determined by their
+selectors. It is sometimes useful to be able to mark a method as having a
+particular conventional meaning despite not having the right selector, or as
+not having the conventional meaning that its selector would suggest. For these
+use cases, we provide an attribute to specifically describe the "method family"
+that a method belongs to.
+
+**Usage**: ``__attribute__((objc_method_family(X)))``, where ``X`` is one of
+``none``, ``alloc``, ``copy``, ``init``, ``mutableCopy``, or ``new``. This
+attribute can only be placed at the end of a method declaration:
+
+.. code-block:: objc
+
+ - (NSString *)initMyStringValue __attribute__((objc_method_family(none)));
+
+Users who do not wish to change the conventional meaning of a method, and who
+merely want to document its non-standard retain and release semantics, should
+use the retaining behavior attributes (``ns_returns_retained``,
+``ns_returns_not_retained``, etc).
+
+Query for this feature with ``__has_attribute(objc_method_family)``.
+
+
+objc_requires_super
+-------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "X","","","", ""
+
+Some Objective-C classes allow a subclass to override a particular method in a
+parent class but expect that the overriding method also calls the overridden
+method in the parent class. For these cases, we provide an attribute to
+designate that a method requires a "call to ``super``" in the overriding
+method in the subclass.
+
+**Usage**: ``__attribute__((objc_requires_super))``. This attribute can only
+be placed at the end of a method declaration:
+
+.. code-block:: objc
+
+ - (void)foo __attribute__((objc_requires_super));
+
+This attribute can only be applied the method declarations within a class, and
+not a protocol. Currently this attribute does not enforce any placement of
+where the call occurs in the overriding method (such as in the case of
+``-dealloc`` where the call must appear at the end). It checks only that it
+exists.
+
+Note that on both OS X and iOS that the Foundation framework provides a
+convenience macro ``NS_REQUIRES_SUPER`` that provides syntactic sugar for this
+attribute:
+
+.. code-block:: objc
+
+ - (void)foo NS_REQUIRES_SUPER;
+
+This macro is conditionally defined depending on the compiler's support for
+this attribute. If the compiler does not support the attribute the macro
+expands to nothing.
+
+Operationally, when a method has this annotation the compiler will warn if the
+implementation of an override in a subclass does not call super. For example:
+
+.. code-block:: objc
+
+ warning: method possibly missing a [super AnnotMeth] call
+ - (void) AnnotMeth{};
+ ^
+
+
+objc_runtime_name
+-----------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "X","","","", ""
+
+By default, the Objective-C interface or protocol identifier is used
+in the metadata name for that object. The `objc_runtime_name`
+attribute allows annotated interfaces or protocols to use the
+specified string argument in the object's metadata name instead of the
+default name.
+
+**Usage**: ``__attribute__((objc_runtime_name("MyLocalName")))``. This attribute
+can only be placed before an @protocol or @interface declaration:
+
+.. code-block:: objc
+
+ __attribute__((objc_runtime_name("MyLocalName")))
+ @interface Message
+ @end
+
+
+objc_runtime_visible
+--------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "X","","","", ""
+
+This attribute specifies that the Objective-C class to which it applies is visible to the Objective-C runtime but not to the linker. Classes annotated with this attribute cannot be subclassed and cannot have categories defined for them.
+
+
+optnone (clang::optnone)
+------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "X","X","","", ""
+
+The ``optnone`` attribute suppresses essentially all optimizations
+on a function or method, regardless of the optimization level applied to
+the compilation unit as a whole. This is particularly useful when you
+need to debug a particular function, but it is infeasible to build the
+entire application without optimization. Avoiding optimization on the
+specified function can improve the quality of the debugging information
+for that function.
+
+This attribute is incompatible with the ``always_inline`` and ``minsize``
+attributes.
+
+
+overloadable
+------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "X","","","", ""
+
+Clang provides support for C++ function overloading in C. Function overloading
+in C is introduced using the ``overloadable`` attribute. For example, one
+might provide several overloaded versions of a ``tgsin`` function that invokes
+the appropriate standard function computing the sine of a value with ``float``,
+``double``, or ``long double`` precision:
+
+.. code-block:: c
+
+ #include <math.h>
+ float __attribute__((overloadable)) tgsin(float x) { return sinf(x); }
+ double __attribute__((overloadable)) tgsin(double x) { return sin(x); }
+ long double __attribute__((overloadable)) tgsin(long double x) { return sinl(x); }
+
+Given these declarations, one can call ``tgsin`` with a ``float`` value to
+receive a ``float`` result, with a ``double`` to receive a ``double`` result,
+etc. Function overloading in C follows the rules of C++ function overloading
+to pick the best overload given the call arguments, with a few C-specific
+semantics:
+
+* Conversion from ``float`` or ``double`` to ``long double`` is ranked as a
+ floating-point promotion (per C99) rather than as a floating-point conversion
+ (as in C++).
+
+* A conversion from a pointer of type ``T*`` to a pointer of type ``U*`` is
+ considered a pointer conversion (with conversion rank) if ``T`` and ``U`` are
+ compatible types.
+
+* A conversion from type ``T`` to a value of type ``U`` is permitted if ``T``
+ and ``U`` are compatible types. This conversion is given "conversion" rank.
+
+* If no viable candidates are otherwise available, we allow a conversion from a
+ pointer of type ``T*`` to a pointer of type ``U*``, where ``T`` and ``U`` are
+ incompatible. This conversion is ranked below all other types of conversions.
+ Please note: ``U`` lacking qualifiers that are present on ``T`` is sufficient
+ for ``T`` and ``U`` to be incompatible.
+
+The declaration of ``overloadable`` functions is restricted to function
+declarations and definitions. Most importantly, if any function with a given
+name is given the ``overloadable`` attribute, then all function declarations
+and definitions with that name (and in that scope) must have the
+``overloadable`` attribute. This rule even applies to redeclarations of
+functions whose original declaration had the ``overloadable`` attribute, e.g.,
+
+.. code-block:: c
+
+ int f(int) __attribute__((overloadable));
+ float f(float); // error: declaration of "f" must have the "overloadable" attribute
+
+ int g(int) __attribute__((overloadable));
+ int g(int) { } // error: redeclaration of "g" must also have the "overloadable" attribute
+
+Functions marked ``overloadable`` must have prototypes. Therefore, the
+following code is ill-formed:
+
+.. code-block:: c
+
+ int h() __attribute__((overloadable)); // error: h does not have a prototype
+
+However, ``overloadable`` functions are allowed to use a ellipsis even if there
+are no named parameters (as is permitted in C++). This feature is particularly
+useful when combined with the ``unavailable`` attribute:
+
+.. code-block:: c++
+
+ void honeypot(...) __attribute__((overloadable, unavailable)); // calling me is an error
+
+Functions declared with the ``overloadable`` attribute have their names mangled
+according to the same rules as C++ function names. For example, the three
+``tgsin`` functions in our motivating example get the mangled names
+``_Z5tgsinf``, ``_Z5tgsind``, and ``_Z5tgsine``, respectively. There are two
+caveats to this use of name mangling:
+
+* Future versions of Clang may change the name mangling of functions overloaded
+ in C, so you should not depend on an specific mangling. To be completely
+ safe, we strongly urge the use of ``static inline`` with ``overloadable``
+ functions.
+
+* The ``overloadable`` attribute has almost no meaning when used in C++,
+ because names will already be mangled and functions are already overloadable.
+ However, when an ``overloadable`` function occurs within an ``extern "C"``
+ linkage specification, it's name *will* be mangled in the same way as it
+ would in C.
+
+Query for this feature with ``__has_extension(attribute_overloadable)``.
+
+
+release_capability (release_shared_capability, clang::release_capability, clang::release_shared_capability)
+-----------------------------------------------------------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "X","X","","", ""
+
+Marks a function as releasing a capability.
+
+
+kernel
+------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "X","","","", ""
+
+``__attribute__((kernel))`` is used to mark a ``kernel`` function in
+RenderScript.
+
+In RenderScript, ``kernel`` functions are used to express data-parallel
+computations. The RenderScript runtime efficiently parallelizes ``kernel``
+functions to run on computational resources such as multi-core CPUs and GPUs.
+See the RenderScript_ documentation for more information.
+
+.. _RenderScript: https://developer.android.com/guide/topics/renderscript/compute.html
+
+
+target (gnu::target)
+--------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "X","X","","", ""
+
+Clang supports the GNU style ``__attribute__((target("OPTIONS")))`` attribute.
+This attribute may be attached to a function definition and instructs
+the backend to use different code generation options than were passed on the
+command line.
+
+The current set of options correspond to the existing "subtarget features" for
+the target with or without a "-mno-" in front corresponding to the absence
+of the feature, as well as ``arch="CPU"`` which will change the default "CPU"
+for the function.
+
+Example "subtarget features" from the x86 backend include: "mmx", "sse", "sse4.2",
+"avx", "xop" and largely correspond to the machine specific options handled by
+the front end.
+
+
+try_acquire_capability (try_acquire_shared_capability, clang::try_acquire_capability, clang::try_acquire_shared_capability)
+---------------------------------------------------------------------------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "X","X","","", ""
+
+Marks a function that attempts to acquire a capability. This function may fail to
+actually acquire the capability; they accept a Boolean value determining
+whether acquiring the capability means success (true), or failing to acquire
+the capability means success (false).
+
+
+nodiscard, warn_unused_result, clang::warn_unused_result, gnu::warn_unused_result
+---------------------------------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "X","X","","", ""
+
+Clang supports the ability to diagnose when the results of a function call
+expression are discarded under suspicious circumstances. A diagnostic is
+generated when a function or its return type is marked with ``[[nodiscard]]``
+(or ``__attribute__((warn_unused_result))``) and the function call appears as a
+potentially-evaluated discarded-value expression that is not explicitly cast to
+`void`.
+
+.. code-block: c++
+ struct [[nodiscard]] error_info { /*...*/ };
+ error_info enable_missile_safety_mode();
+
+ void launch_missiles();
+ void test_missiles() {
+ enable_missile_safety_mode(); // diagnoses
+ launch_missiles();
+ }
+ error_info &foo();
+ void f() { foo(); } // Does not diagnose, error_info is a reference.
+
+
+xray_always_instrument (clang::xray_always_instrument), xray_never_instrument (clang::xray_never_instrument)
+------------------------------------------------------------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "X","X","","", ""
+
+``__attribute__((xray_always_instrument))`` or ``[[clang::xray_always_instrument]]`` is used to mark member functions (in C++), methods (in Objective C), and free functions (in C, C++, and Objective C) to be instrumented with XRay. This will cause the function to always have space at the beginning and exit points to allow for runtime patching.
+
+Conversely, ``__attribute__((xray_never_instrument))`` or ``[[clang::xray_never_instrument]]`` will inhibit the insertion of these instrumentation points.
+
+If a function has neither of these attributes, they become subject to the XRay heuristics used to determine whether a function should be instrumented or otherwise.
+
+
+Variable Attributes
+===================
+
+
+dllexport (gnu::dllexport)
+--------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "X","X","X","", ""
+
+The ``__declspec(dllexport)`` attribute declares a variable, function, or
+Objective-C interface to be exported from the module. It is available under the
+``-fdeclspec`` flag for compatibility with various compilers. The primary use
+is for COFF object files which explicitly specify what interfaces are available
+for external use. See the dllexport_ documentation on MSDN for more
+information.
+
+.. _dllexport: https://msdn.microsoft.com/en-us/library/3y1sfaz2.aspx
+
+
+dllimport (gnu::dllimport)
+--------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "X","X","X","", ""
+
+The ``__declspec(dllimport)`` attribute declares a variable, function, or
+Objective-C interface to be imported from an external module. It is available
+under the ``-fdeclspec`` flag for compatibility with various compilers. The
+primary use is for COFF object files which explicitly specify what interfaces
+are imported from external modules. See the dllimport_ documentation on MSDN
+for more information.
+
+.. _dllimport: https://msdn.microsoft.com/en-us/library/3y1sfaz2.aspx
+
+
+init_seg
+--------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "","","","", "X"
+
+The attribute applied by ``pragma init_seg()`` controls the section into
+which global initialization function pointers are emitted. It is only
+available with ``-fms-extensions``. Typically, this function pointer is
+emitted into ``.CRT$XCU`` on Windows. The user can change the order of
+initialization by using a different section name with the same
+``.CRT$XC`` prefix and a suffix that sorts lexicographically before or
+after the standard ``.CRT$XCU`` sections. See the init_seg_
+documentation on MSDN for more information.
+
+.. _init_seg: http://msdn.microsoft.com/en-us/library/7977wcck(v=vs.110).aspx
+
+
+nodebug (gnu::nodebug)
+----------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "X","X","","", ""
+
+The ``nodebug`` attribute allows you to suppress debugging information for a
+function or method, or for a variable that is not a parameter or a non-static
+data member.
+
+
+nosvm
+-----
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "X","","","", ""
+
+OpenCL 2.0 supports the optional ``__attribute__((nosvm))`` qualifier for
+pointer variable. It informs the compiler that the pointer does not refer
+to a shared virtual memory region. See OpenCL v2.0 s6.7.2 for details.
+
+Since it is not widely used and has been removed from OpenCL 2.1, it is ignored
+by Clang.
+
+
+pass_object_size
+----------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "X","","","", ""
+
+.. Note:: The mangling of functions with parameters that are annotated with
+ ``pass_object_size`` is subject to change. You can get around this by
+ using ``__asm__("foo")`` to explicitly name your functions, thus preserving
+ your ABI; also, non-overloadable C functions with ``pass_object_size`` are
+ not mangled.
+
+The ``pass_object_size(Type)`` attribute can be placed on function parameters to
+instruct clang to call ``__builtin_object_size(param, Type)`` at each callsite
+of said function, and implicitly pass the result of this call in as an invisible
+argument of type ``size_t`` directly after the parameter annotated with
+``pass_object_size``. Clang will also replace any calls to
+``__builtin_object_size(param, Type)`` in the function by said implicit
+parameter.
+
+Example usage:
+
+.. code-block:: c
+
+ int bzero1(char *const p __attribute__((pass_object_size(0))))
+ __attribute__((noinline)) {
+ int i = 0;
+ for (/**/; i < (int)__builtin_object_size(p, 0); ++i) {
+ p[i] = 0;
+ }
+ return i;
+ }
+
+ int main() {
+ char chars[100];
+ int n = bzero1(&chars[0]);
+ assert(n == sizeof(chars));
+ return 0;
+ }
+
+If successfully evaluating ``__builtin_object_size(param, Type)`` at the
+callsite is not possible, then the "failed" value is passed in. So, using the
+definition of ``bzero1`` from above, the following code would exit cleanly:
+
+.. code-block:: c
+
+ int main2(int argc, char *argv[]) {
+ int n = bzero1(argv);
+ assert(n == -1);
+ return 0;
+ }
+
+``pass_object_size`` plays a part in overload resolution. If two overload
+candidates are otherwise equally good, then the overload with one or more
+parameters with ``pass_object_size`` is preferred. This implies that the choice
+between two identical overloads both with ``pass_object_size`` on one or more
+parameters will always be ambiguous; for this reason, having two such overloads
+is illegal. For example:
+
+.. code-block:: c++
+
+ #define PS(N) __attribute__((pass_object_size(N)))
+ // OK
+ void Foo(char *a, char *b); // Overload A
+ // OK -- overload A has no parameters with pass_object_size.
+ void Foo(char *a PS(0), char *b PS(0)); // Overload B
+ // Error -- Same signature (sans pass_object_size) as overload B, and both
+ // overloads have one or more parameters with the pass_object_size attribute.
+ void Foo(void *a PS(0), void *b);
+
+ // OK
+ void Bar(void *a PS(0)); // Overload C
+ // OK
+ void Bar(char *c PS(1)); // Overload D
+
+ void main() {
+ char known[10], *unknown;
+ Foo(unknown, unknown); // Calls overload B
+ Foo(known, unknown); // Calls overload B
+ Foo(unknown, known); // Calls overload B
+ Foo(known, known); // Calls overload B
+
+ Bar(known); // Calls overload D
+ Bar(unknown); // Calls overload D
+ }
+
+Currently, ``pass_object_size`` is a bit restricted in terms of its usage:
+
+* Only one use of ``pass_object_size`` is allowed per parameter.
+
+* It is an error to take the address of a function with ``pass_object_size`` on
+ any of its parameters. If you wish to do this, you can create an overload
+ without ``pass_object_size`` on any parameters.
+
+* It is an error to apply the ``pass_object_size`` attribute to parameters that
+ are not pointers. Additionally, any parameter that ``pass_object_size`` is
+ applied to must be marked ``const`` at its function's definition.
+
+
+require_constant_initialization (clang::require_constant_initialization)
+------------------------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "X","X","","", ""
+
+This attribute specifies that the variable to which it is attached is intended
+to have a `constant initializer <http://en.cppreference.com/w/cpp/language/constant_initialization>`_
+according to the rules of [basic.start.static]. The variable is required to
+have static or thread storage duration. If the initialization of the variable
+is not a constant initializer an error will be produced. This attribute may
+only be used in C++.
+
+Note that in C++03 strict constant expression checking is not done. Instead
+the attribute reports if Clang can emit the variable as a constant, even if it's
+not technically a 'constant initializer'. This behavior is non-portable.
+
+Static storage duration variables with constant initializers avoid hard-to-find
+bugs caused by the indeterminate order of dynamic initialization. They can also
+be safely used during dynamic initialization across translation units.
+
+This attribute acts as a compile time assertion that the requirements
+for constant initialization have been met. Since these requirements change
+between dialects and have subtle pitfalls it's important to fail fast instead
+of silently falling back on dynamic initialization.
+
+.. code-block:: c++
+
+ // -std=c++14
+ #define SAFE_STATIC [[clang::require_constant_initialization]]
+ struct T {
+ constexpr T(int) {}
+ ~T(); // non-trivial
+ };
+ SAFE_STATIC T x = {42}; // Initialization OK. Doesn't check destructor.
+ SAFE_STATIC T y = 42; // error: variable does not have a constant initializer
+ // copy initialization is not a constant expression on a non-literal type.
+
+
+section (gnu::section, __declspec(allocate))
+--------------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "X","X","X","", ""
+
+The ``section`` attribute allows you to specify a specific section a
+global variable or function should be in after translation.
+
+
+swiftcall (gnu::swiftcall)
+--------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "X","X","","", ""
+
+The ``swiftcall`` attribute indicates that a function should be called
+using the Swift calling convention for a function or function pointer.
+
+The lowering for the Swift calling convention, as described by the Swift
+ABI documentation, occurs in multiple phases. The first, "high-level"
+phase breaks down the formal parameters and results into innately direct
+and indirect components, adds implicit paraameters for the generic
+signature, and assigns the context and error ABI treatments to parameters
+where applicable. The second phase breaks down the direct parameters
+and results from the first phase and assigns them to registers or the
+stack. The ``swiftcall`` convention only handles this second phase of
+lowering; the C function type must accurately reflect the results
+of the first phase, as follows:
+
+- Results classified as indirect by high-level lowering should be
+ represented as parameters with the ``swift_indirect_result`` attribute.
+
+- Results classified as direct by high-level lowering should be represented
+ as follows:
+
+ - First, remove any empty direct results.
+
+ - If there are no direct results, the C result type should be ``void``.
+
+ - If there is one direct result, the C result type should be a type with
+ the exact layout of that result type.
+
+ - If there are a multiple direct results, the C result type should be
+ a struct type with the exact layout of a tuple of those results.
+
+- Parameters classified as indirect by high-level lowering should be
+ represented as parameters of pointer type.
+
+- Parameters classified as direct by high-level lowering should be
+ omitted if they are empty types; otherwise, they should be represented
+ as a parameter type with a layout exactly matching the layout of the
+ Swift parameter type.
+
+- The context parameter, if present, should be represented as a trailing
+ parameter with the ``swift_context`` attribute.
+
+- The error result parameter, if present, should be represented as a
+ trailing parameter (always following a context parameter) with the
+ ``swift_error_result`` attribute.
+
+``swiftcall`` does not support variadic arguments or unprototyped functions.
+
+The parameter ABI treatment attributes are aspects of the function type.
+A function type which which applies an ABI treatment attribute to a
+parameter is a different type from an otherwise-identical function type
+that does not. A single parameter may not have multiple ABI treatment
+attributes.
+
+Support for this feature is target-dependent, although it should be
+supported on every target that Swift supports. Query for this support
+with ``__has_attribute(swiftcall)``. This implies support for the
+``swift_context``, ``swift_error_result``, and ``swift_indirect_result``
+attributes.
+
+
+swift_context (gnu::swift_context)
+----------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "X","X","","", ""
+
+The ``swift_context`` attribute marks a parameter of a ``swiftcall``
+function as having the special context-parameter ABI treatment.
+
+This treatment generally passes the context value in a special register
+which is normally callee-preserved.
+
+A ``swift_context`` parameter must either be the last parameter or must be
+followed by a ``swift_error_result`` parameter (which itself must always be
+the last parameter).
+
+A context parameter must have pointer or reference type.
+
+
+swift_error_result (gnu::swift_error_result)
+--------------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "X","X","","", ""
+
+The ``swift_error_result`` attribute marks a parameter of a ``swiftcall``
+function as having the special error-result ABI treatment.
+
+This treatment generally passes the underlying error value in and out of
+the function through a special register which is normally callee-preserved.
+This is modeled in C by pretending that the register is addressable memory:
+
+- The caller appears to pass the address of a variable of pointer type.
+ The current value of this variable is copied into the register before
+ the call; if the call returns normally, the value is copied back into the
+ variable.
+
+- The callee appears to receive the address of a variable. This address
+ is actually a hidden location in its own stack, initialized with the
+ value of the register upon entry. When the function returns normally,
+ the value in that hidden location is written back to the register.
+
+A ``swift_error_result`` parameter must be the last parameter, and it must be
+preceded by a ``swift_context`` parameter.
+
+A ``swift_error_result`` parameter must have type ``T**`` or ``T*&`` for some
+type T. Note that no qualifiers are permitted on the intermediate level.
+
+It is undefined behavior if the caller does not pass a pointer or
+reference to a valid object.
+
+The standard convention is that the error value itself (that is, the
+value stored in the apparent argument) will be null upon function entry,
+but this is not enforced by the ABI.
+
+
+swift_indirect_result (gnu::swift_indirect_result)
+--------------------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "X","X","","", ""
+
+The ``swift_indirect_result`` attribute marks a parameter of a ``swiftcall``
+function as having the special indirect-result ABI treatment.
+
+This treatment gives the parameter the target's normal indirect-result
+ABI treatment, which may involve passing it differently from an ordinary
+parameter. However, only the first indirect result will receive this
+treatment. Furthermore, low-level lowering may decide that a direct result
+must be returned indirectly; if so, this will take priority over the
+``swift_indirect_result`` parameters.
+
+A ``swift_indirect_result`` parameter must either be the first parameter or
+follow another ``swift_indirect_result`` parameter.
+
+A ``swift_indirect_result`` parameter must have type ``T*`` or ``T&`` for
+some object type ``T``. If ``T`` is a complete type at the point of
+definition of a function, it is undefined behavior if the argument
+value does not point to storage of adequate size and alignment for a
+value of type ``T``.
+
+Making indirect results explicit in the signature allows C functions to
+directly construct objects into them without relying on language
+optimizations like C++'s named return value optimization (NRVO).
+
+
+tls_model (gnu::tls_model)
+--------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "X","X","","", ""
+
+The ``tls_model`` attribute allows you to specify which thread-local storage
+model to use. It accepts the following strings:
+
+* global-dynamic
+* local-dynamic
+* initial-exec
+* local-exec
+
+TLS models are mutually exclusive.
+
+
+thread
+------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "","","X","", ""
+
+The ``__declspec(thread)`` attribute declares a variable with thread local
+storage. It is available under the ``-fms-extensions`` flag for MSVC
+compatibility. See the documentation for `__declspec(thread)`_ on MSDN.
+
+.. _`__declspec(thread)`: http://msdn.microsoft.com/en-us/library/9w1sdazb.aspx
+
+In Clang, ``__declspec(thread)`` is generally equivalent in functionality to the
+GNU ``__thread`` keyword. The variable must not have a destructor and must have
+a constant initializer, if any. The attribute only applies to variables
+declared with static storage duration, such as globals, class static data
+members, and static locals.
+
+
+maybe_unused, unused, gnu::unused
+---------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "X","X","","", ""
+
+When passing the ``-Wunused`` flag to Clang, entities that are unused by the
+program may be diagnosed. The ``[[maybe_unused]]`` (or
+``__attribute__((unused))``) attribute can be used to silence such diagnostics
+when the entity cannot be removed. For instance, a local variable may exist
+solely for use in an ``assert()`` statement, which makes the local variable
+unused when ``NDEBUG`` is defined.
+
+The attribute may be applied to the declaration of a class, a typedef, a
+variable, a function or method, a function parameter, an enumeration, an
+enumerator, a non-static data member, or a label.
+
+.. code-block: c++
+ #include <cassert>
+
+ [[maybe_unused]] void f([[maybe_unused]] bool thing1,
+ [[maybe_unused]] bool thing2) {
+ [[maybe_unused]] bool b = thing1 && thing2;
+ assert(b);
+ }
+
+
+Type Attributes
+===============
+
+
+align_value
+-----------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "X","","","", ""
+
+The align_value attribute can be added to the typedef of a pointer type or the
+declaration of a variable of pointer or reference type. It specifies that the
+pointer will point to, or the reference will bind to, only objects with at
+least the provided alignment. This alignment value must be some positive power
+of 2.
+
+ .. code-block:: c
+
+ typedef double * aligned_double_ptr __attribute__((align_value(64)));
+ void foo(double & x __attribute__((align_value(128)),
+ aligned_double_ptr y) { ... }
+
+If the pointer value does not have the specified alignment at runtime, the
+behavior of the program is undefined.
+
+
+empty_bases
+-----------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "","","X","", ""
+
+The empty_bases attribute permits the compiler to utilize the
+empty-base-optimization more frequently.
+This attribute only applies to struct, class, and union types.
+It is only supported when using the Microsoft C++ ABI.
+
+
+flag_enum
+---------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "X","","","", ""
+
+This attribute can be added to an enumerator to signal to the compiler that it
+is intended to be used as a flag type. This will cause the compiler to assume
+that the range of the type includes all of the values that you can get by
+manipulating bits of the enumerator when issuing warnings.
+
+
+lto_visibility_public (clang::lto_visibility_public)
+----------------------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "","X","","", ""
+
+See :doc:`LTOVisibility`.
+
+
+layout_version
+--------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "","","X","", ""
+
+The layout_version attribute requests that the compiler utilize the class
+layout rules of a particular compiler version.
+This attribute only applies to struct, class, and union types.
+It is only supported when using the Microsoft C++ ABI.
+
+
+__single_inhertiance, __multiple_inheritance, __virtual_inheritance
+-------------------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "","","","X", ""
+
+This collection of keywords is enabled under ``-fms-extensions`` and controls
+the pointer-to-member representation used on ``*-*-win32`` targets.
+
+The ``*-*-win32`` targets utilize a pointer-to-member representation which
+varies in size and alignment depending on the definition of the underlying
+class.
+
+However, this is problematic when a forward declaration is only available and
+no definition has been made yet. In such cases, Clang is forced to utilize the
+most general representation that is available to it.
+
+These keywords make it possible to use a pointer-to-member representation other
+than the most general one regardless of whether or not the definition will ever
+be present in the current translation unit.
+
+This family of keywords belong between the ``class-key`` and ``class-name``:
+
+.. code-block:: c++
+
+ struct __single_inheritance S;
+ int S::*i;
+ struct S {};
+
+This keyword can be applied to class templates but only has an effect when used
+on full specializations:
+
+.. code-block:: c++
+
+ template <typename T, typename U> struct __single_inheritance A; // warning: inheritance model ignored on primary template
+ template <typename T> struct __multiple_inheritance A<T, T>; // warning: inheritance model ignored on partial specialization
+ template <> struct __single_inheritance A<int, float>;
+
+Note that choosing an inheritance model less general than strictly necessary is
+an error:
+
+.. code-block:: c++
+
+ struct __multiple_inheritance S; // error: inheritance model does not match definition
+ int S::*i;
+ struct S {};
+
+
+novtable
+--------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "","","X","", ""
+
+This attribute can be added to a class declaration or definition to signal to
+the compiler that constructors and destructors will not reference the virtual
+function table. It is only supported when using the Microsoft C++ ABI.
+
+
+objc_subclassing_restricted
+---------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "X","","","", ""
+
+This attribute can be added to an Objective-C ``@interface`` declaration to
+ensure that this class cannot be subclassed.
+
+
+transparent_union (gnu::transparent_union)
+------------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "X","X","","", ""
+
+This attribute can be applied to a union to change the behaviour of calls to
+functions that have an argument with a transparent union type. The compiler
+behaviour is changed in the following manner:
+
+- A value whose type is any member of the transparent union can be passed as an
+ argument without the need to cast that value.
+
+- The argument is passed to the function using the calling convention of the
+ first member of the transparent union. Consequently, all the members of the
+ transparent union should have the same calling convention as its first member.
+
+Transparent unions are not supported in C++.
+
+
+Statement Attributes
+====================
+
+
+fallthrough, clang::fallthrough
+-------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "","X","","", ""
+
+The ``fallthrough`` (or ``clang::fallthrough``) attribute is used
+to annotate intentional fall-through
+between switch labels. It can only be applied to a null statement placed at a
+point of execution between any statement and the next switch label. It is
+common to mark these places with a specific comment, but this attribute is
+meant to replace comments with a more strict annotation, which can be checked
+by the compiler. This attribute doesn't change semantics of the code and can
+be used wherever an intended fall-through occurs. It is designed to mimic
+control-flow statements like ``break;``, so it can be placed in most places
+where ``break;`` can, but only if there are no statements on the execution path
+between it and the next switch label.
+
+By default, Clang does not warn on unannotated fallthrough from one ``switch``
+case to another. Diagnostics on fallthrough without a corresponding annotation
+can be enabled with the ``-Wimplicit-fallthrough`` argument.
+
+Here is an example:
+
+.. code-block:: c++
+
+ // compile with -Wimplicit-fallthrough
+ switch (n) {
+ case 22:
+ case 33: // no warning: no statements between case labels
+ f();
+ case 44: // warning: unannotated fall-through
+ g();
+ [[clang::fallthrough]];
+ case 55: // no warning
+ if (x) {
+ h();
+ break;
+ }
+ else {
+ i();
+ [[clang::fallthrough]];
+ }
+ case 66: // no warning
+ p();
+ [[clang::fallthrough]]; // warning: fallthrough annotation does not
+ // directly precede case label
+ q();
+ case 77: // warning: unannotated fall-through
+ r();
+ }
+
+
+#pragma clang loop
+------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "","","","", "X"
+
+The ``#pragma clang loop`` directive allows loop optimization hints to be
+specified for the subsequent loop. The directive allows vectorization,
+interleaving, and unrolling to be enabled or disabled. Vector width as well
+as interleave and unrolling count can be manually specified. See
+`language extensions
+<http://clang.llvm.org/docs/LanguageExtensions.html#extensions-for-loop-hint-optimizations>`_
+for details.
+
+
+#pragma unroll, #pragma nounroll
+--------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "","","","", "X"
+
+Loop unrolling optimization hints can be specified with ``#pragma unroll`` and
+``#pragma nounroll``. The pragma is placed immediately before a for, while,
+do-while, or c++11 range-based for loop.
+
+Specifying ``#pragma unroll`` without a parameter directs the loop unroller to
+attempt to fully unroll the loop if the trip count is known at compile time and
+attempt to partially unroll the loop if the trip count is not known at compile
+time:
+
+.. code-block:: c++
+
+ #pragma unroll
+ for (...) {
+ ...
+ }
+
+Specifying the optional parameter, ``#pragma unroll _value_``, directs the
+unroller to unroll the loop ``_value_`` times. The parameter may optionally be
+enclosed in parentheses:
+
+.. code-block:: c++
+
+ #pragma unroll 16
+ for (...) {
+ ...
+ }
+
+ #pragma unroll(16)
+ for (...) {
+ ...
+ }
+
+Specifying ``#pragma nounroll`` indicates that the loop should not be unrolled:
+
+.. code-block:: c++
+
+ #pragma nounroll
+ for (...) {
+ ...
+ }
+
+``#pragma unroll`` and ``#pragma unroll _value_`` have identical semantics to
+``#pragma clang loop unroll(full)`` and
+``#pragma clang loop unroll_count(_value_)`` respectively. ``#pragma nounroll``
+is equivalent to ``#pragma clang loop unroll(disable)``. See
+`language extensions
+<http://clang.llvm.org/docs/LanguageExtensions.html#extensions-for-loop-hint-optimizations>`_
+for further details including limitations of the unroll hints.
+
+
+__read_only, __write_only, __read_write (read_only, write_only, read_write)
+---------------------------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "","","","X", ""
+
+The access qualifiers must be used with image object arguments or pipe arguments
+to declare if they are being read or written by a kernel or function.
+
+The read_only/__read_only, write_only/__write_only and read_write/__read_write
+names are reserved for use as access qualifiers and shall not be used otherwise.
+
+.. code-block:: c
+
+ kernel void
+ foo (read_only image2d_t imageA,
+ write_only image2d_t imageB) {
+ ...
+ }
+
+In the above example imageA is a read-only 2D image object, and imageB is a
+write-only 2D image object.
+
+The read_write (or __read_write) qualifier can not be used with pipe.
+
+More details can be found in the OpenCL C language Spec v2.0, Section 6.6.
+
+
+__attribute__((opencl_unroll_hint))
+-----------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "X","","","", ""
+
+The opencl_unroll_hint attribute qualifier can be used to specify that a loop
+(for, while and do loops) can be unrolled. This attribute qualifier can be
+used to specify full unrolling or partial unrolling by a specified amount.
+This is a compiler hint and the compiler may ignore this directive. See
+`OpenCL v2.0 <https://www.khronos.org/registry/cl/specs/opencl-2.0.pdf>`_
+s6.11.5 for details.
+
+
+Type Safety Checking
+====================
+Clang supports additional attributes to enable checking type safety properties
+that can't be enforced by the C type system. To see warnings produced by these
+checks, ensure that -Wtype-safety is enabled. Use cases include:
+
+* MPI library implementations, where these attributes enable checking that
+ the buffer type matches the passed ``MPI_Datatype``;
+* for HDF5 library there is a similar use case to MPI;
+* checking types of variadic functions' arguments for functions like
+ ``fcntl()`` and ``ioctl()``.
+
+You can detect support for these attributes with ``__has_attribute()``. For
+example:
+
+.. code-block:: c++
+
+ #if defined(__has_attribute)
+ # if __has_attribute(argument_with_type_tag) && \
+ __has_attribute(pointer_with_type_tag) && \
+ __has_attribute(type_tag_for_datatype)
+ # define ATTR_MPI_PWT(buffer_idx, type_idx) __attribute__((pointer_with_type_tag(mpi,buffer_idx,type_idx)))
+ /* ... other macros ... */
+ # endif
+ #endif
+
+ #if !defined(ATTR_MPI_PWT)
+ # define ATTR_MPI_PWT(buffer_idx, type_idx)
+ #endif
+
+ int MPI_Send(void *buf, int count, MPI_Datatype datatype /*, other args omitted */)
+ ATTR_MPI_PWT(1,3);
+
+argument_with_type_tag
+----------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "X","","","", ""
+
+Use ``__attribute__((argument_with_type_tag(arg_kind, arg_idx,
+type_tag_idx)))`` on a function declaration to specify that the function
+accepts a type tag that determines the type of some other argument.
+
+This attribute is primarily useful for checking arguments of variadic functions
+(``pointer_with_type_tag`` can be used in most non-variadic cases).
+
+In the attribute prototype above:
+ * ``arg_kind`` is an identifier that should be used when annotating all
+ applicable type tags.
+ * ``arg_idx`` provides the position of a function argument. The expected type of
+ this function argument will be determined by the function argument specified
+ by ``type_tag_idx``. In the code example below, "3" means that the type of the
+ function's third argument will be determined by ``type_tag_idx``.
+ * ``type_tag_idx`` provides the position of a function argument. This function
+ argument will be a type tag. The type tag will determine the expected type of
+ the argument specified by ``arg_idx``. In the code example below, "2" means
+ that the type tag associated with the function's second argument should agree
+ with the type of the argument specified by ``arg_idx``.
+
+For example:
+
+.. code-block:: c++
+
+ int fcntl(int fd, int cmd, ...)
+ __attribute__(( argument_with_type_tag(fcntl,3,2) ));
+ // The function's second argument will be a type tag; this type tag will
+ // determine the expected type of the function's third argument.
+
+
+pointer_with_type_tag
+---------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "X","","","", ""
+
+Use ``__attribute__((pointer_with_type_tag(ptr_kind, ptr_idx, type_tag_idx)))``
+on a function declaration to specify that the function accepts a type tag that
+determines the pointee type of some other pointer argument.
+
+In the attribute prototype above:
+ * ``ptr_kind`` is an identifier that should be used when annotating all
+ applicable type tags.
+ * ``ptr_idx`` provides the position of a function argument; this function
+ argument will have a pointer type. The expected pointee type of this pointer
+ type will be determined by the function argument specified by
+ ``type_tag_idx``. In the code example below, "1" means that the pointee type
+ of the function's first argument will be determined by ``type_tag_idx``.
+ * ``type_tag_idx`` provides the position of a function argument; this function
+ argument will be a type tag. The type tag will determine the expected pointee
+ type of the pointer argument specified by ``ptr_idx``. In the code example
+ below, "3" means that the type tag associated with the function's third
+ argument should agree with the pointee type of the pointer argument specified
+ by ``ptr_idx``.
+
+For example:
+
+.. code-block:: c++
+
+ typedef int MPI_Datatype;
+ int MPI_Send(void *buf, int count, MPI_Datatype datatype /*, other args omitted */)
+ __attribute__(( pointer_with_type_tag(mpi,1,3) ));
+ // The function's 3rd argument will be a type tag; this type tag will
+ // determine the expected pointee type of the function's 1st argument.
+
+
+type_tag_for_datatype
+---------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "X","","","", ""
+
+When declaring a variable, use
+``__attribute__((type_tag_for_datatype(kind, type)))`` to create a type tag that
+is tied to the ``type`` argument given to the attribute.
+
+In the attribute prototype above:
+ * ``kind`` is an identifier that should be used when annotating all applicable
+ type tags.
+ * ``type`` indicates the name of the type.
+
+Clang supports annotating type tags of two forms.
+
+ * **Type tag that is a reference to a declared identifier.**
+ Use ``__attribute__((type_tag_for_datatype(kind, type)))`` when declaring that
+ identifier:
+
+ .. code-block:: c++
+
+ typedef int MPI_Datatype;
+ extern struct mpi_datatype mpi_datatype_int
+ __attribute__(( type_tag_for_datatype(mpi,int) ));
+ #define MPI_INT ((MPI_Datatype) &mpi_datatype_int)
+ // &mpi_datatype_int is a type tag. It is tied to type "int".
+
+ * **Type tag that is an integral literal.**
+ Declare a ``static const`` variable with an initializer value and attach
+ ``__attribute__((type_tag_for_datatype(kind, type)))`` on that declaration:
+
+ .. code-block:: c++
+
+ typedef int MPI_Datatype;
+ static const MPI_Datatype mpi_datatype_int
+ __attribute__(( type_tag_for_datatype(mpi,int) )) = 42;
+ #define MPI_INT ((MPI_Datatype) 42)
+ // The number 42 is a type tag. It is tied to type "int".
+
+
+The ``type_tag_for_datatype`` attribute also accepts an optional third argument
+that determines how the type of the function argument specified by either
+``arg_idx`` or ``ptr_idx`` is compared against the type associated with the type
+tag. (Recall that for the ``argument_with_type_tag`` attribute, the type of the
+function argument specified by ``arg_idx`` is compared against the type
+associated with the type tag. Also recall that for the ``pointer_with_type_tag``
+attribute, the pointee type of the function argument specified by ``ptr_idx`` is
+compared against the type associated with the type tag.) There are two supported
+values for this optional third argument:
+
+ * ``layout_compatible`` will cause types to be compared according to
+ layout-compatibility rules (In C++11 [class.mem] p 17, 18, see the
+ layout-compatibility rules for two standard-layout struct types and for two
+ standard-layout union types). This is useful when creating a type tag
+ associated with a struct or union type. For example:
+
+ .. code-block:: c++
+
+ /* In mpi.h */
+ typedef int MPI_Datatype;
+ struct internal_mpi_double_int { double d; int i; };
+ extern struct mpi_datatype mpi_datatype_double_int
+ __attribute__(( type_tag_for_datatype(mpi,
+ struct internal_mpi_double_int, layout_compatible) ));
+
+ #define MPI_DOUBLE_INT ((MPI_Datatype) &mpi_datatype_double_int)
+
+ int MPI_Send(void *buf, int count, MPI_Datatype datatype, ...)
+ __attribute__(( pointer_with_type_tag(mpi,1,3) ));
+
+ /* In user code */
+ struct my_pair { double a; int b; };
+ struct my_pair *buffer;
+ MPI_Send(buffer, 1, MPI_DOUBLE_INT /*, ... */); // no warning because the
+ // layout of my_pair is
+ // compatible with that of
+ // internal_mpi_double_int
+
+ struct my_int_pair { int a; int b; }
+ struct my_int_pair *buffer2;
+ MPI_Send(buffer2, 1, MPI_DOUBLE_INT /*, ... */); // warning because the
+ // layout of my_int_pair
+ // does not match that of
+ // internal_mpi_double_int
+
+ * ``must_be_null`` specifies that the function argument specified by either
+ ``arg_idx`` (for the ``argument_with_type_tag`` attribute) or ``ptr_idx`` (for
+ the ``pointer_with_type_tag`` attribute) should be a null pointer constant.
+ The second argument to the ``type_tag_for_datatype`` attribute is ignored. For
+ example:
+
+ .. code-block:: c++
+
+ /* In mpi.h */
+ typedef int MPI_Datatype;
+ extern struct mpi_datatype mpi_datatype_null
+ __attribute__(( type_tag_for_datatype(mpi, void, must_be_null) ));
+
+ #define MPI_DATATYPE_NULL ((MPI_Datatype) &mpi_datatype_null)
+ int MPI_Send(void *buf, int count, MPI_Datatype datatype, ...)
+ __attribute__(( pointer_with_type_tag(mpi,1,3) ));
+
+ /* In user code */
+ struct my_pair { double a; int b; };
+ struct my_pair *buffer;
+ MPI_Send(buffer, 1, MPI_DATATYPE_NULL /*, ... */); // warning: MPI_DATATYPE_NULL
+ // was specified but buffer
+ // is not a null pointer
+
+
+AMD GPU Attributes
+==================
+
+
+amdgpu_flat_work_group_size
+---------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "X","","","", ""
+
+The flat work-group size is the number of work-items in the work-group size
+specified when the kernel is dispatched. It is the product of the sizes of the
+x, y, and z dimension of the work-group.
+
+Clang supports the
+``__attribute__((amdgpu_flat_work_group_size(<min>, <max>)))`` attribute for the
+AMDGPU target. This attribute may be attached to a kernel function definition
+and is an optimization hint.
+
+``<min>`` parameter specifies the minimum flat work-group size, and ``<max>``
+parameter specifies the maximum flat work-group size (must be greater than
+``<min>``) to which all dispatches of the kernel will conform. Passing ``0, 0``
+as ``<min>, <max>`` implies the default behavior (``128, 256``).
+
+If specified, the AMDGPU target backend might be able to produce better machine
+code for barriers and perform scratch promotion by estimating available group
+segment size.
+
+An error will be given if:
+ - Specified values violate subtarget specifications;
+ - Specified values are not compatible with values provided through other
+ attributes.
+
+
+amdgpu_num_sgpr
+---------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "X","","","", ""
+
+Clang supports the ``__attribute__((amdgpu_num_sgpr(<num_sgpr>)))`` and
+``__attribute__((amdgpu_num_vgpr(<num_vgpr>)))`` attributes for the AMDGPU
+target. These attributes may be attached to a kernel function definition and are
+an optimization hint.
+
+If these attributes are specified, then the AMDGPU target backend will attempt
+to limit the number of SGPRs and/or VGPRs used to the specified value(s). The
+number of used SGPRs and/or VGPRs may further be rounded up to satisfy the
+allocation requirements or constraints of the subtarget. Passing ``0`` as
+``num_sgpr`` and/or ``num_vgpr`` implies the default behavior (no limits).
+
+These attributes can be used to test the AMDGPU target backend. It is
+recommended that the ``amdgpu_waves_per_eu`` attribute be used to control
+resources such as SGPRs and VGPRs since it is aware of the limits for different
+subtargets.
+
+An error will be given if:
+ - Specified values violate subtarget specifications;
+ - Specified values are not compatible with values provided through other
+ attributes;
+ - The AMDGPU target backend is unable to create machine code that can meet the
+ request.
+
+
+amdgpu_num_vgpr
+---------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "X","","","", ""
+
+Clang supports the ``__attribute__((amdgpu_num_sgpr(<num_sgpr>)))`` and
+``__attribute__((amdgpu_num_vgpr(<num_vgpr>)))`` attributes for the AMDGPU
+target. These attributes may be attached to a kernel function definition and are
+an optimization hint.
+
+If these attributes are specified, then the AMDGPU target backend will attempt
+to limit the number of SGPRs and/or VGPRs used to the specified value(s). The
+number of used SGPRs and/or VGPRs may further be rounded up to satisfy the
+allocation requirements or constraints of the subtarget. Passing ``0`` as
+``num_sgpr`` and/or ``num_vgpr`` implies the default behavior (no limits).
+
+These attributes can be used to test the AMDGPU target backend. It is
+recommended that the ``amdgpu_waves_per_eu`` attribute be used to control
+resources such as SGPRs and VGPRs since it is aware of the limits for different
+subtargets.
+
+An error will be given if:
+ - Specified values violate subtarget specifications;
+ - Specified values are not compatible with values provided through other
+ attributes;
+ - The AMDGPU target backend is unable to create machine code that can meet the
+ request.
+
+
+amdgpu_waves_per_eu
+-------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "X","","","", ""
+
+A compute unit (CU) is responsible for executing the wavefronts of a work-group.
+It is composed of one or more execution units (EU), which are responsible for
+executing the wavefronts. An EU can have enough resources to maintain the state
+of more than one executing wavefront. This allows an EU to hide latency by
+switching between wavefronts in a similar way to symmetric multithreading on a
+CPU. In order to allow the state for multiple wavefronts to fit on an EU, the
+resources used by a single wavefront have to be limited. For example, the number
+of SGPRs and VGPRs. Limiting such resources can allow greater latency hiding,
+but can result in having to spill some register state to memory.
+
+Clang supports the ``__attribute__((amdgpu_waves_per_eu(<min>[, <max>])))``
+attribute for the AMDGPU target. This attribute may be attached to a kernel
+function definition and is an optimization hint.
+
+``<min>`` parameter specifies the requested minimum number of waves per EU, and
+*optional* ``<max>`` parameter specifies the requested maximum number of waves
+per EU (must be greater than ``<min>`` if specified). If ``<max>`` is omitted,
+then there is no restriction on the maximum number of waves per EU other than
+the one dictated by the hardware for which the kernel is compiled. Passing
+``0, 0`` as ``<min>, <max>`` implies the default behavior (no limits).
+
+If specified, this attribute allows an advanced developer to tune the number of
+wavefronts that are capable of fitting within the resources of an EU. The AMDGPU
+target backend can use this information to limit resources, such as number of
+SGPRs, number of VGPRs, size of available group and private memory segments, in
+such a way that guarantees that at least ``<min>`` wavefronts and at most
+``<max>`` wavefronts are able to fit within the resources of an EU. Requesting
+more wavefronts can hide memory latency but limits available registers which
+can result in spilling. Requesting fewer wavefronts can help reduce cache
+thrashing, but can reduce memory latency hiding.
+
+This attribute controls the machine code generated by the AMDGPU target backend
+to ensure it is capable of meeting the requested values. However, when the
+kernel is executed, there may be other reasons that prevent meeting the request,
+for example, there may be wavefronts from other kernels executing on the EU.
+
+An error will be given if:
+ - Specified values violate subtarget specifications;
+ - Specified values are not compatible with values provided through other
+ attributes;
+ - The AMDGPU target backend is unable to create machine code that can meet the
+ request.
+
+
+Calling Conventions
+===================
+Clang supports several different calling conventions, depending on the target
+platform and architecture. The calling convention used for a function determines
+how parameters are passed, how results are returned to the caller, and other
+low-level details of calling a function.
+
+fastcall (gnu::fastcall, __fastcall, _fastcall)
+-----------------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "X","X","","X", ""
+
+On 32-bit x86 targets, this attribute changes the calling convention of a
+function to use ECX and EDX as register parameters and clear parameters off of
+the stack on return. This convention does not support variadic calls or
+unprototyped functions in C, and has no effect on x86_64 targets. This calling
+convention is supported primarily for compatibility with existing code. Users
+seeking register parameters should use the ``regparm`` attribute, which does
+not require callee-cleanup. See the documentation for `__fastcall`_ on MSDN.
+
+.. _`__fastcall`: http://msdn.microsoft.com/en-us/library/6xa169sk.aspx
+
+
+ms_abi (gnu::ms_abi)
+--------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "X","X","","", ""
+
+On non-Windows x86_64 targets, this attribute changes the calling convention of
+a function to match the default convention used on Windows x86_64. This
+attribute has no effect on Windows targets or non-x86_64 targets.
+
+
+pcs (gnu::pcs)
+--------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "X","X","","", ""
+
+On ARM targets, this attribute can be used to select calling conventions
+similar to ``stdcall`` on x86. Valid parameter values are "aapcs" and
+"aapcs-vfp".
+
+
+preserve_all
+------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "X","","","", ""
+
+On X86-64 and AArch64 targets, this attribute changes the calling convention of
+a function. The ``preserve_all`` calling convention attempts to make the code
+in the caller even less intrusive than the ``preserve_most`` calling convention.
+This calling convention also behaves identical to the ``C`` calling convention
+on how arguments and return values are passed, but it uses a different set of
+caller/callee-saved registers. This removes the burden of saving and
+recovering a large register set before and after the call in the caller. If
+the arguments are passed in callee-saved registers, then they will be
+preserved by the callee across the call. This doesn't apply for values
+returned in callee-saved registers.
+
+- On X86-64 the callee preserves all general purpose registers, except for
+ R11. R11 can be used as a scratch register. Furthermore it also preserves
+ all floating-point registers (XMMs/YMMs).
+
+The idea behind this convention is to support calls to runtime functions
+that don't need to call out to any other functions.
+
+This calling convention, like the ``preserve_most`` calling convention, will be
+used by a future version of the Objective-C runtime and should be considered
+experimental at this time.
+
+
+preserve_most
+-------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "X","","","", ""
+
+On X86-64 and AArch64 targets, this attribute changes the calling convention of
+a function. The ``preserve_most`` calling convention attempts to make the code
+in the caller as unintrusive as possible. This convention behaves identically
+to the ``C`` calling convention on how arguments and return values are passed,
+but it uses a different set of caller/callee-saved registers. This alleviates
+the burden of saving and recovering a large register set before and after the
+call in the caller. If the arguments are passed in callee-saved registers,
+then they will be preserved by the callee across the call. This doesn't
+apply for values returned in callee-saved registers.
+
+- On X86-64 the callee preserves all general purpose registers, except for
+ R11. R11 can be used as a scratch register. Floating-point registers
+ (XMMs/YMMs) are not preserved and need to be saved by the caller.
+
+The idea behind this convention is to support calls to runtime functions
+that have a hot path and a cold path. The hot path is usually a small piece
+of code that doesn't use many registers. The cold path might need to call out to
+another function and therefore only needs to preserve the caller-saved
+registers, which haven't already been saved by the caller. The
+`preserve_most` calling convention is very similar to the ``cold`` calling
+convention in terms of caller/callee-saved registers, but they are used for
+different types of function calls. ``coldcc`` is for function calls that are
+rarely executed, whereas `preserve_most` function calls are intended to be
+on the hot path and definitely executed a lot. Furthermore ``preserve_most``
+doesn't prevent the inliner from inlining the function call.
+
+This calling convention will be used by a future version of the Objective-C
+runtime and should therefore still be considered experimental at this time.
+Although this convention was created to optimize certain runtime calls to
+the Objective-C runtime, it is not limited to this runtime and might be used
+by other runtimes in the future too. The current implementation only
+supports X86-64 and AArch64, but the intention is to support more architectures
+in the future.
+
+
+regcall (gnu::regcall, __regcall)
+---------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "X","X","","X", ""
+
+On x86 targets, this attribute changes the calling convention to
+`__regcall`_ convention. This convention aims to pass as many arguments
+as possible in registers. It also tries to utilize registers for the
+return value whenever it is possible.
+
+.. _`__regcall`: https://software.intel.com/en-us/node/693069
+
+
+regparm (gnu::regparm)
+----------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "X","X","","", ""
+
+On 32-bit x86 targets, the regparm attribute causes the compiler to pass
+the first three integer parameters in EAX, EDX, and ECX instead of on the
+stack. This attribute has no effect on variadic functions, and all parameters
+are passed via the stack as normal.
+
+
+stdcall (gnu::stdcall, __stdcall, _stdcall)
+-------------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "X","X","","X", ""
+
+On 32-bit x86 targets, this attribute changes the calling convention of a
+function to clear parameters off of the stack on return. This convention does
+not support variadic calls or unprototyped functions in C, and has no effect on
+x86_64 targets. This calling convention is used widely by the Windows API and
+COM applications. See the documentation for `__stdcall`_ on MSDN.
+
+.. _`__stdcall`: http://msdn.microsoft.com/en-us/library/zxk0tw93.aspx
+
+
+thiscall (gnu::thiscall, __thiscall, _thiscall)
+-----------------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "X","X","","X", ""
+
+On 32-bit x86 targets, this attribute changes the calling convention of a
+function to use ECX for the first parameter (typically the implicit ``this``
+parameter of C++ methods) and clear parameters off of the stack on return. This
+convention does not support variadic calls or unprototyped functions in C, and
+has no effect on x86_64 targets. See the documentation for `__thiscall`_ on
+MSDN.
+
+.. _`__thiscall`: http://msdn.microsoft.com/en-us/library/ek8tkfbw.aspx
+
+
+vectorcall (__vectorcall, _vectorcall)
+--------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "X","","","X", ""
+
+On 32-bit x86 *and* x86_64 targets, this attribute changes the calling
+convention of a function to pass vector parameters in SSE registers.
+
+On 32-bit x86 targets, this calling convention is similar to ``__fastcall``.
+The first two integer parameters are passed in ECX and EDX. Subsequent integer
+parameters are passed in memory, and callee clears the stack. On x86_64
+targets, the callee does *not* clear the stack, and integer parameters are
+passed in RCX, RDX, R8, and R9 as is done for the default Windows x64 calling
+convention.
+
+On both 32-bit x86 and x86_64 targets, vector and floating point arguments are
+passed in XMM0-XMM5. Homogeneous vector aggregates of up to four elements are
+passed in sequential SSE registers if enough are available. If AVX is enabled,
+256 bit vectors are passed in YMM0-YMM5. Any vector or aggregate type that
+cannot be passed in registers for any reason is passed by reference, which
+allows the caller to align the parameter memory.
+
+See the documentation for `__vectorcall`_ on MSDN for more details.
+
+.. _`__vectorcall`: http://msdn.microsoft.com/en-us/library/dn375768.aspx
+
+
+Consumed Annotation Checking
+============================
+Clang supports additional attributes for checking basic resource management
+properties, specifically for unique objects that have a single owning reference.
+The following attributes are currently supported, although **the implementation
+for these annotations is currently in development and are subject to change.**
+
+callable_when
+-------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "X","","","", ""
+
+Use ``__attribute__((callable_when(...)))`` to indicate what states a method
+may be called in. Valid states are unconsumed, consumed, or unknown. Each
+argument to this attribute must be a quoted string. E.g.:
+
+``__attribute__((callable_when("unconsumed", "unknown")))``
+
+
+consumable
+----------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "X","","","", ""
+
+Each ``class`` that uses any of the typestate annotations must first be marked
+using the ``consumable`` attribute. Failure to do so will result in a warning.
+
+This attribute accepts a single parameter that must be one of the following:
+``unknown``, ``consumed``, or ``unconsumed``.
+
+
+param_typestate
+---------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "X","","","", ""
+
+This attribute specifies expectations about function parameters. Calls to an
+function with annotated parameters will issue a warning if the corresponding
+argument isn't in the expected state. The attribute is also used to set the
+initial state of the parameter when analyzing the function's body.
+
+
+return_typestate
+----------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "X","","","", ""
+
+The ``return_typestate`` attribute can be applied to functions or parameters.
+When applied to a function the attribute specifies the state of the returned
+value. The function's body is checked to ensure that it always returns a value
+in the specified state. On the caller side, values returned by the annotated
+function are initialized to the given state.
+
+When applied to a function parameter it modifies the state of an argument after
+a call to the function returns. The function's body is checked to ensure that
+the parameter is in the expected state before returning.
+
+
+set_typestate
+-------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "X","","","", ""
+
+Annotate methods that transition an object into a new state with
+``__attribute__((set_typestate(new_state)))``. The new state must be
+unconsumed, consumed, or unknown.
+
+
+test_typestate
+--------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "X","","","", ""
+
+Use ``__attribute__((test_typestate(tested_state)))`` to indicate that a method
+returns true if the object is in the specified state..
+
+
+OpenCL Address Spaces
+=====================
+The address space qualifier may be used to specify the region of memory that is
+used to allocate the object. OpenCL supports the following address spaces:
+__generic(generic), __global(global), __local(local), __private(private),
+__constant(constant).
+
+ .. code-block:: c
+
+ __constant int c = ...;
+
+ __generic int* foo(global int* g) {
+ __local int* l;
+ private int p;
+ ...
+ return l;
+ }
+
+More details can be found in the OpenCL C language Spec v2.0, Section 6.5.
+
+constant (__constant)
+---------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "","","","X", ""
+
+The constant address space attribute signals that an object is located in
+a constant (non-modifiable) memory region. It is available to all work items.
+Any type can be annotated with the constant address space attribute. Objects
+with the constant address space qualifier can be declared in any scope and must
+have an initializer.
+
+
+generic (__generic)
+-------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "","","","X", ""
+
+The generic address space attribute is only available with OpenCL v2.0 and later.
+It can be used with pointer types. Variables in global and local scope and
+function parameters in non-kernel functions can have the generic address space
+type attribute. It is intended to be a placeholder for any other address space
+except for '__constant' in OpenCL code which can be used with multiple address
+spaces.
+
+
+global (__global)
+-----------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "","","","X", ""
+
+The global address space attribute specifies that an object is allocated in
+global memory, which is accessible by all work items. The content stored in this
+memory area persists between kernel executions. Pointer types to the global
+address space are allowed as function parameters or local variables. Starting
+with OpenCL v2.0, the global address space can be used with global (program
+scope) variables and static local variable as well.
+
+
+local (__local)
+---------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "","","","X", ""
+
+The local address space specifies that an object is allocated in the local (work
+group) memory area, which is accessible to all work items in the same work
+group. The content stored in this memory region is not accessible after
+the kernel execution ends. In a kernel function scope, any variable can be in
+the local address space. In other scopes, only pointer types to the local address
+space are allowed. Local address space variables cannot have an initializer.
+
+
+private (__private)
+-------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "","","","X", ""
+
+The private address space specifies that an object is allocated in the private
+(work item) memory. Other work items cannot access the same memory area and its
+content is destroyed after work item execution ends. Local variables can be
+declared in the private address space. Function arguments are always in the
+private address space. Kernel function arguments of a pointer or an array type
+cannot point to the private address space.
+
+
+Nullability Attributes
+======================
+Whether a particular pointer may be "null" is an important concern when working with pointers in the C family of languages. The various nullability attributes indicate whether a particular pointer can be null or not, which makes APIs more expressive and can help static analysis tools identify bugs involving null pointers. Clang supports several kinds of nullability attributes: the ``nonnull`` and ``returns_nonnull`` attributes indicate which function or method parameters and result types can never be null, while nullability type qualifiers indicate which pointer types can be null (``_Nullable``) or cannot be null (``_Nonnull``).
+
+The nullability (type) qualifiers express whether a value of a given pointer type can be null (the ``_Nullable`` qualifier), doesn't have a defined meaning for null (the ``_Nonnull`` qualifier), or for which the purpose of null is unclear (the ``_Null_unspecified`` qualifier). Because nullability qualifiers are expressed within the type system, they are more general than the ``nonnull`` and ``returns_nonnull`` attributes, allowing one to express (for example) a nullable pointer to an array of nonnull pointers. Nullability qualifiers are written to the right of the pointer to which they apply. For example:
+
+ .. code-block:: c
+
+ // No meaningful result when 'ptr' is null (here, it happens to be undefined behavior).
+ int fetch(int * _Nonnull ptr) { return *ptr; }
+
+ // 'ptr' may be null.
+ int fetch_or_zero(int * _Nullable ptr) {
+ return ptr ? *ptr : 0;
+ }
+
+ // A nullable pointer to non-null pointers to const characters.
+ const char *join_strings(const char * _Nonnull * _Nullable strings, unsigned n);
+
+In Objective-C, there is an alternate spelling for the nullability qualifiers that can be used in Objective-C methods and properties using context-sensitive, non-underscored keywords. For example:
+
+ .. code-block:: objective-c
+
+ @interface NSView : NSResponder
+ - (nullable NSView *)ancestorSharedWithView:(nonnull NSView *)aView;
+ @property (assign, nullable) NSView *superview;
+ @property (readonly, nonnull) NSArray *subviews;
+ @end
+
+nonnull (gnu::nonnull)
+----------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "X","X","","", ""
+
+The ``nonnull`` attribute indicates that some function parameters must not be null, and can be used in several different ways. It's original usage (`from GCC <https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#Common-Function-Attributes>`_) is as a function (or Objective-C method) attribute that specifies which parameters of the function are nonnull in a comma-separated list. For example:
+
+ .. code-block:: c
+
+ extern void * my_memcpy (void *dest, const void *src, size_t len)
+ __attribute__((nonnull (1, 2)));
+
+Here, the ``nonnull`` attribute indicates that parameters 1 and 2
+cannot have a null value. Omitting the parenthesized list of parameter indices means that all parameters of pointer type cannot be null:
+
+ .. code-block:: c
+
+ extern void * my_memcpy (void *dest, const void *src, size_t len)
+ __attribute__((nonnull));
+
+Clang also allows the ``nonnull`` attribute to be placed directly on a function (or Objective-C method) parameter, eliminating the need to specify the parameter index ahead of type. For example:
+
+ .. code-block:: c
+
+ extern void * my_memcpy (void *dest __attribute__((nonnull)),
+ const void *src __attribute__((nonnull)), size_t len);
+
+Note that the ``nonnull`` attribute indicates that passing null to a non-null parameter is undefined behavior, which the optimizer may take advantage of to, e.g., remove null checks. The ``_Nonnull`` type qualifier indicates that a pointer cannot be null in a more general manner (because it is part of the type system) and does not imply undefined behavior, making it more widely applicable.
+
+
+returns_nonnull (gnu::returns_nonnull)
+--------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "X","X","","", ""
+
+The ``returns_nonnull`` attribute indicates that a particular function (or Objective-C method) always returns a non-null pointer. For example, a particular system ``malloc`` might be defined to terminate a process when memory is not available rather than returning a null pointer:
+
+ .. code-block:: c
+
+ extern void * malloc (size_t size) __attribute__((returns_nonnull));
+
+The ``returns_nonnull`` attribute implies that returning a null pointer is undefined behavior, which the optimizer may take advantage of. The ``_Nonnull`` type qualifier indicates that a pointer cannot be null in a more general manner (because it is part of the type system) and does not imply undefined behavior, making it more widely applicable
+
+
+_Nonnull
+--------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "","","","X", ""
+
+The ``_Nonnull`` nullability qualifier indicates that null is not a meaningful value for a value of the ``_Nonnull`` pointer type. For example, given a declaration such as:
+
+ .. code-block:: c
+
+ int fetch(int * _Nonnull ptr);
+
+a caller of ``fetch`` should not provide a null value, and the compiler will produce a warning if it sees a literal null value passed to ``fetch``. Note that, unlike the declaration attribute ``nonnull``, the presence of ``_Nonnull`` does not imply that passing null is undefined behavior: ``fetch`` is free to consider null undefined behavior or (perhaps for backward-compatibility reasons) defensively handle null.
+
+
+_Null_unspecified
+-----------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "","","","X", ""
+
+The ``_Null_unspecified`` nullability qualifier indicates that neither the ``_Nonnull`` nor ``_Nullable`` qualifiers make sense for a particular pointer type. It is used primarily to indicate that the role of null with specific pointers in a nullability-annotated header is unclear, e.g., due to overly-complex implementations or historical factors with a long-lived API.
+
+
+_Nullable
+---------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+ "","","","X", ""
+
+The ``_Nullable`` nullability qualifier indicates that a value of the ``_Nullable`` pointer type can be null. For example, given:
+
+ .. code-block:: c
+
+ int fetch_or_zero(int * _Nullable ptr);
+
+a caller of ``fetch_or_zero`` can provide null.
+
+
Added: www-releases/trunk/4.0.0/tools/clang/docs/_sources/AutomaticReferenceCounting.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/4.0.0/tools/clang/docs/_sources/AutomaticReferenceCounting.txt?rev=297634&view=auto
==============================================================================
--- www-releases/trunk/4.0.0/tools/clang/docs/_sources/AutomaticReferenceCounting.txt (added)
+++ www-releases/trunk/4.0.0/tools/clang/docs/_sources/AutomaticReferenceCounting.txt Mon Mar 13 11:30:12 2017
@@ -0,0 +1,2288 @@
+.. FIXME: move to the stylesheet or Sphinx plugin
+
+.. raw:: html
+
+ <style>
+ .arc-term { font-style: italic; font-weight: bold; }
+ .revision { font-style: italic; }
+ .when-revised { font-weight: bold; font-style: normal; }
+
+ /*
+ * Automatic numbering is described in this article:
+ * http://dev.opera.com/articles/view/automatic-numbering-with-css-counters/
+ */
+ /*
+ * Automatic numbering for the TOC.
+ * This is wrong from the semantics point of view, since it is an ordered
+ * list, but uses "ul" tag.
+ */
+ div#contents.contents.local ul {
+ counter-reset: toc-section;
+ list-style-type: none;
+ }
+ div#contents.contents.local ul li {
+ counter-increment: toc-section;
+ background: none; // Remove bullets
+ }
+ div#contents.contents.local ul li a.reference:before {
+ content: counters(toc-section, ".") " ";
+ }
+
+ /* Automatic numbering for the body. */
+ body {
+ counter-reset: section subsection subsubsection;
+ }
+ .section h2 {
+ counter-reset: subsection subsubsection;
+ counter-increment: section;
+ }
+ .section h2 a.toc-backref:before {
+ content: counter(section) " ";
+ }
+ .section h3 {
+ counter-reset: subsubsection;
+ counter-increment: subsection;
+ }
+ .section h3 a.toc-backref:before {
+ content: counter(section) "." counter(subsection) " ";
+ }
+ .section h4 {
+ counter-increment: subsubsection;
+ }
+ .section h4 a.toc-backref:before {
+ content: counter(section) "." counter(subsection) "." counter(subsubsection) " ";
+ }
+ </style>
+
+.. role:: arc-term
+.. role:: revision
+.. role:: when-revised
+
+==============================================
+Objective-C Automatic Reference Counting (ARC)
+==============================================
+
+.. contents::
+ :local:
+
+.. _arc.meta:
+
+About this document
+===================
+
+.. _arc.meta.purpose:
+
+Purpose
+-------
+
+The first and primary purpose of this document is to serve as a complete
+technical specification of Automatic Reference Counting. Given a core
+Objective-C compiler and runtime, it should be possible to write a compiler and
+runtime which implements these new semantics.
+
+The secondary purpose is to act as a rationale for why ARC was designed in this
+way. This should remain tightly focused on the technical design and should not
+stray into marketing speculation.
+
+.. _arc.meta.background:
+
+Background
+----------
+
+This document assumes a basic familiarity with C.
+
+:arc-term:`Blocks` are a C language extension for creating anonymous functions.
+Users interact with and transfer block objects using :arc-term:`block
+pointers`, which are represented like a normal pointer. A block may capture
+values from local variables; when this occurs, memory must be dynamically
+allocated. The initial allocation is done on the stack, but the runtime
+provides a ``Block_copy`` function which, given a block pointer, either copies
+the underlying block object to the heap, setting its reference count to 1 and
+returning the new block pointer, or (if the block object is already on the
+heap) increases its reference count by 1. The paired function is
+``Block_release``, which decreases the reference count by 1 and destroys the
+object if the count reaches zero and is on the heap.
+
+Objective-C is a set of language extensions, significant enough to be
+considered a different language. It is a strict superset of C. The extensions
+can also be imposed on C++, producing a language called Objective-C++. The
+primary feature is a single-inheritance object system; we briefly describe the
+modern dialect.
+
+Objective-C defines a new type kind, collectively called the :arc-term:`object
+pointer types`. This kind has two notable builtin members, ``id`` and
+``Class``; ``id`` is the final supertype of all object pointers. The validity
+of conversions between object pointer types is not checked at runtime. Users
+may define :arc-term:`classes`; each class is a type, and the pointer to that
+type is an object pointer type. A class may have a superclass; its pointer
+type is a subtype of its superclass's pointer type. A class has a set of
+:arc-term:`ivars`, fields which appear on all instances of that class. For
+every class *T* there's an associated metaclass; it has no fields, its
+superclass is the metaclass of *T*'s superclass, and its metaclass is a global
+class. Every class has a global object whose class is the class's metaclass;
+metaclasses have no associated type, so pointers to this object have type
+``Class``.
+
+A class declaration (``@interface``) declares a set of :arc-term:`methods`. A
+method has a return type, a list of argument types, and a :arc-term:`selector`:
+a name like ``foo:bar:baz:``, where the number of colons corresponds to the
+number of formal arguments. A method may be an instance method, in which case
+it can be invoked on objects of the class, or a class method, in which case it
+can be invoked on objects of the metaclass. A method may be invoked by
+providing an object (called the :arc-term:`receiver`) and a list of formal
+arguments interspersed with the selector, like so:
+
+.. code-block:: objc
+
+ [receiver foo: fooArg bar: barArg baz: bazArg]
+
+This looks in the dynamic class of the receiver for a method with this name,
+then in that class's superclass, etc., until it finds something it can execute.
+The receiver "expression" may also be the name of a class, in which case the
+actual receiver is the class object for that class, or (within method
+definitions) it may be ``super``, in which case the lookup algorithm starts
+with the static superclass instead of the dynamic class. The actual methods
+dynamically found in a class are not those declared in the ``@interface``, but
+those defined in a separate ``@implementation`` declaration; however, when
+compiling a call, typechecking is done based on the methods declared in the
+``@interface``.
+
+Method declarations may also be grouped into :arc-term:`protocols`, which are not
+inherently associated with any class, but which classes may claim to follow.
+Object pointer types may be qualified with additional protocols that the object
+is known to support.
+
+:arc-term:`Class extensions` are collections of ivars and methods, designed to
+allow a class's ``@interface`` to be split across multiple files; however,
+there is still a primary implementation file which must see the
+``@interface``\ s of all class extensions. :arc-term:`Categories` allow
+methods (but not ivars) to be declared *post hoc* on an arbitrary class; the
+methods in the category's ``@implementation`` will be dynamically added to that
+class's method tables which the category is loaded at runtime, replacing those
+methods in case of a collision.
+
+In the standard environment, objects are allocated on the heap, and their
+lifetime is manually managed using a reference count. This is done using two
+instance methods which all classes are expected to implement: ``retain``
+increases the object's reference count by 1, whereas ``release`` decreases it
+by 1 and calls the instance method ``dealloc`` if the count reaches 0. To
+simplify certain operations, there is also an :arc-term:`autorelease pool`, a
+thread-local list of objects to call ``release`` on later; an object can be
+added to this pool by calling ``autorelease`` on it.
+
+Block pointers may be converted to type ``id``; block objects are laid out in a
+way that makes them compatible with Objective-C objects. There is a builtin
+class that all block objects are considered to be objects of; this class
+implements ``retain`` by adjusting the reference count, not by calling
+``Block_copy``.
+
+.. _arc.meta.evolution:
+
+Evolution
+---------
+
+ARC is under continual evolution, and this document must be updated as the
+language progresses.
+
+If a change increases the expressiveness of the language, for example by
+lifting a restriction or by adding new syntax, the change will be annotated
+with a revision marker, like so:
+
+ ARC applies to Objective-C pointer types, block pointer types, and
+ :when-revised:`[beginning Apple 8.0, LLVM 3.8]` :revision:`BPTRs declared
+ within` ``extern "BCPL"`` blocks.
+
+For now, it is sensible to version this document by the releases of its sole
+implementation (and its host project), clang. "LLVM X.Y" refers to an
+open-source release of clang from the LLVM project. "Apple X.Y" refers to an
+Apple-provided release of the Apple LLVM Compiler. Other organizations that
+prepare their own, separately-versioned clang releases and wish to maintain
+similar information in this document should send requests to cfe-dev.
+
+If a change decreases the expressiveness of the language, for example by
+imposing a new restriction, this should be taken as an oversight in the
+original specification and something to be avoided in all versions. Such
+changes are generally to be avoided.
+
+.. _arc.general:
+
+General
+=======
+
+Automatic Reference Counting implements automatic memory management for
+Objective-C objects and blocks, freeing the programmer from the need to
+explicitly insert retains and releases. It does not provide a cycle collector;
+users must explicitly manage the lifetime of their objects, breaking cycles
+manually or with weak or unsafe references.
+
+ARC may be explicitly enabled with the compiler flag ``-fobjc-arc``. It may
+also be explicitly disabled with the compiler flag ``-fno-objc-arc``. The last
+of these two flags appearing on the compile line "wins".
+
+If ARC is enabled, ``__has_feature(objc_arc)`` will expand to 1 in the
+preprocessor. For more information about ``__has_feature``, see the
+:ref:`language extensions <langext-__has_feature-__has_extension>` document.
+
+.. _arc.objects:
+
+Retainable object pointers
+==========================
+
+This section describes retainable object pointers, their basic operations, and
+the restrictions imposed on their use under ARC. Note in particular that it
+covers the rules for pointer *values* (patterns of bits indicating the location
+of a pointed-to object), not pointer *objects* (locations in memory which store
+pointer values). The rules for objects are covered in the next section.
+
+A :arc-term:`retainable object pointer` (or "retainable pointer") is a value of
+a :arc-term:`retainable object pointer type` ("retainable type"). There are
+three kinds of retainable object pointer types:
+
+* block pointers (formed by applying the caret (``^``) declarator sigil to a
+ function type)
+* Objective-C object pointers (``id``, ``Class``, ``NSFoo*``, etc.)
+* typedefs marked with ``__attribute__((NSObject))``
+
+Other pointer types, such as ``int*`` and ``CFStringRef``, are not subject to
+ARC's semantics and restrictions.
+
+.. admonition:: Rationale
+
+ We are not at liberty to require all code to be recompiled with ARC;
+ therefore, ARC must interoperate with Objective-C code which manages retains
+ and releases manually. In general, there are three requirements in order for
+ a compiler-supported reference-count system to provide reliable
+ interoperation:
+
+ * The type system must reliably identify which objects are to be managed. An
+ ``int*`` might be a pointer to a ``malloc``'ed array, or it might be an
+ interior pointer to such an array, or it might point to some field or local
+ variable. In contrast, values of the retainable object pointer types are
+ never interior.
+
+ * The type system must reliably indicate how to manage objects of a type.
+ This usually means that the type must imply a procedure for incrementing
+ and decrementing retain counts. Supporting single-ownership objects
+ requires a lot more explicit mediation in the language.
+
+ * There must be reliable conventions for whether and when "ownership" is
+ passed between caller and callee, for both arguments and return values.
+ Objective-C methods follow such a convention very reliably, at least for
+ system libraries on Mac OS X, and functions always pass objects at +0. The
+ C-based APIs for Core Foundation objects, on the other hand, have much more
+ varied transfer semantics.
+
+The use of ``__attribute__((NSObject))`` typedefs is not recommended. If it's
+absolutely necessary to use this attribute, be very explicit about using the
+typedef, and do not assume that it will be preserved by language features like
+``__typeof`` and C++ template argument substitution.
+
+.. admonition:: Rationale
+
+ Any compiler operation which incidentally strips type "sugar" from a type
+ will yield a type without the attribute, which may result in unexpected
+ behavior.
+
+.. _arc.objects.retains:
+
+Retain count semantics
+----------------------
+
+A retainable object pointer is either a :arc-term:`null pointer` or a pointer
+to a valid object. Furthermore, if it has block pointer type and is not
+``null`` then it must actually be a pointer to a block object, and if it has
+``Class`` type (possibly protocol-qualified) then it must actually be a pointer
+to a class object. Otherwise ARC does not enforce the Objective-C type system
+as long as the implementing methods follow the signature of the static type.
+It is undefined behavior if ARC is exposed to an invalid pointer.
+
+For ARC's purposes, a valid object is one with "well-behaved" retaining
+operations. Specifically, the object must be laid out such that the
+Objective-C message send machinery can successfully send it the following
+messages:
+
+* ``retain``, taking no arguments and returning a pointer to the object.
+* ``release``, taking no arguments and returning ``void``.
+* ``autorelease``, taking no arguments and returning a pointer to the object.
+
+The behavior of these methods is constrained in the following ways. The term
+:arc-term:`high-level semantics` is an intentionally vague term; the intent is
+that programmers must implement these methods in a way such that the compiler,
+modifying code in ways it deems safe according to these constraints, will not
+violate their requirements. For example, if the user puts logging statements
+in ``retain``, they should not be surprised if those statements are executed
+more or less often depending on optimization settings. These constraints are
+not exhaustive of the optimization opportunities: values held in local
+variables are subject to additional restrictions, described later in this
+document.
+
+It is undefined behavior if a computation history featuring a send of
+``retain`` followed by a send of ``release`` to the same object, with no
+intervening ``release`` on that object, is not equivalent under the high-level
+semantics to a computation history in which these sends are removed. Note that
+this implies that these methods may not raise exceptions.
+
+It is undefined behavior if a computation history features any use whatsoever
+of an object following the completion of a send of ``release`` that is not
+preceded by a send of ``retain`` to the same object.
+
+The behavior of ``autorelease`` must be equivalent to sending ``release`` when
+one of the autorelease pools currently in scope is popped. It may not throw an
+exception.
+
+When the semantics call for performing one of these operations on a retainable
+object pointer, if that pointer is ``null`` then the effect is a no-op.
+
+All of the semantics described in this document are subject to additional
+:ref:`optimization rules <arc.optimization>` which permit the removal or
+optimization of operations based on local knowledge of data flow. The
+semantics describe the high-level behaviors that the compiler implements, not
+an exact sequence of operations that a program will be compiled into.
+
+.. _arc.objects.operands:
+
+Retainable object pointers as operands and arguments
+----------------------------------------------------
+
+In general, ARC does not perform retain or release operations when simply using
+a retainable object pointer as an operand within an expression. This includes:
+
+* loading a retainable pointer from an object with non-weak :ref:`ownership
+ <arc.ownership>`,
+* passing a retainable pointer as an argument to a function or method, and
+* receiving a retainable pointer as the result of a function or method call.
+
+.. admonition:: Rationale
+
+ While this might seem uncontroversial, it is actually unsafe when multiple
+ expressions are evaluated in "parallel", as with binary operators and calls,
+ because (for example) one expression might load from an object while another
+ writes to it. However, C and C++ already call this undefined behavior
+ because the evaluations are unsequenced, and ARC simply exploits that here to
+ avoid needing to retain arguments across a large number of calls.
+
+The remainder of this section describes exceptions to these rules, how those
+exceptions are detected, and what those exceptions imply semantically.
+
+.. _arc.objects.operands.consumed:
+
+Consumed parameters
+^^^^^^^^^^^^^^^^^^^
+
+A function or method parameter of retainable object pointer type may be marked
+as :arc-term:`consumed`, signifying that the callee expects to take ownership
+of a +1 retain count. This is done by adding the ``ns_consumed`` attribute to
+the parameter declaration, like so:
+
+.. code-block:: objc
+
+ void foo(__attribute((ns_consumed)) id x);
+ - (void) foo: (id) __attribute((ns_consumed)) x;
+
+This attribute is part of the type of the function or method, not the type of
+the parameter. It controls only how the argument is passed and received.
+
+When passing such an argument, ARC retains the argument prior to making the
+call.
+
+When receiving such an argument, ARC releases the argument at the end of the
+function, subject to the usual optimizations for local values.
+
+.. admonition:: Rationale
+
+ This formalizes direct transfers of ownership from a caller to a callee. The
+ most common scenario here is passing the ``self`` parameter to ``init``, but
+ it is useful to generalize. Typically, local optimization will remove any
+ extra retains and releases: on the caller side the retain will be merged with
+ a +1 source, and on the callee side the release will be rolled into the
+ initialization of the parameter.
+
+The implicit ``self`` parameter of a method may be marked as consumed by adding
+``__attribute__((ns_consumes_self))`` to the method declaration. Methods in
+the ``init`` :ref:`family <arc.method-families>` are treated as if they were
+implicitly marked with this attribute.
+
+It is undefined behavior if an Objective-C message send to a method with
+``ns_consumed`` parameters (other than self) is made with a null receiver. It
+is undefined behavior if the method to which an Objective-C message send
+statically resolves to has a different set of ``ns_consumed`` parameters than
+the method it dynamically resolves to. It is undefined behavior if a block or
+function call is made through a static type with a different set of
+``ns_consumed`` parameters than the implementation of the called block or
+function.
+
+.. admonition:: Rationale
+
+ Consumed parameters with null receiver are a guaranteed leak. Mismatches
+ with consumed parameters will cause over-retains or over-releases, depending
+ on the direction. The rule about function calls is really just an
+ application of the existing C/C++ rule about calling functions through an
+ incompatible function type, but it's useful to state it explicitly.
+
+.. _arc.object.operands.retained-return-values:
+
+Retained return values
+^^^^^^^^^^^^^^^^^^^^^^
+
+A function or method which returns a retainable object pointer type may be
+marked as returning a retained value, signifying that the caller expects to take
+ownership of a +1 retain count. This is done by adding the
+``ns_returns_retained`` attribute to the function or method declaration, like
+so:
+
+.. code-block:: objc
+
+ id foo(void) __attribute((ns_returns_retained));
+ - (id) foo __attribute((ns_returns_retained));
+
+This attribute is part of the type of the function or method.
+
+When returning from such a function or method, ARC retains the value at the
+point of evaluation of the return statement, before leaving all local scopes.
+
+When receiving a return result from such a function or method, ARC releases the
+value at the end of the full-expression it is contained within, subject to the
+usual optimizations for local values.
+
+.. admonition:: Rationale
+
+ This formalizes direct transfers of ownership from a callee to a caller. The
+ most common scenario this models is the retained return from ``init``,
+ ``alloc``, ``new``, and ``copy`` methods, but there are other cases in the
+ frameworks. After optimization there are typically no extra retains and
+ releases required.
+
+Methods in the ``alloc``, ``copy``, ``init``, ``mutableCopy``, and ``new``
+:ref:`families <arc.method-families>` are implicitly marked
+``__attribute__((ns_returns_retained))``. This may be suppressed by explicitly
+marking the method ``__attribute__((ns_returns_not_retained))``.
+
+It is undefined behavior if the method to which an Objective-C message send
+statically resolves has different retain semantics on its result from the
+method it dynamically resolves to. It is undefined behavior if a block or
+function call is made through a static type with different retain semantics on
+its result from the implementation of the called block or function.
+
+.. admonition:: Rationale
+
+ Mismatches with returned results will cause over-retains or over-releases,
+ depending on the direction. Again, the rule about function calls is really
+ just an application of the existing C/C++ rule about calling functions
+ through an incompatible function type.
+
+.. _arc.objects.operands.unretained-returns:
+
+Unretained return values
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+A method or function which returns a retainable object type but does not return
+a retained value must ensure that the object is still valid across the return
+boundary.
+
+When returning from such a function or method, ARC retains the value at the
+point of evaluation of the return statement, then leaves all local scopes, and
+then balances out the retain while ensuring that the value lives across the
+call boundary. In the worst case, this may involve an ``autorelease``, but
+callers must not assume that the value is actually in the autorelease pool.
+
+ARC performs no extra mandatory work on the caller side, although it may elect
+to do something to shorten the lifetime of the returned value.
+
+.. admonition:: Rationale
+
+ It is common in non-ARC code to not return an autoreleased value; therefore
+ the convention does not force either path. It is convenient to not be
+ required to do unnecessary retains and autoreleases; this permits
+ optimizations such as eliding retain/autoreleases when it can be shown that
+ the original pointer will still be valid at the point of return.
+
+A method or function may be marked with
+``__attribute__((ns_returns_autoreleased))`` to indicate that it returns a
+pointer which is guaranteed to be valid at least as long as the innermost
+autorelease pool. There are no additional semantics enforced in the definition
+of such a method; it merely enables optimizations in callers.
+
+.. _arc.objects.operands.casts:
+
+Bridged casts
+^^^^^^^^^^^^^
+
+A :arc-term:`bridged cast` is a C-style cast annotated with one of three
+keywords:
+
+* ``(__bridge T) op`` casts the operand to the destination type ``T``. If
+ ``T`` is a retainable object pointer type, then ``op`` must have a
+ non-retainable pointer type. If ``T`` is a non-retainable pointer type,
+ then ``op`` must have a retainable object pointer type. Otherwise the cast
+ is ill-formed. There is no transfer of ownership, and ARC inserts no retain
+ operations.
+* ``(__bridge_retained T) op`` casts the operand, which must have retainable
+ object pointer type, to the destination type, which must be a non-retainable
+ pointer type. ARC retains the value, subject to the usual optimizations on
+ local values, and the recipient is responsible for balancing that +1.
+* ``(__bridge_transfer T) op`` casts the operand, which must have
+ non-retainable pointer type, to the destination type, which must be a
+ retainable object pointer type. ARC will release the value at the end of
+ the enclosing full-expression, subject to the usual optimizations on local
+ values.
+
+These casts are required in order to transfer objects in and out of ARC
+control; see the rationale in the section on :ref:`conversion of retainable
+object pointers <arc.objects.restrictions.conversion>`.
+
+Using a ``__bridge_retained`` or ``__bridge_transfer`` cast purely to convince
+ARC to emit an unbalanced retain or release, respectively, is poor form.
+
+.. _arc.objects.restrictions:
+
+Restrictions
+------------
+
+.. _arc.objects.restrictions.conversion:
+
+Conversion of retainable object pointers
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In general, a program which attempts to implicitly or explicitly convert a
+value of retainable object pointer type to any non-retainable type, or
+vice-versa, is ill-formed. For example, an Objective-C object pointer shall
+not be converted to ``void*``. As an exception, cast to ``intptr_t`` is
+allowed because such casts are not transferring ownership. The :ref:`bridged
+casts <arc.objects.operands.casts>` may be used to perform these conversions
+where necessary.
+
+.. admonition:: Rationale
+
+ We cannot ensure the correct management of the lifetime of objects if they
+ may be freely passed around as unmanaged types. The bridged casts are
+ provided so that the programmer may explicitly describe whether the cast
+ transfers control into or out of ARC.
+
+However, the following exceptions apply.
+
+.. _arc.objects.restrictions.conversion.with.known.semantics:
+
+Conversion to retainable object pointer type of expressions with known semantics
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+:when-revised:`[beginning Apple 4.0, LLVM 3.1]`
+:revision:`These exceptions have been greatly expanded; they previously applied
+only to a much-reduced subset which is difficult to categorize but which
+included null pointers, message sends (under the given rules), and the various
+global constants.`
+
+An unbridged conversion to a retainable object pointer type from a type other
+than a retainable object pointer type is ill-formed, as discussed above, unless
+the operand of the cast has a syntactic form which is known retained, known
+unretained, or known retain-agnostic.
+
+An expression is :arc-term:`known retain-agnostic` if it is:
+
+* an Objective-C string literal,
+* a load from a ``const`` system global variable of :ref:`C retainable pointer
+ type <arc.misc.c-retainable>`, or
+* a null pointer constant.
+
+An expression is :arc-term:`known unretained` if it is an rvalue of :ref:`C
+retainable pointer type <arc.misc.c-retainable>` and it is:
+
+* a direct call to a function, and either that function has the
+ ``cf_returns_not_retained`` attribute or it is an :ref:`audited
+ <arc.misc.c-retainable.audit>` function that does not have the
+ ``cf_returns_retained`` attribute and does not follow the create/copy naming
+ convention,
+* a message send, and the declared method either has the
+ ``cf_returns_not_retained`` attribute or it has neither the
+ ``cf_returns_retained`` attribute nor a :ref:`selector family
+ <arc.method-families>` that implies a retained result, or
+* :when-revised:`[beginning LLVM 3.6]` :revision:`a load from a` ``const``
+ :revision:`non-system global variable.`
+
+An expression is :arc-term:`known retained` if it is an rvalue of :ref:`C
+retainable pointer type <arc.misc.c-retainable>` and it is:
+
+* a message send, and the declared method either has the
+ ``cf_returns_retained`` attribute, or it does not have the
+ ``cf_returns_not_retained`` attribute but it does have a :ref:`selector
+ family <arc.method-families>` that implies a retained result.
+
+Furthermore:
+
+* a comma expression is classified according to its right-hand side,
+* a statement expression is classified according to its result expression, if
+ it has one,
+* an lvalue-to-rvalue conversion applied to an Objective-C property lvalue is
+ classified according to the underlying message send, and
+* a conditional operator is classified according to its second and third
+ operands, if they agree in classification, or else the other if one is known
+ retain-agnostic.
+
+If the cast operand is known retained, the conversion is treated as a
+``__bridge_transfer`` cast. If the cast operand is known unretained or known
+retain-agnostic, the conversion is treated as a ``__bridge`` cast.
+
+.. admonition:: Rationale
+
+ Bridging casts are annoying. Absent the ability to completely automate the
+ management of CF objects, however, we are left with relatively poor attempts
+ to reduce the need for a glut of explicit bridges. Hence these rules.
+
+ We've so far consciously refrained from implicitly turning retained CF
+ results from function calls into ``__bridge_transfer`` casts. The worry is
+ that some code patterns --- for example, creating a CF value, assigning it
+ to an ObjC-typed local, and then calling ``CFRelease`` when done --- are a
+ bit too likely to be accidentally accepted, leading to mysterious behavior.
+
+ For loads from ``const`` global variables of :ref:`C retainable pointer type
+ <arc.misc.c-retainable>`, it is reasonable to assume that global system
+ constants were initialitzed with true constants (e.g. string literals), but
+ user constants might have been initialized with something dynamically
+ allocated, using a global initializer.
+
+.. _arc.objects.restrictions.conversion-exception-contextual:
+
+Conversion from retainable object pointer type in certain contexts
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+:when-revised:`[beginning Apple 4.0, LLVM 3.1]`
+
+If an expression of retainable object pointer type is explicitly cast to a
+:ref:`C retainable pointer type <arc.misc.c-retainable>`, the program is
+ill-formed as discussed above unless the result is immediately used:
+
+* to initialize a parameter in an Objective-C message send where the parameter
+ is not marked with the ``cf_consumed`` attribute, or
+* to initialize a parameter in a direct call to an
+ :ref:`audited <arc.misc.c-retainable.audit>` function where the parameter is
+ not marked with the ``cf_consumed`` attribute.
+
+.. admonition:: Rationale
+
+ Consumed parameters are left out because ARC would naturally balance them
+ with a retain, which was judged too treacherous. This is in part because
+ several of the most common consuming functions are in the ``Release`` family,
+ and it would be quite unfortunate for explicit releases to be silently
+ balanced out in this way.
+
+.. _arc.ownership:
+
+Ownership qualification
+=======================
+
+This section describes the behavior of *objects* of retainable object pointer
+type; that is, locations in memory which store retainable object pointers.
+
+A type is a :arc-term:`retainable object owner type` if it is a retainable
+object pointer type or an array type whose element type is a retainable object
+owner type.
+
+An :arc-term:`ownership qualifier` is a type qualifier which applies only to
+retainable object owner types. An array type is ownership-qualified according
+to its element type, and adding an ownership qualifier to an array type so
+qualifies its element type.
+
+A program is ill-formed if it attempts to apply an ownership qualifier to a
+type which is already ownership-qualified, even if it is the same qualifier.
+There is a single exception to this rule: an ownership qualifier may be applied
+to a substituted template type parameter, which overrides the ownership
+qualifier provided by the template argument.
+
+When forming a function type, the result type is adjusted so that any
+top-level ownership qualifier is deleted.
+
+Except as described under the :ref:`inference rules <arc.ownership.inference>`,
+a program is ill-formed if it attempts to form a pointer or reference type to a
+retainable object owner type which lacks an ownership qualifier.
+
+.. admonition:: Rationale
+
+ These rules, together with the inference rules, ensure that all objects and
+ lvalues of retainable object pointer type have an ownership qualifier. The
+ ability to override an ownership qualifier during template substitution is
+ required to counteract the :ref:`inference of __strong for template type
+ arguments <arc.ownership.inference.template.arguments>`. Ownership qualifiers
+ on return types are dropped because they serve no purpose there except to
+ cause spurious problems with overloading and templates.
+
+There are four ownership qualifiers:
+
+* ``__autoreleasing``
+* ``__strong``
+* ``__unsafe_unretained``
+* ``__weak``
+
+A type is :arc-term:`nontrivially ownership-qualified` if it is qualified with
+``__autoreleasing``, ``__strong``, or ``__weak``.
+
+.. _arc.ownership.spelling:
+
+Spelling
+--------
+
+The names of the ownership qualifiers are reserved for the implementation. A
+program may not assume that they are or are not implemented with macros, or
+what those macros expand to.
+
+An ownership qualifier may be written anywhere that any other type qualifier
+may be written.
+
+If an ownership qualifier appears in the *declaration-specifiers*, the
+following rules apply:
+
+* if the type specifier is a retainable object owner type, the qualifier
+ initially applies to that type;
+
+* otherwise, if the outermost non-array declarator is a pointer
+ or block pointer declarator, the qualifier initially applies to
+ that type;
+
+* otherwise the program is ill-formed.
+
+* If the qualifier is so applied at a position in the declaration
+ where the next-innermost declarator is a function declarator, and
+ there is an block declarator within that function declarator, then
+ the qualifier applies instead to that block declarator and this rule
+ is considered afresh beginning from the new position.
+
+If an ownership qualifier appears on the declarator name, or on the declared
+object, it is applied to the innermost pointer or block-pointer type.
+
+If an ownership qualifier appears anywhere else in a declarator, it applies to
+the type there.
+
+.. admonition:: Rationale
+
+ Ownership qualifiers are like ``const`` and ``volatile`` in the sense
+ that they may sensibly apply at multiple distinct positions within a
+ declarator. However, unlike those qualifiers, there are many
+ situations where they are not meaningful, and so we make an effort
+ to "move" the qualifier to a place where it will be meaningful. The
+ general goal is to allow the programmer to write, say, ``__strong``
+ before the entire declaration and have it apply in the leftmost
+ sensible place.
+
+.. _arc.ownership.spelling.property:
+
+Property declarations
+^^^^^^^^^^^^^^^^^^^^^
+
+A property of retainable object pointer type may have ownership. If the
+property's type is ownership-qualified, then the property has that ownership.
+If the property has one of the following modifiers, then the property has the
+corresponding ownership. A property is ill-formed if it has conflicting
+sources of ownership, or if it has redundant ownership modifiers, or if it has
+``__autoreleasing`` ownership.
+
+* ``assign`` implies ``__unsafe_unretained`` ownership.
+* ``copy`` implies ``__strong`` ownership, as well as the usual behavior of
+ copy semantics on the setter.
+* ``retain`` implies ``__strong`` ownership.
+* ``strong`` implies ``__strong`` ownership.
+* ``unsafe_unretained`` implies ``__unsafe_unretained`` ownership.
+* ``weak`` implies ``__weak`` ownership.
+
+With the exception of ``weak``, these modifiers are available in non-ARC
+modes.
+
+A property's specified ownership is preserved in its metadata, but otherwise
+the meaning is purely conventional unless the property is synthesized. If a
+property is synthesized, then the :arc-term:`associated instance variable` is
+the instance variable which is named, possibly implicitly, by the
+``@synthesize`` declaration. If the associated instance variable already
+exists, then its ownership qualification must equal the ownership of the
+property; otherwise, the instance variable is created with that ownership
+qualification.
+
+A property of retainable object pointer type which is synthesized without a
+source of ownership has the ownership of its associated instance variable, if it
+already exists; otherwise, :when-revised:`[beginning Apple 3.1, LLVM 3.1]`
+:revision:`its ownership is implicitly` ``strong``. Prior to this revision, it
+was ill-formed to synthesize such a property.
+
+.. admonition:: Rationale
+
+ Using ``strong`` by default is safe and consistent with the generic ARC rule
+ about :ref:`inferring ownership <arc.ownership.inference.variables>`. It is,
+ unfortunately, inconsistent with the non-ARC rule which states that such
+ properties are implicitly ``assign``. However, that rule is clearly
+ untenable in ARC, since it leads to default-unsafe code. The main merit to
+ banning the properties is to avoid confusion with non-ARC practice, which did
+ not ultimately strike us as sufficient to justify requiring extra syntax and
+ (more importantly) forcing novices to understand ownership rules just to
+ declare a property when the default is so reasonable. Changing the rule away
+ from non-ARC practice was acceptable because we had conservatively banned the
+ synthesis in order to give ourselves exactly this leeway.
+
+Applying ``__attribute__((NSObject))`` to a property not of retainable object
+pointer type has the same behavior it does outside of ARC: it requires the
+property type to be some sort of pointer and permits the use of modifiers other
+than ``assign``. These modifiers only affect the synthesized getter and
+setter; direct accesses to the ivar (even if synthesized) still have primitive
+semantics, and the value in the ivar will not be automatically released during
+deallocation.
+
+.. _arc.ownership.semantics:
+
+Semantics
+---------
+
+There are five :arc-term:`managed operations` which may be performed on an
+object of retainable object pointer type. Each qualifier specifies different
+semantics for each of these operations. It is still undefined behavior to
+access an object outside of its lifetime.
+
+A load or store with "primitive semantics" has the same semantics as the
+respective operation would have on an ``void*`` lvalue with the same alignment
+and non-ownership qualification.
+
+:arc-term:`Reading` occurs when performing a lvalue-to-rvalue conversion on an
+object lvalue.
+
+* For ``__weak`` objects, the current pointee is retained and then released at
+ the end of the current full-expression. This must execute atomically with
+ respect to assignments and to the final release of the pointee.
+* For all other objects, the lvalue is loaded with primitive semantics.
+
+:arc-term:`Assignment` occurs when evaluating an assignment operator. The
+semantics vary based on the qualification:
+
+* For ``__strong`` objects, the new pointee is first retained; second, the
+ lvalue is loaded with primitive semantics; third, the new pointee is stored
+ into the lvalue with primitive semantics; and finally, the old pointee is
+ released. This is not performed atomically; external synchronization must be
+ used to make this safe in the face of concurrent loads and stores.
+* For ``__weak`` objects, the lvalue is updated to point to the new pointee,
+ unless the new pointee is an object currently undergoing deallocation, in
+ which case the lvalue is updated to a null pointer. This must execute
+ atomically with respect to other assignments to the object, to reads from the
+ object, and to the final release of the new pointee.
+* For ``__unsafe_unretained`` objects, the new pointee is stored into the
+ lvalue using primitive semantics.
+* For ``__autoreleasing`` objects, the new pointee is retained, autoreleased,
+ and stored into the lvalue using primitive semantics.
+
+:arc-term:`Initialization` occurs when an object's lifetime begins, which
+depends on its storage duration. Initialization proceeds in two stages:
+
+#. First, a null pointer is stored into the lvalue using primitive semantics.
+ This step is skipped if the object is ``__unsafe_unretained``.
+#. Second, if the object has an initializer, that expression is evaluated and
+ then assigned into the object using the usual assignment semantics.
+
+:arc-term:`Destruction` occurs when an object's lifetime ends. In all cases it
+is semantically equivalent to assigning a null pointer to the object, with the
+proviso that of course the object cannot be legally read after the object's
+lifetime ends.
+
+:arc-term:`Moving` occurs in specific situations where an lvalue is "moved
+from", meaning that its current pointee will be used but the object may be left
+in a different (but still valid) state. This arises with ``__block`` variables
+and rvalue references in C++. For ``__strong`` lvalues, moving is equivalent
+to loading the lvalue with primitive semantics, writing a null pointer to it
+with primitive semantics, and then releasing the result of the load at the end
+of the current full-expression. For all other lvalues, moving is equivalent to
+reading the object.
+
+.. _arc.ownership.restrictions:
+
+Restrictions
+------------
+
+.. _arc.ownership.restrictions.weak:
+
+Weak-unavailable types
+^^^^^^^^^^^^^^^^^^^^^^
+
+It is explicitly permitted for Objective-C classes to not support ``__weak``
+references. It is undefined behavior to perform an operation with weak
+assignment semantics with a pointer to an Objective-C object whose class does
+not support ``__weak`` references.
+
+.. admonition:: Rationale
+
+ Historically, it has been possible for a class to provide its own
+ reference-count implementation by overriding ``retain``, ``release``, etc.
+ However, weak references to an object require coordination with its class's
+ reference-count implementation because, among other things, weak loads and
+ stores must be atomic with respect to the final release. Therefore, existing
+ custom reference-count implementations will generally not support weak
+ references without additional effort. This is unavoidable without breaking
+ binary compatibility.
+
+A class may indicate that it does not support weak references by providing the
+``objc_arc_weak_reference_unavailable`` attribute on the class's interface declaration. A
+retainable object pointer type is **weak-unavailable** if
+is a pointer to an (optionally protocol-qualified) Objective-C class ``T`` where
+``T`` or one of its superclasses has the ``objc_arc_weak_reference_unavailable``
+attribute. A program is ill-formed if it applies the ``__weak`` ownership
+qualifier to a weak-unavailable type or if the value operand of a weak
+assignment operation has a weak-unavailable type.
+
+.. _arc.ownership.restrictions.autoreleasing:
+
+Storage duration of ``__autoreleasing`` objects
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A program is ill-formed if it declares an ``__autoreleasing`` object of
+non-automatic storage duration. A program is ill-formed if it captures an
+``__autoreleasing`` object in a block or, unless by reference, in a C++11
+lambda.
+
+.. admonition:: Rationale
+
+ Autorelease pools are tied to the current thread and scope by their nature.
+ While it is possible to have temporary objects whose instance variables are
+ filled with autoreleased objects, there is no way that ARC can provide any
+ sort of safety guarantee there.
+
+It is undefined behavior if a non-null pointer is assigned to an
+``__autoreleasing`` object while an autorelease pool is in scope and then that
+object is read after the autorelease pool's scope is left.
+
+.. _arc.ownership.restrictions.conversion.indirect:
+
+Conversion of pointers to ownership-qualified types
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A program is ill-formed if an expression of type ``T*`` is converted,
+explicitly or implicitly, to the type ``U*``, where ``T`` and ``U`` have
+different ownership qualification, unless:
+
+* ``T`` is qualified with ``__strong``, ``__autoreleasing``, or
+ ``__unsafe_unretained``, and ``U`` is qualified with both ``const`` and
+ ``__unsafe_unretained``; or
+* either ``T`` or ``U`` is ``cv void``, where ``cv`` is an optional sequence
+ of non-ownership qualifiers; or
+* the conversion is requested with a ``reinterpret_cast`` in Objective-C++; or
+* the conversion is a well-formed :ref:`pass-by-writeback
+ <arc.ownership.restrictions.pass_by_writeback>`.
+
+The analogous rule applies to ``T&`` and ``U&`` in Objective-C++.
+
+.. admonition:: Rationale
+
+ These rules provide a reasonable level of type-safety for indirect pointers,
+ as long as the underlying memory is not deallocated. The conversion to
+ ``const __unsafe_unretained`` is permitted because the semantics of reads are
+ equivalent across all these ownership semantics, and that's a very useful and
+ common pattern. The interconversion with ``void*`` is useful for allocating
+ memory or otherwise escaping the type system, but use it carefully.
+ ``reinterpret_cast`` is considered to be an obvious enough sign of taking
+ responsibility for any problems.
+
+It is undefined behavior to access an ownership-qualified object through an
+lvalue of a differently-qualified type, except that any non-``__weak`` object
+may be read through an ``__unsafe_unretained`` lvalue.
+
+It is undefined behavior if a managed operation is performed on a ``__strong``
+or ``__weak`` object without a guarantee that it contains a primitive zero
+bit-pattern, or if the storage for such an object is freed or reused without the
+object being first assigned a null pointer.
+
+.. admonition:: Rationale
+
+ ARC cannot differentiate between an assignment operator which is intended to
+ "initialize" dynamic memory and one which is intended to potentially replace
+ a value. Therefore the object's pointer must be valid before letting ARC at
+ it. Similarly, C and Objective-C do not provide any language hooks for
+ destroying objects held in dynamic memory, so it is the programmer's
+ responsibility to avoid leaks (``__strong`` objects) and consistency errors
+ (``__weak`` objects).
+
+These requirements are followed automatically in Objective-C++ when creating
+objects of retainable object owner type with ``new`` or ``new[]`` and destroying
+them with ``delete``, ``delete[]``, or a pseudo-destructor expression. Note
+that arrays of nontrivially-ownership-qualified type are not ABI compatible with
+non-ARC code because the element type is non-POD: such arrays that are
+``new[]``'d in ARC translation units cannot be ``delete[]``'d in non-ARC
+translation units and vice-versa.
+
+.. _arc.ownership.restrictions.pass_by_writeback:
+
+Passing to an out parameter by writeback
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If the argument passed to a parameter of type ``T __autoreleasing *`` has type
+``U oq *``, where ``oq`` is an ownership qualifier, then the argument is a
+candidate for :arc-term:`pass-by-writeback`` if:
+
+* ``oq`` is ``__strong`` or ``__weak``, and
+* it would be legal to initialize a ``T __strong *`` with a ``U __strong *``.
+
+For purposes of overload resolution, an implicit conversion sequence requiring
+a pass-by-writeback is always worse than an implicit conversion sequence not
+requiring a pass-by-writeback.
+
+The pass-by-writeback is ill-formed if the argument expression does not have a
+legal form:
+
+* ``&var``, where ``var`` is a scalar variable of automatic storage duration
+ with retainable object pointer type
+* a conditional expression where the second and third operands are both legal
+ forms
+* a cast whose operand is a legal form
+* a null pointer constant
+
+.. admonition:: Rationale
+
+ The restriction in the form of the argument serves two purposes. First, it
+ makes it impossible to pass the address of an array to the argument, which
+ serves to protect against an otherwise serious risk of mis-inferring an
+ "array" argument as an out-parameter. Second, it makes it much less likely
+ that the user will see confusing aliasing problems due to the implementation,
+ below, where their store to the writeback temporary is not immediately seen
+ in the original argument variable.
+
+A pass-by-writeback is evaluated as follows:
+
+#. The argument is evaluated to yield a pointer ``p`` of type ``U oq *``.
+#. If ``p`` is a null pointer, then a null pointer is passed as the argument,
+ and no further work is required for the pass-by-writeback.
+#. Otherwise, a temporary of type ``T __autoreleasing`` is created and
+ initialized to a null pointer.
+#. If the parameter is not an Objective-C method parameter marked ``out``,
+ then ``*p`` is read, and the result is written into the temporary with
+ primitive semantics.
+#. The address of the temporary is passed as the argument to the actual call.
+#. After the call completes, the temporary is loaded with primitive
+ semantics, and that value is assigned into ``*p``.
+
+.. admonition:: Rationale
+
+ This is all admittedly convoluted. In an ideal world, we would see that a
+ local variable is being passed to an out-parameter and retroactively modify
+ its type to be ``__autoreleasing`` rather than ``__strong``. This would be
+ remarkably difficult and not always well-founded under the C type system.
+ However, it was judged unacceptably invasive to require programmers to write
+ ``__autoreleasing`` on all the variables they intend to use for
+ out-parameters. This was the least bad solution.
+
+.. _arc.ownership.restrictions.records:
+
+Ownership-qualified fields of structs and unions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A program is ill-formed if it declares a member of a C struct or union to have
+a nontrivially ownership-qualified type.
+
+.. admonition:: Rationale
+
+ The resulting type would be non-POD in the C++ sense, but C does not give us
+ very good language tools for managing the lifetime of aggregates, so it is
+ more convenient to simply forbid them. It is still possible to manage this
+ with a ``void*`` or an ``__unsafe_unretained`` object.
+
+This restriction does not apply in Objective-C++. However, nontrivally
+ownership-qualified types are considered non-POD: in C++11 terms, they are not
+trivially default constructible, copy constructible, move constructible, copy
+assignable, move assignable, or destructible. It is a violation of C++'s One
+Definition Rule to use a class outside of ARC that, under ARC, would have a
+nontrivially ownership-qualified member.
+
+.. admonition:: Rationale
+
+ Unlike in C, we can express all the necessary ARC semantics for
+ ownership-qualified subobjects as suboperations of the (default) special
+ member functions for the class. These functions then become non-trivial.
+ This has the non-obvious result that the class will have a non-trivial copy
+ constructor and non-trivial destructor; if this would not normally be true
+ outside of ARC, objects of the type will be passed and returned in an
+ ABI-incompatible manner.
+
+.. _arc.ownership.inference:
+
+Ownership inference
+-------------------
+
+.. _arc.ownership.inference.variables:
+
+Objects
+^^^^^^^
+
+If an object is declared with retainable object owner type, but without an
+explicit ownership qualifier, its type is implicitly adjusted to have
+``__strong`` qualification.
+
+As a special case, if the object's base type is ``Class`` (possibly
+protocol-qualified), the type is adjusted to have ``__unsafe_unretained``
+qualification instead.
+
+.. _arc.ownership.inference.indirect_parameters:
+
+Indirect parameters
+^^^^^^^^^^^^^^^^^^^
+
+If a function or method parameter has type ``T*``, where ``T`` is an
+ownership-unqualified retainable object pointer type, then:
+
+* if ``T`` is ``const``-qualified or ``Class``, then it is implicitly
+ qualified with ``__unsafe_unretained``;
+* otherwise, it is implicitly qualified with ``__autoreleasing``.
+
+.. admonition:: Rationale
+
+ ``__autoreleasing`` exists mostly for this case, the Cocoa convention for
+ out-parameters. Since a pointer to ``const`` is obviously not an
+ out-parameter, we instead use a type more useful for passing arrays. If the
+ user instead intends to pass in a *mutable* array, inferring
+ ``__autoreleasing`` is the wrong thing to do; this directs some of the
+ caution in the following rules about writeback.
+
+Such a type written anywhere else would be ill-formed by the general rule
+requiring ownership qualifiers.
+
+This rule does not apply in Objective-C++ if a parameter's type is dependent in
+a template pattern and is only *instantiated* to a type which would be a
+pointer to an unqualified retainable object pointer type. Such code is still
+ill-formed.
+
+.. admonition:: Rationale
+
+ The convention is very unlikely to be intentional in template code.
+
+.. _arc.ownership.inference.template.arguments:
+
+Template arguments
+^^^^^^^^^^^^^^^^^^
+
+If a template argument for a template type parameter is an retainable object
+owner type that does not have an explicit ownership qualifier, it is adjusted
+to have ``__strong`` qualification. This adjustment occurs regardless of
+whether the template argument was deduced or explicitly specified.
+
+.. admonition:: Rationale
+
+ ``__strong`` is a useful default for containers (e.g., ``std::vector<id>``),
+ which would otherwise require explicit qualification. Moreover, unqualified
+ retainable object pointer types are unlikely to be useful within templates,
+ since they generally need to have a qualifier applied to the before being
+ used.
+
+.. _arc.method-families:
+
+Method families
+===============
+
+An Objective-C method may fall into a :arc-term:`method family`, which is a
+conventional set of behaviors ascribed to it by the Cocoa conventions.
+
+A method is in a certain method family if:
+
+* it has a ``objc_method_family`` attribute placing it in that family; or if
+ not that,
+* it does not have an ``objc_method_family`` attribute placing it in a
+ different or no family, and
+* its selector falls into the corresponding selector family, and
+* its signature obeys the added restrictions of the method family.
+
+A selector is in a certain selector family if, ignoring any leading
+underscores, the first component of the selector either consists entirely of
+the name of the method family or it begins with that name followed by a
+character other than a lowercase letter. For example, ``_perform:with:`` and
+``performWith:`` would fall into the ``perform`` family (if we recognized one),
+but ``performing:with`` would not.
+
+The families and their added restrictions are:
+
+* ``alloc`` methods must return a retainable object pointer type.
+* ``copy`` methods must return a retainable object pointer type.
+* ``mutableCopy`` methods must return a retainable object pointer type.
+* ``new`` methods must return a retainable object pointer type.
+* ``init`` methods must be instance methods and must return an Objective-C
+ pointer type. Additionally, a program is ill-formed if it declares or
+ contains a call to an ``init`` method whose return type is neither ``id`` nor
+ a pointer to a super-class or sub-class of the declaring class (if the method
+ was declared on a class) or the static receiver type of the call (if it was
+ declared on a protocol).
+
+ .. admonition:: Rationale
+
+ There are a fair number of existing methods with ``init``-like selectors
+ which nonetheless don't follow the ``init`` conventions. Typically these
+ are either accidental naming collisions or helper methods called during
+ initialization. Because of the peculiar retain/release behavior of
+ ``init`` methods, it's very important not to treat these methods as
+ ``init`` methods if they aren't meant to be. It was felt that implicitly
+ defining these methods out of the family based on the exact relationship
+ between the return type and the declaring class would be much too subtle
+ and fragile. Therefore we identify a small number of legitimate-seeming
+ return types and call everything else an error. This serves the secondary
+ purpose of encouraging programmers not to accidentally give methods names
+ in the ``init`` family.
+
+ Note that a method with an ``init``-family selector which returns a
+ non-Objective-C type (e.g. ``void``) is perfectly well-formed; it simply
+ isn't in the ``init`` family.
+
+A program is ill-formed if a method's declarations, implementations, and
+overrides do not all have the same method family.
+
+.. _arc.family.attribute:
+
+Explicit method family control
+------------------------------
+
+A method may be annotated with the ``objc_method_family`` attribute to
+precisely control which method family it belongs to. If a method in an
+``@implementation`` does not have this attribute, but there is a method
+declared in the corresponding ``@interface`` that does, then the attribute is
+copied to the declaration in the ``@implementation``. The attribute is
+available outside of ARC, and may be tested for with the preprocessor query
+``__has_attribute(objc_method_family)``.
+
+The attribute is spelled
+``__attribute__((objc_method_family(`` *family* ``)))``. If *family* is
+``none``, the method has no family, even if it would otherwise be considered to
+have one based on its selector and type. Otherwise, *family* must be one of
+``alloc``, ``copy``, ``init``, ``mutableCopy``, or ``new``, in which case the
+method is considered to belong to the corresponding family regardless of its
+selector. It is an error if a method that is explicitly added to a family in
+this way does not meet the requirements of the family other than the selector
+naming convention.
+
+.. admonition:: Rationale
+
+ The rules codified in this document describe the standard conventions of
+ Objective-C. However, as these conventions have not heretofore been enforced
+ by an unforgiving mechanical system, they are only imperfectly kept,
+ especially as they haven't always even been precisely defined. While it is
+ possible to define low-level ownership semantics with attributes like
+ ``ns_returns_retained``, this attribute allows the user to communicate
+ semantic intent, which is of use both to ARC (which, e.g., treats calls to
+ ``init`` specially) and the static analyzer.
+
+.. _arc.family.semantics:
+
+Semantics of method families
+----------------------------
+
+A method's membership in a method family may imply non-standard semantics for
+its parameters and return type.
+
+Methods in the ``alloc``, ``copy``, ``mutableCopy``, and ``new`` families ---
+that is, methods in all the currently-defined families except ``init`` ---
+implicitly :ref:`return a retained object
+<arc.object.operands.retained-return-values>` as if they were annotated with
+the ``ns_returns_retained`` attribute. This can be overridden by annotating
+the method with either of the ``ns_returns_autoreleased`` or
+``ns_returns_not_retained`` attributes.
+
+Properties also follow same naming rules as methods. This means that those in
+the ``alloc``, ``copy``, ``mutableCopy``, and ``new`` families provide access
+to :ref:`retained objects <arc.object.operands.retained-return-values>`. This
+can be overridden by annotating the property with ``ns_returns_not_retained``
+attribute.
+
+.. _arc.family.semantics.init:
+
+Semantics of ``init``
+^^^^^^^^^^^^^^^^^^^^^
+
+Methods in the ``init`` family implicitly :ref:`consume
+<arc.objects.operands.consumed>` their ``self`` parameter and :ref:`return a
+retained object <arc.object.operands.retained-return-values>`. Neither of
+these properties can be altered through attributes.
+
+A call to an ``init`` method with a receiver that is either ``self`` (possibly
+parenthesized or casted) or ``super`` is called a :arc-term:`delegate init
+call`. It is an error for a delegate init call to be made except from an
+``init`` method, and excluding blocks within such methods.
+
+As an exception to the :ref:`usual rule <arc.misc.self>`, the variable ``self``
+is mutable in an ``init`` method and has the usual semantics for a ``__strong``
+variable. However, it is undefined behavior and the program is ill-formed, no
+diagnostic required, if an ``init`` method attempts to use the previous value
+of ``self`` after the completion of a delegate init call. It is conventional,
+but not required, for an ``init`` method to return ``self``.
+
+It is undefined behavior for a program to cause two or more calls to ``init``
+methods on the same object, except that each ``init`` method invocation may
+perform at most one delegate init call.
+
+.. _arc.family.semantics.result_type:
+
+Related result types
+^^^^^^^^^^^^^^^^^^^^
+
+Certain methods are candidates to have :arc-term:`related result types`:
+
+* class methods in the ``alloc`` and ``new`` method families
+* instance methods in the ``init`` family
+* the instance method ``self``
+* outside of ARC, the instance methods ``retain`` and ``autorelease``
+
+If the formal result type of such a method is ``id`` or protocol-qualified
+``id``, or a type equal to the declaring class or a superclass, then it is said
+to have a related result type. In this case, when invoked in an explicit
+message send, it is assumed to return a type related to the type of the
+receiver:
+
+* if it is a class method, and the receiver is a class name ``T``, the message
+ send expression has type ``T*``; otherwise
+* if it is an instance method, and the receiver has type ``T``, the message
+ send expression has type ``T``; otherwise
+* the message send expression has the normal result type of the method.
+
+This is a new rule of the Objective-C language and applies outside of ARC.
+
+.. admonition:: Rationale
+
+ ARC's automatic code emission is more prone than most code to signature
+ errors, i.e. errors where a call was emitted against one method signature,
+ but the implementing method has an incompatible signature. Having more
+ precise type information helps drastically lower this risk, as well as
+ catching a number of latent bugs.
+
+.. _arc.optimization:
+
+Optimization
+============
+
+Within this section, the word :arc-term:`function` will be used to
+refer to any structured unit of code, be it a C function, an
+Objective-C method, or a block.
+
+This specification describes ARC as performing specific ``retain`` and
+``release`` operations on retainable object pointers at specific
+points during the execution of a program. These operations make up a
+non-contiguous subsequence of the computation history of the program.
+The portion of this sequence for a particular retainable object
+pointer for which a specific function execution is directly
+responsible is the :arc-term:`formal local retain history` of the
+object pointer. The corresponding actual sequence executed is the
+`dynamic local retain history`.
+
+However, under certain circumstances, ARC is permitted to re-order and
+eliminate operations in a manner which may alter the overall
+computation history beyond what is permitted by the general "as if"
+rule of C/C++ and the :ref:`restrictions <arc.objects.retains>` on
+the implementation of ``retain`` and ``release``.
+
+.. admonition:: Rationale
+
+ Specifically, ARC is sometimes permitted to optimize ``release``
+ operations in ways which might cause an object to be deallocated
+ before it would otherwise be. Without this, it would be almost
+ impossible to eliminate any ``retain``/``release`` pairs. For
+ example, consider the following code:
+
+ .. code-block:: objc
+
+ id x = _ivar;
+ [x foo];
+
+ If we were not permitted in any event to shorten the lifetime of the
+ object in ``x``, then we would not be able to eliminate this retain
+ and release unless we could prove that the message send could not
+ modify ``_ivar`` (or deallocate ``self``). Since message sends are
+ opaque to the optimizer, this is not possible, and so ARC's hands
+ would be almost completely tied.
+
+ARC makes no guarantees about the execution of a computation history
+which contains undefined behavior. In particular, ARC makes no
+guarantees in the presence of race conditions.
+
+ARC may assume that any retainable object pointers it receives or
+generates are instantaneously valid from that point until a point
+which, by the concurrency model of the host language, happens-after
+the generation of the pointer and happens-before a release of that
+object (possibly via an aliasing pointer or indirectly due to
+destruction of a different object).
+
+.. admonition:: Rationale
+
+ There is very little point in trying to guarantee correctness in the
+ presence of race conditions. ARC does not have a stack-scanning
+ garbage collector, and guaranteeing the atomicity of every load and
+ store operation would be prohibitive and preclude a vast amount of
+ optimization.
+
+ARC may assume that non-ARC code engages in sensible balancing
+behavior and does not rely on exact or minimum retain count values
+except as guaranteed by ``__strong`` object invariants or +1 transfer
+conventions. For example, if an object is provably double-retained
+and double-released, ARC may eliminate the inner retain and release;
+it does not need to guard against code which performs an unbalanced
+release followed by a "balancing" retain.
+
+.. _arc.optimization.liveness:
+
+Object liveness
+---------------
+
+ARC may not allow a retainable object ``X`` to be deallocated at a
+time ``T`` in a computation history if:
+
+* ``X`` is the value stored in a ``__strong`` object ``S`` with
+ :ref:`precise lifetime semantics <arc.optimization.precise>`, or
+
+* ``X`` is the value stored in a ``__strong`` object ``S`` with
+ imprecise lifetime semantics and, at some point after ``T`` but
+ before the next store to ``S``, the computation history features a
+ load from ``S`` and in some way depends on the value loaded, or
+
+* ``X`` is a value described as being released at the end of the
+ current full-expression and, at some point after ``T`` but before
+ the end of the full-expression, the computation history depends
+ on that value.
+
+.. admonition:: Rationale
+
+ The intent of the second rule is to say that objects held in normal
+ ``__strong`` local variables may be released as soon as the value in
+ the variable is no longer being used: either the variable stops
+ being used completely or a new value is stored in the variable.
+
+ The intent of the third rule is to say that return values may be
+ released after they've been used.
+
+A computation history depends on a pointer value ``P`` if it:
+
+* performs a pointer comparison with ``P``,
+* loads from ``P``,
+* stores to ``P``,
+* depends on a pointer value ``Q`` derived via pointer arithmetic
+ from ``P`` (including an instance-variable or field access), or
+* depends on a pointer value ``Q`` loaded from ``P``.
+
+Dependency applies only to values derived directly or indirectly from
+a particular expression result and does not occur merely because a
+separate pointer value dynamically aliases ``P``. Furthermore, this
+dependency is not carried by values that are stored to objects.
+
+.. admonition:: Rationale
+
+ The restrictions on dependency are intended to make this analysis
+ feasible by an optimizer with only incomplete information about a
+ program. Essentially, dependence is carried to "obvious" uses of a
+ pointer. Merely passing a pointer argument to a function does not
+ itself cause dependence, but since generally the optimizer will not
+ be able to prove that the function doesn't depend on that parameter,
+ it will be forced to conservatively assume it does.
+
+ Dependency propagates to values loaded from a pointer because those
+ values might be invalidated by deallocating the object. For
+ example, given the code ``__strong id x = p->ivar;``, ARC must not
+ move the release of ``p`` to between the load of ``p->ivar`` and the
+ retain of that value for storing into ``x``.
+
+ Dependency does not propagate through stores of dependent pointer
+ values because doing so would allow dependency to outlive the
+ full-expression which produced the original value. For example, the
+ address of an instance variable could be written to some global
+ location and then freely accessed during the lifetime of the local,
+ or a function could return an inner pointer of an object and store
+ it to a local. These cases would be potentially impossible to
+ reason about and so would basically prevent any optimizations based
+ on imprecise lifetime. There are also uncommon enough to make it
+ reasonable to require the precise-lifetime annotation if someone
+ really wants to rely on them.
+
+ Dependency does propagate through return values of pointer type.
+ The compelling source of need for this rule is a property accessor
+ which returns an un-autoreleased result; the calling function must
+ have the chance to operate on the value, e.g. to retain it, before
+ ARC releases the original pointer. Note again, however, that
+ dependence does not survive a store, so ARC does not guarantee the
+ continued validity of the return value past the end of the
+ full-expression.
+
+.. _arc.optimization.object_lifetime:
+
+No object lifetime extension
+----------------------------
+
+If, in the formal computation history of the program, an object ``X``
+has been deallocated by the time of an observable side-effect, then
+ARC must cause ``X`` to be deallocated by no later than the occurrence
+of that side-effect, except as influenced by the re-ordering of the
+destruction of objects.
+
+.. admonition:: Rationale
+
+ This rule is intended to prohibit ARC from observably extending the
+ lifetime of a retainable object, other than as specified in this
+ document. Together with the rule limiting the transformation of
+ releases, this rule requires ARC to eliminate retains and release
+ only in pairs.
+
+ ARC's power to reorder the destruction of objects is critical to its
+ ability to do any optimization, for essentially the same reason that
+ it must retain the power to decrease the lifetime of an object.
+ Unfortunately, while it's generally poor style for the destruction
+ of objects to have arbitrary side-effects, it's certainly possible.
+ Hence the caveat.
+
+.. _arc.optimization.precise:
+
+Precise lifetime semantics
+--------------------------
+
+In general, ARC maintains an invariant that a retainable object pointer held in
+a ``__strong`` object will be retained for the full formal lifetime of the
+object. Objects subject to this invariant have :arc-term:`precise lifetime
+semantics`.
+
+By default, local variables of automatic storage duration do not have precise
+lifetime semantics. Such objects are simply strong references which hold
+values of retainable object pointer type, and these values are still fully
+subject to the optimizations on values under local control.
+
+.. admonition:: Rationale
+
+ Applying these precise-lifetime semantics strictly would be prohibitive.
+ Many useful optimizations that might theoretically decrease the lifetime of
+ an object would be rendered impossible. Essentially, it promises too much.
+
+A local variable of retainable object owner type and automatic storage duration
+may be annotated with the ``objc_precise_lifetime`` attribute to indicate that
+it should be considered to be an object with precise lifetime semantics.
+
+.. admonition:: Rationale
+
+ Nonetheless, it is sometimes useful to be able to force an object to be
+ released at a precise time, even if that object does not appear to be used.
+ This is likely to be uncommon enough that the syntactic weight of explicitly
+ requesting these semantics will not be burdensome, and may even make the code
+ clearer.
+
+.. _arc.misc:
+
+Miscellaneous
+=============
+
+.. _arc.misc.special_methods:
+
+Special methods
+---------------
+
+.. _arc.misc.special_methods.retain:
+
+Memory management methods
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A program is ill-formed if it contains a method definition, message send, or
+``@selector`` expression for any of the following selectors:
+
+* ``autorelease``
+* ``release``
+* ``retain``
+* ``retainCount``
+
+.. admonition:: Rationale
+
+ ``retainCount`` is banned because ARC robs it of consistent semantics. The
+ others were banned after weighing three options for how to deal with message
+ sends:
+
+ **Honoring** them would work out very poorly if a programmer naively or
+ accidentally tried to incorporate code written for manual retain/release code
+ into an ARC program. At best, such code would do twice as much work as
+ necessary; quite frequently, however, ARC and the explicit code would both
+ try to balance the same retain, leading to crashes. The cost is losing the
+ ability to perform "unrooted" retains, i.e. retains not logically
+ corresponding to a strong reference in the object graph.
+
+ **Ignoring** them would badly violate user expectations about their code.
+ While it *would* make it easier to develop code simultaneously for ARC and
+ non-ARC, there is very little reason to do so except for certain library
+ developers. ARC and non-ARC translation units share an execution model and
+ can seamlessly interoperate. Within a translation unit, a developer who
+ faithfully maintains their code in non-ARC mode is suffering all the
+ restrictions of ARC for zero benefit, while a developer who isn't testing the
+ non-ARC mode is likely to be unpleasantly surprised if they try to go back to
+ it.
+
+ **Banning** them has the disadvantage of making it very awkward to migrate
+ existing code to ARC. The best answer to that, given a number of other
+ changes and restrictions in ARC, is to provide a specialized tool to assist
+ users in that migration.
+
+ Implementing these methods was banned because they are too integral to the
+ semantics of ARC; many tricks which worked tolerably under manual reference
+ counting will misbehave if ARC performs an ephemeral extra retain or two. If
+ absolutely required, it is still possible to implement them in non-ARC code,
+ for example in a category; the implementations must obey the :ref:`semantics
+ <arc.objects.retains>` laid out elsewhere in this document.
+
+.. _arc.misc.special_methods.dealloc:
+
+``dealloc``
+^^^^^^^^^^^
+
+A program is ill-formed if it contains a message send or ``@selector``
+expression for the selector ``dealloc``.
+
+.. admonition:: Rationale
+
+ There are no legitimate reasons to call ``dealloc`` directly.
+
+A class may provide a method definition for an instance method named
+``dealloc``. This method will be called after the final ``release`` of the
+object but before it is deallocated or any of its instance variables are
+destroyed. The superclass's implementation of ``dealloc`` will be called
+automatically when the method returns.
+
+.. admonition:: Rationale
+
+ Even though ARC destroys instance variables automatically, there are still
+ legitimate reasons to write a ``dealloc`` method, such as freeing
+ non-retainable resources. Failing to call ``[super dealloc]`` in such a
+ method is nearly always a bug. Sometimes, the object is simply trying to
+ prevent itself from being destroyed, but ``dealloc`` is really far too late
+ for the object to be raising such objections. Somewhat more legitimately, an
+ object may have been pool-allocated and should not be deallocated with
+ ``free``; for now, this can only be supported with a ``dealloc``
+ implementation outside of ARC. Such an implementation must be very careful
+ to do all the other work that ``NSObject``'s ``dealloc`` would, which is
+ outside the scope of this document to describe.
+
+The instance variables for an ARC-compiled class will be destroyed at some
+point after control enters the ``dealloc`` method for the root class of the
+class. The ordering of the destruction of instance variables is unspecified,
+both within a single class and between subclasses and superclasses.
+
+.. admonition:: Rationale
+
+ The traditional, non-ARC pattern for destroying instance variables is to
+ destroy them immediately before calling ``[super dealloc]``. Unfortunately,
+ message sends from the superclass are quite capable of reaching methods in
+ the subclass, and those methods may well read or write to those instance
+ variables. Making such message sends from dealloc is generally discouraged,
+ since the subclass may well rely on other invariants that were broken during
+ ``dealloc``, but it's not so inescapably dangerous that we felt comfortable
+ calling it undefined behavior. Therefore we chose to delay destroying the
+ instance variables to a point at which message sends are clearly disallowed:
+ the point at which the root class's deallocation routines take over.
+
+ In most code, the difference is not observable. It can, however, be observed
+ if an instance variable holds a strong reference to an object whose
+ deallocation will trigger a side-effect which must be carefully ordered with
+ respect to the destruction of the super class. Such code violates the design
+ principle that semantically important behavior should be explicit. A simple
+ fix is to clear the instance variable manually during ``dealloc``; a more
+ holistic solution is to move semantically important side-effects out of
+ ``dealloc`` and into a separate teardown phase which can rely on working with
+ well-formed objects.
+
+.. _arc.misc.autoreleasepool:
+
+``@autoreleasepool``
+--------------------
+
+To simplify the use of autorelease pools, and to bring them under the control
+of the compiler, a new kind of statement is available in Objective-C. It is
+written ``@autoreleasepool`` followed by a *compound-statement*, i.e. by a new
+scope delimited by curly braces. Upon entry to this block, the current state
+of the autorelease pool is captured. When the block is exited normally,
+whether by fallthrough or directed control flow (such as ``return`` or
+``break``), the autorelease pool is restored to the saved state, releasing all
+the objects in it. When the block is exited with an exception, the pool is not
+drained.
+
+``@autoreleasepool`` may be used in non-ARC translation units, with equivalent
+semantics.
+
+A program is ill-formed if it refers to the ``NSAutoreleasePool`` class.
+
+.. admonition:: Rationale
+
+ Autorelease pools are clearly important for the compiler to reason about, but
+ it is far too much to expect the compiler to accurately reason about control
+ dependencies between two calls. It is also very easy to accidentally forget
+ to drain an autorelease pool when using the manual API, and this can
+ significantly inflate the process's high-water-mark. The introduction of a
+ new scope is unfortunate but basically required for sane interaction with the
+ rest of the language. Not draining the pool during an unwind is apparently
+ required by the Objective-C exceptions implementation.
+
+.. _arc.misc.self:
+
+``self``
+--------
+
+The ``self`` parameter variable of an Objective-C method is never actually
+retained by the implementation. It is undefined behavior, or at least
+dangerous, to cause an object to be deallocated during a message send to that
+object.
+
+To make this safe, for Objective-C instance methods ``self`` is implicitly
+``const`` unless the method is in the :ref:`init family
+<arc.family.semantics.init>`. Further, ``self`` is **always** implicitly
+``const`` within a class method.
+
+.. admonition:: Rationale
+
+ The cost of retaining ``self`` in all methods was found to be prohibitive, as
+ it tends to be live across calls, preventing the optimizer from proving that
+ the retain and release are unnecessary --- for good reason, as it's quite
+ possible in theory to cause an object to be deallocated during its execution
+ without this retain and release. Since it's extremely uncommon to actually
+ do so, even unintentionally, and since there's no natural way for the
+ programmer to remove this retain/release pair otherwise (as there is for
+ other parameters by, say, making the variable ``__unsafe_unretained``), we
+ chose to make this optimizing assumption and shift some amount of risk to the
+ user.
+
+.. _arc.misc.enumeration:
+
+Fast enumeration iteration variables
+------------------------------------
+
+If a variable is declared in the condition of an Objective-C fast enumeration
+loop, and the variable has no explicit ownership qualifier, then it is
+qualified with ``const __strong`` and objects encountered during the
+enumeration are not actually retained.
+
+.. admonition:: Rationale
+
+ This is an optimization made possible because fast enumeration loops promise
+ to keep the objects retained during enumeration, and the collection itself
+ cannot be synchronously modified. It can be overridden by explicitly
+ qualifying the variable with ``__strong``, which will make the variable
+ mutable again and cause the loop to retain the objects it encounters.
+
+.. _arc.misc.blocks:
+
+Blocks
+------
+
+The implicit ``const`` capture variables created when evaluating a block
+literal expression have the same ownership semantics as the local variables
+they capture. The capture is performed by reading from the captured variable
+and initializing the capture variable with that value; the capture variable is
+destroyed when the block literal is, i.e. at the end of the enclosing scope.
+
+The :ref:`inference <arc.ownership.inference>` rules apply equally to
+``__block`` variables, which is a shift in semantics from non-ARC, where
+``__block`` variables did not implicitly retain during capture.
+
+``__block`` variables of retainable object owner type are moved off the stack
+by initializing the heap copy with the result of moving from the stack copy.
+
+With the exception of retains done as part of initializing a ``__strong``
+parameter variable or reading a ``__weak`` variable, whenever these semantics
+call for retaining a value of block-pointer type, it has the effect of a
+``Block_copy``. The optimizer may remove such copies when it sees that the
+result is used only as an argument to a call.
+
+.. _arc.misc.exceptions:
+
+Exceptions
+----------
+
+By default in Objective C, ARC is not exception-safe for normal releases:
+
+* It does not end the lifetime of ``__strong`` variables when their scopes are
+ abnormally terminated by an exception.
+* It does not perform releases which would occur at the end of a
+ full-expression if that full-expression throws an exception.
+
+A program may be compiled with the option ``-fobjc-arc-exceptions`` in order to
+enable these, or with the option ``-fno-objc-arc-exceptions`` to explicitly
+disable them, with the last such argument "winning".
+
+.. admonition:: Rationale
+
+ The standard Cocoa convention is that exceptions signal programmer error and
+ are not intended to be recovered from. Making code exceptions-safe by
+ default would impose severe runtime and code size penalties on code that
+ typically does not actually care about exceptions safety. Therefore,
+ ARC-generated code leaks by default on exceptions, which is just fine if the
+ process is going to be immediately terminated anyway. Programs which do care
+ about recovering from exceptions should enable the option.
+
+In Objective-C++, ``-fobjc-arc-exceptions`` is enabled by default.
+
+.. admonition:: Rationale
+
+ C++ already introduces pervasive exceptions-cleanup code of the sort that ARC
+ introduces. C++ programmers who have not already disabled exceptions are
+ much more likely to actual require exception-safety.
+
+ARC does end the lifetimes of ``__weak`` objects when an exception terminates
+their scope unless exceptions are disabled in the compiler.
+
+.. admonition:: Rationale
+
+ The consequence of a local ``__weak`` object not being destroyed is very
+ likely to be corruption of the Objective-C runtime, so we want to be safer
+ here. Of course, potentially massive leaks are about as likely to take down
+ the process as this corruption is if the program does try to recover from
+ exceptions.
+
+.. _arc.misc.interior:
+
+Interior pointers
+-----------------
+
+An Objective-C method returning a non-retainable pointer may be annotated with
+the ``objc_returns_inner_pointer`` attribute to indicate that it returns a
+handle to the internal data of an object, and that this reference will be
+invalidated if the object is destroyed. When such a message is sent to an
+object, the object's lifetime will be extended until at least the earliest of:
+
+* the last use of the returned pointer, or any pointer derived from it, in the
+ calling function or
+* the autorelease pool is restored to a previous state.
+
+.. admonition:: Rationale
+
+ Rationale: not all memory and resources are managed with reference counts; it
+ is common for objects to manage private resources in their own, private way.
+ Typically these resources are completely encapsulated within the object, but
+ some classes offer their users direct access for efficiency. If ARC is not
+ aware of methods that return such "interior" pointers, its optimizations can
+ cause the owning object to be reclaimed too soon. This attribute informs ARC
+ that it must tread lightly.
+
+ The extension rules are somewhat intentionally vague. The autorelease pool
+ limit is there to permit a simple implementation to simply retain and
+ autorelease the receiver. The other limit permits some amount of
+ optimization. The phrase "derived from" is intended to encompass the results
+ both of pointer transformations, such as casts and arithmetic, and of loading
+ from such derived pointers; furthermore, it applies whether or not such
+ derivations are applied directly in the calling code or by other utility code
+ (for example, the C library routine ``strchr``). However, the implementation
+ never need account for uses after a return from the code which calls the
+ method returning an interior pointer.
+
+As an exception, no extension is required if the receiver is loaded directly
+from a ``__strong`` object with :ref:`precise lifetime semantics
+<arc.optimization.precise>`.
+
+.. admonition:: Rationale
+
+ Implicit autoreleases carry the risk of significantly inflating memory use,
+ so it's important to provide users a way of avoiding these autoreleases.
+ Tying this to precise lifetime semantics is ideal, as for local variables
+ this requires a very explicit annotation, which allows ARC to trust the user
+ with good cheer.
+
+.. _arc.misc.c-retainable:
+
+C retainable pointer types
+--------------------------
+
+A type is a :arc-term:`C retainable pointer type` if it is a pointer to
+(possibly qualified) ``void`` or a pointer to a (possibly qualifier) ``struct``
+or ``class`` type.
+
+.. admonition:: Rationale
+
+ ARC does not manage pointers of CoreFoundation type (or any of the related
+ families of retainable C pointers which interoperate with Objective-C for
+ retain/release operation). In fact, ARC does not even know how to
+ distinguish these types from arbitrary C pointer types. The intent of this
+ concept is to filter out some obviously non-object types while leaving a hook
+ for later tightening if a means of exhaustively marking CF types is made
+ available.
+
+.. _arc.misc.c-retainable.audit:
+
+Auditing of C retainable pointer interfaces
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+:when-revised:`[beginning Apple 4.0, LLVM 3.1]`
+
+A C function may be marked with the ``cf_audited_transfer`` attribute to
+express that, except as otherwise marked with attributes, it obeys the
+parameter (consuming vs. non-consuming) and return (retained vs. non-retained)
+conventions for a C function of its name, namely:
+
+* A parameter of C retainable pointer type is assumed to not be consumed
+ unless it is marked with the ``cf_consumed`` attribute, and
+* A result of C retainable pointer type is assumed to not be returned retained
+ unless the function is either marked ``cf_returns_retained`` or it follows
+ the create/copy naming convention and is not marked
+ ``cf_returns_not_retained``.
+
+A function obeys the :arc-term:`create/copy` naming convention if its name
+contains as a substring:
+
+* either "Create" or "Copy" not followed by a lowercase letter, or
+* either "create" or "copy" not followed by a lowercase letter and
+ not preceded by any letter, whether uppercase or lowercase.
+
+A second attribute, ``cf_unknown_transfer``, signifies that a function's
+transfer semantics cannot be accurately captured using any of these
+annotations. A program is ill-formed if it annotates the same function with
+both ``cf_audited_transfer`` and ``cf_unknown_transfer``.
+
+A pragma is provided to facilitate the mass annotation of interfaces:
+
+.. code-block:: objc
+
+ #pragma clang arc_cf_code_audited begin
+ ...
+ #pragma clang arc_cf_code_audited end
+
+All C functions declared within the extent of this pragma are treated as if
+annotated with the ``cf_audited_transfer`` attribute unless they otherwise have
+the ``cf_unknown_transfer`` attribute. The pragma is accepted in all language
+modes. A program is ill-formed if it attempts to change files, whether by
+including a file or ending the current file, within the extent of this pragma.
+
+It is possible to test for all the features in this section with
+``__has_feature(arc_cf_code_audited)``.
+
+.. admonition:: Rationale
+
+ A significant inconvenience in ARC programming is the necessity of
+ interacting with APIs based around C retainable pointers. These features are
+ designed to make it relatively easy for API authors to quickly review and
+ annotate their interfaces, in turn improving the fidelity of tools such as
+ the static analyzer and ARC. The single-file restriction on the pragma is
+ designed to eliminate the risk of accidentally annotating some other header's
+ interfaces.
+
+.. _arc.runtime:
+
+Runtime support
+===============
+
+This section describes the interaction between the ARC runtime and the code
+generated by the ARC compiler. This is not part of the ARC language
+specification; instead, it is effectively a language-specific ABI supplement,
+akin to the "Itanium" generic ABI for C++.
+
+Ownership qualification does not alter the storage requirements for objects,
+except that it is undefined behavior if a ``__weak`` object is inadequately
+aligned for an object of type ``id``. The other qualifiers may be used on
+explicitly under-aligned memory.
+
+The runtime tracks ``__weak`` objects which holds non-null values. It is
+undefined behavior to direct modify a ``__weak`` object which is being tracked
+by the runtime except through an
+:ref:`objc_storeWeak <arc.runtime.objc_storeWeak>`,
+:ref:`objc_destroyWeak <arc.runtime.objc_destroyWeak>`, or
+:ref:`objc_moveWeak <arc.runtime.objc_moveWeak>` call.
+
+The runtime must provide a number of new entrypoints which the compiler may
+emit, which are described in the remainder of this section.
+
+.. admonition:: Rationale
+
+ Several of these functions are semantically equivalent to a message send; we
+ emit calls to C functions instead because:
+
+ * the machine code to do so is significantly smaller,
+ * it is much easier to recognize the C functions in the ARC optimizer, and
+ * a sufficient sophisticated runtime may be able to avoid the message send in
+ common cases.
+
+ Several other of these functions are "fused" operations which can be
+ described entirely in terms of other operations. We use the fused operations
+ primarily as a code-size optimization, although in some cases there is also a
+ real potential for avoiding redundant operations in the runtime.
+
+.. _arc.runtime.objc_autorelease:
+
+``id objc_autorelease(id value);``
+----------------------------------
+
+*Precondition:* ``value`` is null or a pointer to a valid object.
+
+If ``value`` is null, this call has no effect. Otherwise, it adds the object
+to the innermost autorelease pool exactly as if the object had been sent the
+``autorelease`` message.
+
+Always returns ``value``.
+
+.. _arc.runtime.objc_autoreleasePoolPop:
+
+``void objc_autoreleasePoolPop(void *pool);``
+---------------------------------------------
+
+*Precondition:* ``pool`` is the result of a previous call to
+:ref:`objc_autoreleasePoolPush <arc.runtime.objc_autoreleasePoolPush>` on the
+current thread, where neither ``pool`` nor any enclosing pool have previously
+been popped.
+
+Releases all the objects added to the given autorelease pool and any
+autorelease pools it encloses, then sets the current autorelease pool to the
+pool directly enclosing ``pool``.
+
+.. _arc.runtime.objc_autoreleasePoolPush:
+
+``void *objc_autoreleasePoolPush(void);``
+-----------------------------------------
+
+Creates a new autorelease pool that is enclosed by the current pool, makes that
+the current pool, and returns an opaque "handle" to it.
+
+.. admonition:: Rationale
+
+ While the interface is described as an explicit hierarchy of pools, the rules
+ allow the implementation to just keep a stack of objects, using the stack
+ depth as the opaque pool handle.
+
+.. _arc.runtime.objc_autoreleaseReturnValue:
+
+``id objc_autoreleaseReturnValue(id value);``
+---------------------------------------------
+
+*Precondition:* ``value`` is null or a pointer to a valid object.
+
+If ``value`` is null, this call has no effect. Otherwise, it makes a best
+effort to hand off ownership of a retain count on the object to a call to
+:ref:`objc_retainAutoreleasedReturnValue
+<arc.runtime.objc_retainAutoreleasedReturnValue>` for the same object in an
+enclosing call frame. If this is not possible, the object is autoreleased as
+above.
+
+Always returns ``value``.
+
+.. _arc.runtime.objc_copyWeak:
+
+``void objc_copyWeak(id *dest, id *src);``
+------------------------------------------
+
+*Precondition:* ``src`` is a valid pointer which either contains a null pointer
+or has been registered as a ``__weak`` object. ``dest`` is a valid pointer
+which has not been registered as a ``__weak`` object.
+
+``dest`` is initialized to be equivalent to ``src``, potentially registering it
+with the runtime. Equivalent to the following code:
+
+.. code-block:: objc
+
+ void objc_copyWeak(id *dest, id *src) {
+ objc_release(objc_initWeak(dest, objc_loadWeakRetained(src)));
+ }
+
+Must be atomic with respect to calls to ``objc_storeWeak`` on ``src``.
+
+.. _arc.runtime.objc_destroyWeak:
+
+``void objc_destroyWeak(id *object);``
+--------------------------------------
+
+*Precondition:* ``object`` is a valid pointer which either contains a null
+pointer or has been registered as a ``__weak`` object.
+
+``object`` is unregistered as a weak object, if it ever was. The current value
+of ``object`` is left unspecified; otherwise, equivalent to the following code:
+
+.. code-block:: objc
+
+ void objc_destroyWeak(id *object) {
+ objc_storeWeak(object, nil);
+ }
+
+Does not need to be atomic with respect to calls to ``objc_storeWeak`` on
+``object``.
+
+.. _arc.runtime.objc_initWeak:
+
+``id objc_initWeak(id *object, id value);``
+-------------------------------------------
+
+*Precondition:* ``object`` is a valid pointer which has not been registered as
+a ``__weak`` object. ``value`` is null or a pointer to a valid object.
+
+If ``value`` is a null pointer or the object to which it points has begun
+deallocation, ``object`` is zero-initialized. Otherwise, ``object`` is
+registered as a ``__weak`` object pointing to ``value``. Equivalent to the
+following code:
+
+.. code-block:: objc
+
+ id objc_initWeak(id *object, id value) {
+ *object = nil;
+ return objc_storeWeak(object, value);
+ }
+
+Returns the value of ``object`` after the call.
+
+Does not need to be atomic with respect to calls to ``objc_storeWeak`` on
+``object``.
+
+.. _arc.runtime.objc_loadWeak:
+
+``id objc_loadWeak(id *object);``
+---------------------------------
+
+*Precondition:* ``object`` is a valid pointer which either contains a null
+pointer or has been registered as a ``__weak`` object.
+
+If ``object`` is registered as a ``__weak`` object, and the last value stored
+into ``object`` has not yet been deallocated or begun deallocation, retains and
+autoreleases that value and returns it. Otherwise returns null. Equivalent to
+the following code:
+
+.. code-block:: objc
+
+ id objc_loadWeak(id *object) {
+ return objc_autorelease(objc_loadWeakRetained(object));
+ }
+
+Must be atomic with respect to calls to ``objc_storeWeak`` on ``object``.
+
+.. admonition:: Rationale
+
+ Loading weak references would be inherently prone to race conditions without
+ the retain.
+
+.. _arc.runtime.objc_loadWeakRetained:
+
+``id objc_loadWeakRetained(id *object);``
+-----------------------------------------
+
+*Precondition:* ``object`` is a valid pointer which either contains a null
+pointer or has been registered as a ``__weak`` object.
+
+If ``object`` is registered as a ``__weak`` object, and the last value stored
+into ``object`` has not yet been deallocated or begun deallocation, retains
+that value and returns it. Otherwise returns null.
+
+Must be atomic with respect to calls to ``objc_storeWeak`` on ``object``.
+
+.. _arc.runtime.objc_moveWeak:
+
+``void objc_moveWeak(id *dest, id *src);``
+------------------------------------------
+
+*Precondition:* ``src`` is a valid pointer which either contains a null pointer
+or has been registered as a ``__weak`` object. ``dest`` is a valid pointer
+which has not been registered as a ``__weak`` object.
+
+``dest`` is initialized to be equivalent to ``src``, potentially registering it
+with the runtime. ``src`` may then be left in its original state, in which
+case this call is equivalent to :ref:`objc_copyWeak
+<arc.runtime.objc_copyWeak>`, or it may be left as null.
+
+Must be atomic with respect to calls to ``objc_storeWeak`` on ``src``.
+
+.. _arc.runtime.objc_release:
+
+``void objc_release(id value);``
+--------------------------------
+
+*Precondition:* ``value`` is null or a pointer to a valid object.
+
+If ``value`` is null, this call has no effect. Otherwise, it performs a
+release operation exactly as if the object had been sent the ``release``
+message.
+
+.. _arc.runtime.objc_retain:
+
+``id objc_retain(id value);``
+-----------------------------
+
+*Precondition:* ``value`` is null or a pointer to a valid object.
+
+If ``value`` is null, this call has no effect. Otherwise, it performs a retain
+operation exactly as if the object had been sent the ``retain`` message.
+
+Always returns ``value``.
+
+.. _arc.runtime.objc_retainAutorelease:
+
+``id objc_retainAutorelease(id value);``
+----------------------------------------
+
+*Precondition:* ``value`` is null or a pointer to a valid object.
+
+If ``value`` is null, this call has no effect. Otherwise, it performs a retain
+operation followed by an autorelease operation. Equivalent to the following
+code:
+
+.. code-block:: objc
+
+ id objc_retainAutorelease(id value) {
+ return objc_autorelease(objc_retain(value));
+ }
+
+Always returns ``value``.
+
+.. _arc.runtime.objc_retainAutoreleaseReturnValue:
+
+``id objc_retainAutoreleaseReturnValue(id value);``
+---------------------------------------------------
+
+*Precondition:* ``value`` is null or a pointer to a valid object.
+
+If ``value`` is null, this call has no effect. Otherwise, it performs a retain
+operation followed by the operation described in
+:ref:`objc_autoreleaseReturnValue <arc.runtime.objc_autoreleaseReturnValue>`.
+Equivalent to the following code:
+
+.. code-block:: objc
+
+ id objc_retainAutoreleaseReturnValue(id value) {
+ return objc_autoreleaseReturnValue(objc_retain(value));
+ }
+
+Always returns ``value``.
+
+.. _arc.runtime.objc_retainAutoreleasedReturnValue:
+
+``id objc_retainAutoreleasedReturnValue(id value);``
+----------------------------------------------------
+
+*Precondition:* ``value`` is null or a pointer to a valid object.
+
+If ``value`` is null, this call has no effect. Otherwise, it attempts to
+accept a hand off of a retain count from a call to
+:ref:`objc_autoreleaseReturnValue <arc.runtime.objc_autoreleaseReturnValue>` on
+``value`` in a recently-called function or something it calls. If that fails,
+it performs a retain operation exactly like :ref:`objc_retain
+<arc.runtime.objc_retain>`.
+
+Always returns ``value``.
+
+.. _arc.runtime.objc_retainBlock:
+
+``id objc_retainBlock(id value);``
+----------------------------------
+
+*Precondition:* ``value`` is null or a pointer to a valid block object.
+
+If ``value`` is null, this call has no effect. Otherwise, if the block pointed
+to by ``value`` is still on the stack, it is copied to the heap and the address
+of the copy is returned. Otherwise a retain operation is performed on the
+block exactly as if it had been sent the ``retain`` message.
+
+.. _arc.runtime.objc_storeStrong:
+
+``id objc_storeStrong(id *object, id value);``
+----------------------------------------------
+
+*Precondition:* ``object`` is a valid pointer to a ``__strong`` object which is
+adequately aligned for a pointer. ``value`` is null or a pointer to a valid
+object.
+
+Performs the complete sequence for assigning to a ``__strong`` object of
+non-block type [*]_. Equivalent to the following code:
+
+.. code-block:: objc
+
+ void objc_storeStrong(id *object, id value) {
+ id oldValue = *object;
+ value = [value retain];
+ *object = value;
+ [oldValue release];
+ }
+
+.. [*] This does not imply that a ``__strong`` object of block type is an
+ invalid argument to this function. Rather it implies that an ``objc_retain``
+ and not an ``objc_retainBlock`` operation will be emitted if the argument is
+ a block.
+
+.. _arc.runtime.objc_storeWeak:
+
+``id objc_storeWeak(id *object, id value);``
+--------------------------------------------
+
+*Precondition:* ``object`` is a valid pointer which either contains a null
+pointer or has been registered as a ``__weak`` object. ``value`` is null or a
+pointer to a valid object.
+
+If ``value`` is a null pointer or the object to which it points has begun
+deallocation, ``object`` is assigned null and unregistered as a ``__weak``
+object. Otherwise, ``object`` is registered as a ``__weak`` object or has its
+registration updated to point to ``value``.
+
+Returns the value of ``object`` after the call.
+
Added: www-releases/trunk/4.0.0/tools/clang/docs/_sources/Block-ABI-Apple.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/4.0.0/tools/clang/docs/_sources/Block-ABI-Apple.txt?rev=297634&view=auto
==============================================================================
--- www-releases/trunk/4.0.0/tools/clang/docs/_sources/Block-ABI-Apple.txt (added)
+++ www-releases/trunk/4.0.0/tools/clang/docs/_sources/Block-ABI-Apple.txt Mon Mar 13 11:30:12 2017
@@ -0,0 +1,935 @@
+==================================
+Block Implementation Specification
+==================================
+
+.. contents::
+ :local:
+
+History
+=======
+
+* 2008/7/14 - created.
+* 2008/8/21 - revised, C++.
+* 2008/9/24 - add ``NULL`` ``isa`` field to ``__block`` storage.
+* 2008/10/1 - revise block layout to use a ``static`` descriptor structure.
+* 2008/10/6 - revise block layout to use an unsigned long int flags.
+* 2008/10/28 - specify use of ``_Block_object_assign`` and
+ ``_Block_object_dispose`` for all "Object" types in helper functions.
+* 2008/10/30 - revise new layout to have invoke function in same place.
+* 2008/10/30 - add ``__weak`` support.
+* 2010/3/16 - rev for stret return, signature field.
+* 2010/4/6 - improved wording.
+* 2013/1/6 - improved wording and converted to rst.
+
+This document describes the Apple ABI implementation specification of Blocks.
+
+The first shipping version of this ABI is found in Mac OS X 10.6, and shall be
+referred to as 10.6.ABI. As of 2010/3/16, the following describes the ABI
+contract with the runtime and the compiler, and, as necessary, will be referred
+to as ABI.2010.3.16.
+
+Since the Apple ABI references symbols from other elements of the system, any
+attempt to use this ABI on systems prior to SnowLeopard is undefined.
+
+High Level
+==========
+
+The ABI of ``Blocks`` consist of their layout and the runtime functions required
+by the compiler. A ``Block`` consists of a structure of the following form:
+
+.. code-block:: c
+
+ struct Block_literal_1 {
+ void *isa; // initialized to &_NSConcreteStackBlock or &_NSConcreteGlobalBlock
+ int flags;
+ int reserved;
+ void (*invoke)(void *, ...);
+ struct Block_descriptor_1 {
+ unsigned long int reserved; // NULL
+ unsigned long int size; // sizeof(struct Block_literal_1)
+ // optional helper functions
+ void (*copy_helper)(void *dst, void *src); // IFF (1<<25)
+ void (*dispose_helper)(void *src); // IFF (1<<25)
+ // required ABI.2010.3.16
+ const char *signature; // IFF (1<<30)
+ } *descriptor;
+ // imported variables
+ };
+
+The following flags bits are in use thusly for a possible ABI.2010.3.16:
+
+.. code-block:: c
+
+ enum {
+ BLOCK_HAS_COPY_DISPOSE = (1 << 25),
+ BLOCK_HAS_CTOR = (1 << 26), // helpers have C++ code
+ BLOCK_IS_GLOBAL = (1 << 28),
+ BLOCK_HAS_STRET = (1 << 29), // IFF BLOCK_HAS_SIGNATURE
+ BLOCK_HAS_SIGNATURE = (1 << 30),
+ };
+
+In 10.6.ABI the (1<<29) was usually set and was always ignored by the runtime -
+it had been a transitional marker that did not get deleted after the
+transition. This bit is now paired with (1<<30), and represented as the pair
+(3<<30), for the following combinations of valid bit settings, and their
+meanings:
+
+.. code-block:: c
+
+ switch (flags & (3<<29)) {
+ case (0<<29): 10.6.ABI, no signature field available
+ case (1<<29): 10.6.ABI, no signature field available
+ case (2<<29): ABI.2010.3.16, regular calling convention, presence of signature field
+ case (3<<29): ABI.2010.3.16, stret calling convention, presence of signature field,
+ }
+
+The signature field is not always populated.
+
+The following discussions are presented as 10.6.ABI otherwise.
+
+``Block`` literals may occur within functions where the structure is created in
+stack local memory. They may also appear as initialization expressions for
+``Block`` variables of global or ``static`` local variables.
+
+When a ``Block`` literal expression is evaluated the stack based structure is
+initialized as follows:
+
+1. A ``static`` descriptor structure is declared and initialized as follows:
+
+ a. The ``invoke`` function pointer is set to a function that takes the
+ ``Block`` structure as its first argument and the rest of the arguments (if
+ any) to the ``Block`` and executes the ``Block`` compound statement.
+
+ b. The ``size`` field is set to the size of the following ``Block`` literal
+ structure.
+
+ c. The ``copy_helper`` and ``dispose_helper`` function pointers are set to
+ respective helper functions if they are required by the ``Block`` literal.
+
+2. A stack (or global) ``Block`` literal data structure is created and
+ initialized as follows:
+
+ a. The ``isa`` field is set to the address of the external
+ ``_NSConcreteStackBlock``, which is a block of uninitialized memory supplied
+ in ``libSystem``, or ``_NSConcreteGlobalBlock`` if this is a static or file
+ level ``Block`` literal.
+
+ b. The ``flags`` field is set to zero unless there are variables imported
+ into the ``Block`` that need helper functions for program level
+ ``Block_copy()`` and ``Block_release()`` operations, in which case the
+ (1<<25) flags bit is set.
+
+As an example, the ``Block`` literal expression:
+
+.. code-block:: c
+
+ ^ { printf("hello world\n"); }
+
+would cause the following to be created on a 32-bit system:
+
+.. code-block:: c
+
+ struct __block_literal_1 {
+ void *isa;
+ int flags;
+ int reserved;
+ void (*invoke)(struct __block_literal_1 *);
+ struct __block_descriptor_1 *descriptor;
+ };
+
+ void __block_invoke_1(struct __block_literal_1 *_block) {
+ printf("hello world\n");
+ }
+
+ static struct __block_descriptor_1 {
+ unsigned long int reserved;
+ unsigned long int Block_size;
+ } __block_descriptor_1 = { 0, sizeof(struct __block_literal_1), __block_invoke_1 };
+
+and where the ``Block`` literal itself appears:
+
+.. code-block:: c
+
+ struct __block_literal_1 _block_literal = {
+ &_NSConcreteStackBlock,
+ (1<<29), <uninitialized>,
+ __block_invoke_1,
+ &__block_descriptor_1
+ };
+
+A ``Block`` imports other ``Block`` references, ``const`` copies of other
+variables, and variables marked ``__block``. In Objective-C, variables may
+additionally be objects.
+
+When a ``Block`` literal expression is used as the initial value of a global
+or ``static`` local variable, it is initialized as follows:
+
+.. code-block:: c
+
+ struct __block_literal_1 __block_literal_1 = {
+ &_NSConcreteGlobalBlock,
+ (1<<28)|(1<<29), <uninitialized>,
+ __block_invoke_1,
+ &__block_descriptor_1
+ };
+
+that is, a different address is provided as the first value and a particular
+(1<<28) bit is set in the ``flags`` field, and otherwise it is the same as for
+stack based ``Block`` literals. This is an optimization that can be used for
+any ``Block`` literal that imports no ``const`` or ``__block`` storage
+variables.
+
+Imported Variables
+==================
+
+Variables of ``auto`` storage class are imported as ``const`` copies. Variables
+of ``__block`` storage class are imported as a pointer to an enclosing data
+structure. Global variables are simply referenced and not considered as
+imported.
+
+Imported ``const`` copy variables
+---------------------------------
+
+Automatic storage variables not marked with ``__block`` are imported as
+``const`` copies.
+
+The simplest example is that of importing a variable of type ``int``:
+
+.. code-block:: c
+
+ int x = 10;
+ void (^vv)(void) = ^{ printf("x is %d\n", x); }
+ x = 11;
+ vv();
+
+which would be compiled to:
+
+.. code-block:: c
+
+ struct __block_literal_2 {
+ void *isa;
+ int flags;
+ int reserved;
+ void (*invoke)(struct __block_literal_2 *);
+ struct __block_descriptor_2 *descriptor;
+ const int x;
+ };
+
+ void __block_invoke_2(struct __block_literal_2 *_block) {
+ printf("x is %d\n", _block->x);
+ }
+
+ static struct __block_descriptor_2 {
+ unsigned long int reserved;
+ unsigned long int Block_size;
+ } __block_descriptor_2 = { 0, sizeof(struct __block_literal_2) };
+
+and:
+
+.. code-block:: c
+
+ struct __block_literal_2 __block_literal_2 = {
+ &_NSConcreteStackBlock,
+ (1<<29), <uninitialized>,
+ __block_invoke_2,
+ &__block_descriptor_2,
+ x
+ };
+
+In summary, scalars, structures, unions, and function pointers are generally
+imported as ``const`` copies with no need for helper functions.
+
+Imported ``const`` copy of ``Block`` reference
+----------------------------------------------
+
+The first case where copy and dispose helper functions are required is for the
+case of when a ``Block`` itself is imported. In this case both a
+``copy_helper`` function and a ``dispose_helper`` function are needed. The
+``copy_helper`` function is passed both the existing stack based pointer and the
+pointer to the new heap version and should call back into the runtime to
+actually do the copy operation on the imported fields within the ``Block``. The
+runtime functions are all described in :ref:`RuntimeHelperFunctions`.
+
+A quick example:
+
+.. code-block:: c
+
+ void (^existingBlock)(void) = ...;
+ void (^vv)(void) = ^{ existingBlock(); }
+ vv();
+
+ struct __block_literal_3 {
+ ...; // existing block
+ };
+
+ struct __block_literal_4 {
+ void *isa;
+ int flags;
+ int reserved;
+ void (*invoke)(struct __block_literal_4 *);
+ struct __block_literal_3 *const existingBlock;
+ };
+
+ void __block_invoke_4(struct __block_literal_2 *_block) {
+ __block->existingBlock->invoke(__block->existingBlock);
+ }
+
+ void __block_copy_4(struct __block_literal_4 *dst, struct __block_literal_4 *src) {
+ //_Block_copy_assign(&dst->existingBlock, src->existingBlock, 0);
+ _Block_object_assign(&dst->existingBlock, src->existingBlock, BLOCK_FIELD_IS_BLOCK);
+ }
+
+ void __block_dispose_4(struct __block_literal_4 *src) {
+ // was _Block_destroy
+ _Block_object_dispose(src->existingBlock, BLOCK_FIELD_IS_BLOCK);
+ }
+
+ static struct __block_descriptor_4 {
+ unsigned long int reserved;
+ unsigned long int Block_size;
+ void (*copy_helper)(struct __block_literal_4 *dst, struct __block_literal_4 *src);
+ void (*dispose_helper)(struct __block_literal_4 *);
+ } __block_descriptor_4 = {
+ 0,
+ sizeof(struct __block_literal_4),
+ __block_copy_4,
+ __block_dispose_4,
+ };
+
+and where said ``Block`` is used:
+
+.. code-block:: c
+
+ struct __block_literal_4 _block_literal = {
+ &_NSConcreteStackBlock,
+ (1<<25)|(1<<29), <uninitialized>
+ __block_invoke_4,
+ & __block_descriptor_4
+ existingBlock,
+ };
+
+Importing ``__attribute__((NSObject))`` variables
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+GCC introduces ``__attribute__((NSObject))`` on structure pointers to mean "this
+is an object". This is useful because many low level data structures are
+declared as opaque structure pointers, e.g. ``CFStringRef``, ``CFArrayRef``,
+etc. When used from C, however, these are still really objects and are the
+second case where that requires copy and dispose helper functions to be
+generated. The copy helper functions generated by the compiler should use the
+``_Block_object_assign`` runtime helper function and in the dispose helper the
+``_Block_object_dispose`` runtime helper function should be called.
+
+For example, ``Block`` foo in the following:
+
+.. code-block:: c
+
+ struct Opaque *__attribute__((NSObject)) objectPointer = ...;
+ ...
+ void (^foo)(void) = ^{ CFPrint(objectPointer); };
+
+would have the following helper functions generated:
+
+.. code-block:: c
+
+ void __block_copy_foo(struct __block_literal_5 *dst, struct __block_literal_5 *src) {
+ _Block_object_assign(&dst->objectPointer, src-> objectPointer, BLOCK_FIELD_IS_OBJECT);
+ }
+
+ void __block_dispose_foo(struct __block_literal_5 *src) {
+ _Block_object_dispose(src->objectPointer, BLOCK_FIELD_IS_OBJECT);
+ }
+
+Imported ``__block`` marked variables
+-------------------------------------
+
+Layout of ``__block`` marked variables
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The compiler must embed variables that are marked ``__block`` in a specialized
+structure of the form:
+
+.. code-block:: c
+
+ struct _block_byref_foo {
+ void *isa;
+ struct Block_byref *forwarding;
+ int flags; //refcount;
+ int size;
+ typeof(marked_variable) marked_variable;
+ };
+
+Variables of certain types require helper functions for when ``Block_copy()``
+and ``Block_release()`` are performed upon a referencing ``Block``. At the "C"
+level only variables that are of type ``Block`` or ones that have
+``__attribute__((NSObject))`` marked require helper functions. In Objective-C
+objects require helper functions and in C++ stack based objects require helper
+functions. Variables that require helper functions use the form:
+
+.. code-block:: c
+
+ struct _block_byref_foo {
+ void *isa;
+ struct _block_byref_foo *forwarding;
+ int flags; //refcount;
+ int size;
+ // helper functions called via Block_copy() and Block_release()
+ void (*byref_keep)(void *dst, void *src);
+ void (*byref_dispose)(void *);
+ typeof(marked_variable) marked_variable;
+ };
+
+The structure is initialized such that:
+
+ a. The ``forwarding`` pointer is set to the beginning of its enclosing
+ structure.
+
+ b. The ``size`` field is initialized to the total size of the enclosing
+ structure.
+
+ c. The ``flags`` field is set to either 0 if no helper functions are needed
+ or (1<<25) if they are.
+
+ d. The helper functions are initialized (if present).
+
+ e. The variable itself is set to its initial value.
+
+ f. The ``isa`` field is set to ``NULL``.
+
+Access to ``__block`` variables from within its lexical scope
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In order to "move" the variable to the heap upon a ``copy_helper`` operation the
+compiler must rewrite access to such a variable to be indirect through the
+structures ``forwarding`` pointer. For example:
+
+.. code-block:: c
+
+ int __block i = 10;
+ i = 11;
+
+would be rewritten to be:
+
+.. code-block:: c
+
+ struct _block_byref_i {
+ void *isa;
+ struct _block_byref_i *forwarding;
+ int flags; //refcount;
+ int size;
+ int captured_i;
+ } i = { NULL, &i, 0, sizeof(struct _block_byref_i), 10 };
+
+ i.forwarding->captured_i = 11;
+
+In the case of a ``Block`` reference variable being marked ``__block`` the
+helper code generated must use the ``_Block_object_assign`` and
+``_Block_object_dispose`` routines supplied by the runtime to make the
+copies. For example:
+
+.. code-block:: c
+
+ __block void (voidBlock)(void) = blockA;
+ voidBlock = blockB;
+
+would translate into:
+
+.. code-block:: c
+
+ struct _block_byref_voidBlock {
+ void *isa;
+ struct _block_byref_voidBlock *forwarding;
+ int flags; //refcount;
+ int size;
+ void (*byref_keep)(struct _block_byref_voidBlock *dst, struct _block_byref_voidBlock *src);
+ void (*byref_dispose)(struct _block_byref_voidBlock *);
+ void (^captured_voidBlock)(void);
+ };
+
+ void _block_byref_keep_helper(struct _block_byref_voidBlock *dst, struct _block_byref_voidBlock *src) {
+ //_Block_copy_assign(&dst->captured_voidBlock, src->captured_voidBlock, 0);
+ _Block_object_assign(&dst->captured_voidBlock, src->captured_voidBlock, BLOCK_FIELD_IS_BLOCK | BLOCK_BYREF_CALLER);
+ }
+
+ void _block_byref_dispose_helper(struct _block_byref_voidBlock *param) {
+ //_Block_destroy(param->captured_voidBlock, 0);
+ _Block_object_dispose(param->captured_voidBlock, BLOCK_FIELD_IS_BLOCK | BLOCK_BYREF_CALLER)}
+
+and:
+
+.. code-block:: c
+
+ struct _block_byref_voidBlock voidBlock = {( .forwarding=&voidBlock, .flags=(1<<25), .size=sizeof(struct _block_byref_voidBlock *),
+ .byref_keep=_block_byref_keep_helper, .byref_dispose=_block_byref_dispose_helper,
+ .captured_voidBlock=blockA )};
+
+ voidBlock.forwarding->captured_voidBlock = blockB;
+
+Importing ``__block`` variables into ``Blocks``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A ``Block`` that uses a ``__block`` variable in its compound statement body must
+import the variable and emit ``copy_helper`` and ``dispose_helper`` helper
+functions that, in turn, call back into the runtime to actually copy or release
+the ``byref`` data block using the functions ``_Block_object_assign`` and
+``_Block_object_dispose``.
+
+For example:
+
+.. code-block:: c
+
+ int __block i = 2;
+ functioncall(^{ i = 10; });
+
+would translate to:
+
+.. code-block:: c
+
+ struct _block_byref_i {
+ void *isa; // set to NULL
+ struct _block_byref_voidBlock *forwarding;
+ int flags; //refcount;
+ int size;
+ void (*byref_keep)(struct _block_byref_i *dst, struct _block_byref_i *src);
+ void (*byref_dispose)(struct _block_byref_i *);
+ int captured_i;
+ };
+
+
+ struct __block_literal_5 {
+ void *isa;
+ int flags;
+ int reserved;
+ void (*invoke)(struct __block_literal_5 *);
+ struct __block_descriptor_5 *descriptor;
+ struct _block_byref_i *i_holder;
+ };
+
+ void __block_invoke_5(struct __block_literal_5 *_block) {
+ _block->forwarding->captured_i = 10;
+ }
+
+ void __block_copy_5(struct __block_literal_5 *dst, struct __block_literal_5 *src) {
+ //_Block_byref_assign_copy(&dst->captured_i, src->captured_i);
+ _Block_object_assign(&dst->captured_i, src->captured_i, BLOCK_FIELD_IS_BYREF | BLOCK_BYREF_CALLER);
+ }
+
+ void __block_dispose_5(struct __block_literal_5 *src) {
+ //_Block_byref_release(src->captured_i);
+ _Block_object_dispose(src->captured_i, BLOCK_FIELD_IS_BYREF | BLOCK_BYREF_CALLER);
+ }
+
+ static struct __block_descriptor_5 {
+ unsigned long int reserved;
+ unsigned long int Block_size;
+ void (*copy_helper)(struct __block_literal_5 *dst, struct __block_literal_5 *src);
+ void (*dispose_helper)(struct __block_literal_5 *);
+ } __block_descriptor_5 = { 0, sizeof(struct __block_literal_5) __block_copy_5, __block_dispose_5 };
+
+and:
+
+.. code-block:: c
+
+ struct _block_byref_i i = {( .isa=NULL, .forwarding=&i, .flags=0, .size=sizeof(struct _block_byref_i), .captured_i=2 )};
+ struct __block_literal_5 _block_literal = {
+ &_NSConcreteStackBlock,
+ (1<<25)|(1<<29), <uninitialized>,
+ __block_invoke_5,
+ &__block_descriptor_5,
+ &i,
+ };
+
+Importing ``__attribute__((NSObject))`` ``__block`` variables
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A ``__block`` variable that is also marked ``__attribute__((NSObject))`` should
+have ``byref_keep`` and ``byref_dispose`` helper functions that use
+``_Block_object_assign`` and ``_Block_object_dispose``.
+
+``__block`` escapes
+^^^^^^^^^^^^^^^^^^^
+
+Because ``Blocks`` referencing ``__block`` variables may have ``Block_copy()``
+performed upon them the underlying storage for the variables may move to the
+heap. In Objective-C Garbage Collection Only compilation environments the heap
+used is the garbage collected one and no further action is required. Otherwise
+the compiler must issue a call to potentially release any heap storage for
+``__block`` variables at all escapes or terminations of their scope. The call
+should be:
+
+.. code-block:: c
+
+ _Block_object_dispose(&_block_byref_foo, BLOCK_FIELD_IS_BYREF);
+
+Nesting
+^^^^^^^
+
+``Blocks`` may contain ``Block`` literal expressions. Any variables used within
+inner blocks are imported into all enclosing ``Block`` scopes even if the
+variables are not used. This includes ``const`` imports as well as ``__block``
+variables.
+
+Objective C Extensions to ``Blocks``
+====================================
+
+Importing Objects
+-----------------
+
+Objects should be treated as ``__attribute__((NSObject))`` variables; all
+``copy_helper``, ``dispose_helper``, ``byref_keep``, and ``byref_dispose``
+helper functions should use ``_Block_object_assign`` and
+``_Block_object_dispose``. There should be no code generated that uses
+``*-retain`` or ``*-release`` methods.
+
+``Blocks`` as Objects
+---------------------
+
+The compiler will treat ``Blocks`` as objects when synthesizing property setters
+and getters, will characterize them as objects when generating garbage
+collection strong and weak layout information in the same manner as objects, and
+will issue strong and weak write-barrier assignments in the same manner as
+objects.
+
+``__weak __block`` Support
+--------------------------
+
+Objective-C (and Objective-C++) support the ``__weak`` attribute on ``__block``
+variables. Under normal circumstances the compiler uses the Objective-C runtime
+helper support functions ``objc_assign_weak`` and ``objc_read_weak``. Both
+should continue to be used for all reads and writes of ``__weak __block``
+variables:
+
+.. code-block:: c
+
+ objc_read_weak(&block->byref_i->forwarding->i)
+
+The ``__weak`` variable is stored in a ``_block_byref_foo`` structure and the
+``Block`` has copy and dispose helpers for this structure that call:
+
+.. code-block:: c
+
+ _Block_object_assign(&dest->_block_byref_i, src-> _block_byref_i, BLOCK_FIELD_IS_WEAK | BLOCK_FIELD_IS_BYREF);
+
+and:
+
+.. code-block:: c
+
+ _Block_object_dispose(src->_block_byref_i, BLOCK_FIELD_IS_WEAK | BLOCK_FIELD_IS_BYREF);
+
+In turn, the ``block_byref`` copy support helpers distinguish between whether
+the ``__block`` variable is a ``Block`` or not and should either call:
+
+.. code-block:: c
+
+ _Block_object_assign(&dest->_block_byref_i, src->_block_byref_i, BLOCK_FIELD_IS_WEAK | BLOCK_FIELD_IS_OBJECT | BLOCK_BYREF_CALLER);
+
+for something declared as an object or:
+
+.. code-block:: c
+
+ _Block_object_assign(&dest->_block_byref_i, src->_block_byref_i, BLOCK_FIELD_IS_WEAK | BLOCK_FIELD_IS_BLOCK | BLOCK_BYREF_CALLER);
+
+for something declared as a ``Block``.
+
+A full example follows:
+
+.. code-block:: c
+
+ __block __weak id obj = <initialization expression>;
+ functioncall(^{ [obj somemessage]; });
+
+would translate to:
+
+.. code-block:: c
+
+ struct _block_byref_obj {
+ void *isa; // uninitialized
+ struct _block_byref_obj *forwarding;
+ int flags; //refcount;
+ int size;
+ void (*byref_keep)(struct _block_byref_i *dst, struct _block_byref_i *src);
+ void (*byref_dispose)(struct _block_byref_i *);
+ id captured_obj;
+ };
+
+ void _block_byref_obj_keep(struct _block_byref_voidBlock *dst, struct _block_byref_voidBlock *src) {
+ //_Block_copy_assign(&dst->captured_obj, src->captured_obj, 0);
+ _Block_object_assign(&dst->captured_obj, src->captured_obj, BLOCK_FIELD_IS_OBJECT | BLOCK_FIELD_IS_WEAK | BLOCK_BYREF_CALLER);
+ }
+
+ void _block_byref_obj_dispose(struct _block_byref_voidBlock *param) {
+ //_Block_destroy(param->captured_obj, 0);
+ _Block_object_dispose(param->captured_obj, BLOCK_FIELD_IS_OBJECT | BLOCK_FIELD_IS_WEAK | BLOCK_BYREF_CALLER);
+ };
+
+for the block ``byref`` part and:
+
+.. code-block:: c
+
+ struct __block_literal_5 {
+ void *isa;
+ int flags;
+ int reserved;
+ void (*invoke)(struct __block_literal_5 *);
+ struct __block_descriptor_5 *descriptor;
+ struct _block_byref_obj *byref_obj;
+ };
+
+ void __block_invoke_5(struct __block_literal_5 *_block) {
+ [objc_read_weak(&_block->byref_obj->forwarding->captured_obj) somemessage];
+ }
+
+ void __block_copy_5(struct __block_literal_5 *dst, struct __block_literal_5 *src) {
+ //_Block_byref_assign_copy(&dst->byref_obj, src->byref_obj);
+ _Block_object_assign(&dst->byref_obj, src->byref_obj, BLOCK_FIELD_IS_BYREF | BLOCK_FIELD_IS_WEAK);
+ }
+
+ void __block_dispose_5(struct __block_literal_5 *src) {
+ //_Block_byref_release(src->byref_obj);
+ _Block_object_dispose(src->byref_obj, BLOCK_FIELD_IS_BYREF | BLOCK_FIELD_IS_WEAK);
+ }
+
+ static struct __block_descriptor_5 {
+ unsigned long int reserved;
+ unsigned long int Block_size;
+ void (*copy_helper)(struct __block_literal_5 *dst, struct __block_literal_5 *src);
+ void (*dispose_helper)(struct __block_literal_5 *);
+ } __block_descriptor_5 = { 0, sizeof(struct __block_literal_5), __block_copy_5, __block_dispose_5 };
+
+and within the compound statement:
+
+.. code-block:: c
+
+ truct _block_byref_obj obj = {( .forwarding=&obj, .flags=(1<<25), .size=sizeof(struct _block_byref_obj),
+ .byref_keep=_block_byref_obj_keep, .byref_dispose=_block_byref_obj_dispose,
+ .captured_obj = <initialization expression> )};
+
+ truct __block_literal_5 _block_literal = {
+ &_NSConcreteStackBlock,
+ (1<<25)|(1<<29), <uninitialized>,
+ __block_invoke_5,
+ &__block_descriptor_5,
+ &obj, // a reference to the on-stack structure containing "captured_obj"
+ };
+
+
+ functioncall(_block_literal->invoke(&_block_literal));
+
+C++ Support
+===========
+
+Within a block stack based C++ objects are copied into ``const`` copies using
+the copy constructor. It is an error if a stack based C++ object is used within
+a block if it does not have a copy constructor. In addition both copy and
+destroy helper routines must be synthesized for the block to support the
+``Block_copy()`` operation, and the flags work marked with the (1<<26) bit in
+addition to the (1<<25) bit. The copy helper should call the constructor using
+appropriate offsets of the variable within the supplied stack based block source
+and heap based destination for all ``const`` constructed copies, and similarly
+should call the destructor in the destroy routine.
+
+As an example, suppose a C++ class ``FOO`` existed with a copy constructor.
+Within a code block a stack version of a ``FOO`` object is declared and used
+within a ``Block`` literal expression:
+
+.. code-block:: c++
+
+ {
+ FOO foo;
+ void (^block)(void) = ^{ printf("%d\n", foo.value()); };
+ }
+
+The compiler would synthesize:
+
+.. code-block:: c++
+
+ struct __block_literal_10 {
+ void *isa;
+ int flags;
+ int reserved;
+ void (*invoke)(struct __block_literal_10 *);
+ struct __block_descriptor_10 *descriptor;
+ const FOO foo;
+ };
+
+ void __block_invoke_10(struct __block_literal_10 *_block) {
+ printf("%d\n", _block->foo.value());
+ }
+
+ void __block_literal_10(struct __block_literal_10 *dst, struct __block_literal_10 *src) {
+ FOO_ctor(&dst->foo, &src->foo);
+ }
+
+ void __block_dispose_10(struct __block_literal_10 *src) {
+ FOO_dtor(&src->foo);
+ }
+
+ static struct __block_descriptor_10 {
+ unsigned long int reserved;
+ unsigned long int Block_size;
+ void (*copy_helper)(struct __block_literal_10 *dst, struct __block_literal_10 *src);
+ void (*dispose_helper)(struct __block_literal_10 *);
+ } __block_descriptor_10 = { 0, sizeof(struct __block_literal_10), __block_copy_10, __block_dispose_10 };
+
+and the code would be:
+
+.. code-block:: c++
+
+ {
+ FOO foo;
+ comp_ctor(&foo); // default constructor
+ struct __block_literal_10 _block_literal = {
+ &_NSConcreteStackBlock,
+ (1<<25)|(1<<26)|(1<<29), <uninitialized>,
+ __block_invoke_10,
+ &__block_descriptor_10,
+ };
+ comp_ctor(&_block_literal->foo, &foo); // const copy into stack version
+ struct __block_literal_10 &block = &_block_literal; // assign literal to block variable
+ block->invoke(block); // invoke block
+ comp_dtor(&_block_literal->foo); // destroy stack version of const block copy
+ comp_dtor(&foo); // destroy original version
+ }
+
+
+C++ objects stored in ``__block`` storage start out on the stack in a
+``block_byref`` data structure as do other variables. Such objects (if not
+``const`` objects) must support a regular copy constructor. The ``block_byref``
+data structure will have copy and destroy helper routines synthesized by the
+compiler. The copy helper will have code created to perform the copy
+constructor based on the initial stack ``block_byref`` data structure, and will
+also set the (1<<26) bit in addition to the (1<<25) bit. The destroy helper
+will have code to do the destructor on the object stored within the supplied
+``block_byref`` heap data structure. For example,
+
+.. code-block:: c++
+
+ __block FOO blockStorageFoo;
+
+requires the normal constructor for the embedded ``blockStorageFoo`` object:
+
+.. code-block:: c++
+
+ FOO_ctor(& _block_byref_blockStorageFoo->blockStorageFoo);
+
+and at scope termination the destructor:
+
+.. code-block:: c++
+
+ FOO_dtor(& _block_byref_blockStorageFoo->blockStorageFoo);
+
+Note that the forwarding indirection is *NOT* used.
+
+The compiler would need to generate (if used from a block literal) the following
+copy/dispose helpers:
+
+.. code-block:: c++
+
+ void _block_byref_obj_keep(struct _block_byref_blockStorageFoo *dst, struct _block_byref_blockStorageFoo *src) {
+ FOO_ctor(&dst->blockStorageFoo, &src->blockStorageFoo);
+ }
+
+ void _block_byref_obj_dispose(struct _block_byref_blockStorageFoo *src) {
+ FOO_dtor(&src->blockStorageFoo);
+ }
+
+for the appropriately named constructor and destructor for the class/struct
+``FOO``.
+
+To support member variable and function access the compiler will synthesize a
+``const`` pointer to a block version of the ``this`` pointer.
+
+.. _RuntimeHelperFunctions:
+
+Runtime Helper Functions
+========================
+
+The runtime helper functions are described in
+``/usr/local/include/Block_private.h``. To summarize their use, a ``Block``
+requires copy/dispose helpers if it imports any block variables, ``__block``
+storage variables, ``__attribute__((NSObject))`` variables, or C++ ``const``
+copied objects with constructor/destructors. The (1<<26) bit is set and
+functions are generated.
+
+The block copy helper function should, for each of the variables of the type
+mentioned above, call:
+
+.. code-block:: c
+
+ _Block_object_assign(&dst->target, src->target, BLOCK_FIELD_<appropo>);
+
+in the copy helper and:
+
+.. code-block:: c
+
+ _Block_object_dispose(->target, BLOCK_FIELD_<appropo>);
+
+in the dispose helper where ``<appropo>`` is:
+
+.. code-block:: c
+
+ enum {
+ BLOCK_FIELD_IS_OBJECT = 3, // id, NSObject, __attribute__((NSObject)), block, ...
+ BLOCK_FIELD_IS_BLOCK = 7, // a block variable
+ BLOCK_FIELD_IS_BYREF = 8, // the on stack structure holding the __block variable
+
+ BLOCK_FIELD_IS_WEAK = 16, // declared __weak
+
+ BLOCK_BYREF_CALLER = 128, // called from byref copy/dispose helpers
+ };
+
+and of course the constructors/destructors for ``const`` copied C++ objects.
+
+The ``block_byref`` data structure similarly requires copy/dispose helpers for
+block variables, ``__attribute__((NSObject))`` variables, or C++ ``const``
+copied objects with constructor/destructors, and again the (1<<26) bit is set
+and functions are generated in the same manner.
+
+Under ObjC we allow ``__weak`` as an attribute on ``__block`` variables, and
+this causes the addition of ``BLOCK_FIELD_IS_WEAK`` orred onto the
+``BLOCK_FIELD_IS_BYREF`` flag when copying the ``block_byref`` structure in the
+``Block`` copy helper, and onto the ``BLOCK_FIELD_<appropo>`` field within the
+``block_byref`` copy/dispose helper calls.
+
+The prototypes, and summary, of the helper functions are:
+
+.. code-block:: c
+
+ /* Certain field types require runtime assistance when being copied to the
+ heap. The following function is used to copy fields of types: blocks,
+ pointers to byref structures, and objects (including
+ __attribute__((NSObject)) pointers. BLOCK_FIELD_IS_WEAK is orthogonal to
+ the other choices which are mutually exclusive. Only in a Block copy
+ helper will one see BLOCK_FIELD_IS_BYREF.
+ */
+ void _Block_object_assign(void *destAddr, const void *object, const int flags);
+
+ /* Similarly a compiler generated dispose helper needs to call back for each
+ field of the byref data structure. (Currently the implementation only
+ packs one field into the byref structure but in principle there could be
+ more). The same flags used in the copy helper should be used for each
+ call generated to this function:
+ */
+ void _Block_object_dispose(const void *object, const int flags);
+
+Copyright
+=========
+
+Copyright 2008-2010 Apple, Inc.
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
Added: www-releases/trunk/4.0.0/tools/clang/docs/_sources/BlockLanguageSpec.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/4.0.0/tools/clang/docs/_sources/BlockLanguageSpec.txt?rev=297634&view=auto
==============================================================================
--- www-releases/trunk/4.0.0/tools/clang/docs/_sources/BlockLanguageSpec.txt (added)
+++ www-releases/trunk/4.0.0/tools/clang/docs/_sources/BlockLanguageSpec.txt Mon Mar 13 11:30:12 2017
@@ -0,0 +1,361 @@
+
+.. role:: block-term
+
+=================================
+Language Specification for Blocks
+=================================
+
+.. contents::
+ :local:
+
+Revisions
+=========
+
+- 2008/2/25 --- created
+- 2008/7/28 --- revised, ``__block`` syntax
+- 2008/8/13 --- revised, Block globals
+- 2008/8/21 --- revised, C++ elaboration
+- 2008/11/1 --- revised, ``__weak`` support
+- 2009/1/12 --- revised, explicit return types
+- 2009/2/10 --- revised, ``__block`` objects need retain
+
+Overview
+========
+
+A new derived type is introduced to C and, by extension, Objective-C,
+C++, and Objective-C++
+
+The Block Type
+==============
+
+Like function types, the :block-term:`Block type` is a pair consisting
+of a result value type and a list of parameter types very similar to a
+function type. Blocks are intended to be used much like functions with
+the key distinction being that in addition to executable code they
+also contain various variable bindings to automatic (stack) or managed
+(heap) memory.
+
+The abstract declarator,
+
+.. code-block:: c
+
+ int (^)(char, float)
+
+describes a reference to a Block that, when invoked, takes two
+parameters, the first of type char and the second of type float, and
+returns a value of type int. The Block referenced is of opaque data
+that may reside in automatic (stack) memory, global memory, or heap
+memory.
+
+Block Variable Declarations
+===========================
+
+A :block-term:`variable with Block type` is declared using function
+pointer style notation substituting ``^`` for ``*``. The following are
+valid Block variable declarations:
+
+.. code-block:: c
+
+ void (^blockReturningVoidWithVoidArgument)(void);
+ int (^blockReturningIntWithIntAndCharArguments)(int, char);
+ void (^arrayOfTenBlocksReturningVoidWithIntArgument[10])(int);
+
+Variadic ``...`` arguments are supported. [variadic.c] A Block that
+takes no arguments must specify void in the argument list [voidarg.c].
+An empty parameter list does not represent, as K&R provide, an
+unspecified argument list. Note: both gcc and clang support K&R style
+as a convenience.
+
+A Block reference may be cast to a pointer of arbitrary type and vice
+versa. [cast.c] A Block reference may not be dereferenced via the
+pointer dereference operator ``*``, and thus a Block's size may not be
+computed at compile time. [sizeof.c]
+
+Block Literal Expressions
+=========================
+
+A :block-term:`Block literal expression` produces a reference to a
+Block. It is introduced by the use of the ``^`` token as a unary
+operator.
+
+.. code-block:: c
+
+ Block_literal_expression ::= ^ block_decl compound_statement_body
+ block_decl ::=
+ block_decl ::= parameter_list
+ block_decl ::= type_expression
+
+where type expression is extended to allow ``^`` as a Block reference
+(pointer) where ``*`` is allowed as a function reference (pointer).
+
+The following Block literal:
+
+.. code-block:: c
+
+ ^ void (void) { printf("hello world\n"); }
+
+produces a reference to a Block with no arguments with no return value.
+
+The return type is optional and is inferred from the return
+statements. If the return statements return a value, they all must
+return a value of the same type. If there is no value returned the
+inferred type of the Block is void; otherwise it is the type of the
+return statement value.
+
+If the return type is omitted and the argument list is ``( void )``,
+the ``( void )`` argument list may also be omitted.
+
+So:
+
+.. code-block:: c
+
+ ^ ( void ) { printf("hello world\n"); }
+
+and:
+
+.. code-block:: c
+
+ ^ { printf("hello world\n"); }
+
+are exactly equivalent constructs for the same expression.
+
+The type_expression extends C expression parsing to accommodate Block
+reference declarations as it accommodates function pointer
+declarations.
+
+Given:
+
+.. code-block:: c
+
+ typedef int (*pointerToFunctionThatReturnsIntWithCharArg)(char);
+ pointerToFunctionThatReturnsIntWithCharArg functionPointer;
+ ^ pointerToFunctionThatReturnsIntWithCharArg (float x) { return functionPointer; }
+
+and:
+
+.. code-block:: c
+
+ ^ int ((*)(float x))(char) { return functionPointer; }
+
+are equivalent expressions, as is:
+
+.. code-block:: c
+
+ ^(float x) { return functionPointer; }
+
+[returnfunctionptr.c]
+
+The compound statement body establishes a new lexical scope within
+that of its parent. Variables used within the scope of the compound
+statement are bound to the Block in the normal manner with the
+exception of those in automatic (stack) storage. Thus one may access
+functions and global variables as one would expect, as well as static
+local variables. [testme]
+
+Local automatic (stack) variables referenced within the compound
+statement of a Block are imported and captured by the Block as const
+copies. The capture (binding) is performed at the time of the Block
+literal expression evaluation.
+
+The compiler is not required to capture a variable if it can prove
+that no references to the variable will actually be evaluated.
+Programmers can force a variable to be captured by referencing it in a
+statement at the beginning of the Block, like so:
+
+.. code-block:: c
+
+ (void) foo;
+
+This matters when capturing the variable has side-effects, as it can
+in Objective-C or C++.
+
+The lifetime of variables declared in a Block is that of a function;
+each activation frame contains a new copy of variables declared within
+the local scope of the Block. Such variable declarations should be
+allowed anywhere [testme] rather than only when C99 parsing is
+requested, including for statements. [testme]
+
+Block literal expressions may occur within Block literal expressions
+(nest) and all variables captured by any nested blocks are implicitly
+also captured in the scopes of their enclosing Blocks.
+
+A Block literal expression may be used as the initialization value for
+Block variables at global or local static scope.
+
+The Invoke Operator
+===================
+
+Blocks are :block-term:`invoked` using function call syntax with a
+list of expression parameters of types corresponding to the
+declaration and returning a result type also according to the
+declaration. Given:
+
+.. code-block:: c
+
+ int (^x)(char);
+ void (^z)(void);
+ int (^(*y))(char) = &x;
+
+the following are all legal Block invocations:
+
+.. code-block:: c
+
+ x('a');
+ (*y)('a');
+ (true ? x : *y)('a')
+
+The Copy and Release Operations
+===============================
+
+The compiler and runtime provide :block-term:`copy` and
+:block-term:`release` operations for Block references that create and,
+in matched use, release allocated storage for referenced Blocks.
+
+The copy operation ``Block_copy()`` is styled as a function that takes
+an arbitrary Block reference and returns a Block reference of the same
+type. The release operation, ``Block_release()``, is styled as a
+function that takes an arbitrary Block reference and, if dynamically
+matched to a Block copy operation, allows recovery of the referenced
+allocated memory.
+
+
+The ``__block`` Storage Qualifier
+=================================
+
+In addition to the new Block type we also introduce a new storage
+qualifier, :block-term:`__block`, for local variables. [testme: a
+__block declaration within a block literal] The ``__block`` storage
+qualifier is mutually exclusive to the existing local storage
+qualifiers auto, register, and static. [testme] Variables qualified by
+``__block`` act as if they were in allocated storage and this storage
+is automatically recovered after last use of said variable. An
+implementation may choose an optimization where the storage is
+initially automatic and only "moved" to allocated (heap) storage upon
+a Block_copy of a referencing Block. Such variables may be mutated as
+normal variables are.
+
+In the case where a ``__block`` variable is a Block one must assume
+that the ``__block`` variable resides in allocated storage and as such
+is assumed to reference a Block that is also in allocated storage
+(that it is the result of a ``Block_copy`` operation). Despite this
+there is no provision to do a ``Block_copy`` or a ``Block_release`` if
+an implementation provides initial automatic storage for Blocks. This
+is due to the inherent race condition of potentially several threads
+trying to update the shared variable and the need for synchronization
+around disposing of older values and copying new ones. Such
+synchronization is beyond the scope of this language specification.
+
+
+Control Flow
+============
+
+The compound statement of a Block is treated much like a function body
+with respect to control flow in that goto, break, and continue do not
+escape the Block. Exceptions are treated *normally* in that when
+thrown they pop stack frames until a catch clause is found.
+
+
+Objective-C Extensions
+======================
+
+Objective-C extends the definition of a Block reference type to be
+that also of id. A variable or expression of Block type may be
+messaged or used as a parameter wherever an id may be. The converse is
+also true. Block references may thus appear as properties and are
+subject to the assign, retain, and copy attribute logic that is
+reserved for objects.
+
+All Blocks are constructed to be Objective-C objects regardless of
+whether the Objective-C runtime is operational in the program or
+not. Blocks using automatic (stack) memory are objects and may be
+messaged, although they may not be assigned into ``__weak`` locations
+if garbage collection is enabled.
+
+Within a Block literal expression within a method definition
+references to instance variables are also imported into the lexical
+scope of the compound statement. These variables are implicitly
+qualified as references from self, and so self is imported as a const
+copy. The net effect is that instance variables can be mutated.
+
+The :block-term:`Block_copy` operator retains all objects held in
+variables of automatic storage referenced within the Block expression
+(or form strong references if running under garbage collection).
+Object variables of ``__block`` storage type are assumed to hold
+normal pointers with no provision for retain and release messages.
+
+Foundation defines (and supplies) ``-copy`` and ``-release`` methods for
+Blocks.
+
+In the Objective-C and Objective-C++ languages, we allow the
+``__weak`` specifier for ``__block`` variables of object type. If
+garbage collection is not enabled, this qualifier causes these
+variables to be kept without retain messages being sent. This
+knowingly leads to dangling pointers if the Block (or a copy) outlives
+the lifetime of this object.
+
+In garbage collected environments, the ``__weak`` variable is set to
+nil when the object it references is collected, as long as the
+``__block`` variable resides in the heap (either by default or via
+``Block_copy()``). The initial Apple implementation does in fact
+start ``__block`` variables on the stack and migrate them to the heap
+only as a result of a ``Block_copy()`` operation.
+
+It is a runtime error to attempt to assign a reference to a
+stack-based Block into any storage marked ``__weak``, including
+``__weak`` ``__block`` variables.
+
+
+C++ Extensions
+==============
+
+Block literal expressions within functions are extended to allow const
+use of C++ objects, pointers, or references held in automatic storage.
+
+As usual, within the block, references to captured variables become
+const-qualified, as if they were references to members of a const
+object. Note that this does not change the type of a variable of
+reference type.
+
+For example, given a class Foo:
+
+.. code-block:: c
+
+ Foo foo;
+ Foo &fooRef = foo;
+ Foo *fooPtr = &foo;
+
+A Block that referenced these variables would import the variables as
+const variations:
+
+.. code-block:: c
+
+ const Foo block_foo = foo;
+ Foo &block_fooRef = fooRef;
+ Foo *const block_fooPtr = fooPtr;
+
+Captured variables are copied into the Block at the instant of
+evaluating the Block literal expression. They are also copied when
+calling ``Block_copy()`` on a Block allocated on the stack. In both
+cases, they are copied as if the variable were const-qualified, and
+it's an error if there's no such constructor.
+
+Captured variables in Blocks on the stack are destroyed when control
+leaves the compound statement that contains the Block literal
+expression. Captured variables in Blocks on the heap are destroyed
+when the reference count of the Block drops to zero.
+
+Variables declared as residing in ``__block`` storage may be initially
+allocated in the heap or may first appear on the stack and be copied
+to the heap as a result of a ``Block_copy()`` operation. When copied
+from the stack, ``__block`` variables are copied using their normal
+qualification (i.e. without adding const). In C++11, ``__block``
+variables are copied as x-values if that is possible, then as l-values
+if not; if both fail, it's an error. The destructor for any initial
+stack-based version is called at the variable's normal end of scope.
+
+References to ``this``, as well as references to non-static members of
+any enclosing class, are evaluated by capturing ``this`` just like a
+normal variable of C pointer type.
+
+Member variables that are Blocks may not be overloaded by the types of
+their arguments.
Added: www-releases/trunk/4.0.0/tools/clang/docs/_sources/ClangCheck.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/4.0.0/tools/clang/docs/_sources/ClangCheck.txt?rev=297634&view=auto
==============================================================================
--- www-releases/trunk/4.0.0/tools/clang/docs/_sources/ClangCheck.txt (added)
+++ www-releases/trunk/4.0.0/tools/clang/docs/_sources/ClangCheck.txt Mon Mar 13 11:30:12 2017
@@ -0,0 +1,36 @@
+==========
+ClangCheck
+==========
+
+`ClangCheck` is a small wrapper around :doc:`LibTooling` which can be used to
+do basic error checking and AST dumping.
+
+.. code-block:: console
+
+ $ cat <<EOF > snippet.cc
+ > void f() {
+ > int a = 0
+ > }
+ > EOF
+ $ ~/clang/build/bin/clang-check snippet.cc -ast-dump --
+ Processing: /Users/danieljasper/clang/llvm/tools/clang/docs/snippet.cc.
+ /Users/danieljasper/clang/llvm/tools/clang/docs/snippet.cc:2:12: error: expected ';' at end of
+ declaration
+ int a = 0
+ ^
+ ;
+ (TranslationUnitDecl 0x7ff3a3029ed0 <<invalid sloc>>
+ (TypedefDecl 0x7ff3a302a410 <<invalid sloc>> __int128_t '__int128')
+ (TypedefDecl 0x7ff3a302a470 <<invalid sloc>> __uint128_t 'unsigned __int128')
+ (TypedefDecl 0x7ff3a302a830 <<invalid sloc>> __builtin_va_list '__va_list_tag [1]')
+ (FunctionDecl 0x7ff3a302a8d0 </Users/danieljasper/clang/llvm/tools/clang/docs/snippet.cc:1:1, line:3:1> f 'void (void)'
+ (CompoundStmt 0x7ff3a302aa10 <line:1:10, line:3:1>
+ (DeclStmt 0x7ff3a302a9f8 <line:2:3, line:3:1>
+ (VarDecl 0x7ff3a302a980 <line:2:3, col:11> a 'int'
+ (IntegerLiteral 0x7ff3a302a9d8 <col:11> 'int' 0))))))
+ 1 error generated.
+ Error while processing snippet.cc.
+
+The '--' at the end is important as it prevents :program:`clang-check` from
+searching for a compilation database. For more information on how to setup and
+use :program:`clang-check` in a project, see :doc:`HowToSetupToolingForLLVM`.
Added: www-releases/trunk/4.0.0/tools/clang/docs/_sources/ClangFormat.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/4.0.0/tools/clang/docs/_sources/ClangFormat.txt?rev=297634&view=auto
==============================================================================
--- www-releases/trunk/4.0.0/tools/clang/docs/_sources/ClangFormat.txt (added)
+++ www-releases/trunk/4.0.0/tools/clang/docs/_sources/ClangFormat.txt Mon Mar 13 11:30:12 2017
@@ -0,0 +1,196 @@
+===========
+ClangFormat
+===========
+
+`ClangFormat` describes a set of tools that are built on top of
+:doc:`LibFormat`. It can support your workflow in a variety of ways including a
+standalone tool and editor integrations.
+
+
+Standalone Tool
+===============
+
+:program:`clang-format` is located in `clang/tools/clang-format` and can be used
+to format C/C++/Obj-C code.
+
+.. code-block:: console
+
+ $ clang-format -help
+ OVERVIEW: A tool to format C/C++/Java/JavaScript/Objective-C/Protobuf code.
+
+ If no arguments are specified, it formats the code from standard input
+ and writes the result to the standard output.
+ If <file>s are given, it reformats the files. If -i is specified
+ together with <file>s, the files are edited in-place. Otherwise, the
+ result is written to the standard output.
+
+ USAGE: clang-format [options] [<file> ...]
+
+ OPTIONS:
+
+ Clang-format options:
+
+ -assume-filename=<string> - When reading from stdin, clang-format assumes this
+ filename to look for a style config file (with
+ -style=file) and to determine the language.
+ -cursor=<uint> - The position of the cursor when invoking
+ clang-format from an editor integration
+ -dump-config - Dump configuration options to stdout and exit.
+ Can be used with -style option.
+ -fallback-style=<string> - The name of the predefined style used as a
+ fallback in case clang-format is invoked with
+ -style=file, but can not find the .clang-format
+ file to use.
+ Use -fallback-style=none to skip formatting.
+ -i - Inplace edit <file>s, if specified.
+ -length=<uint> - Format a range of this length (in bytes).
+ Multiple ranges can be formatted by specifying
+ several -offset and -length pairs.
+ When only a single -offset is specified without
+ -length, clang-format will format up to the end
+ of the file.
+ Can only be used with one input file.
+ -lines=<string> - <start line>:<end line> - format a range of
+ lines (both 1-based).
+ Multiple ranges can be formatted by specifying
+ several -lines arguments.
+ Can't be used with -offset and -length.
+ Can only be used with one input file.
+ -offset=<uint> - Format a range starting at this byte offset.
+ Multiple ranges can be formatted by specifying
+ several -offset and -length pairs.
+ Can only be used with one input file.
+ -output-replacements-xml - Output replacements as XML.
+ -sort-includes - Sort touched include lines
+ -style=<string> - Coding style, currently supports:
+ LLVM, Google, Chromium, Mozilla, WebKit.
+ Use -style=file to load style configuration from
+ .clang-format file located in one of the parent
+ directories of the source file (or current
+ directory for stdin).
+ Use -style="{key: value, ...}" to set specific
+ parameters, e.g.:
+ -style="{BasedOnStyle: llvm, IndentWidth: 8}"
+
+ Generic Options:
+
+ -help - Display available options (-help-hidden for more)
+ -help-list - Display list of available options (-help-list-hidden for more)
+ -version - Display the version of this program
+
+
+When the desired code formatting style is different from the available options,
+the style can be customized using the ``-style="{key: value, ...}"`` option or
+by putting your style configuration in the ``.clang-format`` or ``_clang-format``
+file in your project's directory and using ``clang-format -style=file``.
+
+An easy way to create the ``.clang-format`` file is:
+
+.. code-block:: console
+
+ clang-format -style=llvm -dump-config > .clang-format
+
+Available style options are described in :doc:`ClangFormatStyleOptions`.
+
+
+Vim Integration
+===============
+
+There is an integration for :program:`vim` which lets you run the
+:program:`clang-format` standalone tool on your current buffer, optionally
+selecting regions to reformat. The integration has the form of a `python`-file
+which can be found under `clang/tools/clang-format/clang-format.py`.
+
+This can be integrated by adding the following to your `.vimrc`:
+
+.. code-block:: vim
+
+ map <C-K> :pyf <path-to-this-file>/clang-format.py<cr>
+ imap <C-K> <c-o>:pyf <path-to-this-file>/clang-format.py<cr>
+
+The first line enables :program:`clang-format` for NORMAL and VISUAL mode, the
+second line adds support for INSERT mode. Change "C-K" to another binding if
+you need :program:`clang-format` on a different key (C-K stands for Ctrl+k).
+
+With this integration you can press the bound key and clang-format will
+format the current line in NORMAL and INSERT mode or the selected region in
+VISUAL mode. The line or region is extended to the next bigger syntactic
+entity.
+
+It operates on the current, potentially unsaved buffer and does not create
+or save any files. To revert a formatting, just undo.
+
+
+Emacs Integration
+=================
+
+Similar to the integration for :program:`vim`, there is an integration for
+:program:`emacs`. It can be found at `clang/tools/clang-format/clang-format.el`
+and used by adding this to your `.emacs`:
+
+.. code-block:: common-lisp
+
+ (load "<path-to-clang>/tools/clang-format/clang-format.el")
+ (global-set-key [C-M-tab] 'clang-format-region)
+
+This binds the function `clang-format-region` to C-M-tab, which then formats the
+current line or selected region.
+
+
+BBEdit Integration
+==================
+
+:program:`clang-format` cannot be used as a text filter with BBEdit, but works
+well via a script. The AppleScript to do this integration can be found at
+`clang/tools/clang-format/clang-format-bbedit.applescript`; place a copy in
+`~/Library/Application Support/BBEdit/Scripts`, and edit the path within it to
+point to your local copy of :program:`clang-format`.
+
+With this integration you can select the script from the Script menu and
+:program:`clang-format` will format the selection. Note that you can rename the
+menu item by renaming the script, and can assign the menu item a keyboard
+shortcut in the BBEdit preferences, under Menus & Shortcuts.
+
+
+Visual Studio Integration
+=========================
+
+Download the latest Visual Studio extension from the `alpha build site
+<http://llvm.org/builds/>`_. The default key-binding is Ctrl-R,Ctrl-F.
+
+
+Script for patch reformatting
+=============================
+
+The python script `clang/tools/clang-format-diff.py` parses the output of
+a unified diff and reformats all contained lines with :program:`clang-format`.
+
+.. code-block:: console
+
+ usage: clang-format-diff.py [-h] [-i] [-p NUM] [-regex PATTERN] [-style STYLE]
+
+ Reformat changed lines in diff. Without -i option just output the diff that
+ would be introduced.
+
+ optional arguments:
+ -h, --help show this help message and exit
+ -i apply edits to files instead of displaying a diff
+ -p NUM strip the smallest prefix containing P slashes
+ -regex PATTERN custom pattern selecting file paths to reformat
+ -style STYLE formatting style to apply (LLVM, Google, Chromium, Mozilla,
+ WebKit)
+
+So to reformat all the lines in the latest :program:`git` commit, just do:
+
+.. code-block:: console
+
+ git diff -U0 --no-color HEAD^ | clang-format-diff.py -i -p1
+
+In an SVN client, you can do:
+
+.. code-block:: console
+
+ svn diff --diff-cmd=diff -x -U0 | clang-format-diff.py -i
+
+The option `-U0` will create a diff without context lines (the script would format
+those as well).
Added: www-releases/trunk/4.0.0/tools/clang/docs/_sources/ClangFormatStyleOptions.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/4.0.0/tools/clang/docs/_sources/ClangFormatStyleOptions.txt?rev=297634&view=auto
==============================================================================
--- www-releases/trunk/4.0.0/tools/clang/docs/_sources/ClangFormatStyleOptions.txt (added)
+++ www-releases/trunk/4.0.0/tools/clang/docs/_sources/ClangFormatStyleOptions.txt Mon Mar 13 11:30:12 2017
@@ -0,0 +1,875 @@
+==========================
+Clang-Format Style Options
+==========================
+
+:doc:`ClangFormatStyleOptions` describes configurable formatting style options
+supported by :doc:`LibFormat` and :doc:`ClangFormat`.
+
+When using :program:`clang-format` command line utility or
+``clang::format::reformat(...)`` functions from code, one can either use one of
+the predefined styles (LLVM, Google, Chromium, Mozilla, WebKit) or create a
+custom style by configuring specific style options.
+
+
+Configuring Style with clang-format
+===================================
+
+:program:`clang-format` supports two ways to provide custom style options:
+directly specify style configuration in the ``-style=`` command line option or
+use ``-style=file`` and put style configuration in the ``.clang-format`` or
+``_clang-format`` file in the project directory.
+
+When using ``-style=file``, :program:`clang-format` for each input file will
+try to find the ``.clang-format`` file located in the closest parent directory
+of the input file. When the standard input is used, the search is started from
+the current directory.
+
+The ``.clang-format`` file uses YAML format:
+
+.. code-block:: yaml
+
+ key1: value1
+ key2: value2
+ # A comment.
+ ...
+
+The configuration file can consist of several sections each having different
+``Language:`` parameter denoting the programming language this section of the
+configuration is targeted at. See the description of the **Language** option
+below for the list of supported languages. The first section may have no
+language set, it will set the default style options for all lanugages.
+Configuration sections for specific language will override options set in the
+default section.
+
+When :program:`clang-format` formats a file, it auto-detects the language using
+the file name. When formatting standard input or a file that doesn't have the
+extension corresponding to its language, ``-assume-filename=`` option can be
+used to override the file name :program:`clang-format` uses to detect the
+language.
+
+An example of a configuration file for multiple languages:
+
+.. code-block:: yaml
+
+ ---
+ # We'll use defaults from the LLVM style, but with 4 columns indentation.
+ BasedOnStyle: LLVM
+ IndentWidth: 4
+ ---
+ Language: Cpp
+ # Force pointers to the type for C++.
+ DerivePointerAlignment: false
+ PointerAlignment: Left
+ ---
+ Language: JavaScript
+ # Use 100 columns for JS.
+ ColumnLimit: 100
+ ---
+ Language: Proto
+ # Don't format .proto files.
+ DisableFormat: true
+ ...
+
+An easy way to get a valid ``.clang-format`` file containing all configuration
+options of a certain predefined style is:
+
+.. code-block:: console
+
+ clang-format -style=llvm -dump-config > .clang-format
+
+When specifying configuration in the ``-style=`` option, the same configuration
+is applied for all input files. The format of the configuration is:
+
+.. code-block:: console
+
+ -style='{key1: value1, key2: value2, ...}'
+
+
+Disabling Formatting on a Piece of Code
+=======================================
+
+Clang-format understands also special comments that switch formatting in a
+delimited range. The code between a comment ``// clang-format off`` or
+``/* clang-format off */`` up to a comment ``// clang-format on`` or
+``/* clang-format on */`` will not be formatted. The comments themselves
+will be formatted (aligned) normally.
+
+.. code-block:: c++
+
+ int formatted_code;
+ // clang-format off
+ void unformatted_code ;
+ // clang-format on
+ void formatted_code_again;
+
+
+Configuring Style in Code
+=========================
+
+When using ``clang::format::reformat(...)`` functions, the format is specified
+by supplying the `clang::format::FormatStyle
+<http://clang.llvm.org/doxygen/structclang_1_1format_1_1FormatStyle.html>`_
+structure.
+
+
+Configurable Format Style Options
+=================================
+
+This section lists the supported style options. Value type is specified for
+each option. For enumeration types possible values are specified both as a C++
+enumeration member (with a prefix, e.g. ``LS_Auto``), and as a value usable in
+the configuration (without a prefix: ``Auto``).
+
+
+**BasedOnStyle** (``string``)
+ The style used for all options not specifically set in the configuration.
+
+ This option is supported only in the :program:`clang-format` configuration
+ (both within ``-style='{...}'`` and the ``.clang-format`` file).
+
+ Possible values:
+
+ * ``LLVM``
+ A style complying with the `LLVM coding standards
+ <http://llvm.org/docs/CodingStandards.html>`_
+ * ``Google``
+ A style complying with `Google's C++ style guide
+ <http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml>`_
+ * ``Chromium``
+ A style complying with `Chromium's style guide
+ <http://www.chromium.org/developers/coding-style>`_
+ * ``Mozilla``
+ A style complying with `Mozilla's style guide
+ <https://developer.mozilla.org/en-US/docs/Developer_Guide/Coding_Style>`_
+ * ``WebKit``
+ A style complying with `WebKit's style guide
+ <http://www.webkit.org/coding/coding-style.html>`_
+
+.. START_FORMAT_STYLE_OPTIONS
+
+**AccessModifierOffset** (``int``)
+ The extra indent or outdent of access modifiers, e.g. ``public:``.
+
+**AlignAfterOpenBracket** (``BracketAlignmentStyle``)
+ If ``true``, horizontally aligns arguments after an open bracket.
+
+ This applies to round brackets (parentheses), angle brackets and square
+ brackets.
+
+ Possible values:
+
+ * ``BAS_Align`` (in configuration: ``Align``)
+ Align parameters on the open bracket, e.g.:
+
+ .. code-block:: c++
+
+ someLongFunction(argument1,
+ argument2);
+
+ * ``BAS_DontAlign`` (in configuration: ``DontAlign``)
+ Don't align, instead use ``ContinuationIndentWidth``, e.g.:
+
+ .. code-block:: c++
+
+ someLongFunction(argument1,
+ argument2);
+
+ * ``BAS_AlwaysBreak`` (in configuration: ``AlwaysBreak``)
+ Always break after an open bracket, if the parameters don't fit
+ on a single line, e.g.:
+
+ .. code-block:: c++
+
+ someLongFunction(
+ argument1, argument2);
+
+
+
+**AlignConsecutiveAssignments** (``bool``)
+ If ``true``, aligns consecutive assignments.
+
+ This will align the assignment operators of consecutive lines. This
+ will result in formattings like
+
+ .. code-block:: c++
+
+ int aaaa = 12;
+ int b = 23;
+ int ccc = 23;
+
+**AlignConsecutiveDeclarations** (``bool``)
+ If ``true``, aligns consecutive declarations.
+
+ This will align the declaration names of consecutive lines. This
+ will result in formattings like
+
+ .. code-block:: c++
+
+ int aaaa = 12;
+ float b = 23;
+ std::string ccc = 23;
+
+**AlignEscapedNewlinesLeft** (``bool``)
+ If ``true``, aligns escaped newlines as far left as possible.
+ Otherwise puts them into the right-most column.
+
+**AlignOperands** (``bool``)
+ If ``true``, horizontally align operands of binary and ternary
+ expressions.
+
+ Specifically, this aligns operands of a single expression that needs to be
+ split over multiple lines, e.g.:
+
+ .. code-block:: c++
+
+ int aaa = bbbbbbbbbbbbbbb +
+ ccccccccccccccc;
+
+**AlignTrailingComments** (``bool``)
+ If ``true``, aligns trailing comments.
+
+**AllowAllParametersOfDeclarationOnNextLine** (``bool``)
+ Allow putting all parameters of a function declaration onto
+ the next line even if ``BinPackParameters`` is ``false``.
+
+**AllowShortBlocksOnASingleLine** (``bool``)
+ Allows contracting simple braced statements to a single line.
+
+ E.g., this allows ``if (a) { return; }`` to be put on a single line.
+
+**AllowShortCaseLabelsOnASingleLine** (``bool``)
+ If ``true``, short case labels will be contracted to a single line.
+
+**AllowShortFunctionsOnASingleLine** (``ShortFunctionStyle``)
+ Dependent on the value, ``int f() { return 0; }`` can be put on a
+ single line.
+
+ Possible values:
+
+ * ``SFS_None`` (in configuration: ``None``)
+ Never merge functions into a single line.
+
+ * ``SFS_Empty`` (in configuration: ``Empty``)
+ Only merge empty functions.
+
+ * ``SFS_Inline`` (in configuration: ``Inline``)
+ Only merge functions defined inside a class. Implies "empty".
+
+ * ``SFS_All`` (in configuration: ``All``)
+ Merge all functions fitting on a single line.
+
+
+
+**AllowShortIfStatementsOnASingleLine** (``bool``)
+ If ``true``, ``if (a) return;`` can be put on a single line.
+
+**AllowShortLoopsOnASingleLine** (``bool``)
+ If ``true``, ``while (true) continue;`` can be put on a single
+ line.
+
+**AlwaysBreakAfterDefinitionReturnType** (``DefinitionReturnTypeBreakingStyle``)
+ The function definition return type breaking style to use. This
+ option is deprecated and is retained for backwards compatibility.
+
+ Possible values:
+
+ * ``DRTBS_None`` (in configuration: ``None``)
+ Break after return type automatically.
+ ``PenaltyReturnTypeOnItsOwnLine`` is taken into account.
+
+ * ``DRTBS_All`` (in configuration: ``All``)
+ Always break after the return type.
+
+ * ``DRTBS_TopLevel`` (in configuration: ``TopLevel``)
+ Always break after the return types of top-level functions.
+
+
+
+**AlwaysBreakAfterReturnType** (``ReturnTypeBreakingStyle``)
+ The function declaration return type breaking style to use.
+
+ Possible values:
+
+ * ``RTBS_None`` (in configuration: ``None``)
+ Break after return type automatically.
+ ``PenaltyReturnTypeOnItsOwnLine`` is taken into account.
+
+ * ``RTBS_All`` (in configuration: ``All``)
+ Always break after the return type.
+
+ * ``RTBS_TopLevel`` (in configuration: ``TopLevel``)
+ Always break after the return types of top-level functions.
+
+ * ``RTBS_AllDefinitions`` (in configuration: ``AllDefinitions``)
+ Always break after the return type of function definitions.
+
+ * ``RTBS_TopLevelDefinitions`` (in configuration: ``TopLevelDefinitions``)
+ Always break after the return type of top-level definitions.
+
+
+
+**AlwaysBreakBeforeMultilineStrings** (``bool``)
+ If ``true``, always break before multiline string literals.
+
+ This flag is mean to make cases where there are multiple multiline strings
+ in a file look more consistent. Thus, it will only take effect if wrapping
+ the string at that point leads to it being indented
+ ``ContinuationIndentWidth`` spaces from the start of the line.
+
+**AlwaysBreakTemplateDeclarations** (``bool``)
+ If ``true``, always break after the ``template<...>`` of a template
+ declaration.
+
+**BinPackArguments** (``bool``)
+ If ``false``, a function call's arguments will either be all on the
+ same line or will have one line each.
+
+**BinPackParameters** (``bool``)
+ If ``false``, a function declaration's or function definition's
+ parameters will either all be on the same line or will have one line each.
+
+**BraceWrapping** (``BraceWrappingFlags``)
+ Control of individual brace wrapping cases.
+
+ If ``BreakBeforeBraces`` is set to ``BS_Custom``, use this to specify how
+ each individual brace case should be handled. Otherwise, this is ignored.
+
+ Nested configuration flags:
+
+ * ``bool AfterClass`` Wrap class definitions.
+ * ``bool AfterControlStatement`` Wrap control statements (``if``/``for``/``while``/``switch``/..).
+ * ``bool AfterEnum`` Wrap enum definitions.
+ * ``bool AfterFunction`` Wrap function definitions.
+ * ``bool AfterNamespace`` Wrap namespace definitions.
+ * ``bool AfterObjCDeclaration`` Wrap ObjC definitions (``@autoreleasepool``, interfaces, ..).
+ * ``bool AfterStruct`` Wrap struct definitions.
+ * ``bool AfterUnion`` Wrap union definitions.
+ * ``bool BeforeCatch`` Wrap before ``catch``.
+ * ``bool BeforeElse`` Wrap before ``else``.
+ * ``bool IndentBraces`` Indent the wrapped braces themselves.
+
+
+**BreakAfterJavaFieldAnnotations** (``bool``)
+ Break after each annotation on a field in Java files.
+
+**BreakBeforeBinaryOperators** (``BinaryOperatorStyle``)
+ The way to wrap binary operators.
+
+ Possible values:
+
+ * ``BOS_None`` (in configuration: ``None``)
+ Break after operators.
+
+ * ``BOS_NonAssignment`` (in configuration: ``NonAssignment``)
+ Break before operators that aren't assignments.
+
+ * ``BOS_All`` (in configuration: ``All``)
+ Break before operators.
+
+
+
+**BreakBeforeBraces** (``BraceBreakingStyle``)
+ The brace breaking style to use.
+
+ Possible values:
+
+ * ``BS_Attach`` (in configuration: ``Attach``)
+ Always attach braces to surrounding context.
+
+ * ``BS_Linux`` (in configuration: ``Linux``)
+ Like ``Attach``, but break before braces on function, namespace and
+ class definitions.
+
+ * ``BS_Mozilla`` (in configuration: ``Mozilla``)
+ Like ``Attach``, but break before braces on enum, function, and record
+ definitions.
+
+ * ``BS_Stroustrup`` (in configuration: ``Stroustrup``)
+ Like ``Attach``, but break before function definitions, ``catch``, and
+ ``else``.
+
+ * ``BS_Allman`` (in configuration: ``Allman``)
+ Always break before braces.
+
+ * ``BS_GNU`` (in configuration: ``GNU``)
+ Always break before braces and add an extra level of indentation to
+ braces of control statements, not to those of class, function
+ or other definitions.
+
+ * ``BS_WebKit`` (in configuration: ``WebKit``)
+ Like ``Attach``, but break before functions.
+
+ * ``BS_Custom`` (in configuration: ``Custom``)
+ Configure each individual brace in `BraceWrapping`.
+
+
+
+**BreakBeforeTernaryOperators** (``bool``)
+ If ``true``, ternary operators will be placed after line breaks.
+
+**BreakConstructorInitializersBeforeComma** (``bool``)
+ Always break constructor initializers before commas and align
+ the commas with the colon.
+
+**BreakStringLiterals** (``bool``)
+ Allow breaking string literals when formatting.
+
+**ColumnLimit** (``unsigned``)
+ The column limit.
+
+ A column limit of ``0`` means that there is no column limit. In this case,
+ clang-format will respect the input's line breaking decisions within
+ statements unless they contradict other rules.
+
+**CommentPragmas** (``std::string``)
+ A regular expression that describes comments with special meaning,
+ which should not be split into lines or otherwise changed.
+
+**ConstructorInitializerAllOnOneLineOrOnePerLine** (``bool``)
+ If the constructor initializers don't fit on a line, put each
+ initializer on its own line.
+
+**ConstructorInitializerIndentWidth** (``unsigned``)
+ The number of characters to use for indentation of constructor
+ initializer lists.
+
+**ContinuationIndentWidth** (``unsigned``)
+ Indent width for line continuations.
+
+**Cpp11BracedListStyle** (``bool``)
+ If ``true``, format braced lists as best suited for C++11 braced
+ lists.
+
+ Important differences:
+ - No spaces inside the braced list.
+ - No line break before the closing brace.
+ - Indentation with the continuation indent, not with the block indent.
+
+ Fundamentally, C++11 braced lists are formatted exactly like function
+ calls would be formatted in their place. If the braced list follows a name
+ (e.g. a type or variable name), clang-format formats as if the ``{}`` were
+ the parentheses of a function call with that name. If there is no name,
+ a zero-length name is assumed.
+
+**DerivePointerAlignment** (``bool``)
+ If ``true``, analyze the formatted file for the most common
+ alignment of ``&`` and ``\*``. ``PointerAlignment`` is then used only as
+ fallback.
+
+**DisableFormat** (``bool``)
+ Disables formatting completely.
+
+**ExperimentalAutoDetectBinPacking** (``bool``)
+ If ``true``, clang-format detects whether function calls and
+ definitions are formatted with one parameter per line.
+
+ Each call can be bin-packed, one-per-line or inconclusive. If it is
+ inconclusive, e.g. completely on one line, but a decision needs to be
+ made, clang-format analyzes whether there are other bin-packed cases in
+ the input file and act accordingly.
+
+ NOTE: This is an experimental flag, that might go away or be renamed. Do
+ not use this in config files, etc. Use at your own risk.
+
+**ForEachMacros** (``std::vector<std::string>``)
+ A vector of macros that should be interpreted as foreach loops
+ instead of as function calls.
+
+ These are expected to be macros of the form:
+
+ .. code-block:: c++
+
+ FOREACH(<variable-declaration>, ...)
+ <loop-body>
+
+ In the .clang-format configuration file, this can be configured like:
+
+ .. code-block:: yaml
+
+ ForEachMacros: ['RANGES_FOR', 'FOREACH']
+
+ For example: BOOST_FOREACH.
+
+**IncludeCategories** (``std::vector<IncludeCategory>``)
+ Regular expressions denoting the different ``#include`` categories
+ used for ordering ``#includes``.
+
+ These regular expressions are matched against the filename of an include
+ (including the <> or "") in order. The value belonging to the first
+ matching regular expression is assigned and ``#includes`` are sorted first
+ according to increasing category number and then alphabetically within
+ each category.
+
+ If none of the regular expressions match, INT_MAX is assigned as
+ category. The main header for a source file automatically gets category 0.
+ so that it is generally kept at the beginning of the ``#includes``
+ (http://llvm.org/docs/CodingStandards.html#include-style). However, you
+ can also assign negative priorities if you have certain headers that
+ always need to be first.
+
+ To configure this in the .clang-format file, use:
+
+ .. code-block:: yaml
+
+ IncludeCategories:
+ - Regex: '^"(llvm|llvm-c|clang|clang-c)/'
+ Priority: 2
+ - Regex: '^(<|"(gtest|isl|json)/)'
+ Priority: 3
+ - Regex: '.\*'
+ Priority: 1
+
+**IncludeIsMainRegex** (``std::string``)
+ Specify a regular expression of suffixes that are allowed in the
+ file-to-main-include mapping.
+
+ When guessing whether a #include is the "main" include (to assign
+ category 0, see above), use this regex of allowed suffixes to the header
+ stem. A partial match is done, so that:
+ - "" means "arbitrary suffix"
+ - "$" means "no suffix"
+
+ For example, if configured to "(_test)?$", then a header a.h would be seen
+ as the "main" include in both a.cc and a_test.cc.
+
+**IndentCaseLabels** (``bool``)
+ Indent case labels one level from the switch statement.
+
+ When ``false``, use the same indentation level as for the switch statement.
+ Switch statement body is always indented one level more than case labels.
+
+**IndentWidth** (``unsigned``)
+ The number of columns to use for indentation.
+
+**IndentWrappedFunctionNames** (``bool``)
+ Indent if a function definition or declaration is wrapped after the
+ type.
+
+**JavaScriptQuotes** (``JavaScriptQuoteStyle``)
+ The JavaScriptQuoteStyle to use for JavaScript strings.
+
+ Possible values:
+
+ * ``JSQS_Leave`` (in configuration: ``Leave``)
+ Leave string quotes as they are.
+
+ * ``JSQS_Single`` (in configuration: ``Single``)
+ Always use single quotes.
+
+ * ``JSQS_Double`` (in configuration: ``Double``)
+ Always use double quotes.
+
+
+
+**KeepEmptyLinesAtTheStartOfBlocks** (``bool``)
+ If true, empty lines at the start of blocks are kept.
+
+**Language** (``LanguageKind``)
+ Language, this format style is targeted at.
+
+ Possible values:
+
+ * ``LK_None`` (in configuration: ``None``)
+ Do not use.
+
+ * ``LK_Cpp`` (in configuration: ``Cpp``)
+ Should be used for C, C++, ObjectiveC, ObjectiveC++.
+
+ * ``LK_Java`` (in configuration: ``Java``)
+ Should be used for Java.
+
+ * ``LK_JavaScript`` (in configuration: ``JavaScript``)
+ Should be used for JavaScript.
+
+ * ``LK_Proto`` (in configuration: ``Proto``)
+ Should be used for Protocol Buffers
+ (https://developers.google.com/protocol-buffers/).
+
+ * ``LK_TableGen`` (in configuration: ``TableGen``)
+ Should be used for TableGen code.
+
+
+
+**MacroBlockBegin** (``std::string``)
+ A regular expression matching macros that start a block.
+
+**MacroBlockEnd** (``std::string``)
+ A regular expression matching macros that end a block.
+
+**MaxEmptyLinesToKeep** (``unsigned``)
+ The maximum number of consecutive empty lines to keep.
+
+**NamespaceIndentation** (``NamespaceIndentationKind``)
+ The indentation used for namespaces.
+
+ Possible values:
+
+ * ``NI_None`` (in configuration: ``None``)
+ Don't indent in namespaces.
+
+ * ``NI_Inner`` (in configuration: ``Inner``)
+ Indent only in inner namespaces (nested in other namespaces).
+
+ * ``NI_All`` (in configuration: ``All``)
+ Indent in all namespaces.
+
+
+
+**ObjCBlockIndentWidth** (``unsigned``)
+ The number of characters to use for indentation of ObjC blocks.
+
+**ObjCSpaceAfterProperty** (``bool``)
+ Add a space after ``@property`` in Objective-C, i.e. use
+ ``@property (readonly)`` instead of ``@property(readonly)``.
+
+**ObjCSpaceBeforeProtocolList** (``bool``)
+ Add a space in front of an Objective-C protocol list, i.e. use
+ ``Foo <Protocol>`` instead of ``Foo<Protocol>``.
+
+**PenaltyBreakBeforeFirstCallParameter** (``unsigned``)
+ The penalty for breaking a function call after ``call(``.
+
+**PenaltyBreakComment** (``unsigned``)
+ The penalty for each line break introduced inside a comment.
+
+**PenaltyBreakFirstLessLess** (``unsigned``)
+ The penalty for breaking before the first ``<<``.
+
+**PenaltyBreakString** (``unsigned``)
+ The penalty for each line break introduced inside a string literal.
+
+**PenaltyExcessCharacter** (``unsigned``)
+ The penalty for each character outside of the column limit.
+
+**PenaltyReturnTypeOnItsOwnLine** (``unsigned``)
+ Penalty for putting the return type of a function onto its own
+ line.
+
+**PointerAlignment** (``PointerAlignmentStyle``)
+ Pointer and reference alignment style.
+
+ Possible values:
+
+ * ``PAS_Left`` (in configuration: ``Left``)
+ Align pointer to the left.
+
+ * ``PAS_Right`` (in configuration: ``Right``)
+ Align pointer to the right.
+
+ * ``PAS_Middle`` (in configuration: ``Middle``)
+ Align pointer in the middle.
+
+
+
+**ReflowComments** (``bool``)
+ If ``true``, clang-format will attempt to re-flow comments.
+
+**SortIncludes** (``bool``)
+ If ``true``, clang-format will sort ``#includes``.
+
+**SpaceAfterCStyleCast** (``bool``)
+ If ``true``, a space may be inserted after C style casts.
+
+**SpaceAfterTemplateKeyword** (``bool``)
+ If ``true``, a space will be inserted after the 'template' keyword.
+
+**SpaceBeforeAssignmentOperators** (``bool``)
+ If ``false``, spaces will be removed before assignment operators.
+
+**SpaceBeforeParens** (``SpaceBeforeParensOptions``)
+ Defines in which cases to put a space before opening parentheses.
+
+ Possible values:
+
+ * ``SBPO_Never`` (in configuration: ``Never``)
+ Never put a space before opening parentheses.
+
+ * ``SBPO_ControlStatements`` (in configuration: ``ControlStatements``)
+ Put a space before opening parentheses only after control statement
+ keywords (``for/if/while...``).
+
+ * ``SBPO_Always`` (in configuration: ``Always``)
+ Always put a space before opening parentheses, except when it's
+ prohibited by the syntax rules (in function-like macro definitions) or
+ when determined by other style rules (after unary operators, opening
+ parentheses, etc.)
+
+
+
+**SpaceInEmptyParentheses** (``bool``)
+ If ``true``, spaces may be inserted into ``()``.
+
+**SpacesBeforeTrailingComments** (``unsigned``)
+ The number of spaces before trailing line comments
+ (``//`` - comments).
+
+ This does not affect trailing block comments (``/*`` - comments) as
+ those commonly have different usage patterns and a number of special
+ cases.
+
+**SpacesInAngles** (``bool``)
+ If ``true``, spaces will be inserted after ``<`` and before ``>``
+ in template argument lists.
+
+**SpacesInCStyleCastParentheses** (``bool``)
+ If ``true``, spaces may be inserted into C style casts.
+
+**SpacesInContainerLiterals** (``bool``)
+ If ``true``, spaces are inserted inside container literals (e.g.
+ ObjC and Javascript array and dict literals).
+
+**SpacesInParentheses** (``bool``)
+ If ``true``, spaces will be inserted after ``(`` and before ``)``.
+
+**SpacesInSquareBrackets** (``bool``)
+ If ``true``, spaces will be inserted after ``[`` and before ``]``.
+
+**Standard** (``LanguageStandard``)
+ Format compatible with this standard, e.g. use ``A<A<int> >``
+ instead of ``A<A<int>>`` for ``LS_Cpp03``.
+
+ Possible values:
+
+ * ``LS_Cpp03`` (in configuration: ``Cpp03``)
+ Use C++03-compatible syntax.
+
+ * ``LS_Cpp11`` (in configuration: ``Cpp11``)
+ Use features of C++11 (e.g. ``A<A<int>>`` instead of ``A<A<int> >``).
+
+ * ``LS_Auto`` (in configuration: ``Auto``)
+ Automatic detection based on the input.
+
+
+
+**TabWidth** (``unsigned``)
+ The number of columns used for tab stops.
+
+**UseTab** (``UseTabStyle``)
+ The way to use tab characters in the resulting file.
+
+ Possible values:
+
+ * ``UT_Never`` (in configuration: ``Never``)
+ Never use tab.
+
+ * ``UT_ForIndentation`` (in configuration: ``ForIndentation``)
+ Use tabs only for indentation.
+
+ * ``UT_Always`` (in configuration: ``Always``)
+ Use tabs whenever we need to fill whitespace that spans at least from
+ one tab stop to the next one.
+
+
+
+.. END_FORMAT_STYLE_OPTIONS
+
+Adding additional style options
+===============================
+
+Each additional style option adds costs to the clang-format project. Some of
+these costs affect the clang-format development itself, as we need to make
+sure that any given combination of options work and that new features don't
+break any of the existing options in any way. There are also costs for end users
+as options become less discoverable and people have to think about and make a
+decision on options they don't really care about.
+
+The goal of the clang-format project is more on the side of supporting a
+limited set of styles really well as opposed to supporting every single style
+used by a codebase somewhere in the wild. Of course, we do want to support all
+major projects and thus have established the following bar for adding style
+options. Each new style option must ..
+
+ * be used in a project of significant size (have dozens of contributors)
+ * have a publicly accessible style guide
+ * have a person willing to contribute and maintain patches
+
+Examples
+========
+
+A style similar to the `Linux Kernel style
+<https://www.kernel.org/doc/Documentation/CodingStyle>`_:
+
+.. code-block:: yaml
+
+ BasedOnStyle: LLVM
+ IndentWidth: 8
+ UseTab: Always
+ BreakBeforeBraces: Linux
+ AllowShortIfStatementsOnASingleLine: false
+ IndentCaseLabels: false
+
+The result is (imagine that tabs are used for indentation here):
+
+.. code-block:: c++
+
+ void test()
+ {
+ switch (x) {
+ case 0:
+ case 1:
+ do_something();
+ break;
+ case 2:
+ do_something_else();
+ break;
+ default:
+ break;
+ }
+ if (condition)
+ do_something_completely_different();
+
+ if (x == y) {
+ q();
+ } else if (x > y) {
+ w();
+ } else {
+ r();
+ }
+ }
+
+A style similar to the default Visual Studio formatting style:
+
+.. code-block:: yaml
+
+ UseTab: Never
+ IndentWidth: 4
+ BreakBeforeBraces: Allman
+ AllowShortIfStatementsOnASingleLine: false
+ IndentCaseLabels: false
+ ColumnLimit: 0
+
+The result is:
+
+.. code-block:: c++
+
+ void test()
+ {
+ switch (suffix)
+ {
+ case 0:
+ case 1:
+ do_something();
+ break;
+ case 2:
+ do_something_else();
+ break;
+ default:
+ break;
+ }
+ if (condition)
+ do_somthing_completely_different();
+
+ if (x == y)
+ {
+ q();
+ }
+ else if (x > y)
+ {
+ w();
+ }
+ else
+ {
+ r();
+ }
+ }
+
Added: www-releases/trunk/4.0.0/tools/clang/docs/_sources/ClangPlugins.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/4.0.0/tools/clang/docs/_sources/ClangPlugins.txt?rev=297634&view=auto
==============================================================================
--- www-releases/trunk/4.0.0/tools/clang/docs/_sources/ClangPlugins.txt (added)
+++ www-releases/trunk/4.0.0/tools/clang/docs/_sources/ClangPlugins.txt Mon Mar 13 11:30:12 2017
@@ -0,0 +1,130 @@
+=============
+Clang Plugins
+=============
+
+Clang Plugins make it possible to run extra user defined actions during a
+compilation. This document will provide a basic walkthrough of how to write and
+run a Clang Plugin.
+
+Introduction
+============
+
+Clang Plugins run FrontendActions over code. See the :doc:`FrontendAction
+tutorial <RAVFrontendAction>` on how to write a ``FrontendAction`` using the
+``RecursiveASTVisitor``. In this tutorial, we'll demonstrate how to write a
+simple clang plugin.
+
+Writing a ``PluginASTAction``
+=============================
+
+The main difference from writing normal ``FrontendActions`` is that you can
+handle plugin command line options. The ``PluginASTAction`` base class declares
+a ``ParseArgs`` method which you have to implement in your plugin.
+
+.. code-block:: c++
+
+ bool ParseArgs(const CompilerInstance &CI,
+ const std::vector<std::string>& args) {
+ for (unsigned i = 0, e = args.size(); i != e; ++i) {
+ if (args[i] == "-some-arg") {
+ // Handle the command line argument.
+ }
+ }
+ return true;
+ }
+
+Registering a plugin
+====================
+
+A plugin is loaded from a dynamic library at runtime by the compiler. To
+register a plugin in a library, use ``FrontendPluginRegistry::Add<>``:
+
+.. code-block:: c++
+
+ static FrontendPluginRegistry::Add<MyPlugin> X("my-plugin-name", "my plugin description");
+
+Defining pragmas
+================
+
+Plugins can also define pragmas by declaring a ``PragmaHandler`` and
+registering it using ``PragmaHandlerRegistry::Add<>``:
+
+.. code-block:: c++
+
+ // Define a pragma handler for #pragma example_pragma
+ class ExamplePragmaHandler : public PragmaHandler {
+ public:
+ ExamplePragmaHandler() : PragmaHandler("example_pragma") { }
+ void HandlePragma(Preprocessor &PP, PragmaIntroducerKind Introducer,
+ Token &PragmaTok) {
+ // Handle the pragma
+ }
+ };
+
+ static PragmaHandlerRegistry::Add<ExamplePragmaHandler> Y("example_pragma","example pragma description");
+
+Putting it all together
+=======================
+
+Let's look at an example plugin that prints top-level function names. This
+example is checked into the clang repository; please take a look at
+the `latest version of PrintFunctionNames.cpp
+<http://llvm.org/viewvc/llvm-project/cfe/trunk/examples/PrintFunctionNames/PrintFunctionNames.cpp?view=markup>`_.
+
+Running the plugin
+==================
+
+
+Using the cc1 command line
+--------------------------
+
+To run a plugin, the dynamic library containing the plugin registry must be
+loaded via the `-load` command line option. This will load all plugins
+that are registered, and you can select the plugins to run by specifying the
+`-plugin` option. Additional parameters for the plugins can be passed with
+`-plugin-arg-<plugin-name>`.
+
+Note that those options must reach clang's cc1 process. There are two
+ways to do so:
+
+* Directly call the parsing process by using the `-cc1` option; this
+ has the downside of not configuring the default header search paths, so
+ you'll need to specify the full system path configuration on the command
+ line.
+* Use clang as usual, but prefix all arguments to the cc1 process with
+ `-Xclang`.
+
+For example, to run the ``print-function-names`` plugin over a source file in
+clang, first build the plugin, and then call clang with the plugin from the
+source tree:
+
+.. code-block:: console
+
+ $ export BD=/path/to/build/directory
+ $ (cd $BD && make PrintFunctionNames )
+ $ clang++ -D_GNU_SOURCE -D_DEBUG -D__STDC_CONSTANT_MACROS \
+ -D__STDC_FORMAT_MACROS -D__STDC_LIMIT_MACROS -D_GNU_SOURCE \
+ -I$BD/tools/clang/include -Itools/clang/include -I$BD/include -Iinclude \
+ tools/clang/tools/clang-check/ClangCheck.cpp -fsyntax-only \
+ -Xclang -load -Xclang $BD/lib/PrintFunctionNames.so -Xclang \
+ -plugin -Xclang print-fns
+
+Also see the print-function-name plugin example's
+`README <http://llvm.org/viewvc/llvm-project/cfe/trunk/examples/PrintFunctionNames/README.txt?view=markup>`_
+
+
+Using the clang command line
+----------------------------
+
+Using `-fplugin=plugin` on the clang command line passes the plugin
+through as an argument to `-load` on the cc1 command line. If the plugin
+class implements the ``getActionType`` method then the plugin is run
+automatically. For example, to run the plugin automatically after the main AST
+action (i.e. the same as using `-add-plugin`):
+
+.. code-block:: c++
+
+ // Automatically run the plugin after the main AST action
+ PluginASTAction::ActionType getActionType() override {
+ return AddAfterMainAction;
+ }
Added: www-releases/trunk/4.0.0/tools/clang/docs/_sources/ClangTools.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/4.0.0/tools/clang/docs/_sources/ClangTools.txt?rev=297634&view=auto
==============================================================================
--- www-releases/trunk/4.0.0/tools/clang/docs/_sources/ClangTools.txt (added)
+++ www-releases/trunk/4.0.0/tools/clang/docs/_sources/ClangTools.txt Mon Mar 13 11:30:12 2017
@@ -0,0 +1,167 @@
+========
+Overview
+========
+
+Clang Tools are standalone command line (and potentially GUI) tools
+designed for use by C++ developers who are already using and enjoying
+Clang as their compiler. These tools provide developer-oriented
+functionality such as fast syntax checking, automatic formatting,
+refactoring, etc.
+
+Only a couple of the most basic and fundamental tools are kept in the
+primary Clang Subversion project. The rest of the tools are kept in a
+side-project so that developers who don't want or need to build them
+don't. If you want to get access to the extra Clang Tools repository,
+simply check it out into the tools tree of your Clang checkout and
+follow the usual process for building and working with a combined
+LLVM/Clang checkout:
+
+- With Subversion:
+
+ - ``cd llvm/tools/clang/tools``
+ - ``svn co http://llvm.org/svn/llvm-project/clang-tools-extra/trunk extra``
+
+- Or with Git:
+
+ - ``cd llvm/tools/clang/tools``
+ - ``git clone http://llvm.org/git/clang-tools-extra.git extra``
+
+This document describes a high-level overview of the organization of
+Clang Tools within the project as well as giving an introduction to some
+of the more important tools. However, it should be noted that this
+document is currently focused on Clang and Clang Tool developers, not on
+end users of these tools.
+
+Clang Tools Organization
+========================
+
+Clang Tools are CLI or GUI programs that are intended to be directly
+used by C++ developers. That is they are *not* primarily for use by
+Clang developers, although they are hopefully useful to C++ developers
+who happen to work on Clang, and we try to actively dogfood their
+functionality. They are developed in three components: the underlying
+infrastructure for building a standalone tool based on Clang, core
+shared logic used by many different tools in the form of refactoring and
+rewriting libraries, and the tools themselves.
+
+The underlying infrastructure for Clang Tools is the
+:doc:`LibTooling <LibTooling>` platform. See its documentation for much
+more detailed information about how this infrastructure works. The
+common refactoring and rewriting toolkit-style library is also part of
+LibTooling organizationally.
+
+A few Clang Tools are developed along side the core Clang libraries as
+examples and test cases of fundamental functionality. However, most of
+the tools are developed in a side repository to provide easy separation
+from the core libraries. We intentionally do not support public
+libraries in the side repository, as we want to carefully review and
+find good APIs for libraries as they are lifted out of a few tools and
+into the core Clang library set.
+
+Regardless of which repository Clang Tools' code resides in, the
+development process and practices for all Clang Tools are exactly those
+of Clang itself. They are entirely within the Clang *project*,
+regardless of the version control scheme.
+
+Core Clang Tools
+================
+
+The core set of Clang tools that are within the main repository are
+tools that very specifically complement, and allow use and testing of
+*Clang* specific functionality.
+
+``clang-check``
+---------------
+
+:doc:`ClangCheck` combines the LibTooling framework for running a
+Clang tool with the basic Clang diagnostics by syntax checking specific files
+in a fast, command line interface. It can also accept flags to re-display the
+diagnostics in different formats with different flags, suitable for use driving
+an IDE or editor. Furthermore, it can be used in fixit-mode to directly apply
+fixit-hints offered by clang. See :doc:`HowToSetupToolingForLLVM` for
+instructions on how to setup and used `clang-check`.
+
+``clang-format``
+----------------
+
+Clang-format is both a :doc:`library <LibFormat>` and a :doc:`stand-alone tool
+<ClangFormat>` with the goal of automatically reformatting C++ sources files
+according to configurable style guides. To do so, clang-format uses Clang's
+``Lexer`` to transform an input file into a token stream and then changes all
+the whitespace around those tokens. The goal is for clang-format to serve both
+as a user tool (ideally with powerful IDE integrations) and as part of other
+refactoring tools, e.g. to do a reformatting of all the lines changed during a
+renaming.
+
+
+Extra Clang Tools
+=================
+
+As various categories of Clang Tools are added to the extra repository,
+they'll be tracked here. The focus of this documentation is on the scope
+and features of the tools for other tool developers; each tool should
+provide its own user-focused documentation.
+
+``clang-tidy``
+--------------
+
+`clang-tidy <http://clang.llvm.org/extra/clang-tidy/>`_ is a clang-based C++
+linter tool. It provides an extensible framework for building compiler-based
+static analyses detecting and fixing bug-prone patterns, performance,
+portability and maintainability issues.
+
+
+Ideas for new Tools
+===================
+
+* C++ cast conversion tool. Will convert C-style casts (``(type) value``) to
+ appropriate C++ cast (``static_cast``, ``const_cast`` or
+ ``reinterpret_cast``).
+* Non-member ``begin()`` and ``end()`` conversion tool. Will convert
+ ``foo.begin()`` into ``begin(foo)`` and similarly for ``end()``, where
+ ``foo`` is a standard container. We could also detect similar patterns for
+ arrays.
+* ``tr1`` removal tool. Will migrate source code from using TR1 library
+ features to C++11 library. For example:
+
+ .. code-block:: c++
+
+ #include <tr1/unordered_map>
+ int main()
+ {
+ std::tr1::unordered_map <int, int> ma;
+ std::cout << ma.size () << std::endl;
+ return 0;
+ }
+
+ should be rewritten to:
+
+ .. code-block:: c++
+
+ #include <unordered_map>
+ int main()
+ {
+ std::unordered_map <int, int> ma;
+ std::cout << ma.size () << std::endl;
+ return 0;
+ }
+
+* A tool to remove ``auto``. Will convert ``auto`` to an explicit type or add
+ comments with deduced types. The motivation is that there are developers
+ that don't want to use ``auto`` because they are afraid that they might lose
+ control over their code.
+
+* C++14: less verbose operator function objects (`N3421
+ <http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2012/n3421.htm>`_).
+ For example:
+
+ .. code-block:: c++
+
+ sort(v.begin(), v.end(), greater<ValueType>());
+
+ should be rewritten to:
+
+ .. code-block:: c++
+
+ sort(v.begin(), v.end(), greater<>());
+
Added: www-releases/trunk/4.0.0/tools/clang/docs/_sources/CommandGuide/clang.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/4.0.0/tools/clang/docs/_sources/CommandGuide/clang.txt?rev=297634&view=auto
==============================================================================
--- www-releases/trunk/4.0.0/tools/clang/docs/_sources/CommandGuide/clang.txt (added)
+++ www-releases/trunk/4.0.0/tools/clang/docs/_sources/CommandGuide/clang.txt Mon Mar 13 11:30:12 2017
@@ -0,0 +1,517 @@
+clang - the Clang C, C++, and Objective-C compiler
+==================================================
+
+SYNOPSIS
+--------
+
+:program:`clang` [*options*] *filename ...*
+
+DESCRIPTION
+-----------
+
+:program:`clang` is a C, C++, and Objective-C compiler which encompasses
+preprocessing, parsing, optimization, code generation, assembly, and linking.
+Depending on which high-level mode setting is passed, Clang will stop before
+doing a full link. While Clang is highly integrated, it is important to
+understand the stages of compilation, to understand how to invoke it. These
+stages are:
+
+Driver
+ The clang executable is actually a small driver which controls the overall
+ execution of other tools such as the compiler, assembler and linker.
+ Typically you do not need to interact with the driver, but you
+ transparently use it to run the other tools.
+
+Preprocessing
+ This stage handles tokenization of the input source file, macro expansion,
+ #include expansion and handling of other preprocessor directives. The
+ output of this stage is typically called a ".i" (for C), ".ii" (for C++),
+ ".mi" (for Objective-C), or ".mii" (for Objective-C++) file.
+
+Parsing and Semantic Analysis
+ This stage parses the input file, translating preprocessor tokens into a
+ parse tree. Once in the form of a parse tree, it applies semantic
+ analysis to compute types for expressions as well and determine whether
+ the code is well formed. This stage is responsible for generating most of
+ the compiler warnings as well as parse errors. The output of this stage is
+ an "Abstract Syntax Tree" (AST).
+
+Code Generation and Optimization
+ This stage translates an AST into low-level intermediate code (known as
+ "LLVM IR") and ultimately to machine code. This phase is responsible for
+ optimizing the generated code and handling target-specific code generation.
+ The output of this stage is typically called a ".s" file or "assembly" file.
+
+ Clang also supports the use of an integrated assembler, in which the code
+ generator produces object files directly. This avoids the overhead of
+ generating the ".s" file and of calling the target assembler.
+
+Assembler
+ This stage runs the target assembler to translate the output of the
+ compiler into a target object file. The output of this stage is typically
+ called a ".o" file or "object" file.
+
+Linker
+ This stage runs the target linker to merge multiple object files into an
+ executable or dynamic library. The output of this stage is typically called
+ an "a.out", ".dylib" or ".so" file.
+
+:program:`Clang Static Analyzer`
+
+The Clang Static Analyzer is a tool that scans source code to try to find bugs
+through code analysis. This tool uses many parts of Clang and is built into
+the same driver. Please see <http://clang-analyzer.llvm.org> for more details
+on how to use the static analyzer.
+
+OPTIONS
+-------
+
+Stage Selection Options
+~~~~~~~~~~~~~~~~~~~~~~~
+
+.. option:: -E
+
+ Run the preprocessor stage.
+
+.. option:: -fsyntax-only
+
+ Run the preprocessor, parser and type checking stages.
+
+.. option:: -S
+
+ Run the previous stages as well as LLVM generation and optimization stages
+ and target-specific code generation, producing an assembly file.
+
+.. option:: -c
+
+ Run all of the above, plus the assembler, generating a target ".o" object file.
+
+.. option:: no stage selection option
+
+ If no stage selection option is specified, all stages above are run, and the
+ linker is run to combine the results into an executable or shared library.
+
+Language Selection and Mode Options
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. option:: -x <language>
+
+ Treat subsequent input files as having type language.
+
+.. option:: -std=<language>
+
+ Specify the language standard to compile for.
+
+.. option:: -stdlib=<library>
+
+ Specify the C++ standard library to use; supported options are libstdc++ and
+ libc++. If not specified, platform default will be used.
+
+.. option:: -rtlib=<library>
+
+ Specify the compiler runtime library to use; supported options are libgcc and
+ compiler-rt. If not specified, platform default will be used.
+
+.. option:: -ansi
+
+ Same as -std=c89.
+
+.. option:: -ObjC, -ObjC++
+
+ Treat source input files as Objective-C and Object-C++ inputs respectively.
+
+.. option:: -trigraphs
+
+ Enable trigraphs.
+
+.. option:: -ffreestanding
+
+ Indicate that the file should be compiled for a freestanding, not a hosted,
+ environment.
+
+.. option:: -fno-builtin
+
+ Disable special handling and optimizations of builtin functions like
+ :c:func:`strlen` and :c:func:`malloc`.
+
+.. option:: -fmath-errno
+
+ Indicate that math functions should be treated as updating :c:data:`errno`.
+
+.. option:: -fpascal-strings
+
+ Enable support for Pascal-style strings with "\\pfoo".
+
+.. option:: -fms-extensions
+
+ Enable support for Microsoft extensions.
+
+.. option:: -fmsc-version=
+
+ Set _MSC_VER. Defaults to 1300 on Windows. Not set otherwise.
+
+.. option:: -fborland-extensions
+
+ Enable support for Borland extensions.
+
+.. option:: -fwritable-strings
+
+ Make all string literals default to writable. This disables uniquing of
+ strings and other optimizations.
+
+.. option:: -flax-vector-conversions
+
+ Allow loose type checking rules for implicit vector conversions.
+
+.. option:: -fblocks
+
+ Enable the "Blocks" language feature.
+
+.. option:: -fobjc-abi-version=version
+
+ Select the Objective-C ABI version to use. Available versions are 1 (legacy
+ "fragile" ABI), 2 (non-fragile ABI 1), and 3 (non-fragile ABI 2).
+
+.. option:: -fobjc-nonfragile-abi-version=<version>
+
+ Select the Objective-C non-fragile ABI version to use by default. This will
+ only be used as the Objective-C ABI when the non-fragile ABI is enabled
+ (either via :option:`-fobjc-nonfragile-abi`, or because it is the platform
+ default).
+
+.. option:: -fobjc-nonfragile-abi, -fno-objc-nonfragile-abi
+
+ Enable use of the Objective-C non-fragile ABI. On platforms for which this is
+ the default ABI, it can be disabled with :option:`-fno-objc-nonfragile-abi`.
+
+Target Selection Options
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Clang fully supports cross compilation as an inherent part of its design.
+Depending on how your version of Clang is configured, it may have support for a
+number of cross compilers, or may only support a native target.
+
+.. option:: -arch <architecture>
+
+ Specify the architecture to build for.
+
+.. option:: -mmacosx-version-min=<version>
+
+ When building for Mac OS X, specify the minimum version supported by your
+ application.
+
+.. option:: -miphoneos-version-min
+
+ When building for iPhone OS, specify the minimum version supported by your
+ application.
+
+.. option:: -march=<cpu>
+
+ Specify that Clang should generate code for a specific processor family
+ member and later. For example, if you specify -march=i486, the compiler is
+ allowed to generate instructions that are valid on i486 and later processors,
+ but which may not exist on earlier ones.
+
+
+Code Generation Options
+~~~~~~~~~~~~~~~~~~~~~~~
+
+.. option:: -O0, -O1, -O2, -O3, -Ofast, -Os, -Oz, -Og, -O, -O4
+
+ Specify which optimization level to use:
+
+ :option:`-O0` Means "no optimization": this level compiles the fastest and
+ generates the most debuggable code.
+
+ :option:`-O1` Somewhere between :option:`-O0` and :option:`-O2`.
+
+ :option:`-O2` Moderate level of optimization which enables most
+ optimizations.
+
+ :option:`-O3` Like :option:`-O2`, except that it enables optimizations that
+ take longer to perform or that may generate larger code (in an attempt to
+ make the program run faster).
+
+ :option:`-Ofast` Enables all the optimizations from :option:`-O3` along
+ with other aggressive optimizations that may violate strict compliance with
+ language standards.
+
+ :option:`-Os` Like :option:`-O2` with extra optimizations to reduce code
+ size.
+
+ :option:`-Oz` Like :option:`-Os` (and thus :option:`-O2`), but reduces code
+ size further.
+
+ :option:`-Og` Like :option:`-O1`. In future versions, this option might
+ disable different optimizations in order to improve debuggability.
+
+ :option:`-O` Equivalent to :option:`-O2`.
+
+ :option:`-O4` and higher
+
+ Currently equivalent to :option:`-O3`
+
+.. option:: -g, -gline-tables-only, -gmodules
+
+ Control debug information output. Note that Clang debug information works
+ best at :option:`-O0`. When more than one option starting with `-g` is
+ specified, the last one wins:
+
+ :option:`-g` Generate debug information.
+
+ :option:`-gline-tables-only` Generate only line table debug information. This
+ allows for symbolicated backtraces with inlining information, but does not
+ include any information about variables, their locations or types.
+
+ :option:`-gmodules` Generate debug information that contains external
+ references to types defined in Clang modules or precompiled headers instead
+ of emitting redundant debug type information into every object file. This
+ option transparently switches the Clang module format to object file
+ containers that hold the Clang module together with the debug information.
+ When compiling a program that uses Clang modules or precompiled headers,
+ this option produces complete debug information with faster compile
+ times and much smaller object files.
+
+ This option should not be used when building static libraries for
+ distribution to other machines because the debug info will contain
+ references to the module cache on the machine the object files in the
+ library were built on.
+
+.. option:: -fstandalone-debug -fno-standalone-debug
+
+ Clang supports a number of optimizations to reduce the size of debug
+ information in the binary. They work based on the assumption that the
+ debug type information can be spread out over multiple compilation units.
+ For instance, Clang will not emit type definitions for types that are not
+ needed by a module and could be replaced with a forward declaration.
+ Further, Clang will only emit type info for a dynamic C++ class in the
+ module that contains the vtable for the class.
+
+ The :option:`-fstandalone-debug` option turns off these optimizations.
+ This is useful when working with 3rd-party libraries that don't come with
+ debug information. This is the default on Darwin. Note that Clang will
+ never emit type information for types that are not referenced at all by the
+ program.
+
+.. option:: -fexceptions
+
+ Enable generation of unwind information. This allows exceptions to be thrown
+ through Clang compiled stack frames. This is on by default in x86-64.
+
+.. option:: -ftrapv
+
+ Generate code to catch integer overflow errors. Signed integer overflow is
+ undefined in C. With this flag, extra code is generated to detect this and
+ abort when it happens.
+
+.. option:: -fvisibility
+
+ This flag sets the default visibility level.
+
+.. option:: -fcommon, -fno-common
+
+ This flag specifies that variables without initializers get common linkage.
+ It can be disabled with :option:`-fno-common`.
+
+.. option:: -ftls-model=<model>
+
+ Set the default thread-local storage (TLS) model to use for thread-local
+ variables. Valid values are: "global-dynamic", "local-dynamic",
+ "initial-exec" and "local-exec". The default is "global-dynamic". The default
+ model can be overridden with the tls_model attribute. The compiler will try
+ to choose a more efficient model if possible.
+
+.. option:: -flto, -flto=full, -flto=thin, -emit-llvm
+
+ Generate output files in LLVM formats, suitable for link time optimization.
+ When used with :option:`-S` this generates LLVM intermediate language
+ assembly files, otherwise this generates LLVM bitcode format object files
+ (which may be passed to the linker depending on the stage selection options).
+
+ The default for :option:`-flto` is "full", in which the
+ LLVM bitcode is suitable for monolithic Link Time Optimization (LTO), where
+ the linker merges all such modules into a single combined module for
+ optimization. With "thin", :doc:`ThinLTO <../ThinLTO>`
+ compilation is invoked instead.
+
+Driver Options
+~~~~~~~~~~~~~~
+
+.. option:: -###
+
+ Print (but do not run) the commands to run for this compilation.
+
+.. option:: --help
+
+ Display available options.
+
+.. option:: -Qunused-arguments
+
+ Do not emit any warnings for unused driver arguments.
+
+.. option:: -Wa,<args>
+
+ Pass the comma separated arguments in args to the assembler.
+
+.. option:: -Wl,<args>
+
+ Pass the comma separated arguments in args to the linker.
+
+.. option:: -Wp,<args>
+
+ Pass the comma separated arguments in args to the preprocessor.
+
+.. option:: -Xanalyzer <arg>
+
+ Pass arg to the static analyzer.
+
+.. option:: -Xassembler <arg>
+
+ Pass arg to the assembler.
+
+.. option:: -Xlinker <arg>
+
+ Pass arg to the linker.
+
+.. option:: -Xpreprocessor <arg>
+
+ Pass arg to the preprocessor.
+
+.. option:: -o <file>
+
+ Write output to file.
+
+.. option:: -print-file-name=<file>
+
+ Print the full library path of file.
+
+.. option:: -print-libgcc-file-name
+
+ Print the library path for the currently used compiler runtime library
+ ("libgcc.a" or "libclang_rt.builtins.*.a").
+
+.. option:: -print-prog-name=<name>
+
+ Print the full program path of name.
+
+.. option:: -print-search-dirs
+
+ Print the paths used for finding libraries and programs.
+
+.. option:: -save-temps
+
+ Save intermediate compilation results.
+
+.. option:: -save-stats, -save-stats=cwd, -save-stats=obj
+
+ Save internal code generation (LLVM) statistics to a file in the current
+ directory (:option:`-save-stats`/"-save-stats=cwd") or the directory
+ of the output file ("-save-state=obj").
+
+.. option:: -integrated-as, -no-integrated-as
+
+ Used to enable and disable, respectively, the use of the integrated
+ assembler. Whether the integrated assembler is on by default is target
+ dependent.
+
+.. option:: -time
+
+ Time individual commands.
+
+.. option:: -ftime-report
+
+ Print timing summary of each stage of compilation.
+
+.. option:: -v
+
+ Show commands to run and use verbose output.
+
+
+Diagnostics Options
+~~~~~~~~~~~~~~~~~~~
+
+.. option:: -fshow-column, -fshow-source-location, -fcaret-diagnostics, -fdiagnostics-fixit-info, -fdiagnostics-parseable-fixits, -fdiagnostics-print-source-range-info, -fprint-source-range-info, -fdiagnostics-show-option, -fmessage-length
+
+ These options control how Clang prints out information about diagnostics
+ (errors and warnings). Please see the Clang User's Manual for more information.
+
+Preprocessor Options
+~~~~~~~~~~~~~~~~~~~~
+
+.. option:: -D<macroname>=<value>
+
+ Adds an implicit #define into the predefines buffer which is read before the
+ source file is preprocessed.
+
+.. option:: -U<macroname>
+
+ Adds an implicit #undef into the predefines buffer which is read before the
+ source file is preprocessed.
+
+.. option:: -include <filename>
+
+ Adds an implicit #include into the predefines buffer which is read before the
+ source file is preprocessed.
+
+.. option:: -I<directory>
+
+ Add the specified directory to the search path for include files.
+
+.. option:: -F<directory>
+
+ Add the specified directory to the search path for framework include files.
+
+.. option:: -nostdinc
+
+ Do not search the standard system directories or compiler builtin directories
+ for include files.
+
+.. option:: -nostdlibinc
+
+ Do not search the standard system directories for include files, but do
+ search compiler builtin include directories.
+
+.. option:: -nobuiltininc
+
+ Do not search clang's builtin directory for include files.
+
+
+ENVIRONMENT
+-----------
+
+.. envvar:: TMPDIR, TEMP, TMP
+
+ These environment variables are checked, in order, for the location to write
+ temporary files used during the compilation process.
+
+.. envvar:: CPATH
+
+ If this environment variable is present, it is treated as a delimited list of
+ paths to be added to the default system include path list. The delimiter is
+ the platform dependent delimiter, as used in the PATH environment variable.
+
+ Empty components in the environment variable are ignored.
+
+.. envvar:: C_INCLUDE_PATH, OBJC_INCLUDE_PATH, CPLUS_INCLUDE_PATH, OBJCPLUS_INCLUDE_PATH
+
+ These environment variables specify additional paths, as for :envvar:`CPATH`, which are
+ only used when processing the appropriate language.
+
+.. envvar:: MACOSX_DEPLOYMENT_TARGET
+
+ If :option:`-mmacosx-version-min` is unspecified, the default deployment
+ target is read from this environment variable. This option only affects
+ Darwin targets.
+
+BUGS
+----
+
+To report bugs, please visit <http://llvm.org/bugs/>. Most bug reports should
+include preprocessed source files (use the :option:`-E` option) and the full
+output of the compiler, along with information to reproduce.
+
+SEE ALSO
+--------
+
+:manpage:`as(1)`, :manpage:`ld(1)`
+
Added: www-releases/trunk/4.0.0/tools/clang/docs/_sources/CommandGuide/index.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/4.0.0/tools/clang/docs/_sources/CommandGuide/index.txt?rev=297634&view=auto
==============================================================================
--- www-releases/trunk/4.0.0/tools/clang/docs/_sources/CommandGuide/index.txt (added)
+++ www-releases/trunk/4.0.0/tools/clang/docs/_sources/CommandGuide/index.txt Mon Mar 13 11:30:12 2017
@@ -0,0 +1,17 @@
+Clang "man" pages
+-----------------
+
+The following documents are command descriptions for all of the Clang tools.
+These pages describe how to use the Clang 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
+
+ clang
Added: www-releases/trunk/4.0.0/tools/clang/docs/_sources/ControlFlowIntegrity.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/4.0.0/tools/clang/docs/_sources/ControlFlowIntegrity.txt?rev=297634&view=auto
==============================================================================
--- www-releases/trunk/4.0.0/tools/clang/docs/_sources/ControlFlowIntegrity.txt (added)
+++ www-releases/trunk/4.0.0/tools/clang/docs/_sources/ControlFlowIntegrity.txt Mon Mar 13 11:30:12 2017
@@ -0,0 +1,286 @@
+======================
+Control Flow Integrity
+======================
+
+.. toctree::
+ :hidden:
+
+ ControlFlowIntegrityDesign
+
+.. contents::
+ :local:
+
+Introduction
+============
+
+Clang includes an implementation of a number of control flow integrity (CFI)
+schemes, which are designed to abort the program upon detecting certain forms
+of undefined behavior that can potentially allow attackers to subvert the
+program's control flow. These schemes have been optimized for performance,
+allowing developers to enable them in release builds.
+
+To enable Clang's available CFI schemes, use the flag ``-fsanitize=cfi``.
+You can also enable a subset of available :ref:`schemes <cfi-schemes>`.
+As currently implemented, all schemes rely on link-time optimization (LTO);
+so it is required to specify ``-flto``, and the linker used must support LTO,
+for example via the `gold plugin`_.
+
+To allow the checks to be implemented efficiently, the program must
+be structured such that certain object files are compiled with CFI
+enabled, and are statically linked into the program. This may preclude
+the use of shared libraries in some cases.
+
+The compiler will only produce CFI checks for a class if it can infer hidden
+LTO visibility for that class. LTO visibility is a property of a class that
+is inferred from flags and attributes. For more details, see the documentation
+for :doc:`LTO visibility <LTOVisibility>`.
+
+The ``-fsanitize=cfi-{vcall,nvcall,derived-cast,unrelated-cast}`` flags
+require that a ``-fvisibility=`` flag also be specified. This is because the
+default visibility setting is ``-fvisibility=default``, which would disable
+CFI checks for classes without visibility attributes. Most users will want
+to specify ``-fvisibility=hidden``, which enables CFI checks for such classes.
+
+Experimental support for :ref:`cross-DSO control flow integrity
+<cfi-cross-dso>` exists that does not require classes to have hidden LTO
+visibility. This cross-DSO support has unstable ABI at this time.
+
+.. _gold plugin: http://llvm.org/docs/GoldPlugin.html
+
+.. _cfi-schemes:
+
+Available schemes
+=================
+
+Available schemes are:
+
+ - ``-fsanitize=cfi-cast-strict``: Enables :ref:`strict cast checks
+ <cfi-strictness>`.
+ - ``-fsanitize=cfi-derived-cast``: Base-to-derived cast to the wrong
+ dynamic type.
+ - ``-fsanitize=cfi-unrelated-cast``: Cast from ``void*`` or another
+ unrelated type to the wrong dynamic type.
+ - ``-fsanitize=cfi-nvcall``: Non-virtual call via an object whose vptr is of
+ the wrong dynamic type.
+ - ``-fsanitize=cfi-vcall``: Virtual call via an object whose vptr is of the
+ wrong dynamic type.
+ - ``-fsanitize=cfi-icall``: Indirect call of a function with wrong dynamic
+ type.
+
+You can use ``-fsanitize=cfi`` to enable all the schemes and use
+``-fno-sanitize`` flag to narrow down the set of schemes as desired.
+For example, you can build your program with
+``-fsanitize=cfi -fno-sanitize=cfi-nvcall,cfi-icall``
+to use all schemes except for non-virtual member function call and indirect call
+checking.
+
+Remember that you have to provide ``-flto`` if at least one CFI scheme is
+enabled.
+
+Trapping and Diagnostics
+========================
+
+By default, CFI will abort the program immediately upon detecting a control
+flow integrity violation. You can use the :ref:`-fno-sanitize-trap=
+<controlling-code-generation>` flag to cause CFI to print a diagnostic
+similar to the one below before the program aborts.
+
+.. code-block:: console
+
+ bad-cast.cpp:109:7: runtime error: control flow integrity check for type 'B' failed during base-to-derived cast (vtable address 0x000000425a50)
+ 0x000000425a50: note: vtable is of type 'A'
+ 00 00 00 00 f0 f1 41 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 20 5a 42 00
+ ^
+
+If diagnostics are enabled, you can also configure CFI to continue program
+execution instead of aborting by using the :ref:`-fsanitize-recover=
+<controlling-code-generation>` flag.
+
+Forward-Edge CFI for Virtual Calls
+==================================
+
+This scheme checks that virtual calls take place using a vptr of the correct
+dynamic type; that is, the dynamic type of the called object must be a
+derived class of the static type of the object used to make the call.
+This CFI scheme can be enabled on its own using ``-fsanitize=cfi-vcall``.
+
+For this scheme to work, all translation units containing the definition
+of a virtual member function (whether inline or not), other than members
+of :ref:`blacklisted <cfi-blacklist>` types, must be compiled with
+``-fsanitize=cfi-vcall`` enabled and be statically linked into the program.
+
+Performance
+-----------
+
+A performance overhead of less than 1% has been measured by running the
+Dromaeo benchmark suite against an instrumented version of the Chromium
+web browser. Another good performance benchmark for this mechanism is the
+virtual-call-heavy SPEC 2006 xalancbmk.
+
+Note that this scheme has not yet been optimized for binary size; an increase
+of up to 15% has been observed for Chromium.
+
+Bad Cast Checking
+=================
+
+This scheme checks that pointer casts are made to an object of the correct
+dynamic type; that is, the dynamic type of the object must be a derived class
+of the pointee type of the cast. The checks are currently only introduced
+where the class being casted to is a polymorphic class.
+
+Bad casts are not in themselves control flow integrity violations, but they
+can also create security vulnerabilities, and the implementation uses many
+of the same mechanisms.
+
+There are two types of bad cast that may be forbidden: bad casts
+from a base class to a derived class (which can be checked with
+``-fsanitize=cfi-derived-cast``), and bad casts from a pointer of
+type ``void*`` or another unrelated type (which can be checked with
+``-fsanitize=cfi-unrelated-cast``).
+
+The difference between these two types of casts is that the first is defined
+by the C++ standard to produce an undefined value, while the second is not
+in itself undefined behavior (it is well defined to cast the pointer back
+to its original type) unless the object is uninitialized and the cast is a
+``static_cast`` (see C++14 [basic.life]p5).
+
+If a program as a matter of policy forbids the second type of cast, that
+restriction can normally be enforced. However it may in some cases be necessary
+for a function to perform a forbidden cast to conform with an external API
+(e.g. the ``allocate`` member function of a standard library allocator). Such
+functions may be :ref:`blacklisted <cfi-blacklist>`.
+
+For this scheme to work, all translation units containing the definition
+of a virtual member function (whether inline or not), other than members
+of :ref:`blacklisted <cfi-blacklist>` types, must be compiled with
+``-fsanitize=cfi-derived-cast`` or ``-fsanitize=cfi-unrelated-cast`` enabled
+and be statically linked into the program.
+
+Non-Virtual Member Function Call Checking
+=========================================
+
+This scheme checks that non-virtual calls take place using an object of
+the correct dynamic type; that is, the dynamic type of the called object
+must be a derived class of the static type of the object used to make the
+call. The checks are currently only introduced where the object is of a
+polymorphic class type. This CFI scheme can be enabled on its own using
+``-fsanitize=cfi-nvcall``.
+
+For this scheme to work, all translation units containing the definition
+of a virtual member function (whether inline or not), other than members
+of :ref:`blacklisted <cfi-blacklist>` types, must be compiled with
+``-fsanitize=cfi-nvcall`` enabled and be statically linked into the program.
+
+.. _cfi-strictness:
+
+Strictness
+----------
+
+If a class has a single non-virtual base and does not introduce or override
+virtual member functions or fields other than an implicitly defined virtual
+destructor, it will have the same layout and virtual function semantics as
+its base. By default, casts to such classes are checked as if they were made
+to the least derived such class.
+
+Casting an instance of a base class to such a derived class is technically
+undefined behavior, but it is a relatively common hack for introducing
+member functions on class instances with specific properties that works under
+most compilers and should not have security implications, so we allow it by
+default. It can be disabled with ``-fsanitize=cfi-cast-strict``.
+
+Indirect Function Call Checking
+===============================
+
+This scheme checks that function calls take place using a function of the
+correct dynamic type; that is, the dynamic type of the function must match
+the static type used at the call. This CFI scheme can be enabled on its own
+using ``-fsanitize=cfi-icall``.
+
+For this scheme to work, each indirect function call in the program, other
+than calls in :ref:`blacklisted <cfi-blacklist>` functions, must call a
+function which was either compiled with ``-fsanitize=cfi-icall`` enabled,
+or whose address was taken by a function in a translation unit compiled with
+``-fsanitize=cfi-icall``.
+
+If a function in a translation unit compiled with ``-fsanitize=cfi-icall``
+takes the address of a function not compiled with ``-fsanitize=cfi-icall``,
+that address may differ from the address taken by a function in a translation
+unit not compiled with ``-fsanitize=cfi-icall``. This is technically a
+violation of the C and C++ standards, but it should not affect most programs.
+
+Each translation unit compiled with ``-fsanitize=cfi-icall`` must be
+statically linked into the program or shared library, and calls across
+shared library boundaries are handled as if the callee was not compiled with
+``-fsanitize=cfi-icall``.
+
+This scheme is currently only supported on the x86 and x86_64 architectures.
+
+``-fsanitize=cfi-icall`` and ``-fsanitize=function``
+----------------------------------------------------
+
+This tool is similar to ``-fsanitize=function`` in that both tools check
+the types of function calls. However, the two tools occupy different points
+on the design space; ``-fsanitize=function`` is a developer tool designed
+to find bugs in local development builds, whereas ``-fsanitize=cfi-icall``
+is a security hardening mechanism designed to be deployed in release builds.
+
+``-fsanitize=function`` has a higher space and time overhead due to a more
+complex type check at indirect call sites, as well as a need for run-time
+type information (RTTI), which may make it unsuitable for deployment. Because
+of the need for RTTI, ``-fsanitize=function`` can only be used with C++
+programs, whereas ``-fsanitize=cfi-icall`` can protect both C and C++ programs.
+
+On the other hand, ``-fsanitize=function`` conforms more closely with the C++
+standard and user expectations around interaction with shared libraries;
+the identity of function pointers is maintained, and calls across shared
+library boundaries are no different from calls within a single program or
+shared library.
+
+.. _cfi-blacklist:
+
+Blacklist
+=========
+
+A :doc:`SanitizerSpecialCaseList` can be used to relax CFI checks for certain
+source files, functions and types using the ``src``, ``fun`` and ``type``
+entity types.
+
+.. code-block:: bash
+
+ # Suppress checking for code in a file.
+ src:bad_file.cpp
+ src:bad_header.h
+ # Ignore all functions with names containing MyFooBar.
+ fun:*MyFooBar*
+ # Ignore all types in the standard library.
+ type:std::*
+
+.. _cfi-cross-dso:
+
+Shared library support
+======================
+
+Use **-f[no-]sanitize-cfi-cross-dso** to enable the cross-DSO control
+flow integrity mode, which allows all CFI schemes listed above to
+apply across DSO boundaries. As in the regular CFI, each DSO must be
+built with ``-flto``.
+
+Normally, CFI checks will only be performed for classes that have hidden LTO
+visibility. With this flag enabled, the compiler will emit cross-DSO CFI
+checks for all classes, except for those which appear in the CFI blacklist
+or which use a ``no_sanitize`` attribute.
+
+Design
+======
+
+Please refer to the :doc:`design document<ControlFlowIntegrityDesign>`.
+
+Publications
+============
+
+`Control-Flow Integrity: Principles, Implementations, and Applications <http://research.microsoft.com/pubs/64250/ccs05.pdf>`_.
+Martin Abadi, Mihai Budiu, Ãlfar Erlingsson, Jay Ligatti.
+
+`Enforcing Forward-Edge Control-Flow Integrity in GCC & LLVM <http://www.pcc.me.uk/~peter/acad/usenix14.pdf>`_.
+Caroline Tice, Tom Roeder, Peter Collingbourne, Stephen Checkoway,
+Ãlfar Erlingsson, Luis Lozano, Geoff Pike.
Added: www-releases/trunk/4.0.0/tools/clang/docs/_sources/ControlFlowIntegrityDesign.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/4.0.0/tools/clang/docs/_sources/ControlFlowIntegrityDesign.txt?rev=297634&view=auto
==============================================================================
--- www-releases/trunk/4.0.0/tools/clang/docs/_sources/ControlFlowIntegrityDesign.txt (added)
+++ www-releases/trunk/4.0.0/tools/clang/docs/_sources/ControlFlowIntegrityDesign.txt Mon Mar 13 11:30:12 2017
@@ -0,0 +1,553 @@
+===========================================
+Control Flow Integrity Design Documentation
+===========================================
+
+This page documents the design of the :doc:`ControlFlowIntegrity` schemes
+supported by Clang.
+
+Forward-Edge CFI for Virtual Calls
+==================================
+
+This scheme works by allocating, for each static type used to make a virtual
+call, a region of read-only storage in the object file holding a bit vector
+that maps onto to the region of storage used for those virtual tables. Each
+set bit in the bit vector corresponds to the `address point`_ for a virtual
+table compatible with the static type for which the bit vector is being built.
+
+For example, consider the following three C++ classes:
+
+.. code-block:: c++
+
+ struct A {
+ virtual void f1();
+ virtual void f2();
+ virtual void f3();
+ };
+
+ struct B : A {
+ virtual void f1();
+ virtual void f2();
+ virtual void f3();
+ };
+
+ struct C : A {
+ virtual void f1();
+ virtual void f2();
+ virtual void f3();
+ };
+
+The scheme will cause the virtual tables for A, B and C to be laid out
+consecutively:
+
+.. csv-table:: Virtual Table Layout for A, B, C
+ :header: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14
+
+ A::offset-to-top, &A::rtti, &A::f1, &A::f2, &A::f3, B::offset-to-top, &B::rtti, &B::f1, &B::f2, &B::f3, C::offset-to-top, &C::rtti, &C::f1, &C::f2, &C::f3
+
+The bit vector for static types A, B and C will look like this:
+
+.. csv-table:: Bit Vectors for A, B, C
+ :header: Class, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14
+
+ A, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0
+ B, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0
+ C, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0
+
+Bit vectors are represented in the object file as byte arrays. By loading
+from indexed offsets into the byte array and applying a mask, a program can
+test bits from the bit set with a relatively short instruction sequence. Bit
+vectors may overlap so long as they use different bits. For the full details,
+see the `ByteArrayBuilder`_ class.
+
+In this case, assuming A is laid out at offset 0 in bit 0, B at offset 0 in
+bit 1 and C at offset 0 in bit 2, the byte array would look like this:
+
+.. code-block:: c++
+
+ char bits[] = { 0, 0, 1, 0, 0, 0, 3, 0, 0, 0, 0, 5, 0, 0 };
+
+To emit a virtual call, the compiler will assemble code that checks that
+the object's virtual table pointer is in-bounds and aligned and that the
+relevant bit is set in the bit vector.
+
+For example on x86 a typical virtual call may look like this:
+
+.. code-block:: none
+
+ ca7fbb: 48 8b 0f mov (%rdi),%rcx
+ ca7fbe: 48 8d 15 c3 42 fb 07 lea 0x7fb42c3(%rip),%rdx
+ ca7fc5: 48 89 c8 mov %rcx,%rax
+ ca7fc8: 48 29 d0 sub %rdx,%rax
+ ca7fcb: 48 c1 c0 3d rol $0x3d,%rax
+ ca7fcf: 48 3d 7f 01 00 00 cmp $0x17f,%rax
+ ca7fd5: 0f 87 36 05 00 00 ja ca8511
+ ca7fdb: 48 8d 15 c0 0b f7 06 lea 0x6f70bc0(%rip),%rdx
+ ca7fe2: f6 04 10 10 testb $0x10,(%rax,%rdx,1)
+ ca7fe6: 0f 84 25 05 00 00 je ca8511
+ ca7fec: ff 91 98 00 00 00 callq *0x98(%rcx)
+ [...]
+ ca8511: 0f 0b ud2
+
+The compiler relies on co-operation from the linker in order to assemble
+the bit vectors for the whole program. It currently does this using LLVM's
+`type metadata`_ mechanism together with link-time optimization.
+
+.. _address point: https://mentorembedded.github.io/cxx-abi/abi.html#vtable-general
+.. _type metadata: http://llvm.org/docs/TypeMetadata.html
+.. _ByteArrayBuilder: http://llvm.org/docs/doxygen/html/structllvm_1_1ByteArrayBuilder.html
+
+Optimizations
+-------------
+
+The scheme as described above is the fully general variant of the scheme.
+Most of the time we are able to apply one or more of the following
+optimizations to improve binary size or performance.
+
+In fact, if you try the above example with the current version of the
+compiler, you will probably find that it will not use the described virtual
+table layout or machine instructions. Some of the optimizations we are about
+to introduce cause the compiler to use a different layout or a different
+sequence of machine instructions.
+
+Stripping Leading/Trailing Zeros in Bit Vectors
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If a bit vector contains leading or trailing zeros, we can strip them from
+the vector. The compiler will emit code to check if the pointer is in range
+of the region covered by ones, and perform the bit vector check using a
+truncated version of the bit vector. For example, the bit vectors for our
+example class hierarchy will be emitted like this:
+
+.. csv-table:: Bit Vectors for A, B, C
+ :header: Class, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14
+
+ A, , , 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, ,
+ B, , , , , , , , 1, , , , , , ,
+ C, , , , , , , , , , , , , 1, ,
+
+Short Inline Bit Vectors
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+If the vector is sufficiently short, we can represent it as an inline constant
+on x86. This saves us a few instructions when reading the correct element
+of the bit vector.
+
+If the bit vector fits in 32 bits, the code looks like this:
+
+.. code-block:: none
+
+ dc2: 48 8b 03 mov (%rbx),%rax
+ dc5: 48 8d 15 14 1e 00 00 lea 0x1e14(%rip),%rdx
+ dcc: 48 89 c1 mov %rax,%rcx
+ dcf: 48 29 d1 sub %rdx,%rcx
+ dd2: 48 c1 c1 3d rol $0x3d,%rcx
+ dd6: 48 83 f9 03 cmp $0x3,%rcx
+ dda: 77 2f ja e0b <main+0x9b>
+ ddc: ba 09 00 00 00 mov $0x9,%edx
+ de1: 0f a3 ca bt %ecx,%edx
+ de4: 73 25 jae e0b <main+0x9b>
+ de6: 48 89 df mov %rbx,%rdi
+ de9: ff 10 callq *(%rax)
+ [...]
+ e0b: 0f 0b ud2
+
+Or if the bit vector fits in 64 bits:
+
+.. code-block:: none
+
+ 11a6: 48 8b 03 mov (%rbx),%rax
+ 11a9: 48 8d 15 d0 28 00 00 lea 0x28d0(%rip),%rdx
+ 11b0: 48 89 c1 mov %rax,%rcx
+ 11b3: 48 29 d1 sub %rdx,%rcx
+ 11b6: 48 c1 c1 3d rol $0x3d,%rcx
+ 11ba: 48 83 f9 2a cmp $0x2a,%rcx
+ 11be: 77 35 ja 11f5 <main+0xb5>
+ 11c0: 48 ba 09 00 00 00 00 movabs $0x40000000009,%rdx
+ 11c7: 04 00 00
+ 11ca: 48 0f a3 ca bt %rcx,%rdx
+ 11ce: 73 25 jae 11f5 <main+0xb5>
+ 11d0: 48 89 df mov %rbx,%rdi
+ 11d3: ff 10 callq *(%rax)
+ [...]
+ 11f5: 0f 0b ud2
+
+If the bit vector consists of a single bit, there is only one possible
+virtual table, and the check can consist of a single equality comparison:
+
+.. code-block:: none
+
+ 9a2: 48 8b 03 mov (%rbx),%rax
+ 9a5: 48 8d 0d a4 13 00 00 lea 0x13a4(%rip),%rcx
+ 9ac: 48 39 c8 cmp %rcx,%rax
+ 9af: 75 25 jne 9d6 <main+0x86>
+ 9b1: 48 89 df mov %rbx,%rdi
+ 9b4: ff 10 callq *(%rax)
+ [...]
+ 9d6: 0f 0b ud2
+
+Virtual Table Layout
+~~~~~~~~~~~~~~~~~~~~
+
+The compiler lays out classes of disjoint hierarchies in separate regions
+of the object file. At worst, bit vectors in disjoint hierarchies only
+need to cover their disjoint hierarchy. But the closer that classes in
+sub-hierarchies are laid out to each other, the smaller the bit vectors for
+those sub-hierarchies need to be (see "Stripping Leading/Trailing Zeros in Bit
+Vectors" above). The `GlobalLayoutBuilder`_ class is responsible for laying
+out the globals efficiently to minimize the sizes of the underlying bitsets.
+
+.. _GlobalLayoutBuilder: http://llvm.org/viewvc/llvm-project/llvm/trunk/include/llvm/Transforms/IPO/LowerTypeTests.h?view=markup
+
+Alignment
+~~~~~~~~~
+
+If all gaps between address points in a particular bit vector are multiples
+of powers of 2, the compiler can compress the bit vector by strengthening
+the alignment requirements of the virtual table pointer. For example, given
+this class hierarchy:
+
+.. code-block:: c++
+
+ struct A {
+ virtual void f1();
+ virtual void f2();
+ };
+
+ struct B : A {
+ virtual void f1();
+ virtual void f2();
+ virtual void f3();
+ virtual void f4();
+ virtual void f5();
+ virtual void f6();
+ };
+
+ struct C : A {
+ virtual void f1();
+ virtual void f2();
+ };
+
+The virtual tables will be laid out like this:
+
+.. csv-table:: Virtual Table Layout for A, B, C
+ :header: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15
+
+ A::offset-to-top, &A::rtti, &A::f1, &A::f2, B::offset-to-top, &B::rtti, &B::f1, &B::f2, &B::f3, &B::f4, &B::f5, &B::f6, C::offset-to-top, &C::rtti, &C::f1, &C::f2
+
+Notice that each address point for A is separated by 4 words. This lets us
+emit a compressed bit vector for A that looks like this:
+
+.. csv-table::
+ :header: 2, 6, 10, 14
+
+ 1, 1, 0, 1
+
+At call sites, the compiler will strengthen the alignment requirements by
+using a different rotate count. For example, on a 64-bit machine where the
+address points are 4-word aligned (as in A from our example), the ``rol``
+instruction may look like this:
+
+.. code-block:: none
+
+ dd2: 48 c1 c1 3b rol $0x3b,%rcx
+
+Padding to Powers of 2
+~~~~~~~~~~~~~~~~~~~~~~
+
+Of course, this alignment scheme works best if the address points are
+in fact aligned correctly. To make this more likely to happen, we insert
+padding between virtual tables that in many cases aligns address points to
+a power of 2. Specifically, our padding aligns virtual tables to the next
+highest power of 2 bytes; because address points for specific base classes
+normally appear at fixed offsets within the virtual table, this normally
+has the effect of aligning the address points as well.
+
+This scheme introduces tradeoffs between decreased space overhead for
+instructions and bit vectors and increased overhead in the form of padding. We
+therefore limit the amount of padding so that we align to no more than 128
+bytes. This number was found experimentally to provide a good tradeoff.
+
+Eliminating Bit Vector Checks for All-Ones Bit Vectors
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If the bit vector is all ones, the bit vector check is redundant; we simply
+need to check that the address is in range and well aligned. This is more
+likely to occur if the virtual tables are padded.
+
+Forward-Edge CFI for Indirect Function Calls
+============================================
+
+Under forward-edge CFI for indirect function calls, each unique function
+type has its own bit vector, and at each call site we need to check that the
+function pointer is a member of the function type's bit vector. This scheme
+works in a similar way to forward-edge CFI for virtual calls, the distinction
+being that we need to build bit vectors of function entry points rather than
+of virtual tables.
+
+Unlike when re-arranging global variables, we cannot re-arrange functions
+in a particular order and base our calculations on the layout of the
+functions' entry points, as we have no idea how large a particular function
+will end up being (the function sizes could even depend on how we arrange
+the functions). Instead, we build a jump table, which is a block of code
+consisting of one branch instruction for each of the functions in the bit
+set that branches to the target function, and redirect any taken function
+addresses to the corresponding jump table entry. In this way, the distance
+between function entry points is predictable and controllable. In the object
+file's symbol table, the symbols for the target functions also refer to the
+jump table entries, so that addresses taken outside the module will pass
+any verification done inside the module.
+
+In more concrete terms, suppose we have three functions ``f``, ``g``,
+``h`` which are all of the same type, and a function foo that returns their
+addresses:
+
+.. code-block:: none
+
+ f:
+ mov 0, %eax
+ ret
+
+ g:
+ mov 1, %eax
+ ret
+
+ h:
+ mov 2, %eax
+ ret
+
+ foo:
+ mov f, %eax
+ mov g, %edx
+ mov h, %ecx
+ ret
+
+Our jump table will (conceptually) look like this:
+
+.. code-block:: none
+
+ f:
+ jmp .Ltmp0 ; 5 bytes
+ int3 ; 1 byte
+ int3 ; 1 byte
+ int3 ; 1 byte
+
+ g:
+ jmp .Ltmp1 ; 5 bytes
+ int3 ; 1 byte
+ int3 ; 1 byte
+ int3 ; 1 byte
+
+ h:
+ jmp .Ltmp2 ; 5 bytes
+ int3 ; 1 byte
+ int3 ; 1 byte
+ int3 ; 1 byte
+
+ .Ltmp0:
+ mov 0, %eax
+ ret
+
+ .Ltmp1:
+ mov 1, %eax
+ ret
+
+ .Ltmp2:
+ mov 2, %eax
+ ret
+
+ foo:
+ mov f, %eax
+ mov g, %edx
+ mov h, %ecx
+ ret
+
+Because the addresses of ``f``, ``g``, ``h`` are evenly spaced at a power of
+2, and function types do not overlap (unlike class types with base classes),
+we can normally apply the `Alignment`_ and `Eliminating Bit Vector Checks
+for All-Ones Bit Vectors`_ optimizations thus simplifying the check at each
+call site to a range and alignment check.
+
+Shared library support
+======================
+
+**EXPERIMENTAL**
+
+The basic CFI mode described above assumes that the application is a
+monolithic binary; at least that all possible virtual/indirect call
+targets and the entire class hierarchy are known at link time. The
+cross-DSO mode, enabled with **-f[no-]sanitize-cfi-cross-dso** relaxes
+this requirement by allowing virtual and indirect calls to cross the
+DSO boundary.
+
+Assuming the following setup: the binary consists of several
+instrumented and several uninstrumented DSOs. Some of them may be
+dlopen-ed/dlclose-d periodically, even frequently.
+
+ - Calls made from uninstrumented DSOs are not checked and just work.
+ - Calls inside any instrumented DSO are fully protected.
+ - Calls between different instrumented DSOs are also protected, with
+ a performance penalty (in addition to the monolithic CFI
+ overhead).
+ - Calls from an instrumented DSO to an uninstrumented one are
+ unchecked and just work, with performance penalty.
+ - Calls from an instrumented DSO outside of any known DSO are
+ detected as CFI violations.
+
+In the monolithic scheme a call site is instrumented as
+
+.. code-block:: none
+
+ if (!InlinedFastCheck(f))
+ abort();
+ call *f
+
+In the cross-DSO scheme it becomes
+
+.. code-block:: none
+
+ if (!InlinedFastCheck(f))
+ __cfi_slowpath(CallSiteTypeId, f);
+ call *f
+
+CallSiteTypeId
+--------------
+
+``CallSiteTypeId`` is a stable process-wide identifier of the
+call-site type. For a virtual call site, the type in question is the class
+type; for an indirect function call it is the function signature. The
+mapping from a type to an identifier is an ABI detail. In the current,
+experimental, implementation the identifier of type T is calculated as
+follows:
+
+ - Obtain the mangled name for "typeinfo name for T".
+ - Calculate MD5 hash of the name as a string.
+ - Reinterpret the first 8 bytes of the hash as a little-endian
+ 64-bit integer.
+
+It is possible, but unlikely, that collisions in the
+``CallSiteTypeId`` hashing will result in weaker CFI checks that would
+still be conservatively correct.
+
+CFI_Check
+---------
+
+In the general case, only the target DSO knows whether the call to
+function ``f`` with type ``CallSiteTypeId`` is valid or not. To
+export this information, every DSO implements
+
+.. code-block:: none
+
+ void __cfi_check(uint64 CallSiteTypeId, void *TargetAddr)
+
+This function provides external modules with access to CFI checks for the
+targets inside this DSO. For each known ``CallSiteTypeId``, this function
+performs an ``llvm.type.test`` with the corresponding type identifier. It
+aborts if the type is unknown, or if the check fails.
+
+The basic implementation is a large switch statement over all values
+of CallSiteTypeId supported by this DSO, and each case is similar to
+the InlinedFastCheck() in the basic CFI mode.
+
+CFI Shadow
+----------
+
+To route CFI checks to the target DSO's __cfi_check function, a
+mapping from possible virtual / indirect call targets to
+the corresponding __cfi_check functions is maintained. This mapping is
+implemented as a sparse array of 2 bytes for every possible page (4096
+bytes) of memory. The table is kept readonly (FIXME: not yet) most of
+the time.
+
+There are 3 types of shadow values:
+
+ - Address in a CFI-instrumented DSO.
+ - Unchecked address (a âtrustedâ non-instrumented DSO). Encoded as
+ value 0xFFFF.
+ - Invalid address (everything else). Encoded as value 0.
+
+For a CFI-instrumented DSO, a shadow value encodes the address of the
+__cfi_check function for all call targets in the corresponding memory
+page. If Addr is the target address, and V is the shadow value, then
+the address of __cfi_check is calculated as
+
+.. code-block:: none
+
+ __cfi_check = AlignUpTo(Addr, 4096) - (V + 1) * 4096
+
+This works as long as __cfi_check is aligned by 4096 bytes and located
+below any call targets in its DSO, but not more than 256MB apart from
+them.
+
+CFI_SlowPath
+------------
+
+The slow path check is implemented in compiler-rt library as
+
+.. code-block:: none
+
+ void __cfi_slowpath(uint64 CallSiteTypeId, void *TargetAddr)
+
+This functions loads a shadow value for ``TargetAddr``, finds the
+address of __cfi_check as described above and calls that.
+
+Position-independent executable requirement
+-------------------------------------------
+
+Cross-DSO CFI mode requires that the main executable is built as PIE.
+In non-PIE executables the address of an external function (taken from
+the main executable) is the address of that functionâs PLT record in
+the main executable. This would break the CFI checks.
+
+
+Hardware support
+================
+
+We believe that the above design can be efficiently implemented in hardware.
+A single new instruction added to an ISA would allow to perform the CFI check
+with fewer bytes per check (smaller code size overhead) and potentially more
+efficiently. The current software-only instrumentation requires at least
+32-bytes per check (on x86_64).
+A hardware instruction may probably be less than ~ 12 bytes.
+Such instruction would check that the argument pointer is in-bounds,
+and is properly aligned, and if the checks fail it will either trap (in monolithic scheme)
+or call the slow path function (cross-DSO scheme).
+The bit vector lookup is probably too complex for a hardware implementation.
+
+.. code-block:: none
+
+ // This instruction checks that 'Ptr'
+ // * is aligned by (1 << kAlignment) and
+ // * is inside [kRangeBeg, kRangeBeg+(kRangeSize<<kAlignment))
+ // and if the check fails it jumps to the given target (slow path).
+ //
+ // 'Ptr' is a register, pointing to the virtual function table
+ // or to the function which we need to check. We may require an explicit
+ // fixed register to be used.
+ // 'kAlignment' is a 4-bit constant.
+ // 'kRangeSize' is a ~20-bit constant.
+ // 'kRangeBeg' is a PC-relative constant (~28 bits)
+ // pointing to the beginning of the allowed range for 'Ptr'.
+ // 'kFailedCheckTarget': is a PC-relative constant (~28 bits)
+ // representing the target to branch to when the check fails.
+ // If kFailedCheckTarget==0, the process will trap
+ // (monolithic binary scheme).
+ // Otherwise it will jump to a handler that implements `CFI_SlowPath`
+ // (cross-DSO scheme).
+ CFI_Check(Ptr, kAlignment, kRangeSize, kRangeBeg, kFailedCheckTarget) {
+ if (Ptr < kRangeBeg ||
+ Ptr >= kRangeBeg + (kRangeSize << kAlignment) ||
+ Ptr & ((1 << kAlignment) - 1))
+ Jump(kFailedCheckTarget);
+ }
+
+An alternative and more compact enconding would not use `kFailedCheckTarget`,
+and will trap on check failure instead.
+This will allow us to fit the instruction into **8-9 bytes**.
+The cross-DSO checks will be performed by a trap handler and
+performance-critical ones will have to be black-listed and checked using the
+software-only scheme.
+
+Note that such hardware extension would be complementary to checks
+at the callee side, such as e.g. **Intel ENDBRANCH**.
+Moreover, CFI would have two benefits over ENDBRANCH: a) precision and b)
+ability to protect against invalid casts between polymorphic types.
Added: www-releases/trunk/4.0.0/tools/clang/docs/_sources/CrossCompilation.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/4.0.0/tools/clang/docs/_sources/CrossCompilation.txt?rev=297634&view=auto
==============================================================================
--- www-releases/trunk/4.0.0/tools/clang/docs/_sources/CrossCompilation.txt (added)
+++ www-releases/trunk/4.0.0/tools/clang/docs/_sources/CrossCompilation.txt Mon Mar 13 11:30:12 2017
@@ -0,0 +1,203 @@
+===================================================================
+Cross-compilation using Clang
+===================================================================
+
+Introduction
+============
+
+This document will guide you in choosing the right Clang options
+for cross-compiling your code to a different architecture. It assumes you
+already know how to compile the code in question for the host architecture,
+and that you know how to choose additional include and library paths.
+
+However, this document is *not* a "how to" and won't help you setting your
+build system or Makefiles, nor choosing the right CMake options, etc.
+Also, it does not cover all the possible options, nor does it contain
+specific examples for specific architectures. For a concrete example, the
+`instructions for cross-compiling LLVM itself
+<http://llvm.org/docs/HowToCrossCompileLLVM.html>`_ may be of interest.
+
+After reading this document, you should be familiar with the main issues
+related to cross-compilation, and what main compiler options Clang provides
+for performing cross-compilation.
+
+Cross compilation issues
+========================
+
+In GCC world, every host/target combination has its own set of binaries,
+headers, libraries, etc. So, it's usually simple to download a package
+with all files in, unzip to a directory and point the build system to
+that compiler, that will know about its location and find all it needs to
+when compiling your code.
+
+On the other hand, Clang/LLVM is natively a cross-compiler, meaning that
+one set of programs can compile to all targets by setting the ``-target``
+option. That makes it a lot easier for programmers wishing to compile to
+different platforms and architectures, and for compiler developers that
+only have to maintain one build system, and for OS distributions, that
+need only one set of main packages.
+
+But, as is true to any cross-compiler, and given the complexity of
+different architectures, OS's and options, it's not always easy finding
+the headers, libraries or binutils to generate target specific code.
+So you'll need special options to help Clang understand what target
+you're compiling to, where your tools are, etc.
+
+Another problem is that compilers come with standard libraries only (like
+``compiler-rt``, ``libcxx``, ``libgcc``, ``libm``, etc), so you'll have to
+find and make available to the build system, every other library required
+to build your software, that is specific to your target. It's not enough to
+have your host's libraries installed.
+
+Finally, not all toolchains are the same, and consequently, not every Clang
+option will work magically. Some options, like ``--sysroot`` (which
+effectively changes the logical root for headers and libraries), assume
+all your binaries and libraries are in the same directory, which may not
+true when your cross-compiler was installed by the distribution's package
+management. So, for each specific case, you may use more than one
+option, and in most cases, you'll end up setting include paths (``-I``) and
+library paths (``-L``) manually.
+
+To sum up, different toolchains can:
+ * be host/target specific or more flexible
+ * be in a single directory, or spread out across your system
+ * have different sets of libraries and headers by default
+ * need special options, which your build system won't be able to figure
+ out by itself
+
+General Cross-Compilation Options in Clang
+==========================================
+
+Target Triple
+-------------
+
+The basic option is to define the target architecture. For that, use
+``-target <triple>``. If you don't specify the target, CPU names won't
+match (since Clang assumes the host triple), and the compilation will
+go ahead, creating code for the host platform, which will break later
+on when assembling or linking.
+
+The triple has the general format ``<arch><sub>-<vendor>-<sys>-<abi>``, where:
+ * ``arch`` = ``x86_64``, ``i386``, ``arm``, ``thumb``, ``mips``, etc.
+ * ``sub`` = for ex. on ARM: ``v5``, ``v6m``, ``v7a``, ``v7m``, etc.
+ * ``vendor`` = ``pc``, ``apple``, ``nvidia``, ``ibm``, etc.
+ * ``sys`` = ``none``, ``linux``, ``win32``, ``darwin``, ``cuda``, etc.
+ * ``abi`` = ``eabi``, ``gnu``, ``android``, ``macho``, ``elf``, etc.
+
+The sub-architecture options are available for their own architectures,
+of course, so "x86v7a" doesn't make sense. The vendor needs to be
+specified only if there's a relevant change, for instance between PC
+and Apple. Most of the time it can be omitted (and Unknown)
+will be assumed, which sets the defaults for the specified architecture.
+The system name is generally the OS (linux, darwin), but could be special
+like the bare-metal "none".
+
+When a parameter is not important, it can be omitted, or you can
+choose ``unknown`` and the defaults will be used. If you choose a parameter
+that Clang doesn't know, like ``blerg``, it'll ignore and assume
+``unknown``, which is not always desired, so be careful.
+
+Finally, the ABI option is something that will pick default CPU/FPU,
+define the specific behaviour of your code (PCS, extensions),
+and also choose the correct library calls, etc.
+
+CPU, FPU, ABI
+-------------
+
+Once your target is specified, it's time to pick the hardware you'll
+be compiling to. For every architecture, a default set of CPU/FPU/ABI
+will be chosen, so you'll almost always have to change it via flags.
+
+Typical flags include:
+ * ``-mcpu=<cpu-name>``, like x86-64, swift, cortex-a15
+ * ``-mfpu=<fpu-name>``, like SSE3, NEON, controlling the FP unit available
+ * ``-mfloat-abi=<fabi>``, like soft, hard, controlling which registers
+ to use for floating-point
+
+The default is normally the common denominator, so that Clang doesn't
+generate code that breaks. But that also means you won't get the best
+code for your specific hardware, which may mean orders of magnitude
+slower than you expect.
+
+For example, if your target is ``arm-none-eabi``, the default CPU will
+be ``arm7tdmi`` using soft float, which is extremely slow on modern cores,
+whereas if your triple is ``armv7a-none-eabi``, it'll be Cortex-A8 with
+NEON, but still using soft-float, which is much better, but still not
+great.
+
+Toolchain Options
+-----------------
+
+There are three main options to control access to your cross-compiler:
+``--sysroot``, ``-I``, and ``-L``. The two last ones are well known,
+but they're particularly important for additional libraries
+and headers that are specific to your target.
+
+There are two main ways to have a cross-compiler:
+
+#. When you have extracted your cross-compiler from a zip file into
+ a directory, you have to use ``--sysroot=<path>``. The path is the
+ root directory where you have unpacked your file, and Clang will
+ look for the directories ``bin``, ``lib``, ``include`` in there.
+
+ In this case, your setup should be pretty much done (if no
+ additional headers or libraries are needed), as Clang will find
+ all binaries it needs (assembler, linker, etc) in there.
+
+#. When you have installed via a package manager (modern Linux
+ distributions have cross-compiler packages available), make
+ sure the target triple you set is *also* the prefix of your
+ cross-compiler toolchain.
+
+ In this case, Clang will find the other binaries (assembler,
+ linker), but not always where the target headers and libraries
+ are. People add system-specific clues to Clang often, but as
+ things change, it's more likely that it won't find than the
+ other way around.
+
+ So, here, you'll be a lot safer if you specify the include/library
+ directories manually (via ``-I`` and ``-L``).
+
+Target-Specific Libraries
+=========================
+
+All libraries that you compile as part of your build will be
+cross-compiled to your target, and your build system will probably
+find them in the right place. But all dependencies that are
+normally checked against (like ``libxml`` or ``libz`` etc) will match
+against the host platform, not the target.
+
+So, if the build system is not aware that you want to cross-compile
+your code, it will get every dependency wrong, and your compilation
+will fail during build time, not configure time.
+
+Also, finding the libraries for your target are not as easy
+as for your host machine. There aren't many cross-libraries available
+as packages to most OS's, so you'll have to either cross-compile them
+from source, or download the package for your target platform,
+extract the libraries and headers, put them in specific directories
+and add ``-I`` and ``-L`` pointing to them.
+
+Also, some libraries have different dependencies on different targets,
+so configuration tools to find dependencies in the host can get the
+list wrong for the target platform. This means that the configuration
+of your build can get things wrong when setting their own library
+paths, and you'll have to augment it via additional flags (configure,
+Make, CMake, etc).
+
+Multilibs
+---------
+
+When you want to cross-compile to more than one configuration, for
+example hard-float-ARM and soft-float-ARM, you'll have to have multiple
+copies of your libraries and (possibly) headers.
+
+Some Linux distributions have support for Multilib, which handle that
+for you in an easier way, but if you're not careful and, for instance,
+forget to specify ``-ccc-gcc-name armv7l-linux-gnueabihf-gcc`` (which
+uses hard-float), Clang will pick the ``armv7l-linux-gnueabi-ld``
+(which uses soft-float) and linker errors will happen.
+
+The same is true if you're compiling for different ABIs, like ``gnueabi``
+and ``androideabi``, and might even link and run, but produce run-time
+errors, which are much harder to track down and fix.
Added: www-releases/trunk/4.0.0/tools/clang/docs/_sources/DataFlowSanitizer.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/4.0.0/tools/clang/docs/_sources/DataFlowSanitizer.txt?rev=297634&view=auto
==============================================================================
--- www-releases/trunk/4.0.0/tools/clang/docs/_sources/DataFlowSanitizer.txt (added)
+++ www-releases/trunk/4.0.0/tools/clang/docs/_sources/DataFlowSanitizer.txt Mon Mar 13 11:30:12 2017
@@ -0,0 +1,158 @@
+=================
+DataFlowSanitizer
+=================
+
+.. toctree::
+ :hidden:
+
+ DataFlowSanitizerDesign
+
+.. contents::
+ :local:
+
+Introduction
+============
+
+DataFlowSanitizer is a generalised dynamic data flow analysis.
+
+Unlike other Sanitizer tools, this tool is not designed to detect a
+specific class of bugs on its own. Instead, it provides a generic
+dynamic data flow analysis framework to be used by clients to help
+detect application-specific issues within their own code.
+
+Usage
+=====
+
+With no program changes, applying DataFlowSanitizer to a program
+will not alter its behavior. To use DataFlowSanitizer, the program
+uses API functions to apply tags to data to cause it to be tracked, and to
+check the tag of a specific data item. DataFlowSanitizer manages
+the propagation of tags through the program according to its data flow.
+
+The APIs are defined in the header file ``sanitizer/dfsan_interface.h``.
+For further information about each function, please refer to the header
+file.
+
+ABI List
+--------
+
+DataFlowSanitizer uses a list of functions known as an ABI list to decide
+whether a call to a specific function should use the operating system's native
+ABI or whether it should use a variant of this ABI that also propagates labels
+through function parameters and return values. The ABI list file also controls
+how labels are propagated in the former case. DataFlowSanitizer comes with a
+default ABI list which is intended to eventually cover the glibc library on
+Linux but it may become necessary for users to extend the ABI list in cases
+where a particular library or function cannot be instrumented (e.g. because
+it is implemented in assembly or another language which DataFlowSanitizer does
+not support) or a function is called from a library or function which cannot
+be instrumented.
+
+DataFlowSanitizer's ABI list file is a :doc:`SanitizerSpecialCaseList`.
+The pass treats every function in the ``uninstrumented`` category in the
+ABI list file as conforming to the native ABI. Unless the ABI list contains
+additional categories for those functions, a call to one of those functions
+will produce a warning message, as the labelling behavior of the function
+is unknown. The other supported categories are ``discard``, ``functional``
+and ``custom``.
+
+* ``discard`` -- To the extent that this function writes to (user-accessible)
+ memory, it also updates labels in shadow memory (this condition is trivially
+ satisfied for functions which do not write to user-accessible memory). Its
+ return value is unlabelled.
+* ``functional`` -- Like ``discard``, except that the label of its return value
+ is the union of the label of its arguments.
+* ``custom`` -- Instead of calling the function, a custom wrapper ``__dfsw_F``
+ is called, where ``F`` is the name of the function. This function may wrap
+ the original function or provide its own implementation. This category is
+ generally used for uninstrumentable functions which write to user-accessible
+ memory or which have more complex label propagation behavior. The signature
+ of ``__dfsw_F`` is based on that of ``F`` with each argument having a
+ label of type ``dfsan_label`` appended to the argument list. If ``F``
+ is of non-void return type a final argument of type ``dfsan_label *``
+ is appended to which the custom function can store the label for the
+ return value. For example:
+
+.. code-block:: c++
+
+ void f(int x);
+ void __dfsw_f(int x, dfsan_label x_label);
+
+ void *memcpy(void *dest, const void *src, size_t n);
+ void *__dfsw_memcpy(void *dest, const void *src, size_t n,
+ dfsan_label dest_label, dfsan_label src_label,
+ dfsan_label n_label, dfsan_label *ret_label);
+
+If a function defined in the translation unit being compiled belongs to the
+``uninstrumented`` category, it will be compiled so as to conform to the
+native ABI. Its arguments will be assumed to be unlabelled, but it will
+propagate labels in shadow memory.
+
+For example:
+
+.. code-block:: none
+
+ # main is called by the C runtime using the native ABI.
+ fun:main=uninstrumented
+ fun:main=discard
+
+ # malloc only writes to its internal data structures, not user-accessible memory.
+ fun:malloc=uninstrumented
+ fun:malloc=discard
+
+ # tolower is a pure function.
+ fun:tolower=uninstrumented
+ fun:tolower=functional
+
+ # memcpy needs to copy the shadow from the source to the destination region.
+ # This is done in a custom function.
+ fun:memcpy=uninstrumented
+ fun:memcpy=custom
+
+Example
+=======
+
+The following program demonstrates label propagation by checking that
+the correct labels are propagated.
+
+.. code-block:: c++
+
+ #include <sanitizer/dfsan_interface.h>
+ #include <assert.h>
+
+ int main(void) {
+ int i = 1;
+ dfsan_label i_label = dfsan_create_label("i", 0);
+ dfsan_set_label(i_label, &i, sizeof(i));
+
+ int j = 2;
+ dfsan_label j_label = dfsan_create_label("j", 0);
+ dfsan_set_label(j_label, &j, sizeof(j));
+
+ int k = 3;
+ dfsan_label k_label = dfsan_create_label("k", 0);
+ dfsan_set_label(k_label, &k, sizeof(k));
+
+ dfsan_label ij_label = dfsan_get_label(i + j);
+ assert(dfsan_has_label(ij_label, i_label));
+ assert(dfsan_has_label(ij_label, j_label));
+ assert(!dfsan_has_label(ij_label, k_label));
+
+ dfsan_label ijk_label = dfsan_get_label(i + j + k);
+ assert(dfsan_has_label(ijk_label, i_label));
+ assert(dfsan_has_label(ijk_label, j_label));
+ assert(dfsan_has_label(ijk_label, k_label));
+
+ return 0;
+ }
+
+Current status
+==============
+
+DataFlowSanitizer is a work in progress, currently under development for
+x86\_64 Linux.
+
+Design
+======
+
+Please refer to the :doc:`design document<DataFlowSanitizerDesign>`.
Added: www-releases/trunk/4.0.0/tools/clang/docs/_sources/DataFlowSanitizerDesign.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/4.0.0/tools/clang/docs/_sources/DataFlowSanitizerDesign.txt?rev=297634&view=auto
==============================================================================
--- www-releases/trunk/4.0.0/tools/clang/docs/_sources/DataFlowSanitizerDesign.txt (added)
+++ www-releases/trunk/4.0.0/tools/clang/docs/_sources/DataFlowSanitizerDesign.txt Mon Mar 13 11:30:12 2017
@@ -0,0 +1,220 @@
+DataFlowSanitizer Design Document
+=================================
+
+This document sets out the design for DataFlowSanitizer, a general
+dynamic data flow analysis. Unlike other Sanitizer tools, this tool is
+not designed to detect a specific class of bugs on its own. Instead,
+it provides a generic dynamic data flow analysis framework to be used
+by clients to help detect application-specific issues within their
+own code.
+
+DataFlowSanitizer is a program instrumentation which can associate
+a number of taint labels with any data stored in any memory region
+accessible by the program. The analysis is dynamic, which means that
+it operates on a running program, and tracks how the labels propagate
+through that program. The tool shall support a large (>100) number
+of labels, such that programs which operate on large numbers of data
+items may be analysed with each data item being tracked separately.
+
+Use Cases
+---------
+
+This instrumentation can be used as a tool to help monitor how data
+flows from a program's inputs (sources) to its outputs (sinks).
+This has applications from a privacy/security perspective in that
+one can audit how a sensitive data item is used within a program and
+ensure it isn't exiting the program anywhere it shouldn't be.
+
+Interface
+---------
+
+A number of functions are provided which will create taint labels,
+attach labels to memory regions and extract the set of labels
+associated with a specific memory region. These functions are declared
+in the header file ``sanitizer/dfsan_interface.h``.
+
+.. code-block:: c
+
+ /// Creates and returns a base label with the given description and user data.
+ dfsan_label dfsan_create_label(const char *desc, void *userdata);
+
+ /// Sets the label for each address in [addr,addr+size) to \c label.
+ void dfsan_set_label(dfsan_label label, void *addr, size_t size);
+
+ /// Sets the label for each address in [addr,addr+size) to the union of the
+ /// current label for that address and \c label.
+ void dfsan_add_label(dfsan_label label, void *addr, size_t size);
+
+ /// Retrieves the label associated with the given data.
+ ///
+ /// The type of 'data' is arbitrary. The function accepts a value of any type,
+ /// which can be truncated or extended (implicitly or explicitly) as necessary.
+ /// The truncation/extension operations will preserve the label of the original
+ /// value.
+ dfsan_label dfsan_get_label(long data);
+
+ /// Retrieves a pointer to the dfsan_label_info struct for the given label.
+ const struct dfsan_label_info *dfsan_get_label_info(dfsan_label label);
+
+ /// Returns whether the given label label contains the label elem.
+ int dfsan_has_label(dfsan_label label, dfsan_label elem);
+
+ /// If the given label label contains a label with the description desc, returns
+ /// that label, else returns 0.
+ dfsan_label dfsan_has_label_with_desc(dfsan_label label, const char *desc);
+
+Taint label representation
+--------------------------
+
+As stated above, the tool must track a large number of taint
+labels. This poses an implementation challenge, as most multiple-label
+tainting systems assign one label per bit to shadow storage, and
+union taint labels using a bitwise or operation. This will not scale
+to clients which use hundreds or thousands of taint labels, as the
+label union operation becomes O(n) in the number of supported labels,
+and data associated with it will quickly dominate the live variable
+set, causing register spills and hampering performance.
+
+Instead, a low overhead approach is proposed which is best-case O(log\
+:sub:`2` n) during execution. The underlying assumption is that
+the required space of label unions is sparse, which is a reasonable
+assumption to make given that we are optimizing for the case where
+applications mostly copy data from one place to another, without often
+invoking the need for an actual union operation. The representation
+of a taint label is a 16-bit integer, and new labels are allocated
+sequentially from a pool. The label identifier 0 is special, and means
+that the data item is unlabelled.
+
+When a label union operation is requested at a join point (any
+arithmetic or logical operation with two or more operands, such as
+addition), the code checks whether a union is required, whether the
+same union has been requested before, and whether one union label
+subsumes the other. If so, it returns the previously allocated union
+label. If not, it allocates a new union label from the same pool used
+for new labels.
+
+Specifically, the instrumentation pass will insert code like this
+to decide the union label ``lu`` for a pair of labels ``l1``
+and ``l2``:
+
+.. code-block:: c
+
+ if (l1 == l2)
+ lu = l1;
+ else
+ lu = __dfsan_union(l1, l2);
+
+The equality comparison is outlined, to provide an early exit in
+the common cases where the program is processing unlabelled data, or
+where the two data items have the same label. ``__dfsan_union`` is
+a runtime library function which performs all other union computation.
+
+Further optimizations are possible, for example if ``l1`` is known
+at compile time to be zero (e.g. it is derived from a constant),
+``l2`` can be used for ``lu``, and vice versa.
+
+Memory layout and label management
+----------------------------------
+
+The following is the current memory layout for Linux/x86\_64:
+
++---------------+---------------+--------------------+
+| Start | End | Use |
++===============+===============+====================+
+| 0x700000008000|0x800000000000 | application memory |
++---------------+---------------+--------------------+
+| 0x200200000000|0x700000008000 | unused |
++---------------+---------------+--------------------+
+| 0x200000000000|0x200200000000 | union table |
++---------------+---------------+--------------------+
+| 0x000000010000|0x200000000000 | shadow memory |
++---------------+---------------+--------------------+
+| 0x000000000000|0x000000010000 | reserved by kernel |
++---------------+---------------+--------------------+
+
+Each byte of application memory corresponds to two bytes of shadow
+memory, which are used to store its taint label. As for LLVM SSA
+registers, we have not found it necessary to associate a label with
+each byte or bit of data, as some other tools do. Instead, labels are
+associated directly with registers. Loads will result in a union of
+all shadow labels corresponding to bytes loaded (which most of the
+time will be short circuited by the initial comparison) and stores will
+result in a copy of the label to the shadow of all bytes stored to.
+
+Propagating labels through arguments
+------------------------------------
+
+In order to propagate labels through function arguments and return values,
+DataFlowSanitizer changes the ABI of each function in the translation unit.
+There are currently two supported ABIs:
+
+* Args -- Argument and return value labels are passed through additional
+ arguments and by modifying the return type.
+
+* TLS -- Argument and return value labels are passed through TLS variables
+ ``__dfsan_arg_tls`` and ``__dfsan_retval_tls``.
+
+The main advantage of the TLS ABI is that it is more tolerant of ABI mismatches
+(TLS storage is not shared with any other form of storage, whereas extra
+arguments may be stored in registers which under the native ABI are not used
+for parameter passing and thus could contain arbitrary values). On the other
+hand the args ABI is more efficient and allows ABI mismatches to be more easily
+identified by checking for nonzero labels in nominally unlabelled programs.
+
+Implementing the ABI list
+-------------------------
+
+The `ABI list <DataFlowSanitizer.html#abi-list>`_ provides a list of functions
+which conform to the native ABI, each of which is callable from an instrumented
+program. This is implemented by replacing each reference to a native ABI
+function with a reference to a function which uses the instrumented ABI.
+Such functions are automatically-generated wrappers for the native functions.
+For example, given the ABI list example provided in the user manual, the
+following wrappers will be generated under the args ABI:
+
+.. code-block:: llvm
+
+ define linkonce_odr { i8*, i16 } @"dfsw$malloc"(i64 %0, i16 %1) {
+ entry:
+ %2 = call i8* @malloc(i64 %0)
+ %3 = insertvalue { i8*, i16 } undef, i8* %2, 0
+ %4 = insertvalue { i8*, i16 } %3, i16 0, 1
+ ret { i8*, i16 } %4
+ }
+
+ define linkonce_odr { i32, i16 } @"dfsw$tolower"(i32 %0, i16 %1) {
+ entry:
+ %2 = call i32 @tolower(i32 %0)
+ %3 = insertvalue { i32, i16 } undef, i32 %2, 0
+ %4 = insertvalue { i32, i16 } %3, i16 %1, 1
+ ret { i32, i16 } %4
+ }
+
+ define linkonce_odr { i8*, i16 } @"dfsw$memcpy"(i8* %0, i8* %1, i64 %2, i16 %3, i16 %4, i16 %5) {
+ entry:
+ %labelreturn = alloca i16
+ %6 = call i8* @__dfsw_memcpy(i8* %0, i8* %1, i64 %2, i16 %3, i16 %4, i16 %5, i16* %labelreturn)
+ %7 = load i16* %labelreturn
+ %8 = insertvalue { i8*, i16 } undef, i8* %6, 0
+ %9 = insertvalue { i8*, i16 } %8, i16 %7, 1
+ ret { i8*, i16 } %9
+ }
+
+As an optimization, direct calls to native ABI functions will call the
+native ABI function directly and the pass will compute the appropriate label
+internally. This has the advantage of reducing the number of union operations
+required when the return value label is known to be zero (i.e. ``discard``
+functions, or ``functional`` functions with known unlabelled arguments).
+
+Checking ABI Consistency
+------------------------
+
+DFSan changes the ABI of each function in the module. This makes it possible
+for a function with the native ABI to be called with the instrumented ABI,
+or vice versa, thus possibly invoking undefined behavior. A simple way
+of statically detecting instances of this problem is to prepend the prefix
+"dfs$" to the name of each instrumented-ABI function.
+
+This will not catch every such problem; in particular function pointers passed
+across the instrumented-native barrier cannot be used on the other side.
+These problems could potentially be caught dynamically.
More information about the llvm-commits
mailing list