From: Jakub Staszak Date: Wed, 6 Jul 2011 18:31:02 +0000 (+0000) Subject: Add documenation about "branch_weight" metadata and __builtin_expect instruction X-Git-Url: http://demsky.eecs.uci.edu/git/?a=commitdiff_plain;h=29057766f741edc16d0faa70d4babec700b254e4;p=oota-llvm.git Add documenation about "branch_weight" metadata and __builtin_expect instruction git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@134517 91177308-0d34-0410-b5e6-96231b3b80d8 --- diff --git a/docs/BranchWeightMetadata.html b/docs/BranchWeightMetadata.html new file mode 100644 index 00000000000..6106e6ffac7 --- /dev/null +++ b/docs/BranchWeightMetadata.html @@ -0,0 +1,163 @@ + + + + LLVM Branch Weight Metadata + + + + +

+ LLVM Branch Weight Metadata +

+ +
    +
  1. Introduction
    2. +
  2. Supported Instructions
    3. +
  3. Built-in "expect" Instruction
    4. +
  4. CFG Modifications
    5. +
+ +
+

Written by Jakub Staszak

+
+ +

+ 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.

+
+
+ 
+!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).

+
+
+ 
+!0 = metadata !{
+  metadata !"branch_weights",
+  i32 <DEFAULT_BRANCH_WEIGHT>
+  [ , i32 <CASE_BRANCH_WEIGHT> ... ]
+}
+
+
+ +

IndirectBrInst

+
+

Branch weights are assign to every destination.

+
+
+ 
+!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.

+
+
+ +

+ 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 comparision 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: +

+
+
+ 
+  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.

+
+
+ 
+  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.

+
+ +
+
+ Valid CSS + Valid HTML 4.01 + + Jakub Staszak
+ LLVM Compiler Infrastructure
+
+ + + diff --git a/docs/index.html b/docs/index.html index f9ebaa196ef..fa9f1fae0fc 100644 --- a/docs/index.html +++ b/docs/index.html @@ -164,6 +164,7 @@ understand how to use the libraries produced when LLVM is compiled.
  • How To Release LLVM To The Public - This is a guide to preparing LLVM releases. Most developers can ignore it.
    • +
  • Doxygen generated documentation (classes) @@ -239,6 +240,10 @@ programs with link-time optimization on Linux.
  • The GDB JIT interface - How to debug JITed code with GDB.
    • + +
  • Branch Weight Metadata - Provides +information about Branch Prediction Information.
    • +