Doxygenize the documentation comments

src/IceTargetLoweringX86Base.h

 //===- subzero/src/IceTargetLoweringX86Base.h - x86 lowering ----*- C++ -*-===//
 //
 //                        The Subzero Code Generator
 //
 // This file is distributed under the University of Illinois Open Source
 // License. See LICENSE.TXT for details.
 //
 //===----------------------------------------------------------------------===//
-//
-// This file declares the TargetLoweringX86 template class, which
-// implements the TargetLowering base interface for the x86
-// architecture.
-//
+///
+/// \file
+/// This file declares the TargetLoweringX86 template class, which
+/// implements the TargetLowering base interface for the x86
+/// architecture.
+///
 //===----------------------------------------------------------------------===//
 
 #ifndef SUBZERO_SRC_ICETARGETLOWERINGX86BASE_H
 #define SUBZERO_SRC_ICETARGETLOWERINGX86BASE_H
 
 #include "IceDefs.h"
 #include "IceInst.h"
 #include "IceTargetLowering.h"
 
 #include <type_traits>
@@ skipping 110 matching lines @@
   void emit(const ConstantUndef *C) const final;
   void emit(const ConstantInteger32 *C) const final;
   void emit(const ConstantInteger64 *C) const final;
   void emit(const ConstantFloat *C) const final;
   void emit(const ConstantDouble *C) const final;
 
   void lowerArguments() override;
   void initNodeForLowering(CfgNode *Node) override;
   void addProlog(CfgNode *Node) override;
   void addEpilog(CfgNode *Node) override;
-  // Ensure that a 64-bit Variable has been split into 2 32-bit
-  // Variables, creating them if necessary.  This is needed for all
-  // I64 operations, and it is needed for pushing F64 arguments for
-  // function calls using the 32-bit push instruction (though the
-  // latter could be done by directly writing to the stack).
+  /// Ensure that a 64-bit Variable has been split into 2 32-bit
+  /// Variables, creating them if necessary.  This is needed for all
+  /// I64 operations, and it is needed for pushing F64 arguments for
+  /// function calls using the 32-bit push instruction (though the
+  /// latter could be done by directly writing to the stack).
   void split64(Variable *Var);
   Operand *loOperand(Operand *Operand);
   Operand *hiOperand(Operand *Operand);
   void finishArgumentLowering(Variable *Arg, Variable *FramePtr,
                               size_t BasicFrameOffset, size_t &InArgsSizeBytes);
   typename Traits::Address
   stackVarToAsmOperand(const Variable *Var) const final;
 
   typename Traits::InstructionSet getInstructionSet() const final {
     return InstructionSet;
@@ skipping 24 matching lines @@
   void lowerUnreachable(const InstUnreachable *Inst) override;
   void lowerOther(const Inst *Instr) override;
   void lowerRMW(const InstX8632FakeRMW *RMW);
   void prelowerPhis() override;
   void lowerPhiAssignments(CfgNode *Node,
                            const AssignList &Assignments) override;
   void doAddressOptLoad() override;
   void doAddressOptStore() override;
   void randomlyInsertNop(float Probability) override;
 
-  // Naive lowering of cmpxchg.
+  /// Naive lowering of cmpxchg.
   void lowerAtomicCmpxchg(Variable *DestPrev, Operand *Ptr, Operand *Expected,
                           Operand *Desired);
-  // Attempt a more optimized lowering of cmpxchg. Returns true if optimized.
+  /// Attempt a more optimized lowering of cmpxchg. Returns true if optimized.
   bool tryOptimizedCmpxchgCmpBr(Variable *DestPrev, Operand *Ptr,
                                 Operand *Expected, Operand *Desired);
   void lowerAtomicRMW(Variable *Dest, uint32_t Operation, Operand *Ptr,
                       Operand *Val);
   void lowerCountZeros(bool Cttz, Type Ty, Variable *Dest, Operand *FirstVal,
                        Operand *SecondVal);
 
   typedef void (TargetX86Base::*LowerBinOp)(Variable *, Operand *);
   void expandAtomicRMWAsCmpxchg(LowerBinOp op_lo, LowerBinOp op_hi,
                                 Variable *Dest, Operand *Ptr, Operand *Val);
 
   void eliminateNextVectorSextInstruction(Variable *SignExtendedResult);
 
   void scalarizeArithmetic(InstArithmetic::OpKind K, Variable *Dest,
                            Operand *Src0, Operand *Src1);
 
-  // Operand legalization helpers.  To deal with address mode
-  // constraints, the helpers will create a new Operand and emit
-  // instructions that guarantee that the Operand kind is one of those
-  // indicated by the LegalMask (a bitmask of allowed kinds).  If the
-  // input Operand is known to already meet the constraints, it may be
-  // simply returned as the result, without creating any new
-  // instructions or operands.
+  /// Operand legalization helpers.  To deal with address mode
+  /// constraints, the helpers will create a new Operand and emit
+  /// instructions that guarantee that the Operand kind is one of those
+  /// indicated by the LegalMask (a bitmask of allowed kinds).  If the
+  /// input Operand is known to already meet the constraints, it may be
+  /// simply returned as the result, without creating any new
+  /// instructions or operands.
   enum OperandLegalization {
     Legal_None = 0,
     Legal_Reg = 1 << 0, // physical register, not stack location
     Legal_Imm = 1 << 1,
     Legal_Mem = 1 << 2, // includes [eax+4*ecx] as well as [esp+12]
     Legal_All = ~Legal_None
   };
   typedef uint32_t LegalMask;
   Operand *legalize(Operand *From, LegalMask Allowed = Legal_All,
                     int32_t RegNum = Variable::NoRegister);
   Variable *legalizeToVar(Operand *From, int32_t RegNum = Variable::NoRegister);
-  // Legalize the first source operand for use in the cmp instruction.
+  /// Legalize the first source operand for use in the cmp instruction.
   Operand *legalizeSrc0ForCmp(Operand *Src0, Operand *Src1);
-  // Turn a pointer operand into a memory operand that can be
-  // used by a real load/store operation. Legalizes the operand as well.
-  // This is a nop if the operand is already a legal memory operand.
+  /// Turn a pointer operand into a memory operand that can be
+  /// used by a real load/store operation. Legalizes the operand as well.
+  /// This is a nop if the operand is already a legal memory operand.
   OperandX8632Mem *formMemoryOperand(Operand *Ptr, Type Ty,
                                      bool DoLegalize = true);
 
   Variable *makeReg(Type Ty, int32_t RegNum = Variable::NoRegister);
   static Type stackSlotType();
 
   Variable *copyToReg(Operand *Src, int32_t RegNum = Variable::NoRegister);
 
-  // Returns a vector in a register with the given constant entries.
+  /// Returns a vector in a register with the given constant entries.
   Variable *makeVectorOfZeros(Type Ty, int32_t RegNum = Variable::NoRegister);
   Variable *makeVectorOfOnes(Type Ty, int32_t RegNum = Variable::NoRegister);
   Variable *makeVectorOfMinusOnes(Type Ty,
                                   int32_t RegNum = Variable::NoRegister);
   Variable *makeVectorOfHighOrderBits(Type Ty,
                                       int32_t RegNum = Variable::NoRegister);
   Variable *makeVectorOfFabsMask(Type Ty,
                                  int32_t RegNum = Variable::NoRegister);
 
-  // Return a memory operand corresponding to a stack allocated Variable.
+  /// Return a memory operand corresponding to a stack allocated Variable.
   OperandX8632Mem *getMemoryOperandForStackSlot(Type Ty, Variable *Slot,
                                                 uint32_t Offset = 0);
 
   void makeRandomRegisterPermutation(
       llvm::SmallVectorImpl<int32_t> &Permutation,
       const llvm::SmallBitVector &ExcludeRegisters) const override;
 
   // TODO(jpp): move the helper methods below to the MachineTraits.
-  // The following are helpers that insert lowered x86 instructions
-  // with minimal syntactic overhead, so that the lowering code can
-  // look as close to assembly as practical.
+  /// The following are helpers that insert lowered x86 instructions
+  /// with minimal syntactic overhead, so that the lowering code can
+  /// look as close to assembly as practical.
   void _adc(Variable *Dest, Operand *Src0) {
     Context.insert(InstX8632Adc::create(Func, Dest, Src0));
   }
   void _adc_rmw(OperandX8632Mem *DestSrc0, Operand *Src1) {
     Context.insert(InstX8632AdcRMW::create(Func, DestSrc0, Src1));
   }
   void _add(Variable *Dest, Operand *Src0) {
     Context.insert(InstX8632Add::create(Func, Dest, Src0));
   }
   void _add_rmw(OperandX8632Mem *DestSrc0, Operand *Src1) {
@@ skipping 102 matching lines @@
   void _insertps(Variable *Dest, Operand *Src0, Operand *Src1) {
     Context.insert(InstX8632Insertps::create(Func, Dest, Src0, Src1));
   }
   void _jmp(Operand *Target) {
     Context.insert(InstX8632Jmp::create(Func, Target));
   }
   void _lea(Variable *Dest, Operand *Src0) {
     Context.insert(InstX8632Lea::create(Func, Dest, Src0));
   }
   void _mfence() { Context.insert(InstX8632Mfence::create(Func)); }
-  // If Dest=nullptr is passed in, then a new variable is created,
-  // marked as infinite register allocation weight, and returned
-  // through the in/out Dest argument.
+  /// If Dest=nullptr is passed in, then a new variable is created,
+  /// marked as infinite register allocation weight, and returned
+  /// through the in/out Dest argument.
   void _mov(Variable *&Dest, Operand *Src0,
             int32_t RegNum = Variable::NoRegister) {
     if (Dest == nullptr)
       Dest = makeReg(Src0->getType(), RegNum);
     Context.insert(InstX8632Mov::create(Func, Dest, Src0));
   }
   void _mov_nonkillable(Variable *Dest, Operand *Src0) {
     Inst *NewInst = InstX8632Mov::create(Func, Dest, Src0);
     NewInst->setDestNonKillable();
     Context.insert(NewInst);
@@ skipping 193 matching lines @@
       Traits::InstructionSet::Begin;
   bool IsEbpBasedFrame = false;
   bool NeedsStackAlignment = false;
   size_t SpillAreaSizeBytes = 0;
   llvm::SmallBitVector TypeToRegisterSet[IceType_NUM];
   llvm::SmallBitVector ScratchRegs;
   llvm::SmallBitVector RegsUsed;
   VarList PhysicalRegisters[IceType_NUM];
   static IceString RegNames[];
 
-  // Randomize a given immediate operand
+  /// Randomize a given immediate operand
   Operand *randomizeOrPoolImmediate(Constant *Immediate,
                                     int32_t RegNum = Variable::NoRegister);
   OperandX8632Mem *
   randomizeOrPoolImmediate(OperandX8632Mem *MemOperand,
                            int32_t RegNum = Variable::NoRegister);
   bool RandomizationPoolingPaused = false;
 
 private:
   ~TargetX86Base() override {}
   BoolFolding FoldingInfo;
 };
 } // end of namespace X86Internal
 } // end of namespace Ice
 
 #include "IceTargetLoweringX86BaseImpl.h"
 
 #endif // SUBZERO_SRC_ICETARGETLOWERINGX86BASE_H