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