Doxygenize the documentation comments
There were many // comment used to document classes, functions etc. but
those are not picked up by doxygen which expects /// comments. This
converts many comments from // to /// in order to improve the generated
documentation.
BUG=
R=jvoung@chromium.org, kschimpf@google.com
Review URL: https://codereview.chromium.org/1216963007.
diff --git a/src/IceInst.h b/src/IceInst.h
index 7aad054..cfa6dd3 100644
--- a/src/IceInst.h
+++ b/src/IceInst.h
@@ -6,11 +6,12 @@
// License. See LICENSE.TXT for details.
//
//===----------------------------------------------------------------------===//
-//
-// This file declares the Inst class and its target-independent
-// subclasses, which represent the high-level Vanilla ICE instructions
-// and map roughly 1:1 to LLVM instructions.
-//
+///
+/// \file
+/// This file declares the Inst class and its target-independent
+/// subclasses, which represent the high-level Vanilla ICE instructions
+/// and map roughly 1:1 to LLVM instructions.
+///
//===----------------------------------------------------------------------===//
#ifndef SUBZERO_SRC_ICEINST_H
@@ -31,10 +32,10 @@
namespace Ice {
-// Base instruction class for ICE. Inst has two subclasses:
-// InstHighLevel and InstTarget. High-level ICE instructions inherit
-// from InstHighLevel, and low-level (target-specific) ICE
-// instructions inherit from InstTarget.
+/// Base instruction class for ICE. Inst has two subclasses:
+/// InstHighLevel and InstTarget. High-level ICE instructions inherit
+/// from InstHighLevel, and low-level (target-specific) ICE
+/// instructions inherit from InstTarget.
class Inst : public llvm::ilist_node<Inst> {
Inst() = delete;
Inst(const Inst &) = delete;
@@ -105,8 +106,8 @@
bool isLastUse(const Operand *Src) const;
void spliceLivenessInfo(Inst *OrigInst, Inst *SpliceAssn);
- // Returns a list of out-edges corresponding to a terminator
- // instruction, which is the last instruction of the block.
+ /// Returns a list of out-edges corresponding to a terminator
+ /// instruction, which is the last instruction of the block.
virtual NodeList getTerminatorEdges() const {
// All valid terminator instructions override this method. For
// the default implementation, we assert in case some CfgNode
@@ -116,10 +117,10 @@
return NodeList();
}
virtual bool isUnconditionalBranch() const { return false; }
- // If the instruction is a branch-type instruction with OldNode as a
- // target, repoint it to NewNode and return true, otherwise return
- // false. Only repoint one instance, even if the instruction has
- // multiple instances of OldNode as a target.
+ /// If the instruction is a branch-type instruction with OldNode as a
+ /// target, repoint it to NewNode and return true, otherwise return
+ /// false. Only repoint one instance, even if the instruction has
+ /// multiple instances of OldNode as a target.
virtual bool repointEdge(CfgNode *OldNode, CfgNode *NewNode) {
(void)OldNode;
(void)NewNode;
@@ -129,19 +130,19 @@
virtual bool isSimpleAssign() const { return false; }
void livenessLightweight(Cfg *Func, LivenessBV &Live);
- // Calculates liveness for this instruction. Returns true if this
- // instruction is (tentatively) still live and should be retained,
- // and false if this instruction is (tentatively) dead and should be
- // deleted. The decision is tentative until the liveness dataflow
- // algorithm has converged, and then a separate pass permanently
- // deletes dead instructions.
+ /// Calculates liveness for this instruction. Returns true if this
+ /// instruction is (tentatively) still live and should be retained,
+ /// and false if this instruction is (tentatively) dead and should be
+ /// deleted. The decision is tentative until the liveness dataflow
+ /// algorithm has converged, and then a separate pass permanently
+ /// deletes dead instructions.
bool liveness(InstNumberT InstNumber, LivenessBV &Live, Liveness *Liveness,
LiveBeginEndMap *LiveBegin, LiveBeginEndMap *LiveEnd);
- // Get the number of native instructions that this instruction
- // ultimately emits. By default, high-level instructions don't
- // result in any native instructions, and a target-specific
- // instruction results in a single native instruction.
+ /// Get the number of native instructions that this instruction
+ /// ultimately emits. By default, high-level instructions don't
+ /// result in any native instructions, and a target-specific
+ /// instruction results in a single native instruction.
virtual uint32_t getEmitInstCount() const { return 0; }
// TODO(stichnot): Change Inst back to abstract once the g++ build
// issue is fixed. llvm::ilist<Ice::Inst> doesn't work under g++
@@ -179,26 +180,26 @@
LiveRangesEnded |= (((LREndedBits)1u) << VarIndex);
}
void resetLastUses() { LiveRangesEnded = 0; }
- // The destroy() method lets the instruction cleanly release any
- // memory that was allocated via the Cfg's allocator.
+ /// The destroy() method lets the instruction cleanly release any
+ /// memory that was allocated via the Cfg's allocator.
virtual void destroy(Cfg *Func) { Func->deallocateArrayOf<Operand *>(Srcs); }
const InstKind Kind;
- // Number is the instruction number for describing live ranges.
+ /// Number is the instruction number for describing live ranges.
InstNumberT Number;
- // Deleted means irrevocably deleted.
+ /// Deleted means irrevocably deleted.
bool Deleted = false;
- // Dead means one of two things depending on context: (1) pending
- // deletion after liveness analysis converges, or (2) marked for
- // deletion during lowering due to a folded bool operation.
+ /// Dead means one of two things depending on context: (1) pending
+ /// deletion after liveness analysis converges, or (2) marked for
+ /// deletion during lowering due to a folded bool operation.
bool Dead = false;
- // HasSideEffects means the instruction is something like a function
- // call or a volatile load that can't be removed even if its Dest
- // variable is not live.
+ /// HasSideEffects means the instruction is something like a function
+ /// call or a volatile load that can't be removed even if its Dest
+ /// variable is not live.
bool HasSideEffects = false;
- // IsDestNonKillable means that liveness analysis shouldn't consider
- // this instruction to kill the Dest variable. This is used when
- // lowering produces two assignments to the same variable.
+ /// IsDestNonKillable means that liveness analysis shouldn't consider
+ /// this instruction to kill the Dest variable. This is used when
+ /// lowering produces two assignments to the same variable.
bool IsDestNonKillable = false;
Variable *Dest;
@@ -206,15 +207,15 @@
SizeT NumSrcs = 0;
Operand **Srcs;
- // LiveRangesEnded marks which Variables' live ranges end in this
- // instruction. An instruction can have an arbitrary number of
- // source operands (e.g. a call instruction), and each source
- // operand can contain 0 or 1 Variable (and target-specific operands
- // could contain more than 1 Variable). All the variables in an
- // instruction are conceptually flattened and each variable is
- // mapped to one bit position of the LiveRangesEnded bit vector.
- // Only the first CHAR_BIT * sizeof(LREndedBits) variables are
- // tracked this way.
+ /// LiveRangesEnded marks which Variables' live ranges end in this
+ /// instruction. An instruction can have an arbitrary number of
+ /// source operands (e.g. a call instruction), and each source
+ /// operand can contain 0 or 1 Variable (and target-specific operands
+ /// could contain more than 1 Variable). All the variables in an
+ /// instruction are conceptually flattened and each variable is
+ /// mapped to one bit position of the LiveRangesEnded bit vector.
+ /// Only the first CHAR_BIT * sizeof(LREndedBits) variables are
+ /// tracked this way.
typedef uint32_t LREndedBits; // only first 32 src operands tracked, sorry
LREndedBits LiveRangesEnded;
};
@@ -235,9 +236,9 @@
}
};
-// Alloca instruction. This captures the size in bytes as getSrc(0),
-// and the required alignment in bytes. The alignment must be either
-// 0 (no alignment required) or a power of 2.
+/// Alloca instruction. This captures the size in bytes as getSrc(0),
+/// and the required alignment in bytes. The alignment must be either
+/// 0 (no alignment required) or a power of 2.
class InstAlloca : public InstHighLevel {
InstAlloca() = delete;
InstAlloca(const InstAlloca &) = delete;
@@ -261,8 +262,8 @@
const uint32_t AlignInBytes;
};
-// Binary arithmetic instruction. The source operands are captured in
-// getSrc(0) and getSrc(1).
+/// Binary arithmetic instruction. The source operands are captured in
+/// getSrc(0) and getSrc(1).
class InstArithmetic : public InstHighLevel {
InstArithmetic() = delete;
InstArithmetic(const InstArithmetic &) = delete;
@@ -296,12 +297,12 @@
const OpKind Op;
};
-// Assignment instruction. The source operand is captured in
-// getSrc(0). This is not part of the LLVM bitcode, but is a useful
-// abstraction for some of the lowering. E.g., if Phi instruction
-// lowering happens before target lowering, or for representing an
-// Inttoptr instruction, or as an intermediate step for lowering a
-// Load instruction.
+/// Assignment instruction. The source operand is captured in
+/// getSrc(0). This is not part of the LLVM bitcode, but is a useful
+/// abstraction for some of the lowering. E.g., if Phi instruction
+/// lowering happens before target lowering, or for representing an
+/// Inttoptr instruction, or as an intermediate step for lowering a
+/// Load instruction.
class InstAssign : public InstHighLevel {
InstAssign() = delete;
InstAssign(const InstAssign &) = delete;
@@ -319,22 +320,22 @@
InstAssign(Cfg *Func, Variable *Dest, Operand *Source);
};
-// Branch instruction. This represents both conditional and
-// unconditional branches.
+/// Branch instruction. This represents both conditional and
+/// unconditional branches.
class InstBr : public InstHighLevel {
InstBr() = delete;
InstBr(const InstBr &) = delete;
InstBr &operator=(const InstBr &) = delete;
public:
- // Create a conditional branch. If TargetTrue==TargetFalse, it is
- // optimized to an unconditional branch.
+ /// Create a conditional branch. If TargetTrue==TargetFalse, it is
+ /// optimized to an unconditional branch.
static InstBr *create(Cfg *Func, Operand *Source, CfgNode *TargetTrue,
CfgNode *TargetFalse) {
return new (Func->allocate<InstBr>())
InstBr(Func, Source, TargetTrue, TargetFalse);
}
- // Create an unconditional branch.
+ /// Create an unconditional branch.
static InstBr *create(Cfg *Func, CfgNode *Target) {
return new (Func->allocate<InstBr>()) InstBr(Func, Target);
}
@@ -356,17 +357,17 @@
static bool classof(const Inst *Inst) { return Inst->getKind() == Br; }
private:
- // Conditional branch
+ /// Conditional branch
InstBr(Cfg *Func, Operand *Source, CfgNode *TargetTrue, CfgNode *TargetFalse);
- // Unconditional branch
+ /// Unconditional branch
InstBr(Cfg *Func, CfgNode *Target);
- CfgNode *TargetFalse; // Doubles as unconditional branch target
- CfgNode *TargetTrue; // nullptr if unconditional branch
+ CfgNode *TargetFalse; /// Doubles as unconditional branch target
+ CfgNode *TargetTrue; /// nullptr if unconditional branch
};
-// Call instruction. The call target is captured as getSrc(0), and
-// arg I is captured as getSrc(I+1).
+/// Call instruction. The call target is captured as getSrc(0), and
+/// arg I is captured as getSrc(I+1).
class InstCall : public InstHighLevel {
InstCall() = delete;
InstCall(const InstCall &) = delete;
@@ -375,9 +376,9 @@
public:
static InstCall *create(Cfg *Func, SizeT NumArgs, Variable *Dest,
Operand *CallTarget, bool HasTailCall) {
- // Set HasSideEffects to true so that the call instruction can't be
- // dead-code eliminated. IntrinsicCalls can override this if the
- // particular intrinsic is deletable and has no side-effects.
+ /// Set HasSideEffects to true so that the call instruction can't be
+ /// dead-code eliminated. IntrinsicCalls can override this if the
+ /// particular intrinsic is deletable and has no side-effects.
const bool HasSideEffects = true;
const InstKind Kind = Inst::Call;
return new (Func->allocate<InstCall>()) InstCall(
@@ -404,7 +405,7 @@
bool HasTailCall;
};
-// Cast instruction (a.k.a. conversion operation).
+/// Cast instruction (a.k.a. conversion operation).
class InstCast : public InstHighLevel {
InstCast() = delete;
InstCast(const InstCast &) = delete;
@@ -435,7 +436,7 @@
const OpKind CastKind;
};
-// ExtractElement instruction.
+/// ExtractElement instruction.
class InstExtractElement : public InstHighLevel {
InstExtractElement() = delete;
InstExtractElement(const InstExtractElement &) = delete;
@@ -458,8 +459,8 @@
Operand *Source2);
};
-// Floating-point comparison instruction. The source operands are
-// captured in getSrc(0) and getSrc(1).
+/// Floating-point comparison instruction. The source operands are
+/// captured in getSrc(0) and getSrc(1).
class InstFcmp : public InstHighLevel {
InstFcmp() = delete;
InstFcmp(const InstFcmp &) = delete;
@@ -489,8 +490,8 @@
const FCond Condition;
};
-// Integer comparison instruction. The source operands are captured
-// in getSrc(0) and getSrc(1).
+/// Integer comparison instruction. The source operands are captured
+/// in getSrc(0) and getSrc(1).
class InstIcmp : public InstHighLevel {
InstIcmp() = delete;
InstIcmp(const InstIcmp &) = delete;
@@ -520,7 +521,7 @@
const ICond Condition;
};
-// InsertElement instruction.
+/// InsertElement instruction.
class InstInsertElement : public InstHighLevel {
InstInsertElement() = delete;
InstInsertElement(const InstInsertElement &) = delete;
@@ -543,8 +544,8 @@
Operand *Source2, Operand *Source3);
};
-// Call to an intrinsic function. The call target is captured as getSrc(0),
-// and arg I is captured as getSrc(I+1).
+/// Call to an intrinsic function. The call target is captured as getSrc(0),
+/// and arg I is captured as getSrc(I+1).
class InstIntrinsicCall : public InstCall {
InstIntrinsicCall() = delete;
InstIntrinsicCall(const InstIntrinsicCall &) = delete;
@@ -573,7 +574,7 @@
const Intrinsics::IntrinsicInfo Info;
};
-// Load instruction. The source address is captured in getSrc(0).
+/// Load instruction. The source address is captured in getSrc(0).
class InstLoad : public InstHighLevel {
InstLoad() = delete;
InstLoad(const InstLoad &) = delete;
@@ -594,8 +595,8 @@
InstLoad(Cfg *Func, Variable *Dest, Operand *SourceAddr);
};
-// Phi instruction. For incoming edge I, the node is Labels[I] and
-// the Phi source operand is getSrc(I).
+/// Phi instruction. For incoming edge I, the node is Labels[I] and
+/// the Phi source operand is getSrc(I).
class InstPhi : public InstHighLevel {
InstPhi() = delete;
InstPhi(const InstPhi &) = delete;
@@ -621,15 +622,15 @@
Inst::destroy(Func);
}
- // Labels[] duplicates the InEdges[] information in the enclosing
- // CfgNode, but the Phi instruction is created before InEdges[]
- // is available, so it's more complicated to share the list.
+ /// Labels[] duplicates the InEdges[] information in the enclosing
+ /// CfgNode, but the Phi instruction is created before InEdges[]
+ /// is available, so it's more complicated to share the list.
CfgNode **Labels;
};
-// Ret instruction. The return value is captured in getSrc(0), but if
-// there is no return value (void-type function), then
-// getSrcSize()==0 and hasRetValue()==false.
+/// Ret instruction. The return value is captured in getSrc(0), but if
+/// there is no return value (void-type function), then
+/// getSrcSize()==0 and hasRetValue()==false.
class InstRet : public InstHighLevel {
InstRet() = delete;
InstRet(const InstRet &) = delete;
@@ -652,7 +653,7 @@
InstRet(Cfg *Func, Operand *RetValue);
};
-// Select instruction. The condition, true, and false operands are captured.
+/// Select instruction. The condition, true, and false operands are captured.
class InstSelect : public InstHighLevel {
InstSelect() = delete;
InstSelect(const InstSelect &) = delete;
@@ -675,8 +676,8 @@
Operand *Source2);
};
-// Store instruction. The address operand is captured, along with the
-// data operand to be stored into the address.
+/// Store instruction. The address operand is captured, along with the
+/// data operand to be stored into the address.
class InstStore : public InstHighLevel {
InstStore() = delete;
InstStore(const InstStore &) = delete;
@@ -700,8 +701,8 @@
InstStore(Cfg *Func, Operand *Data, Operand *Addr);
};
-// Switch instruction. The single source operand is captured as
-// getSrc(0).
+/// Switch instruction. The single source operand is captured as
+/// getSrc(0).
class InstSwitch : public InstHighLevel {
InstSwitch() = delete;
InstSwitch(const InstSwitch &) = delete;
@@ -739,13 +740,13 @@
}
CfgNode *LabelDefault;
- SizeT NumCases; // not including the default case
- uint64_t *Values; // size is NumCases
- CfgNode **Labels; // size is NumCases
+ SizeT NumCases; /// not including the default case
+ uint64_t *Values; /// size is NumCases
+ CfgNode **Labels; /// size is NumCases
};
-// Unreachable instruction. This is a terminator instruction with no
-// operands.
+/// Unreachable instruction. This is a terminator instruction with no
+/// operands.
class InstUnreachable : public InstHighLevel {
InstUnreachable() = delete;
InstUnreachable(const InstUnreachable &) = delete;
@@ -765,8 +766,8 @@
explicit InstUnreachable(Cfg *Func);
};
-// BundleLock instruction. There are no operands. Contains an option
-// indicating whether align_to_end is specified.
+/// BundleLock instruction. There are no operands. Contains an option
+/// indicating whether align_to_end is specified.
class InstBundleLock : public InstHighLevel {
InstBundleLock() = delete;
InstBundleLock(const InstBundleLock &) = delete;
@@ -791,7 +792,7 @@
InstBundleLock(Cfg *Func, Option BundleOption);
};
-// BundleUnlock instruction. There are no operands.
+/// BundleUnlock instruction. There are no operands.
class InstBundleUnlock : public InstHighLevel {
InstBundleUnlock() = delete;
InstBundleUnlock(const InstBundleUnlock &) = delete;
@@ -812,18 +813,18 @@
explicit InstBundleUnlock(Cfg *Func);
};
-// FakeDef instruction. This creates a fake definition of a variable,
-// which is how we represent the case when an instruction produces
-// multiple results. This doesn't happen with high-level ICE
-// instructions, but might with lowered instructions. For example,
-// this would be a way to represent condition flags being modified by
-// an instruction.
-//
-// It's generally useful to set the optional source operand to be the
-// dest variable of the instruction that actually produces the FakeDef
-// dest. Otherwise, the original instruction could be dead-code
-// eliminated if its dest operand is unused, and therefore the FakeDef
-// dest wouldn't be properly initialized.
+/// FakeDef instruction. This creates a fake definition of a variable,
+/// which is how we represent the case when an instruction produces
+/// multiple results. This doesn't happen with high-level ICE
+/// instructions, but might with lowered instructions. For example,
+/// this would be a way to represent condition flags being modified by
+/// an instruction.
+///
+/// It's generally useful to set the optional source operand to be the
+/// dest variable of the instruction that actually produces the FakeDef
+/// dest. Otherwise, the original instruction could be dead-code
+/// eliminated if its dest operand is unused, and therefore the FakeDef
+/// dest wouldn't be properly initialized.
class InstFakeDef : public InstHighLevel {
InstFakeDef() = delete;
InstFakeDef(const InstFakeDef &) = delete;
@@ -843,11 +844,11 @@
InstFakeDef(Cfg *Func, Variable *Dest, Variable *Src);
};
-// FakeUse instruction. This creates a fake use of a variable, to
-// keep the instruction that produces that variable from being
-// dead-code eliminated. This is useful in a variety of lowering
-// situations. The FakeUse instruction has no dest, so it can itself
-// never be dead-code eliminated.
+/// FakeUse instruction. This creates a fake use of a variable, to
+/// keep the instruction that produces that variable from being
+/// dead-code eliminated. This is useful in a variety of lowering
+/// situations. The FakeUse instruction has no dest, so it can itself
+/// never be dead-code eliminated.
class InstFakeUse : public InstHighLevel {
InstFakeUse() = delete;
InstFakeUse(const InstFakeUse &) = delete;
@@ -866,16 +867,16 @@
InstFakeUse(Cfg *Func, Variable *Src);
};
-// FakeKill instruction. This "kills" a set of variables by modeling
-// a trivial live range at this instruction for each (implicit)
-// variable. The primary use is to indicate that scratch registers
-// are killed after a call, so that the register allocator won't
-// assign a scratch register to a variable whose live range spans a
-// call.
-//
-// The FakeKill instruction also holds a pointer to the instruction
-// that kills the set of variables, so that if that linked instruction
-// gets dead-code eliminated, the FakeKill instruction will as well.
+/// FakeKill instruction. This "kills" a set of variables by modeling
+/// a trivial live range at this instruction for each (implicit)
+/// variable. The primary use is to indicate that scratch registers
+/// are killed after a call, so that the register allocator won't
+/// assign a scratch register to a variable whose live range spans a
+/// call.
+///
+/// The FakeKill instruction also holds a pointer to the instruction
+/// that kills the set of variables, so that if that linked instruction
+/// gets dead-code eliminated, the FakeKill instruction will as well.
class InstFakeKill : public InstHighLevel {
InstFakeKill() = delete;
InstFakeKill(const InstFakeKill &) = delete;
@@ -894,12 +895,12 @@
private:
InstFakeKill(Cfg *Func, const Inst *Linked);
- // This instruction is ignored if Linked->isDeleted() is true.
+ /// This instruction is ignored if Linked->isDeleted() is true.
const Inst *Linked;
};
-// The Target instruction is the base class for all target-specific
-// instructions.
+/// The Target instruction is the base class for all target-specific
+/// instructions.
class InstTarget : public Inst {
InstTarget() = delete;
InstTarget(const InstTarget &) = delete;
@@ -923,8 +924,8 @@
namespace llvm {
-// Override the default ilist traits so that Inst's private ctor and
-// deleted dtor aren't invoked.
+/// Override the default ilist traits so that Inst's private ctor and
+/// deleted dtor aren't invoked.
template <>
struct ilist_traits<Ice::Inst> : public ilist_default_traits<Ice::Inst> {
Ice::Inst *createSentinel() const {
