[llvm-commits] [llvm] r158810 - in /llvm/trunk/docs: BranchWeightMetadata.html BranchWeightMetadata.rst subsystems.rst
Bill Wendling
isanbard at gmail.com
Wed Jun 20 03:17:46 PDT 2012
Author: void
Date: Wed Jun 20 05:17:46 2012
New Revision: 158810
URL: http://llvm.org/viewvc/llvm-project?rev=158810&view=rev
Log:
Sphinxify BranchWeightMetadata document.
Added:
llvm/trunk/docs/BranchWeightMetadata.rst
Removed:
llvm/trunk/docs/BranchWeightMetadata.html
Modified:
llvm/trunk/docs/subsystems.rst
Removed: llvm/trunk/docs/BranchWeightMetadata.html
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/BranchWeightMetadata.html?rev=158809&view=auto
==============================================================================
--- llvm/trunk/docs/BranchWeightMetadata.html (original)
+++ llvm/trunk/docs/BranchWeightMetadata.html (removed)
@@ -1,164 +0,0 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
- "http://www.w3.org/TR/html4/strict.dtd">
-<html>
-<head>
- <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
- <title>LLVM Branch Weight Metadata</title>
- <link rel="stylesheet" href="_static/llvm.css" type="text/css">
-</head>
-<body>
-
-<h1>
- LLVM Branch Weight Metadata
-</h1>
-
-<ol>
- <li><a href="#introduction">Introduction</a></li>
- <li><a href="#supported_instructions">Supported Instructions</a></li>
- <li><a href="#builtin_expect">Built-in "expect" Instruction </a></li>
- <li><a href="#cfg_modifications">CFG Modifications</a></li>
-</ol>
-
-<div class="doc_author">
- <p>Written by <a href="mailto:jstaszak at apple.com">Jakub Staszak</a></p>
-</div>
-
-<h2>
- <a name="introduction">Introduction</a>
-</h2>
-<div>
-<p>Branch Weight Metadata represents branch weights as its likeliness to
-be taken. Metadata is assigned to the <tt>TerminatorInst</tt> as a
-<tt>MDNode</tt> of the <tt>MD_prof</tt> kind. The first operator is always a
-<tt>MDString</tt> node with the string "branch_weights". Number of operators
-depends on the terminator type.</p>
-
-<p>Branch weights might be fetch from the profiling file, or generated based on
-<a href="#builtin_expect"><tt>__builtin_expect</tt></a> instruction.
-</p>
-
-<p>All weights are represented as an unsigned 32-bit values, where higher value
-indicates greater chance to be taken.</p>
-</div>
-
-<h2>
- <a name="supported_instructions">Supported Instructions</a>
-</h2>
-
-<div>
- <h4>BranchInst</h4>
- <div>
- <p>Metadata is only assign to the conditional branches. There are two extra
- operarands, for the true and the false branch.</p>
- </div>
- <div class="doc_code">
- <pre>
-!0 = metadata !{
- metadata !"branch_weights",
- i32 <TRUE_BRANCH_WEIGHT>,
- i32 <FALSE_BRANCH_WEIGHT>
-}
- </pre>
- </div>
-
- <h4>SwitchInst</h4>
- <div>
- <p>Branch weights are assign to every case (including <tt>default</tt> case
- which is always case #0).</p>
- </div>
- <div class="doc_code">
- <pre>
-!0 = metadata !{
- metadata !"branch_weights",
- i32 <DEFAULT_BRANCH_WEIGHT>
- [ , i32 <CASE_BRANCH_WEIGHT> ... ]
-}
- </pre>
- </div>
-
- <h4>IndirectBrInst</h4>
- <div>
- <p>Branch weights are assign to every destination.</p>
- </div>
- <div class="doc_code">
- <pre>
-!0 = metadata !{
- metadata !"branch_weights",
- i32 <LABEL_BRANCH_WEIGHT>
- [ , i32 <LABEL_BRANCH_WEIGHT> ... ]
-}
- </pre>
- </div>
-
- <h4>Other</h4>
- <div>
- <p>Other terminator instructions are not allowed to contain Branch Weight
- Metadata.</p>
- </div>
-</div>
-
-<h2>
- <a name="builtin_expect">Built-in "expect" Instructions</a>
-</h2>
-<div>
- <p><tt>__builtin_expect(long exp, long c)</tt> instruction provides branch
- prediction information. The return value is the value of <tt>exp</tt>.</p>
-
- <p>It is especially useful in conditional statements. Currently Clang supports
- two conditional statements:
- </p>
- <h4><tt>if</tt> statement</h4>
- <div>
- <p>The <tt>exp</tt> parameter is the condition. The <tt>c</tt> parameter is
- the expected comparison value. If it is equal to 1 (true), the condition is
- likely to be true, in other case condition is likely to be false. For example:
- </p>
- </div>
- <div class="doc_code">
- <pre>
- if (__builtin_expect(x > 0, 1)) {
- // This block is likely to be taken.
- }
- </pre>
- </div>
-
- <h4><tt>switch</tt> statement</h4>
- <div>
- <p>The <tt>exp</tt> parameter is the value. The <tt>c</tt> parameter is the
- expected value. If the expected value doesn't show on the cases list, the
- <tt>default</tt> case is assumed to be likely taken.</p>
- </div>
- <div class="doc_code">
- <pre>
- switch (__builtin_expect(x, 5)) {
- default: break;
- case 0: // ...
- case 3: // ...
- case 5: // This case is likely to be taken.
- }
- </pre>
- </div>
-</div>
-
-<h2>
- <a name="cfg_modifications">CFG Modifications</a>
-</h2>
-<div>
-<p>Branch Weight Metatada is not proof against CFG changes. If terminator
-operands' are changed some action should be taken. In other case some
-misoptimizations may occur due to incorrent branch prediction information.</p>
-</div>
-
-<hr>
-<address>
- <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
- src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
- <a href="http://validator.w3.org/check/referer"><img
- src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
-
- <a href="mailto:jstaszak at apple.com">Jakub Staszak</a><br>
- <a href="http://llvm.org/">LLVM Compiler Infrastructure</a><br>
-</address>
-
-</body>
-</html>
Added: llvm/trunk/docs/BranchWeightMetadata.rst
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/BranchWeightMetadata.rst?rev=158810&view=auto
==============================================================================
--- llvm/trunk/docs/BranchWeightMetadata.rst (added)
+++ llvm/trunk/docs/BranchWeightMetadata.rst Wed Jun 20 05:17:46 2012
@@ -0,0 +1,118 @@
+.. _branch_weight:
+
+===========================
+LLVM Branch Weight Metadata
+===========================
+
+.. contents::
+ :local:
+
+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 weights might be fetch from the profiling file, or generated based on
+`__builtin_expect`_ instruction.
+
+All weights are represented as an unsigned 32-bit values, where higher value
+indicates greater chance to be taken.
+
+Supported Instructions
+======================
+
+``BranchInst``
+^^^^^^^^^^^^^^
+
+Metadata is only assign to the conditional branches. There are two extra
+operarands, for the true and the false branch.
+
+.. code-block:: llvm
+
+ !0 = metadata !{
+ metadata !"branch_weights",
+ i32 <TRUE_BRANCH_WEIGHT>,
+ i32 <FALSE_BRANCH_WEIGHT>
+ }
+
+``SwitchInst``
+^^^^^^^^^^^^^^
+
+Branch weights are assign to every case (including ``default`` case which is
+always case #0).
+
+.. code-block:: llvm
+
+ !0 = metadata !{
+ metadata !"branch_weights",
+ i32 <DEFAULT_BRANCH_WEIGHT>
+ [ , i32 <CASE_BRANCH_WEIGHT> ... ]
+ }
+
+``IndirectBrInst``
+^^^^^^^^^^^^^^^^^^
+
+Branch weights are assign to every destination.
+
+.. code-block:: llvm
+
+ !0 = metadata !{
+ metadata !"branch_weights",
+ i32 <LABEL_BRANCH_WEIGHT>
+ [ , i32 <LABEL_BRANCH_WEIGHT> ... ]
+ }
+
+Other
+^^^^^
+
+Other terminator instructions are not allowed to contain Branch Weight Metadata.
+
+.. _\__builtin_expect:
+
+Built-in ``expect`` Instructions
+================================
+
+``__builtin_expect(long exp, long c)`` instruction provides branch prediction
+information. The return value is the value of ``exp``.
+
+It is especially useful in conditional statements. Currently Clang supports two
+conditional statements:
+
+``if`` statement
+^^^^^^^^^^^^^^^^
+
+The ``exp`` parameter is the condition. The ``c`` parameter is the expected
+comparison value. If it is equal to 1 (true), the condition is likely to be
+true, in other case condition is likely to be false. For example:
+
+.. code-block:: c++
+
+ if (__builtin_expect(x > 0, 1)) {
+ // This block is likely to be taken.
+ }
+
+``switch`` statement
+^^^^^^^^^^^^^^^^^^^^
+
+The ``exp`` parameter is the value. The ``c`` parameter is the expected
+value. If the expected value doesn't show on the cases list, the ``default``
+case is assumed to be likely taken.
+
+.. code-block:: c++
+
+ switch (__builtin_expect(x, 5)) {
+ default: break;
+ case 0: // ...
+ case 3: // ...
+ case 5: // This case is likely to be taken.
+ }
+
+CFG Modifications
+=================
+
+Branch Weight Metatada is not proof against CFG changes. If terminator operands'
+are changed some action should be taken. In other case some misoptimizations may
+occur due to incorrent branch prediction information.
Modified: llvm/trunk/docs/subsystems.rst
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/subsystems.rst?rev=158810&r1=158809&r2=158810&view=diff
==============================================================================
--- llvm/trunk/docs/subsystems.rst (original)
+++ llvm/trunk/docs/subsystems.rst Wed Jun 20 05:17:46 2012
@@ -7,6 +7,7 @@
:hidden:
AliasAnalysis
+ BranchWeightMetadata
LinkTimeOptimization
* `Writing an LLVM Pass <WritingAnLLVMPass.html>`_
@@ -75,6 +76,6 @@
How to debug JITed code with GDB.
-* `Branch Weight Metadata <BranchWeightMetadata.html>`_
+* :ref:`branch_weight`
Provides information about Branch Prediction Information.
More information about the llvm-commits
mailing list