Update Clang for 3.5 rebase (r209713).
Change-Id: I8c9133b0f8f776dc915f270b60f94962e771bc83
diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt
index 635ea1f..20a1396 100644
--- a/docs/CMakeLists.txt
+++ b/docs/CMakeLists.txt
@@ -80,3 +80,12 @@
endif()
endif()
endif()
+
+if (LLVM_ENABLE_SPHINX)
+ if (SPHINX_FOUND)
+ include(AddSphinxTarget)
+ if (${SPHINX_OUTPUT_HTML})
+ add_sphinx_target(html clang)
+ endif()
+ endif()
+endif()
diff --git a/docs/ClangFormat.rst b/docs/ClangFormat.rst
index 3f8499b..86c5ec5 100644
--- a/docs/ClangFormat.rst
+++ b/docs/ClangFormat.rst
@@ -177,5 +177,11 @@
git diff -U0 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).
diff --git a/docs/ClangFormatStyleOptions.rst b/docs/ClangFormatStyleOptions.rst
index db77372..0483bd7 100644
--- a/docs/ClangFormatStyleOptions.rst
+++ b/docs/ClangFormatStyleOptions.rst
@@ -106,9 +106,24 @@
Allow putting all parameters of a function declaration onto
the next line even if ``BinPackParameters`` is ``false``.
-**AllowShortFunctionsOnASingleLine** (``bool``)
- If ``true``, ``int f() { return 0; }`` can be put on a single
- line.
+**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.
+
+**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_Inline`` (in configuration: ``Inline``)
+ Only merge functions defined inside a class.
+ * ``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
@@ -213,12 +228,16 @@
not use this in config files, etc. Use at your own risk.
**ForEachMacros** (``std::vector<std::string>``)
- A list of macros that should be interpreted as foreach loops instead of as
- function calls.
+ A vector of macros that should be interpreted as foreach loops
+ instead of as function calls.
- For example, ``ForEachMacros: [BOOST_FOREACH, Q_FOREACH]`` tells
- clang-format to treat ``BOOST_FOREACH`` and ``Q_FOREACH`` as loop control
- statements.
+ These are expected to be macros of the form:
+ \code
+ FOREACH(<variable-declaration>, ...)
+ <loop-body>
+ \endcode
+
+ For example: BOOST_FOREACH.
**IndentCaseLabels** (``bool``)
Indent case labels one level from the switch statement.
@@ -233,6 +252,9 @@
**IndentWidth** (``unsigned``)
The number of columns to use for indentation.
+**KeepEmptyLinesAtTheStartOfBlocks** (``bool``)
+ If true, empty lines at the start of blocks are kept.
+
**Language** (``LanguageKind``)
Language, this format style is targeted at.
@@ -267,7 +289,7 @@
**ObjCSpaceAfterProperty** (``bool``)
Add a space after ``@property`` in Objective-C, i.e. use
- ``@property (readonly)`` instead of ``@property(readonly)``.
+ ``\@property (readonly)`` instead of ``\@property(readonly)``.
**ObjCSpaceBeforeProtocolList** (``bool``)
Add a space in front of an Objective-C protocol list, i.e. use
@@ -319,7 +341,11 @@
If ``true``, spaces may be inserted into '()'.
**SpacesBeforeTrailingComments** (``unsigned``)
- The number of spaces to before trailing line comments.
+ 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
diff --git a/docs/LanguageExtensions.rst b/docs/LanguageExtensions.rst
index 392e679..5e957cb 100644
--- a/docs/LanguageExtensions.rst
+++ b/docs/LanguageExtensions.rst
@@ -134,6 +134,26 @@
(double underscore) to avoid interference from a macro with the same name. For
instance, ``__always_inline__`` can be used instead of ``always_inline``.
+``__is_identifier``
+-------------------
+
+This function-like macro takes a single identifier argument that might be either
+a reserved word or a regular identifier. It evaluates to 1 if the argument is just
+a regular identifier and not a reserved word, in the sense that it can then be
+used as the name of a user-defined function or variable. Otherwise it evaluates
+to 0. It can be used like this:
+
+.. code-block:: c++
+
+ ...
+ #ifdef __is_identifier // Compatibility with non-clang compilers.
+ #if __is_identifier(__wchar_t)
+ typedef wchar_t __wchar_t;
+ #endif
+ #endif
+
+ __wchar_t WideCharacter;
+ ...
Include File Checking Macros
============================
@@ -730,16 +750,16 @@
C++1y generalized lambda capture
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Use ``__has_feature(cxx_init_capture)`` or
-``__has_extension(cxx_init_capture)`` to determine if support for
+Use ``__has_feature(cxx_init_captures)`` or
+``__has_extension(cxx_init_captures)`` to determine if support for
lambda captures with explicit initializers is enabled
(for instance, ``[n(0)] { return ++n; }``).
C++1y generic lambdas
^^^^^^^^^^^^^^^^^^^^^
-Use ``__has_feature(cxx_generic_lambda)`` or
-``__has_extension(cxx_generic_lambda)`` to determine if support for generic
+Use ``__has_feature(cxx_generic_lambdas)`` or
+``__has_extension(cxx_generic_lambdas)`` to determine if support for generic
(polymorphic) lambdas is enabled
(for instance, ``[] (auto x) { return x + 1; }``).
@@ -1546,7 +1566,7 @@
void __builtin_arm_clrex(void);
The types ``T`` currently supported are:
-* Integer types with width at most 64 bits (or 128 bits on ARM64).
+* Integer types with width at most 64 bits (or 128 bits on AArch64).
* Floating-point types
* Pointer types.
diff --git a/docs/LibASTMatchersReference.html b/docs/LibASTMatchersReference.html
index f701f11..c308635 100644
--- a/docs/LibASTMatchersReference.html
+++ b/docs/LibASTMatchersReference.html
@@ -631,6 +631,15 @@
</pre></td></tr>
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('exprWithCleanups0')"><a name="exprWithCleanups0Anchor">exprWithCleanups</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ExprWithCleanups.html">ExprWithCleanups</a>>...</td></tr>
+<tr><td colspan="4" class="doc" id="exprWithCleanups0"><pre>Matches expressions that introduce cleanups to be run at the end
+of the sub-expression's evaluation.
+
+Example matches std::string()
+ const std::string str = std::string();
+</pre></td></tr>
+
+
<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('floatLiteral0')"><a name="floatLiteral0Anchor">floatLiteral</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1FloatingLiteral.html">FloatingLiteral</a>>...</td></tr>
<tr><td colspan="4" class="doc" id="floatLiteral0"><pre>Matches float literals of all sizes encodings, e.g.
1.0, 1.0f, 1.0L and 1e10.
@@ -1357,12 +1366,6 @@
</pre></td></tr>
-<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXConstructorDecl.html">CXXConstructorDecl</a>></td><td class="name" onclick="toggle('isImplicit0')"><a name="isImplicit0Anchor">isImplicit</a></td><td></td></tr>
-<tr><td colspan="4" class="doc" id="isImplicit0"><pre>Matches a constructor declaration that has been implicitly added
-by the compiler (eg. implicit defaultcopy constructors).
-</pre></td></tr>
-
-
<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXCtorInitializer.html">CXXCtorInitializer</a>></td><td class="name" onclick="toggle('isWritten0')"><a name="isWritten0Anchor">isWritten</a></td><td></td></tr>
<tr><td colspan="4" class="doc" id="isWritten0"><pre>Matches a constructor initializer if it is explicitly written in
code (as opposed to implicitly added by the compiler).
@@ -1598,13 +1601,19 @@
</pre></td></tr>
-<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>></td><td class="name" onclick="toggle('equalsNode0')"><a name="equalsNode0Anchor">equalsNode</a></td><td>Decl* Other</td></tr>
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>></td><td class="name" onclick="toggle('equalsNode0')"><a name="equalsNode0Anchor">equalsNode</a></td><td>Decl *Node</td></tr>
<tr><td colspan="4" class="doc" id="equalsNode0"><pre>Matches if a node equals another node.
Decl has pointer identity in the AST.
</pre></td></tr>
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>></td><td class="name" onclick="toggle('isImplicit0')"><a name="isImplicit0Anchor">isImplicit</a></td><td></td></tr>
+<tr><td colspan="4" class="doc" id="isImplicit0"><pre>Matches a declaration that has been implicitly added
+by the compiler (eg. implicit defaultcopy constructors).
+</pre></td></tr>
+
+
<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>></td><td class="name" onclick="toggle('isPrivate0')"><a name="isPrivate0Anchor">isPrivate</a></td><td></td></tr>
<tr><td colspan="4" class="doc" id="isPrivate0"><pre>Matches private C++ declarations.
@@ -1891,7 +1900,7 @@
</pre></td></tr>
-<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('equalsNode1')"><a name="equalsNode1Anchor">equalsNode</a></td><td>Stmt* Other</td></tr>
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('equalsNode1')"><a name="equalsNode1Anchor">equalsNode</a></td><td>Stmt *Node</td></tr>
<tr><td colspan="4" class="doc" id="equalsNode1"><pre>Matches if a node equals another node.
Stmt has pointer identity in the AST.
@@ -2393,6 +2402,19 @@
</pre></td></tr>
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXForRangeStmt.html">CXXForRangeStmt</a>></td><td class="name" onclick="toggle('hasBody3')"><a name="hasBody3Anchor">hasBody</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="hasBody3"><pre>Matches a 'for', 'while', or 'do while' statement that has
+a given body.
+
+Given
+ for (;;) {}
+hasBody(compoundStmt())
+ matches 'for (;;) {}'
+with compoundStmt()
+ matching '{}'
+</pre></td></tr>
+
+
<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXForRangeStmt.html">CXXForRangeStmt</a>></td><td class="name" onclick="toggle('hasLoopVariable0')"><a name="hasLoopVariable0Anchor">hasLoopVariable</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1VarDecl.html">VarDecl</a>> InnerMatcher</td></tr>
<tr><td colspan="4" class="doc" id="hasLoopVariable0"><pre>Matches the initialization statement of a for loop.
@@ -2403,6 +2425,16 @@
</pre></td></tr>
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXForRangeStmt.html">CXXForRangeStmt</a>></td><td class="name" onclick="toggle('hasRangeInit0')"><a name="hasRangeInit0Anchor">hasRangeInit</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="hasRangeInit0"><pre>Matches the range initialization statement of a for loop.
+
+Example:
+ forStmt(hasRangeInit(anything()))
+matches 'a' in
+ for (int x : a) { }
+</pre></td></tr>
+
+
<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXMemberCallExpr.html">CXXMemberCallExpr</a>></td><td class="name" onclick="toggle('onImplicitObjectArgument0')"><a name="onImplicitObjectArgument0Anchor">onImplicitObjectArgument</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>> InnerMatcher</td></tr>
<tr><td colspan="4" class="doc" id="onImplicitObjectArgument0"><pre></pre></td></tr>
@@ -3068,6 +3100,24 @@
</pre></td></tr>
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1IfStmt.html">IfStmt</a>></td><td class="name" onclick="toggle('hasElse0')"><a name="hasElse0Anchor">hasElse</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="hasElse0"><pre>Matches the else-statement of an if statement.
+
+Examples matches the if statement
+ (matcher = ifStmt(hasElse(boolLiteral(equals(true)))))
+ if (false) false; else true;
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1IfStmt.html">IfStmt</a>></td><td class="name" onclick="toggle('hasThen0')"><a name="hasThen0Anchor">hasThen</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="hasThen0"><pre>Matches the then-statement of an if statement.
+
+Examples matches the if statement
+ (matcher = ifStmt(hasThen(boolLiteral(equals(true)))))
+ if (false) true; else false;
+</pre></td></tr>
+
+
<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ImplicitCastExpr.html">ImplicitCastExpr</a>></td><td class="name" onclick="toggle('hasImplicitDestinationType0')"><a name="hasImplicitDestinationType0Anchor">hasImplicitDestinationType</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1QualType.html">QualType</a>> InnerMatcher</td></tr>
<tr><td colspan="4" class="doc" id="hasImplicitDestinationType0"><pre>Matches implicit casts whose destination type matches a given
matcher.
diff --git a/docs/LibASTMatchersTutorial.rst b/docs/LibASTMatchersTutorial.rst
index 13749fb..1e88ec2 100644
--- a/docs/LibASTMatchersTutorial.rst
+++ b/docs/LibASTMatchersTutorial.rst
@@ -153,7 +153,7 @@
CommonOptionsParser OptionsParser(argc, argv, MyToolCategory);
ClangTool Tool(OptionsParser.getCompilations(),
OptionsParser.getSourcePathList());
- return Tool.run(newFrontendActionFactory<clang::SyntaxOnlyAction>());
+ return Tool.run(newFrontendActionFactory<clang::SyntaxOnlyAction>().get());
}
And that's it! You can compile our new tool by running ninja from the
@@ -299,7 +299,7 @@
MatchFinder Finder;
Finder.addMatcher(LoopMatcher, &Printer);
- return Tool.run(newFrontendActionFactory(&Finder));
+ return Tool.run(newFrontendActionFactory(&Finder).get());
}
Now, you should be able to recompile and run the code to discover for
diff --git a/docs/LibTooling.rst b/docs/LibTooling.rst
index 57f207f..75ef6a0 100644
--- a/docs/LibTooling.rst
+++ b/docs/LibTooling.rst
@@ -99,7 +99,7 @@
// on. Thus, it takes a FrontendActionFactory as parameter. To create a
// FrontendActionFactory from a given FrontendAction type, we call
// newFrontendActionFactory<clang::SyntaxOnlyAction>().
- int result = Tool.run(newFrontendActionFactory<clang::SyntaxOnlyAction>());
+ int result = Tool.run(newFrontendActionFactory<clang::SyntaxOnlyAction>().get());
Putting it together --- the first tool
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -136,7 +136,7 @@
CommonOptionsParser OptionsParser(argc, argv, MyToolCategory);
ClangTool Tool(OptionsParser.getCompilations(),
OptionsParser.getSourcePathList());
- return Tool.run(newFrontendActionFactory<clang::SyntaxOnlyAction>());
+ return Tool.run(newFrontendActionFactory<clang::SyntaxOnlyAction>().get());
}
Running the tool on some code
diff --git a/docs/Modules.rst b/docs/Modules.rst
index eec0b77..ce1e717 100644
--- a/docs/Modules.rst
+++ b/docs/Modules.rst
@@ -198,6 +198,9 @@
``-fmodule-map-file=<file>``
Load the given module map file if a header from its directory or one of its subdirectories is loaded.
+``-fmodules-search-all``
+ If a symbol is not found, search modules referenced in the current module maps but not imported for symbols, so the error message can reference the module by name. Note that if the global module index has not been built before, this might take some time as it needs to build all the modules. Note that this option doesn't apply in module builds, to avoid the recursion.
+
Module Semantics
================
@@ -761,7 +764,7 @@
because the header ``Foo_Private.h`` won't always be available. The
module map file could be customized based on whether
-``Foo_Private.h``is available or not, but doing so requires custom
+``Foo_Private.h`` is available or not, but doing so requires custom
build machinery.
Private module map files, which are named ``module.private.modulemap``
@@ -770,7 +773,7 @@
example, we would split the module map file above into two module map
files:
-.. parsed-literal::
+.. code-block:: c
/* module.modulemap */
module Foo {
@@ -839,7 +842,7 @@
=================================
The Clang source code provides additional information about modules:
-``clang/lib/Headers/module.map``
+``clang/lib/Headers/module.modulemap``
Module map for Clang's compiler-specific header files.
``clang/test/Modules/``
diff --git a/docs/SanitizerSpecialCaseList.rst b/docs/SanitizerSpecialCaseList.rst
index 8f4727c..a4165b2 100644
--- a/docs/SanitizerSpecialCaseList.rst
+++ b/docs/SanitizerSpecialCaseList.rst
@@ -24,7 +24,7 @@
thread stack, bypassing the frame boundaries);
* ignore a known problem.
-To achieve this, user may create a file listing the entities he wants to
+To achieve this, user may create a file listing the entities they want to
ignore, and pass it to clang at compile-time using
``-fsanitize-blacklist`` flag. See :doc:`UsersManual` for details.
diff --git a/docs/UsersManual.rst b/docs/UsersManual.rst
index 5b761a8..19603d4 100644
--- a/docs/UsersManual.rst
+++ b/docs/UsersManual.rst
@@ -1065,6 +1065,166 @@
only. This only applies to the AArch64 architecture.
+Using Sampling Profilers for Optimization
+-----------------------------------------
+
+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.
+
+In particular, sample profilers can provide execution counts for all
+instructions in the code and information on branches taken and function
+invocation. The compiler can use this information in its optimization
+cost models. For example, knowing that a branch is taken very
+frequently helps the compiler make better decisions when ordering
+basic blocks. Knowing that a function ``foo`` is called more
+frequently than another function ``bar`` helps the inliner.
+
+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:
+
+1. 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 ``-gline-tables-only`` or ``-g`` to the
+ command line. This is important for the profiler to be able to map
+ instructions back to source line locations.
+
+ .. code-block:: console
+
+ $ clang++ -O2 -gline-tables-only code.cc -o code
+
+2. 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
+ (https://perf.wiki.kernel.org/), so these examples assume that you
+ are using Linux Perf to profile your code.
+
+ .. code-block:: console
+
+ $ perf record -b ./code
+
+ Note the use of the ``-b`` 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.
+
+3. Convert the collected profile data to LLVM's sample profile format.
+ This is currently supported via the AutoFDO converter ``create_llvm_prof``.
+ It is available at http://github.com/google/autofdo. Once built and
+ installed, you can convert the ``perf.data`` file to LLVM using
+ the command:
+
+ .. code-block:: console
+
+ $ create_llvm_prof --binary=./code --out=code.prof
+
+ This will read ``perf.data`` and the binary file ``./code`` and emit
+ the profile data in ``code.prof``. Note that if you ran ``perf``
+ without the ``-b`` flag, you need to use ``--use_lbr=false`` when
+ calling ``create_llvm_prof``.
+
+4. 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 ``-gline-tables-only`` and ``-fprofile-sample-use``.
+
+ .. code-block:: console
+
+ $ clang++ -O2 -gline-tables-only -fprofile-sample-use=code.prof code.cc -o code
+
+
+Sample Profile Format
+^^^^^^^^^^^^^^^^^^^^^
+
+If you are not using Linux Perf to collect profiles, you will need to
+write a conversion tool from your profiler to LLVM's format. This section
+explains the file format expected by the backend.
+
+Sample profiles are written as ASCII text. The file is divided into sections,
+which correspond to each of the functions executed at runtime. Each
+section has the following format (taken from
+https://github.com/google/autofdo/blob/master/profile_writer.h):
+
+.. code-block:: console
+
+ function1:total_samples:total_head_samples
+ offset1[.discriminator]: number_of_samples [fn1:num fn2:num ... ]
+ offset2[.discriminator]: number_of_samples [fn3:num fn4:num ... ]
+ ...
+ offsetN[.discriminator]: number_of_samples [fn5:num fn6:num ... ]
+
+The file may contain blank lines between sections and within a
+section. However, the spacing within a single line is fixed. Additional
+spaces will result in an error while reading the file.
+
+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.
+
+Each sampled line may contain several items. Some are optional (marked
+below):
+
+a. 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.
+
+ 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).
+
+b. [OPTIONAL] Discriminator. This is used if the sampled program
+ was compiled with DWARF discriminator support
+ (http://wiki.dwarfstd.org/index.php?title=Path_Discriminators).
+ DWARF discriminators are unsigned integer values that allow the
+ compiler to distinguish between multiple execution paths on the
+ same source line location.
+
+ For example, consider the line of code ``if (cond) foo(); else bar();``.
+ If the predicate ``cond`` is true 80% of the time, then the edge
+ into function ``foo`` should be considered to be taken most of the
+ time. But both calls to ``foo`` and ``bar`` 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.
+
+ This is what discriminators provide. In this case, the calls to
+ ``foo`` and ``bar`` will be at the same line, but will have
+ different discriminator values. This allows the compiler to correctly
+ set edge weights into ``foo`` and ``bar``.
+
+c. Number of samples. This is an integer quantity representing the
+ number of samples collected by the profiler at this source
+ location.
+
+d. [OPTIONAL] Potential call targets and samples. If present, this
+ line contains a call instruction. This models both direct and
+ number of samples. For example,
+
+ .. code-block:: console
+
+ 130: 7 foo:3 bar:2 baz:7
+
+ The above means that at relative line offset 130 there is a call
+ instruction that calls one of ``foo()``, ``bar()`` and ``baz()``,
+ with ``baz()`` being the relatively more frequently called target.
+
+
Controlling Size of Debug Information
-------------------------------------
diff --git a/docs/tools/dump_format_style.py b/docs/tools/dump_format_style.py
old mode 100644
new mode 100755
index addda2a..66bad8b
--- a/docs/tools/dump_format_style.py
+++ b/docs/tools/dump_format_style.py
@@ -98,7 +98,7 @@
enum = Enum(name, comment)
elif line.endswith(';'):
state = State.InStruct
- field_type, field_name = re.match(r'([:\w]+)\s+(\w+);', line).groups()
+ field_type, field_name = re.match(r'([<>:\w]+)\s+(\w+);', line).groups()
option = Option(str(field_name), str(field_type), comment)
options.append(option)
else:
@@ -122,7 +122,8 @@
raise Exception('Not finished by the end of file')
for option in options:
- if not option.type in ['bool', 'unsigned', 'int', 'std::string']:
+ if not option.type in ['bool', 'unsigned', 'int', 'std::string',
+ 'std::vector<std::string>']:
if enums.has_key(option.type):
option.enum = enums[option.type]
else: