<div dir="ltr">Neat! It's not everyday that we get a whole new document!<div><br></div><div>-- Sean Silva</div></div><div class="gmail_extra"><br><br><div class="gmail_quote">On Fri, Apr 11, 2014 at 7:21 PM, Duncan P. N. Exon Smith <span dir="ltr"><<a href="mailto:dexonsmith@apple.com" target="_blank">dexonsmith@apple.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">Author: dexonsmith<br>
Date: Fri Apr 11 18:21:07 2014<br>
New Revision: 206086<br>
<br>
URL: <a href="http://llvm.org/viewvc/llvm-project?rev=206086&view=rev" target="_blank">http://llvm.org/viewvc/llvm-project?rev=206086&view=rev</a><br>
Log:<br>
blockfreq: Document BlockFrequencyInfo terminology<br>
<br>
Documents terminology used in the forthcoming rewrite of<br>
BlockFrequencyInfo.<br>
<br>
<rdar://problem/14292693><br>
<br>
Added:<br>
llvm/trunk/docs/BlockFrequencyTerminology.rst<br>
Modified:<br>
llvm/trunk/docs/BranchWeightMetadata.rst<br>
llvm/trunk/docs/index.rst<br>
<br>
Added: llvm/trunk/docs/BlockFrequencyTerminology.rst<br>
URL: <a href="http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/BlockFrequencyTerminology.rst?rev=206086&view=auto" target="_blank">http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/BlockFrequencyTerminology.rst?rev=206086&view=auto</a><br>
==============================================================================<br>
--- llvm/trunk/docs/BlockFrequencyTerminology.rst (added)<br>
+++ llvm/trunk/docs/BlockFrequencyTerminology.rst Fri Apr 11 18:21:07 2014<br>
@@ -0,0 +1,130 @@<br>
+================================<br>
+LLVM Block Frequency Terminology<br>
+================================<br>
+<br>
+.. contents::<br>
+ :local:<br>
+<br>
+Introduction<br>
+============<br>
+<br>
+Block Frequency is a metric for estimating the relative frequency of different<br>
+basic blocks. This document describes the terminology that the<br>
+``BlockFrequencyInfo`` and ``MachineBlockFrequencyInfo`` analysis passes use.<br>
+<br>
+Branch Probability<br>
+==================<br>
+<br>
+Blocks with multiple successors have probabilities associated with each<br>
+outgoing edge. These are called branch probabilities. For a given block, the<br>
+sum of its outgoing branch probabilities should be 1.0.<br>
+<br>
+Branch Weight<br>
+=============<br>
+<br>
+Rather than storing fractions on each edge, we store an integer weight.<br>
+Weights are relative to the other edges of a given predecessor block. The<br>
+branch probability associated with a given edge is its own weight divided by<br>
+the sum of the weights on the predecessor's outgoing edges.<br>
+<br>
+For example, consider this IR:<br>
+<br>
+.. code-block:: llvm<br>
+<br>
+ define void @foo() {<br>
+ ; ...<br>
+ A:<br>
+ br i1 %cond, label %B, label %C, !prof !0<br>
+ ; ...<br>
+ }<br>
+ !0 = metadata !{metadata !"branch_weights", i32 7, i32 8}<br>
+<br>
+and this simple graph representation::<br>
+<br>
+ A -> B (edge-weight: 7)<br>
+ A -> C (edge-weight: 8)<br>
+<br>
+The probability of branching from block A to block B is 7/15, and the<br>
+probability of branching from block A to block C is 8/15.<br>
+<br>
+See :doc:`BranchWeightMetadata` for details about the branch weight IR<br>
+representation.<br>
+<br>
+Block Frequency<br>
+===============<br>
+<br>
+Block frequency is a relative metric that represents the number of times a<br>
+block executes. The ratio of a block frequency to the entry block frequency is<br>
+the expected number of times the block will execute per entry to the function.<br>
+<br>
+Block frequency is the main output of the ``BlockFrequencyInfo`` and<br>
+``MachineBlockFrequencyInfo`` analysis passes.<br>
+<br>
+Implementation: a series of DAGs<br>
+================================<br>
+<br>
+The implementation of the block frequency calculation analyses each loop,<br>
+bottom-up, ignoring backedges; i.e., as a DAG. After each loop is processed,<br>
+it's packaged up to act as a pseudo-node in its parent loop's (or the<br>
+function's) DAG analysis.<br>
+<br>
+Block Mass<br>
+==========<br>
+<br>
+For each DAG, the entry node is assigned a mass of ``UINT64_MAX`` and mass is<br>
+distributed to successors according to branch weights. Block Mass uses a<br>
+fixed-point representation where ``UINT64_MAX`` represents ``1.0`` and ``0``<br>
+represents a number just above ``0.0``.<br>
+<br>
+After mass is fully distributed, in any cut of the DAG that separates the exit<br>
+nodes from the entry node, the sum of the block masses of the nodes succeeded<br>
+by a cut edge should equal ``UINT64_MAX``. In other words, mass is conserved<br>
+as it "falls" through the DAG.<br>
+<br>
+If a function's basic block graph is a DAG, then block masses are valid block<br>
+frequencies. This works poorly in practise though, since downstream users rely<br>
+on adding block frequencies together without hitting the maximum.<br>
+<br>
+Loop Scale<br>
+==========<br>
+<br>
+Loop scale is a metric that indicates how many times a loop iterates per entry.<br>
+As mass is distributed through the loop's DAG, the (otherwise ignored) backedge<br>
+mass is collected. This backedge mass is used to compute the exit frequency,<br>
+and thus the loop scale.<br>
+<br>
+Implementation: Getting from mass and scale to frequency<br>
+========================================================<br>
+<br>
+After analysing the complete series of DAGs, each block has a mass (local to<br>
+its containing loop, if any), and each loop psuedo-node has a loop scale and<br>
+its own mass (from its parent's DAG).<br>
+<br>
+We can get an initial frequency assignment (with entry frequency of 1.0) by<br>
+multiplying these masses and loop scales together. A given block's frequency<br>
+is the product of its mass, the mass of containing loops' pseudo nodes, and the<br>
+containing loops' loop scales.<br>
+<br>
+Since downstream users need integers (not floating point), this initial<br>
+frequency assignment is shifted as necessary into the range of ``uint64_t``.<br>
+<br>
+Block Bias<br>
+==========<br>
+<br>
+Block bias is a proposed *absolute* metric to indicate a bias toward or away<br>
+from a given block during a function's execution. The idea is that bias can be<br>
+used in isolation to indicate whether a block is relatively hot or cold, or to<br>
+compare two blocks to indicate whether one is hotter or colder than the other.<br>
+<br>
+The proposed calculation involves calculating a *reference* block frequency,<br>
+where:<br>
+<br>
+* every branch weight is assumed to be 1 (i.e., every branch probability<br>
+ distribution is even) and<br>
+<br>
+* loop scales are ignored.<br>
+<br>
+This reference frequency represents what the block frequency would be in an<br>
+unbiased graph.<br>
+<br>
+The bias is the ratio of the block frequency to this reference block frequency.<br>
<br>
Modified: llvm/trunk/docs/BranchWeightMetadata.rst<br>
URL: <a href="http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/BranchWeightMetadata.rst?rev=206086&r1=206085&r2=206086&view=diff" target="_blank">http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/BranchWeightMetadata.rst?rev=206086&r1=206085&r2=206086&view=diff</a><br>
==============================================================================<br>
--- llvm/trunk/docs/BranchWeightMetadata.rst (original)<br>
+++ llvm/trunk/docs/BranchWeightMetadata.rst Fri Apr 11 18:21:07 2014<br>
@@ -8,10 +8,11 @@ LLVM Branch Weight Metadata<br>
Introduction<br>
============<br>
<br>
-Branch Weight Metadata represents branch weights as its likeliness to be<br>
-taken. Metadata is assigned to the ``TerminatorInst`` as a ``MDNode`` of the<br>
-``MD_prof`` kind. The first operator is always a ``MDString`` node with the<br>
-string "branch_weights". Number of operators depends on the terminator type.<br>
+Branch Weight Metadata represents branch weights as its likeliness to be taken<br>
+(see :doc:`BlockFrequencyTerminology`). Metadata is assigned to the<br>
+``TerminatorInst`` as a ``MDNode`` of the ``MD_prof`` kind. The first operator<br>
+is always a ``MDString`` node with the string "branch_weights". Number of<br>
+operators depends on the terminator type.<br>
<br>
Branch weights might be fetch from the profiling file, or generated based on<br>
`__builtin_expect`_ instruction.<br>
<br>
Modified: llvm/trunk/docs/index.rst<br>
URL: <a href="http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/index.rst?rev=206086&r1=206085&r2=206086&view=diff" target="_blank">http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/index.rst?rev=206086&r1=206085&r2=206086&view=diff</a><br>
==============================================================================<br>
--- llvm/trunk/docs/index.rst (original)<br>
+++ llvm/trunk/docs/index.rst Fri Apr 11 18:21:07 2014<br>
@@ -215,6 +215,7 @@ For API clients and LLVM developers.<br>
<br>
AliasAnalysis<br>
BitCodeFormat<br>
+ BlockFrequencyTerminology<br>
BranchWeightMetadata<br>
Bugpoint<br>
CodeGenerator<br>
@@ -298,6 +299,10 @@ For API clients and LLVM developers.<br>
:doc:`BranchWeightMetadata`<br>
Provides information about Branch Prediction Information.<br>
<br>
+:doc:`BlockFrequencyTerminology`<br>
+ Provides information about terminology used in the ``BlockFrequencyInfo``<br>
+ analysis pass.<br>
+<br>
:doc:`SegmentedStacks`<br>
This document describes segmented stacks and how they are used in LLVM.<br>
<br>
<br>
<br>
_______________________________________________<br>
llvm-commits mailing list<br>
<a href="mailto:llvm-commits@cs.uiuc.edu">llvm-commits@cs.uiuc.edu</a><br>
<a href="http://lists.cs.uiuc.edu/mailman/listinfo/llvm-commits" target="_blank">http://lists.cs.uiuc.edu/mailman/listinfo/llvm-commits</a><br>
</blockquote></div><br></div>