[llvm] r206086 - blockfreq: Document BlockFrequencyInfo terminology

[Sean Silva]

Neat! It's not everyday that we get a whole new document!

-- Sean Silva


On Fri, Apr 11, 2014 at 7:21 PM, Duncan P. N. Exon Smith <
dexonsmith at apple.com> wrote:

> 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.
>
>
>
> _______________________________________________
> llvm-commits mailing list
> llvm-commits at cs.uiuc.edu
> http://lists.cs.uiuc.edu/mailman/listinfo/llvm-commits
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20140411/d46e1e2d/attachment.html>