From c1d3c66cb8a973577a4e1758d9eb6fa6619eac52 Mon Sep 17 00:00:00 2001 From: Daniel Berlin Date: Fri, 10 Mar 2017 20:44:39 +0000 Subject: [PATCH] Fix all these headers to properly mark the doxygen comments. git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@297505 91177308-0d34-0410-b5e6-96231b3b80d8 --- include/llvm/Support/DebugCounter.h | 63 ++++----- include/llvm/Transforms/Utils/MemorySSA.h | 122 +++++++++--------- include/llvm/Transforms/Utils/PredicateInfo.h | 81 ++++++------ 3 files changed, 134 insertions(+), 132 deletions(-) diff --git a/include/llvm/Support/DebugCounter.h b/include/llvm/Support/DebugCounter.h index ee56ecf39ca..9691b80fce8 100644 --- a/include/llvm/Support/DebugCounter.h +++ b/include/llvm/Support/DebugCounter.h @@ -6,37 +6,40 @@ // License. See LICENSE.TXT for details. // //===----------------------------------------------------------------------===// -// \file This file provides an implementation of debug counters. Debug counters -// are a tool that let you narrow down a miscompilation to a specific thing -// happening. To give a use case: Imagine you have a file, very large, and you -// are trying to understand the minimal transformation that breaks it. Bugpoint -// and bisection is often helpful here in narrowing it down to a specific pass, -// but it's still a very large file, and a very complicated pass to try to -// debug. That is where debug counting steps in. You can instrument the pass -// with a debug counter before it does a certain thing, and depending on the -// counts, it will either execute that thing or not. The debug counter itself -// consists of a skip and a count. Skip is the number of times shouldExecute -// needs to be called before it returns true. Count is the number of times to -// return true once Skip is 0. So a skip=47, count=2 ,would skip the first 47 -// executions by returning false from shouldExecute, then execute twice, and -// then return false again. -// Note that a counter set to a negative number will always execute. - -// For a concrete example, during predicateinfo creation, the renaming pass -// replaces each use with a renamed use. +/// \file +/// \brief This file provides an implementation of debug counters. Debug counters +/// are a tool that let you narrow down a miscompilation to a specific thing +/// happening. /// -// If I use DEBUG_COUNTER to create a counter called "predicateinfo", and -// variable name RenameCounter, and then instrument this renaming with a debug -// counter, like so: -// -// if (!DebugCounter::shouldExecute(RenameCounter) -// -// -// Now I can, from the command line, make it rename or not rename certain uses -// by setting the skip and count. -// So for example -// bin/opt -debug-counter=predicateinfo-skip=47,predicateinfo-count=1 -// will skip renaming the first 47 uses, then rename one, then skip the rest. +/// To give a use case: Imagine you have a file, very large, and you +/// are trying to understand the minimal transformation that breaks it. Bugpoint +/// and bisection is often helpful here in narrowing it down to a specific pass, +/// but it's still a very large file, and a very complicated pass to try to +/// debug. That is where debug counting steps in. You can instrument the pass +/// with a debug counter before it does a certain thing, and depending on the +/// counts, it will either execute that thing or not. The debug counter itself +/// consists of a skip and a count. Skip is the number of times shouldExecute +/// needs to be called before it returns true. Count is the number of times to +/// return true once Skip is 0. So a skip=47, count=2 ,would skip the first 47 +/// executions by returning false from shouldExecute, then execute twice, and +/// then return false again. +/// Note that a counter set to a negative number will always execute. +/// For a concrete example, during predicateinfo creation, the renaming pass +/// replaces each use with a renamed use. +//// +/// If I use DEBUG_COUNTER to create a counter called "predicateinfo", and +/// variable name RenameCounter, and then instrument this renaming with a debug +/// counter, like so: +/// +/// if (!DebugCounter::shouldExecute(RenameCounter) +/// +/// +/// Now I can, from the command line, make it rename or not rename certain uses +/// by setting the skip and count. +/// So for example +/// bin/opt -debug-counter=predicateinfo-skip=47,predicateinfo-count=1 +/// will skip renaming the first 47 uses, then rename one, then skip the rest. +//===----------------------------------------------------------------------===// #ifndef LLVM_SUPPORT_DEBUGCOUNTER_H #define LLVM_SUPPORT_DEBUGCOUNTER_H diff --git a/include/llvm/Transforms/Utils/MemorySSA.h b/include/llvm/Transforms/Utils/MemorySSA.h index 7ef18b43fa7..50e9186791a 100644 --- a/include/llvm/Transforms/Utils/MemorySSA.h +++ b/include/llvm/Transforms/Utils/MemorySSA.h @@ -6,67 +6,67 @@ // License. See LICENSE.TXT for details. // //===----------------------------------------------------------------------===// -// -// \file -// \brief This file exposes an interface to building/using memory SSA to -// walk memory instructions using a use/def graph. -// -// Memory SSA class builds an SSA form that links together memory access -// instructions such as loads, stores, atomics, and calls. Additionally, it does -// a trivial form of "heap versioning" Every time the memory state changes in -// the program, we generate a new heap version. It generates MemoryDef/Uses/Phis -// that are overlayed on top of the existing instructions. -// -// As a trivial example, -// define i32 @main() #0 { -// entry: -// %call = call noalias i8* @_Znwm(i64 4) #2 -// %0 = bitcast i8* %call to i32* -// %call1 = call noalias i8* @_Znwm(i64 4) #2 -// %1 = bitcast i8* %call1 to i32* -// store i32 5, i32* %0, align 4 -// store i32 7, i32* %1, align 4 -// %2 = load i32* %0, align 4 -// %3 = load i32* %1, align 4 -// %add = add nsw i32 %2, %3 -// ret i32 %add -// } -// -// Will become -// define i32 @main() #0 { -// entry: -// ; 1 = MemoryDef(0) -// %call = call noalias i8* @_Znwm(i64 4) #3 -// %2 = bitcast i8* %call to i32* -// ; 2 = MemoryDef(1) -// %call1 = call noalias i8* @_Znwm(i64 4) #3 -// %4 = bitcast i8* %call1 to i32* -// ; 3 = MemoryDef(2) -// store i32 5, i32* %2, align 4 -// ; 4 = MemoryDef(3) -// store i32 7, i32* %4, align 4 -// ; MemoryUse(3) -// %7 = load i32* %2, align 4 -// ; MemoryUse(4) -// %8 = load i32* %4, align 4 -// %add = add nsw i32 %7, %8 -// ret i32 %add -// } -// -// Given this form, all the stores that could ever effect the load at %8 can be -// gotten by using the MemoryUse associated with it, and walking from use to def -// until you hit the top of the function. -// -// Each def also has a list of users associated with it, so you can walk from -// both def to users, and users to defs. Note that we disambiguate MemoryUses, -// but not the RHS of MemoryDefs. You can see this above at %7, which would -// otherwise be a MemoryUse(4). Being disambiguated means that for a given -// store, all the MemoryUses on its use lists are may-aliases of that store (but -// the MemoryDefs on its use list may not be). -// -// MemoryDefs are not disambiguated because it would require multiple reaching -// definitions, which would require multiple phis, and multiple memoryaccesses -// per instruction. +/// +/// \file +/// \brief This file exposes an interface to building/using memory SSA to +/// walk memory instructions using a use/def graph. +/// +/// Memory SSA class builds an SSA form that links together memory access +/// instructions such as loads, stores, atomics, and calls. Additionally, it does +/// a trivial form of "heap versioning" Every time the memory state changes in +/// the program, we generate a new heap version. It generates MemoryDef/Uses/Phis +/// that are overlayed on top of the existing instructions. +/// +/// As a trivial example, +/// define i32 @main() #0 { +/// entry: +/// %call = call noalias i8* @_Znwm(i64 4) #2 +/// %0 = bitcast i8* %call to i32* +/// %call1 = call noalias i8* @_Znwm(i64 4) #2 +/// %1 = bitcast i8* %call1 to i32* +/// store i32 5, i32* %0, align 4 +/// store i32 7, i32* %1, align 4 +/// %2 = load i32* %0, align 4 +/// %3 = load i32* %1, align 4 +/// %add = add nsw i32 %2, %3 +/// ret i32 %add +/// } +/// +/// Will become +/// define i32 @main() #0 { +/// entry: +/// ; 1 = MemoryDef(0) +/// %call = call noalias i8* @_Znwm(i64 4) #3 +/// %2 = bitcast i8* %call to i32* +/// ; 2 = MemoryDef(1) +/// %call1 = call noalias i8* @_Znwm(i64 4) #3 +/// %4 = bitcast i8* %call1 to i32* +/// ; 3 = MemoryDef(2) +/// store i32 5, i32* %2, align 4 +/// ; 4 = MemoryDef(3) +/// store i32 7, i32* %4, align 4 +/// ; MemoryUse(3) +/// %7 = load i32* %2, align 4 +/// ; MemoryUse(4) +/// %8 = load i32* %4, align 4 +/// %add = add nsw i32 %7, %8 +/// ret i32 %add +/// } +/// +/// Given this form, all the stores that could ever effect the load at %8 can be +/// gotten by using the MemoryUse associated with it, and walking from use to def +/// until you hit the top of the function. +/// +/// Each def also has a list of users associated with it, so you can walk from +/// both def to users, and users to defs. Note that we disambiguate MemoryUses, +/// but not the RHS of MemoryDefs. You can see this above at %7, which would +/// otherwise be a MemoryUse(4). Being disambiguated means that for a given +/// store, all the MemoryUses on its use lists are may-aliases of that store (but +/// the MemoryDefs on its use list may not be). +/// +/// MemoryDefs are not disambiguated because it would require multiple reaching +/// definitions, which would require multiple phis, and multiple memoryaccesses +/// per instruction. //===----------------------------------------------------------------------===// #ifndef LLVM_TRANSFORMS_UTILS_MEMORYSSA_H diff --git a/include/llvm/Transforms/Utils/PredicateInfo.h b/include/llvm/Transforms/Utils/PredicateInfo.h index 5e242820d23..1322c686eb9 100644 --- a/include/llvm/Transforms/Utils/PredicateInfo.h +++ b/include/llvm/Transforms/Utils/PredicateInfo.h @@ -6,47 +6,46 @@ // License. See LICENSE.TXT for details. // //===----------------------------------------------------------------------===// -// -// \file -// \brief -// -// This file implements the PredicateInfo analysis, which creates an Extended -// SSA form for operations used in branch comparisons and llvm.assume -// comparisons. Copies of these operations are inserted into the true/false -// edge (and after assumes), and information attached to the copies. All uses -// of the original operation in blocks dominated by the true/false edge (and -// assume), are replaced with uses of the copies. This enables passes to easily -// and sparsely propagate condition based info into the operations that may be -// affected. -// -// Example: -// %cmp = icmp eq i32 %x, 50 -// br i1 %cmp, label %true, label %false -// true: -// ret i32 %x -// false: -// ret i32 1 -// -// will become -// -// %cmp = icmp eq i32, %x, 50 -// br i1 %cmp, label %true, label %false -// true: -// %x.0 = call @llvm.ssa_copy.i32(i32 %x) -// ret i32 %x.0 -// false: -// ret i32 1 -// -// Using getPredicateInfoFor on x.0 will give you the comparison it is -// dominated by (the icmp), and that you are located in the true edge of that -// comparison, which tells you x.0 is 50. -// -// In order to reduce the number of copies inserted, predicateinfo is only -// inserted where it would actually be live. This means if there are no uses of -// an operation dominated by the branch edges, or by an assume, the associated -// predicate info is never inserted. -// -// +/// +/// \file +/// \brief This file implements the PredicateInfo analysis, which creates an Extended +/// SSA form for operations used in branch comparisons and llvm.assume +/// comparisons. +/// +/// Copies of these operations are inserted into the true/false edge (and after +/// assumes), and information attached to the copies. All uses of the original +/// operation in blocks dominated by the true/false edge (and assume), are +/// replaced with uses of the copies. This enables passes to easily and sparsely +/// propagate condition based info into the operations that may be affected. +/// +/// Example: +/// %cmp = icmp eq i32 %x, 50 +/// br i1 %cmp, label %true, label %false +/// true: +/// ret i32 %x +/// false: +/// ret i32 1 +/// +/// will become +/// +/// %cmp = icmp eq i32, %x, 50 +/// br i1 %cmp, label %true, label %false +/// true: +/// %x.0 = call @llvm.ssa_copy.i32(i32 %x) +/// ret i32 %x.0 +/// false: +/// ret i32 1 +/// +/// Using getPredicateInfoFor on x.0 will give you the comparison it is +/// dominated by (the icmp), and that you are located in the true edge of that +/// comparison, which tells you x.0 is 50. +/// +/// In order to reduce the number of copies inserted, predicateinfo is only +/// inserted where it would actually be live. This means if there are no uses of +/// an operation dominated by the branch edges, or by an assume, the associated +/// predicate info is never inserted. +/// +/// //===----------------------------------------------------------------------===// #ifndef LLVM_TRANSFORMS_UTILS_PREDICATEINFO_H -- 2.50.1