From isanbard at gmail.com Mon Feb 11 01:09:01 2008 From: isanbard at gmail.com (Bill Wendling) Date: Sun, 10 Feb 2008 23:09:01 -0800 Subject: [llvm-commits] [llvm] r46922 - /llvm/trunk/lib/CodeGen/SelectionDAG/DAGCombiner.cpp In-Reply-To: <241F94F0-D3FB-4D23-B552-6A5C9E66F868@apple.com> References: <200802100810.m1A8AOS2007775@zion.cs.uiuc.edu> <241F94F0-D3FB-4D23-B552-6A5C9E66F868@apple.com> Message-ID: <84E5BEBC-5D19-4941-B711-1E6DAD6196AE@gmail.com> On Feb 10, 2008, at 7:46 PM, Evan Cheng wrote: > What is this fixing? The code as it was was a no-op. This makes it do what the comment says it's supposed to do. > I would expect SelectionDAG to constant > evaluating it to a constant node? > Perhaps. But then why is it here at all then? -bw > On Feb 10, 2008, at 12:10 AM, Bill Wendling wrote: > >> Author: void >> Date: Sun Feb 10 02:10:24 2008 >> New Revision: 46922 >> >> URL: http://llvm.org/viewvc/llvm-project?rev=46922&view=rev >> Log: >> Return "(c1 + c2)" instead of yet another ADD node (which made this a >> no-op). >> >> ===================================================================== >> = >> --- llvm/trunk/lib/CodeGen/SelectionDAG/DAGCombiner.cpp (original) >> +++ llvm/trunk/lib/CodeGen/SelectionDAG/DAGCombiner.cpp Sun Feb 10 >> 02:10:24 2008 >> @@ -923,7 +923,7 @@ >> return N1; >> // fold (add c1, c2) -> c1+c2 >> if (N0C && N1C) >> - return DAG.getNode(ISD::ADD, VT, N0, N1); >> + return DAG.getConstant(N0C->getValue() + N1C->getValue(), VT); >> // canonicalize constant to RHS >> if (N0C && !N1C) >> return DAG.getNode(ISD::ADD, VT, N1, N0); >> >> >> _______________________________________________ >> llvm-commits mailing list >> llvm-commits at cs.uiuc.edu >> http://lists.cs.uiuc.edu/mailman/listinfo/llvm-commits > > _______________________________________________ > llvm-commits mailing list > llvm-commits at cs.uiuc.edu > http://lists.cs.uiuc.edu/mailman/listinfo/llvm-commits From sabre at nondot.org Mon Feb 11 01:21:09 2008 From: sabre at nondot.org (Chris Lattner) Date: Mon, 11 Feb 2008 07:21:09 -0000 Subject: [llvm-commits] [llvm] r46951 - /llvm/trunk/docs/ReleaseNotes.html Message-ID: <200802110721.m1B7LArr015184@zion.cs.uiuc.edu> Author: lattner Date: Mon Feb 11 01:21:08 2008 New Revision: 46951 URL: http://llvm.org/viewvc/llvm-project?rev=46951&view=rev Log: updates from Evan Modified: llvm/trunk/docs/ReleaseNotes.html Modified: llvm/trunk/docs/ReleaseNotes.html URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/ReleaseNotes.html?rev=46951&r1=46950&r2=46951&view=diff ============================================================================== --- llvm/trunk/docs/ReleaseNotes.html (original) +++ llvm/trunk/docs/ReleaseNotes.html Mon Feb 11 01:21:08 2008 @@ -97,7 +97,8 @@ LLVM 2.1, llvm-gcc 4.2 was beta). Since LLVM 2.1, the llvm-gcc 4.2 front-end has made leaps and bounds and is now at least as good as 4.0 in virtually every area, and is better in several areas (for example, exception handling -correctness, support for Ada and Fortran). We strongly recommend that you +correctness, support for Ada and Fortran, better ABI compatibility, etc). We +strongly recommend that you migrate from llvm-gcc 4.0 to llvm-gcc 4.2 in this release cycle because LLVM 2.2 is the last release that will support llvm-gcc 4.0: LLVM 2.3 will only support the llvm-gcc 4.2 front-end.

@@ -265,7 +266,8 @@ llvm-gcc by default, but can be accessed through 'opt'.
  • Dan Gohman contributed several enhancements to Loop Strength Reduction (LSR) -to make it more aggressive with SSE intrinsics.
    • +to make it more aggressive with SSE intrinsics and when induction variables are +used by non-memory instructions.
  • Evan added support for simple exit value substitution to LSR.
    • From sabre at nondot.org Mon Feb 11 01:27:22 2008 From: sabre at nondot.org (Chris Lattner) Date: Mon, 11 Feb 2008 07:27:22 -0000 Subject: [llvm-commits] [llvm] r46952 - /llvm/trunk/docs/ReleaseNotes.html Message-ID: <200802110727.m1B7RMl3015334@zion.cs.uiuc.edu> Author: lattner Date: Mon Feb 11 01:27:21 2008 New Revision: 46952 URL: http://llvm.org/viewvc/llvm-project?rev=46952&view=rev Log: tweaks from dale. Modified: llvm/trunk/docs/ReleaseNotes.html Modified: llvm/trunk/docs/ReleaseNotes.html URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/ReleaseNotes.html?rev=46952&r1=46951&r2=46952&view=diff ============================================================================== --- llvm/trunk/docs/ReleaseNotes.html (original) +++ llvm/trunk/docs/ReleaseNotes.html Mon Feb 11 01:27:21 2008 @@ -292,8 +292,8 @@
  • Evan contributed support to the X86 backend to model the mod/ref behavior of the EFLAGS register explicitly in all instructions. This gives more freedom to the scheduler, and is a more explicit way to model the instructions.
    • -
  • Dale contributed support for exception handling on Darwin/x86-64 and -Darwin/PPC.
    • +
  • Dale contributed support for exception handling on Darwin/PPC and he and +Anton got x86-64 working.
  • Evan turned on if-conversion by default for ARM, allowing LLVM to take advantage of its predication features.
  • Bruno added PIC support to the MIPS backend, fixed many bugs and improved From baldrick at free.fr Mon Feb 11 02:18:11 2008 From: baldrick at free.fr (Duncan Sands) Date: Mon, 11 Feb 2008 09:18:11 +0100 Subject: [llvm-commits] [llvm-gcc-4.2] r46726 - /llvm-gcc-4.2/trunk/gcc/llvm-convert.cpp In-Reply-To: <6C2B9229-8B1C-4B6D-8107-A8C7A72BB547@apple.com> References: <200802042324.m14NOiBg021071@zion.cs.uiuc.edu> <200802092224.20812.baldrick@free.fr> <6C2B9229-8B1C-4B6D-8107-A8C7A72BB547@apple.com> Message-ID: <200802110918.13428.baldrick@free.fr> > > the current LLVM implementation means that anyone using threading > > needs > > to not do bitfield accesses, since the compiler generated code could > > cause trouble. > > This is not handled by LLVM, this is handled by FE that is translating > source code into LLVM IR. Unless all front-ends enforce this, we can > not claim that LLVM guarantees bit-field thread safety (I do think, it > is convenient if tools support bit-field thread safety). If you are > suggesting to handle this some how inside LLVM itself then I mis- > understood your comment. I was talking about how llvm-gcc handles bitfields. Sorry for the confusion. Ciao, Duncan. From evan.cheng at apple.com Mon Feb 11 02:30:52 2008 From: evan.cheng at apple.com (Evan Cheng) Date: Mon, 11 Feb 2008 08:30:52 -0000 Subject: [llvm-commits] [llvm] r46953 - in /llvm/trunk: lib/CodeGen/RegAllocLocal.cpp test/CodeGen/PowerPC/2008-02-09-LocalRegAllocAssert.ll Message-ID: <200802110830.m1B8UqSs017255@zion.cs.uiuc.edu> Author: evancheng Date: Mon Feb 11 02:30:52 2008 New Revision: 46953 URL: http://llvm.org/viewvc/llvm-project?rev=46953&view=rev Log: Determine whether a spill kills the register it's spilling before insertion rather than trying to undo the kill marker afterwards. Added: llvm/trunk/test/CodeGen/PowerPC/2008-02-09-LocalRegAllocAssert.ll Modified: llvm/trunk/lib/CodeGen/RegAllocLocal.cpp Modified: llvm/trunk/lib/CodeGen/RegAllocLocal.cpp URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/lib/CodeGen/RegAllocLocal.cpp?rev=46953&r1=46952&r2=46953&view=diff ============================================================================== --- llvm/trunk/lib/CodeGen/RegAllocLocal.cpp (original) +++ llvm/trunk/lib/CodeGen/RegAllocLocal.cpp Mon Feb 11 02:30:52 2008 @@ -303,17 +303,12 @@ const TargetRegisterClass *RC = MF->getRegInfo().getRegClass(VirtReg); int FrameIndex = getStackSpaceFor(VirtReg, RC); DOUT << " to stack slot #" << FrameIndex; - TII->storeRegToStackSlot(MBB, I, PhysReg, true, FrameIndex, RC); - // If the instruction reads the register that's spilled, (e.g. this can // happen if it is a move to a physical register), then the spill // instruction is not a kill. - if (I != MBB.end() && I->findRegisterUseOperandIdx(PhysReg) != -1) { - MachineBasicBlock::iterator StoreMI = prior(I); - int Idx = StoreMI->findRegisterUseOperandIdx(PhysReg, true); - assert(Idx != -1 && "Unrecognized spill instruction!"); - StoreMI->getOperand(Idx).setIsKill(false); - } + bool isKill = !(I != MBB.end() && + I->findRegisterUseOperandIdx(PhysReg) != -1); + TII->storeRegToStackSlot(MBB, I, PhysReg, isKill, FrameIndex, RC); ++NumStores; // Update statistics } Added: llvm/trunk/test/CodeGen/PowerPC/2008-02-09-LocalRegAllocAssert.ll URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/test/CodeGen/PowerPC/2008-02-09-LocalRegAllocAssert.ll?rev=46953&view=auto ============================================================================== --- llvm/trunk/test/CodeGen/PowerPC/2008-02-09-LocalRegAllocAssert.ll (added) +++ llvm/trunk/test/CodeGen/PowerPC/2008-02-09-LocalRegAllocAssert.ll Mon Feb 11 02:30:52 2008 @@ -0,0 +1,10 @@ +; RUN: llvm-as < %s | llc -mtriple=powerpc-apple-darwin -regalloc=local + +define i32 @bork(i64 %foo, i64 %bar) { +entry: + %tmp = load i64* null, align 8 ; [#uses=2] + %tmp2 = icmp ule i64 %tmp, 0 ; [#uses=1] + %min = select i1 %tmp2, i64 %tmp, i64 0 ; [#uses=1] + store i64 %min, i64* null, align 8 + ret i32 0 +} From baldrick at free.fr Mon Feb 11 04:37:06 2008 From: baldrick at free.fr (Duncan Sands) Date: Mon, 11 Feb 2008 10:37:06 -0000 Subject: [llvm-commits] [llvm] r46954 - in /llvm/trunk: include/llvm/Target/TargetLowering.h lib/CodeGen/SelectionDAG/DAGCombiner.cpp lib/CodeGen/SelectionDAG/LegalizeDAG.cpp lib/CodeGen/SelectionDAG/LegalizeTypesExpand.cpp Message-ID: <200802111037.m1BAb7Jm028916@zion.cs.uiuc.edu> Author: baldrick Date: Mon Feb 11 04:37:04 2008 New Revision: 46954 URL: http://llvm.org/viewvc/llvm-project?rev=46954&view=rev Log: Add a isBigEndian method to complement isLittleEndian. Modified: llvm/trunk/include/llvm/Target/TargetLowering.h llvm/trunk/lib/CodeGen/SelectionDAG/DAGCombiner.cpp llvm/trunk/lib/CodeGen/SelectionDAG/LegalizeDAG.cpp llvm/trunk/lib/CodeGen/SelectionDAG/LegalizeTypesExpand.cpp Modified: llvm/trunk/include/llvm/Target/TargetLowering.h URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/include/llvm/Target/TargetLowering.h?rev=46954&r1=46953&r2=46954&view=diff ============================================================================== --- llvm/trunk/include/llvm/Target/TargetLowering.h (original) +++ llvm/trunk/include/llvm/Target/TargetLowering.h Mon Feb 11 04:37:04 2008 @@ -85,6 +85,7 @@ TargetMachine &getTargetMachine() const { return TM; } const TargetData *getTargetData() const { return TD; } + bool isBigEndian() const { return !IsLittleEndian; } bool isLittleEndian() const { return IsLittleEndian; } MVT::ValueType getPointerTy() const { return PointerTy; } MVT::ValueType getShiftAmountTy() const { return ShiftAmountTy; } Modified: llvm/trunk/lib/CodeGen/SelectionDAG/DAGCombiner.cpp URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/lib/CodeGen/SelectionDAG/DAGCombiner.cpp?rev=46954&r1=46953&r2=46954&view=diff ============================================================================== --- llvm/trunk/lib/CodeGen/SelectionDAG/DAGCombiner.cpp (original) +++ llvm/trunk/lib/CodeGen/SelectionDAG/DAGCombiner.cpp Mon Feb 11 04:37:04 2008 @@ -1739,7 +1739,7 @@ unsigned PtrOff = LVTStoreBytes - EVTStoreBytes; unsigned Alignment = LN0->getAlignment(); SDOperand NewPtr = LN0->getBasePtr(); - if (!TLI.isLittleEndian()) { + if (TLI.isBigEndian()) { NewPtr = DAG.getNode(ISD::ADD, PtrType, NewPtr, DAG.getConstant(PtrOff, PtrType)); Alignment = MinAlign(Alignment, PtrOff); @@ -3086,7 +3086,7 @@ MVT::ValueType PtrType = N0.getOperand(1).getValueType(); // For big endian targets, we need to adjust the offset to the pointer to // load the correct bytes. - if (!TLI.isLittleEndian()) { + if (TLI.isBigEndian()) { unsigned LVTStoreBits = MVT::getStoreSizeInBits(N0.getValueType()); unsigned EVTStoreBits = MVT::getStoreSizeInBits(EVT); ShAmt = LVTStoreBits - EVTStoreBits - ShAmt; @@ -3460,7 +3460,7 @@ } // For big endian targets, swap the order of the pieces of each element. - if (!TLI.isLittleEndian()) + if (TLI.isBigEndian()) std::reverse(Ops.end()-NumOutputsPerInput, Ops.end()); } MVT::ValueType VT = MVT::getVectorType(DstEltVT, Ops.size()); @@ -4386,7 +4386,7 @@ uint64_t Val = CFP->getValueAPF().convertToAPInt().getZExtValue(); SDOperand Lo = DAG.getConstant(Val & 0xFFFFFFFF, MVT::i32); SDOperand Hi = DAG.getConstant(Val >> 32, MVT::i32); - if (!TLI.isLittleEndian()) std::swap(Lo, Hi); + if (TLI.isBigEndian()) std::swap(Lo, Hi); int SVOffset = ST->getSrcValueOffset(); unsigned Alignment = ST->getAlignment(); Modified: llvm/trunk/lib/CodeGen/SelectionDAG/LegalizeDAG.cpp URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/lib/CodeGen/SelectionDAG/LegalizeDAG.cpp?rev=46954&r1=46953&r2=46954&view=diff ============================================================================== --- llvm/trunk/lib/CodeGen/SelectionDAG/LegalizeDAG.cpp (original) +++ llvm/trunk/lib/CodeGen/SelectionDAG/LegalizeDAG.cpp Mon Feb 11 04:37:04 2008 @@ -2117,7 +2117,7 @@ ExpandOp(Tmp2, Lo, Hi); // Big endian systems want the hi reg first. - if (!TLI.isLittleEndian()) + if (TLI.isBigEndian()) std::swap(Lo, Hi); if (Hi.Val) @@ -2256,7 +2256,7 @@ uint64_t IntVal =CFP->getValueAPF().convertToAPInt().getZExtValue(); SDOperand Lo = DAG.getConstant(uint32_t(IntVal), MVT::i32); SDOperand Hi = DAG.getConstant(uint32_t(IntVal >>32), MVT::i32); - if (!TLI.isLittleEndian()) std::swap(Lo, Hi); + if (TLI.isBigEndian()) std::swap(Lo, Hi); Lo = DAG.getStore(Tmp1, Lo, Tmp2, ST->getSrcValue(), SVOffset, isVolatile, Alignment); @@ -2356,7 +2356,7 @@ ExpandOp(Node->getOperand(1), Lo, Hi); IncrementSize = Hi.Val ? MVT::getSizeInBits(Hi.getValueType())/8 : 0; - if (!TLI.isLittleEndian()) + if (TLI.isBigEndian()) std::swap(Lo, Hi); } @@ -5766,7 +5766,7 @@ // Remember that we legalized the chain. Hi = LegalizeOp(Hi); AddLegalizedOperand(Op.getValue(1), Hi.getValue(1)); - if (!TLI.isLittleEndian()) + if (TLI.isBigEndian()) std::swap(Lo, Hi); break; } @@ -5809,7 +5809,7 @@ // Remember that we legalized the chain. AddLegalizedOperand(Op.getValue(1), LegalizeOp(TF)); - if (!TLI.isLittleEndian()) + if (TLI.isBigEndian()) std::swap(Lo, Hi); } else { MVT::ValueType EVT = LD->getMemoryVT(); Modified: llvm/trunk/lib/CodeGen/SelectionDAG/LegalizeTypesExpand.cpp URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/lib/CodeGen/SelectionDAG/LegalizeTypesExpand.cpp?rev=46954&r1=46953&r2=46954&view=diff ============================================================================== --- llvm/trunk/lib/CodeGen/SelectionDAG/LegalizeTypesExpand.cpp (original) +++ llvm/trunk/lib/CodeGen/SelectionDAG/LegalizeTypesExpand.cpp Mon Feb 11 04:37:04 2008 @@ -293,7 +293,7 @@ Hi.getValue(1)); // Handle endianness of the load. - if (!TLI.isLittleEndian()) + if (TLI.isBigEndian()) std::swap(Lo, Hi); } else if (MVT::getSizeInBits(N->getMemoryVT()) <= MVT::getSizeInBits(NVT)) { MVT::ValueType EVT = N->getMemoryVT(); @@ -1076,7 +1076,7 @@ GetExpandedOp(N->getValue(), Lo, Hi); IncrementSize = MVT::getSizeInBits(Hi.getValueType())/8; - if (!TLI.isLittleEndian()) + if (TLI.isBigEndian()) std::swap(Lo, Hi); Lo = DAG.getStore(Ch, Lo, Ptr, N->getSrcValue(), From wmatyjewicz at fastmail.fm Mon Feb 11 05:03:16 2008 From: wmatyjewicz at fastmail.fm (Wojciech Matyjewicz) Date: Mon, 11 Feb 2008 11:03:16 -0000 Subject: [llvm-commits] [llvm] r46955 - in /llvm/trunk: include/llvm/Analysis/ScalarEvolution.h include/llvm/Analysis/ScalarEvolutionExpander.h include/llvm/Analysis/ScalarEvolutionExpressions.h lib/Analysis/ScalarEvolution.cpp test/Analysis/ScalarEvolution/2007-11-14-SignedAddRec.ll Message-ID: <200802111103.m1BB3H9Z029639@zion.cs.uiuc.edu> Author: wmat Date: Mon Feb 11 05:03:14 2008 New Revision: 46955 URL: http://llvm.org/viewvc/llvm-project?rev=46955&view=rev Log: Fix PR1798 - an error in the evaluation of SCEVAddRecExpr at an arbitrary iteration. The patch: 1) changes SCEVSDivExpr into SCEVUDivExpr, 2) replaces PartialFact() function with BinomialCoefficient(); the computations (essentially, the division) in BinomialCoefficient() are performed with the apprioprate bitwidth necessary to avoid overflow; unsigned division is used instead of the signed one. Computations in BinomialCoefficient() require support from the code generator for APInts. Currently, we use a hack rounding up the neccessary bitwidth to the nearest power of 2. The hack is easy to turn off in future. One remaining issue: we assume the divisor of the binomial coefficient formula can be computed accurately using 16 bits. It means we can handle AddRecs of length up to 9. In future, we should use APInts to evaluate the divisor. Thanks to Nicholas for cooperation! Modified: llvm/trunk/include/llvm/Analysis/ScalarEvolution.h llvm/trunk/include/llvm/Analysis/ScalarEvolutionExpander.h llvm/trunk/include/llvm/Analysis/ScalarEvolutionExpressions.h llvm/trunk/lib/Analysis/ScalarEvolution.cpp llvm/trunk/test/Analysis/ScalarEvolution/2007-11-14-SignedAddRec.ll Modified: llvm/trunk/include/llvm/Analysis/ScalarEvolution.h URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/include/llvm/Analysis/ScalarEvolution.h?rev=46955&r1=46954&r2=46955&view=diff ============================================================================== --- llvm/trunk/include/llvm/Analysis/ScalarEvolution.h (original) +++ llvm/trunk/include/llvm/Analysis/ScalarEvolution.h Mon Feb 11 05:03:14 2008 @@ -225,7 +225,7 @@ Ops.push_back(RHS); return getMulExpr(Ops); } - SCEVHandle getSDivExpr(const SCEVHandle &LHS, const SCEVHandle &RHS); + SCEVHandle getUDivExpr(const SCEVHandle &LHS, const SCEVHandle &RHS); SCEVHandle getAddRecExpr(const SCEVHandle &Start, const SCEVHandle &Step, const Loop *L); SCEVHandle getAddRecExpr(std::vector &Operands, Modified: llvm/trunk/include/llvm/Analysis/ScalarEvolutionExpander.h URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/include/llvm/Analysis/ScalarEvolutionExpander.h?rev=46955&r1=46954&r2=46955&view=diff ============================================================================== --- llvm/trunk/include/llvm/Analysis/ScalarEvolutionExpander.h (original) +++ llvm/trunk/include/llvm/Analysis/ScalarEvolutionExpander.h Mon Feb 11 05:03:14 2008 @@ -126,10 +126,10 @@ Value *visitMulExpr(SCEVMulExpr *S); - Value *visitSDivExpr(SCEVSDivExpr *S) { + Value *visitUDivExpr(SCEVUDivExpr *S) { Value *LHS = expand(S->getLHS()); Value *RHS = expand(S->getRHS()); - return InsertBinop(Instruction::SDiv, LHS, RHS, InsertPt); + return InsertBinop(Instruction::UDiv, LHS, RHS, InsertPt); } Value *visitAddRecExpr(SCEVAddRecExpr *S); Modified: llvm/trunk/include/llvm/Analysis/ScalarEvolutionExpressions.h URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/include/llvm/Analysis/ScalarEvolutionExpressions.h?rev=46955&r1=46954&r2=46955&view=diff ============================================================================== --- llvm/trunk/include/llvm/Analysis/ScalarEvolutionExpressions.h (original) +++ llvm/trunk/include/llvm/Analysis/ScalarEvolutionExpressions.h Mon Feb 11 05:03:14 2008 @@ -25,7 +25,7 @@ // These should be ordered in terms of increasing complexity to make the // folders simpler. scConstant, scTruncate, scZeroExtend, scSignExtend, scAddExpr, scMulExpr, - scSDivExpr, scAddRecExpr, scSMaxExpr, scUnknown, scCouldNotCompute + scUDivExpr, scAddRecExpr, scSMaxExpr, scUnknown, scCouldNotCompute }; //===--------------------------------------------------------------------===// @@ -322,16 +322,16 @@ //===--------------------------------------------------------------------===// - /// SCEVSDivExpr - This class represents a binary signed division operation. + /// SCEVUDivExpr - This class represents a binary unsigned division operation. /// - class SCEVSDivExpr : public SCEV { + class SCEVUDivExpr : public SCEV { friend class ScalarEvolution; SCEVHandle LHS, RHS; - SCEVSDivExpr(const SCEVHandle &lhs, const SCEVHandle &rhs) - : SCEV(scSDivExpr), LHS(lhs), RHS(rhs) {} + SCEVUDivExpr(const SCEVHandle &lhs, const SCEVHandle &rhs) + : SCEV(scUDivExpr), LHS(lhs), RHS(rhs) {} - virtual ~SCEVSDivExpr(); + virtual ~SCEVUDivExpr(); public: const SCEVHandle &getLHS() const { return LHS; } const SCEVHandle &getRHS() const { return RHS; } @@ -353,7 +353,7 @@ if (L == LHS && R == RHS) return this; else - return SE.getSDivExpr(L, R); + return SE.getUDivExpr(L, R); } @@ -363,9 +363,9 @@ void print(std::ostream *OS) const { if (OS) print(*OS); } /// Methods for support type inquiry through isa, cast, and dyn_cast: - static inline bool classof(const SCEVSDivExpr *S) { return true; } + static inline bool classof(const SCEVUDivExpr *S) { return true; } static inline bool classof(const SCEV *S) { - return S->getSCEVType() == scSDivExpr; + return S->getSCEVType() == scUDivExpr; } }; @@ -540,8 +540,8 @@ return ((SC*)this)->visitAddExpr((SCEVAddExpr*)S); case scMulExpr: return ((SC*)this)->visitMulExpr((SCEVMulExpr*)S); - case scSDivExpr: - return ((SC*)this)->visitSDivExpr((SCEVSDivExpr*)S); + case scUDivExpr: + return ((SC*)this)->visitUDivExpr((SCEVUDivExpr*)S); case scAddRecExpr: return ((SC*)this)->visitAddRecExpr((SCEVAddRecExpr*)S); case scSMaxExpr: Modified: llvm/trunk/lib/Analysis/ScalarEvolution.cpp URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/lib/Analysis/ScalarEvolution.cpp?rev=46955&r1=46954&r2=46955&view=diff ============================================================================== --- llvm/trunk/lib/Analysis/ScalarEvolution.cpp (original) +++ llvm/trunk/lib/Analysis/ScalarEvolution.cpp Mon Feb 11 05:03:14 2008 @@ -328,21 +328,21 @@ } -// SCEVSDivs - Only allow the creation of one SCEVSDivExpr for any particular +// SCEVUDivs - Only allow the creation of one SCEVUDivExpr for any particular // input. Don't use a SCEVHandle here, or else the object will never be // deleted! static ManagedStatic, - SCEVSDivExpr*> > SCEVSDivs; + SCEVUDivExpr*> > SCEVUDivs; -SCEVSDivExpr::~SCEVSDivExpr() { - SCEVSDivs->erase(std::make_pair(LHS, RHS)); +SCEVUDivExpr::~SCEVUDivExpr() { + SCEVUDivs->erase(std::make_pair(LHS, RHS)); } -void SCEVSDivExpr::print(std::ostream &OS) const { - OS << "(" << *LHS << " /s " << *RHS << ")"; +void SCEVUDivExpr::print(std::ostream &OS) const { + OS << "(" << *LHS << " /u " << *RHS << ")"; } -const Type *SCEVSDivExpr::getType() const { +const Type *SCEVUDivExpr::getType() const { return LHS->getType(); } @@ -532,57 +532,110 @@ } -/// PartialFact - Compute V!/(V-NumSteps)! -static SCEVHandle PartialFact(SCEVHandle V, unsigned NumSteps, - ScalarEvolution &SE) { +/// BinomialCoefficient - Compute BC(It, K). The result is of the same type as +/// It. Assume, K > 0. +static SCEVHandle BinomialCoefficient(SCEVHandle It, unsigned K, + ScalarEvolution &SE) { + // We are using the following formula for BC(It, K): + // + // BC(It, K) = (It * (It - 1) * ... * (It - K + 1)) / K! + // + // Suppose, W is the bitwidth of It (and of the return value as well). We + // must be prepared for overflow. Hence, we must assure that the result of + // our computation is equal to the accurate one modulo 2^W. Unfortunately, + // division isn't safe in modular arithmetic. This means we must perform the + // whole computation accurately and then truncate the result to W bits. + // + // The dividend of the formula is a multiplication of K integers of bitwidth + // W. K*W bits suffice to compute it accurately. + // + // FIXME: We assume the divisor can be accurately computed using 16-bit + // unsigned integer type. It is true up to K = 8 (AddRecs of length 9). In + // future we may use APInt to use the minimum number of bits necessary to + // compute it accurately. + // + // It is safe to use unsigned division here: the dividend is nonnegative and + // the divisor is positive. + + // Handle the simplest case efficiently. + if (K == 1) + return It; + + assert(K < 9 && "We cannot handle such long AddRecs yet."); + + // FIXME: A temporary hack to remove in future. Arbitrary precision integers + // aren't supported by the code generator yet. For the dividend, the bitwidth + // we use is the smallest power of 2 greater or equal to K*W and less or equal + // to 64. Note that setting the upper bound for bitwidth may still lead to + // miscompilation in some cases. + unsigned DividendBits = 1U << Log2_32_Ceil(K * It->getBitWidth()); + if (DividendBits > 64) + DividendBits = 64; +#if 0 // Waiting for the APInt support in the code generator... + unsigned DividendBits = K * It->getBitWidth(); +#endif + + const IntegerType *DividendTy = IntegerType::get(DividendBits); + const SCEVHandle ExIt = SE.getZeroExtendExpr(It, DividendTy); + + // The final number of bits we need to perform the division is the maximum of + // dividend and divisor bitwidths. + const IntegerType *DivisionTy = + IntegerType::get(std::max(DividendBits, 16U)); + + // Compute K! We know K >= 2 here. + unsigned F = 2; + for (unsigned i = 3; i <= K; ++i) + F *= i; + APInt Divisor(DivisionTy->getBitWidth(), F); + // Handle this case efficiently, it is common to have constant iteration // counts while computing loop exit values. - if (SCEVConstant *SC = dyn_cast(V)) { - const APInt& Val = SC->getValue()->getValue(); - APInt Result(Val.getBitWidth(), 1); - for (; NumSteps; --NumSteps) - Result *= Val-(NumSteps-1); - return SE.getConstant(Result); - } - - const Type *Ty = V->getType(); - if (NumSteps == 0) - return SE.getIntegerSCEV(1, Ty); - - SCEVHandle Result = V; - for (unsigned i = 1; i != NumSteps; ++i) - Result = SE.getMulExpr(Result, SE.getMinusSCEV(V, - SE.getIntegerSCEV(i, Ty))); - return Result; + if (SCEVConstant *SC = dyn_cast(ExIt)) { + const APInt& N = SC->getValue()->getValue(); + APInt Dividend(N.getBitWidth(), 1); + for (; K; --K) + Dividend *= N-(K-1); + if (DividendTy != DivisionTy) + Dividend = Dividend.zext(DivisionTy->getBitWidth()); + return SE.getConstant(Dividend.udiv(Divisor).trunc(It->getBitWidth())); + } + + SCEVHandle Dividend = ExIt; + for (unsigned i = 1; i != K; ++i) + Dividend = + SE.getMulExpr(Dividend, + SE.getMinusSCEV(ExIt, SE.getIntegerSCEV(i, DividendTy))); + if (DividendTy != DivisionTy) + Dividend = SE.getZeroExtendExpr(Dividend, DivisionTy); + return + SE.getTruncateExpr(SE.getUDivExpr(Dividend, SE.getConstant(Divisor)), + It->getType()); } - /// evaluateAtIteration - Return the value of this chain of recurrences at /// the specified iteration number. We can evaluate this recurrence by /// multiplying each element in the chain by the binomial coefficient /// corresponding to it. In other words, we can evaluate {A,+,B,+,C,+,D} as: /// -/// A*choose(It, 0) + B*choose(It, 1) + C*choose(It, 2) + D*choose(It, 3) +/// A*BC(It, 0) + B*BC(It, 1) + C*BC(It, 2) + D*BC(It, 3) /// -/// FIXME/VERIFY: I don't trust that this is correct in the face of overflow. -/// Is the binomial equation safe using modular arithmetic?? +/// where BC(It, k) stands for binomial coefficient. /// SCEVHandle SCEVAddRecExpr::evaluateAtIteration(SCEVHandle It, ScalarEvolution &SE) const { SCEVHandle Result = getStart(); - int Divisor = 1; - const Type *Ty = It->getType(); for (unsigned i = 1, e = getNumOperands(); i != e; ++i) { - SCEVHandle BC = PartialFact(It, i, SE); - Divisor *= i; - SCEVHandle Val = SE.getSDivExpr(SE.getMulExpr(BC, getOperand(i)), - SE.getIntegerSCEV(Divisor,Ty)); + // The computation is correct in the face of overflow provided that the + // multiplication is performed _after_ the evaluation of the binomial + // coefficient. + SCEVHandle Val = SE.getMulExpr(getOperand(i), + BinomialCoefficient(It, i, SE)); Result = SE.getAddExpr(Result, Val); } return Result; } - //===----------------------------------------------------------------------===// // SCEV Expression folder implementations //===----------------------------------------------------------------------===// @@ -1039,24 +1092,22 @@ return Result; } -SCEVHandle ScalarEvolution::getSDivExpr(const SCEVHandle &LHS, const SCEVHandle &RHS) { +SCEVHandle ScalarEvolution::getUDivExpr(const SCEVHandle &LHS, const SCEVHandle &RHS) { if (SCEVConstant *RHSC = dyn_cast(RHS)) { if (RHSC->getValue()->equalsInt(1)) - return LHS; // X sdiv 1 --> x - if (RHSC->getValue()->isAllOnesValue()) - return getNegativeSCEV(LHS); // X sdiv -1 --> -x + return LHS; // X udiv 1 --> x if (SCEVConstant *LHSC = dyn_cast(LHS)) { Constant *LHSCV = LHSC->getValue(); Constant *RHSCV = RHSC->getValue(); - return getUnknown(ConstantExpr::getSDiv(LHSCV, RHSCV)); + return getUnknown(ConstantExpr::getUDiv(LHSCV, RHSCV)); } } // FIXME: implement folding of (X*4)/4 when we know X*4 doesn't overflow. - SCEVSDivExpr *&Result = (*SCEVSDivs)[std::make_pair(LHS, RHS)]; - if (Result == 0) Result = new SCEVSDivExpr(LHS, RHS); + SCEVUDivExpr *&Result = (*SCEVUDivs)[std::make_pair(LHS, RHS)]; + if (Result == 0) Result = new SCEVUDivExpr(LHS, RHS); return Result; } @@ -1555,7 +1606,7 @@ return MinOpRes; } - // SCEVSDivExpr, SCEVUnknown + // SCEVUDivExpr, SCEVUnknown return 0; } @@ -1574,8 +1625,8 @@ case Instruction::Mul: return SE.getMulExpr(getSCEV(I->getOperand(0)), getSCEV(I->getOperand(1))); - case Instruction::SDiv: - return SE.getSDivExpr(getSCEV(I->getOperand(0)), + case Instruction::UDiv: + return SE.getUDivExpr(getSCEV(I->getOperand(0)), getSCEV(I->getOperand(1))); case Instruction::Sub: return SE.getMinusSCEV(getSCEV(I->getOperand(0)), @@ -2264,14 +2315,14 @@ return Comm; } - if (SCEVSDivExpr *Div = dyn_cast(V)) { + if (SCEVUDivExpr *Div = dyn_cast(V)) { SCEVHandle LHS = getSCEVAtScope(Div->getLHS(), L); if (LHS == UnknownValue) return LHS; SCEVHandle RHS = getSCEVAtScope(Div->getRHS(), L); if (RHS == UnknownValue) return RHS; if (LHS == Div->getLHS() && RHS == Div->getRHS()) return Div; // must be loop invariant - return SE.getSDivExpr(LHS, RHS); + return SE.getUDivExpr(LHS, RHS); } // If this is a loop recurrence for a loop that does not contain L, then we Modified: llvm/trunk/test/Analysis/ScalarEvolution/2007-11-14-SignedAddRec.ll URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/test/Analysis/ScalarEvolution/2007-11-14-SignedAddRec.ll?rev=46955&r1=46954&r2=46955&view=diff ============================================================================== --- llvm/trunk/test/Analysis/ScalarEvolution/2007-11-14-SignedAddRec.ll (original) +++ llvm/trunk/test/Analysis/ScalarEvolution/2007-11-14-SignedAddRec.ll Mon Feb 11 05:03:14 2008 @@ -1,6 +1,5 @@ ; RUN: llvm-as < %s | opt -indvars | llvm-dis | grep printd | grep 1206807378 ; PR1798 -; XFAIL: * declare void @printd(i32) From baldrick at free.fr Mon Feb 11 05:09:23 2008 From: baldrick at free.fr (Duncan Sands) Date: Mon, 11 Feb 2008 11:09:23 -0000 Subject: [llvm-commits] [llvm] r46956 - /llvm/trunk/include/llvm/Target/TargetLowering.h Message-ID: <200802111109.m1BB9O9w029793@zion.cs.uiuc.edu> Author: baldrick Date: Mon Feb 11 05:09:23 2008 New Revision: 46956 URL: http://llvm.org/viewvc/llvm-project?rev=46956&view=rev Log: Add arbitrary integer support to getRegisterType and getNumRegisters. This is needed for calling functions with apint parameters or return values. Modified: llvm/trunk/include/llvm/Target/TargetLowering.h Modified: llvm/trunk/include/llvm/Target/TargetLowering.h URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/include/llvm/Target/TargetLowering.h?rev=46956&r1=46955&r2=46956&view=diff ============================================================================== --- llvm/trunk/include/llvm/Target/TargetLowering.h (original) +++ llvm/trunk/include/llvm/Target/TargetLowering.h Mon Feb 11 05:09:23 2008 @@ -434,13 +434,18 @@ (void)getVectorTypeBreakdown(VT, VT1, NumIntermediates, RegisterVT); return RegisterVT; } + if (MVT::isInteger(VT)) { + return getRegisterType(getTypeToTransformTo(VT)); + } assert(0 && "Unsupported extended type!"); } /// getNumRegisters - Return the number of registers that this ValueType will /// eventually require. This is one for any types promoted to live in larger /// registers, but may be more than one for types (like i64) that are split - /// into pieces. + /// into pieces. For types like i140, which are first promoted then expanded, + /// it is the number of registers needed to hold all the bits of the original + /// type. For an i140 on a 32 bit machine this means 5 registers. unsigned getNumRegisters(MVT::ValueType VT) const { if (!MVT::isExtendedVT(VT)) { assert(VT < array_lengthof(NumRegistersForVT)); @@ -451,6 +456,11 @@ unsigned NumIntermediates; return getVectorTypeBreakdown(VT, VT1, NumIntermediates, VT2); } + if (MVT::isInteger(VT)) { + unsigned BitWidth = MVT::getSizeInBits(VT); + unsigned RegWidth = MVT::getSizeInBits(getRegisterType(VT)); + return (BitWidth + RegWidth - 1) / RegWidth; + } assert(0 && "Unsupported extended type!"); } From wmatyjewicz at fastmail.fm Mon Feb 11 05:11:44 2008 From: wmatyjewicz at fastmail.fm (Wojciech Matyjewicz) Date: Mon, 11 Feb 2008 12:11:44 +0100 Subject: [llvm-commits] Fix for PR1798 (ScalarEvolution) In-Reply-To: <47AF97A4.6090909@mxc.ca> References: <478D2769.8060503@fastmail.fm> <47ADE232.5070407@fastmail.fm> <47AF7E72.6080609@mxc.ca> <47AF8647.8090505@fastmail.fm> <47AF97A4.6090909@mxc.ca> Message-ID: <47B02D70.1060906@fastmail.fm> Nick Lewycky wrote: >> After your question, I have realized that 32 bits for the divisor may be >> too much... Using "only" 16 bits would allow us to handle AddRecs up to >> length 8. If you agree 16 is a safe bitwidth, I'll change it. However, >> the maximum operation you ask about will still be necessary. > > Optimally, we'd use APInt and get the right length up front, but there's > no need for that to hold up this patch. Ok. I've added a comment for that. I've also lifted the restriction that the dividend should be at least 32 bits wide. Currently, the dividend is computed with the minimum necessary bitwidth and extended, if needed, just before the division. The patch is here: http://lists.cs.uiuc.edu/pipermail/llvm-commits/Week-of-Mon-20080211/058097.html I think it's a good idea to keep the PR open. It will prevent us from forgetting to turn off the hack in future... Wojtek From kremenek at apple.com Mon Feb 11 11:24:52 2008 From: kremenek at apple.com (Ted Kremenek) Date: Mon, 11 Feb 2008 17:24:52 -0000 Subject: [llvm-commits] [llvm] r46957 - in /llvm/trunk: include/llvm/ADT/APFloat.h include/llvm/ADT/FoldingSet.h include/llvm/Support/AlignOf.h lib/CodeGen/SelectionDAG/SelectionDAG.cpp lib/Support/APFloat.cpp lib/Support/FoldingSet.cpp Message-ID: <200802111724.m1BHOq5a008341@zion.cs.uiuc.edu> Author: kremenek Date: Mon Feb 11 11:24:50 2008 New Revision: 46957 URL: http://llvm.org/viewvc/llvm-project?rev=46957&view=rev Log: Added "Profile" method to APFloat for use with FoldingSet. Added member template "Add" to FoldingSetNodeID that allows "adding" arbitrary objects to a profile via dispatch to FoldingSetTrait::Profile(). Removed FoldingSetNodeID::AddAPFloat and FoldingSetNodeID::APInt, as their functionality is now replaced using the above mentioned member template. Modified: llvm/trunk/include/llvm/ADT/APFloat.h llvm/trunk/include/llvm/ADT/FoldingSet.h llvm/trunk/include/llvm/Support/AlignOf.h llvm/trunk/lib/CodeGen/SelectionDAG/SelectionDAG.cpp llvm/trunk/lib/Support/APFloat.cpp llvm/trunk/lib/Support/FoldingSet.cpp Modified: llvm/trunk/include/llvm/ADT/APFloat.h URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/include/llvm/ADT/APFloat.h?rev=46957&r1=46956&r2=46957&view=diff ============================================================================== --- llvm/trunk/include/llvm/ADT/APFloat.h (original) +++ llvm/trunk/include/llvm/ADT/APFloat.h Mon Feb 11 11:24:50 2008 @@ -181,6 +181,10 @@ APFloat(const APFloat &); ~APFloat(); + /// Profile - Used to insert APFloat objects, or objects that contain + /// APFloat objects, into FoldingSets. + void Profile(FoldingSetNodeID& NID) const; + /// @brief Used by the Bitcode serializer to emit APInts to Bitcode. void Emit(Serializer& S) const; Modified: llvm/trunk/include/llvm/ADT/FoldingSet.h URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/include/llvm/ADT/FoldingSet.h?rev=46957&r1=46956&r2=46957&view=diff ============================================================================== --- llvm/trunk/include/llvm/ADT/FoldingSet.h (original) +++ llvm/trunk/include/llvm/ADT/FoldingSet.h Mon Feb 11 11:24:50 2008 @@ -178,6 +178,19 @@ virtual void GetNodeProfile(FoldingSetNodeID &ID, Node *N) const = 0; }; +//===----------------------------------------------------------------------===// +/// FoldingSetTrait - This trait class is used to define behavior of how +/// to "profile" (in the FoldingSet parlance) an object of a given type. +/// The default behavior is to invoke a 'Profile' method on an object, but +/// through template specialization the behavior can be tailored for specific +/// types. Combined with the FoldingSetNodeWrapper classs, one can add objects +/// to FoldingSets that were not originally designed to have that behavior. +/// +template struct FoldingSetTrait { + static inline void Profile(const T& X, FoldingSetNodeID& ID) { X.Profile(ID);} + static inline void Profile(T& X, FoldingSetNodeID& ID) { X.Profile(ID); } +}; + //===--------------------------------------------------------------------===// /// FoldingSetNodeID - This class is used to gather all the unique data bits of /// a node. When all the bits are gathered this class is used to produce a @@ -206,10 +219,11 @@ void AddInteger(uint64_t I); void AddFloat(float F); void AddDouble(double D); - void AddAPFloat(const APFloat& apf); - void AddAPInt(const APInt& api); void AddString(const std::string &String); + template + inline void Add(const T& x) { FoldingSetTrait::Profile(x, *this); } + /// clear - Clear the accumulated profile, allowing this FoldingSetNodeID /// object to be used to compute a new profile. inline void clear() { Bits.clear(); } @@ -227,19 +241,6 @@ typedef FoldingSetImpl::Node FoldingSetNode; template class FoldingSetIterator; template class FoldingSetBucketIterator; - -//===----------------------------------------------------------------------===// -/// FoldingSetTrait - This trait class is used to define behavior of how -/// to "profile" (in the FoldingSet parlance) an object of a given type. -/// The default behavior is to invoke a 'Profile' method on an object, but -/// through template specialization the behavior can be tailored for specific -/// types. Combined with the FoldingSetNodeWrapper classs, one can add objects -/// to FoldingSets that were not originally designed to have that behavior. -/// -template struct FoldingSetTrait { - static inline void Profile(const T& X, FoldingSetNodeID& ID) { X.Profile(ID);} - static inline void Profile(T& X, FoldingSetNodeID& ID) { X.Profile(ID); } -}; //===----------------------------------------------------------------------===// /// FoldingSet - This template class is used to instantiate a specialized Modified: llvm/trunk/include/llvm/Support/AlignOf.h URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/include/llvm/Support/AlignOf.h?rev=46957&r1=46956&r2=46957&view=diff ============================================================================== --- llvm/trunk/include/llvm/Support/AlignOf.h (original) +++ llvm/trunk/include/llvm/Support/AlignOf.h Mon Feb 11 11:24:50 2008 @@ -35,6 +35,10 @@ template struct AlignOf { enum { Alignment = sizeof(AlignmentCalcImpl) - sizeof(T) }; + enum { Alignment_GreaterEqual_2Bytes = Alignment >= 2 ? 1 : 0 }; + enum { Alignment_GreaterEqual_4Bytes = Alignment >= 4 ? 1 : 0 }; + enum { Alignment_GreaterEqual_8Bytes = Alignment >= 8 ? 1 : 0 }; + enum { Alignment_GreaterEqual_16Bytes = Alignment >= 16 ? 1 : 0 }; }; /// alignof - A templated function that returns the mininum alignment of Modified: llvm/trunk/lib/CodeGen/SelectionDAG/SelectionDAG.cpp URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/lib/CodeGen/SelectionDAG/SelectionDAG.cpp?rev=46957&r1=46956&r2=46957&view=diff ============================================================================== --- llvm/trunk/lib/CodeGen/SelectionDAG/SelectionDAG.cpp (original) +++ llvm/trunk/lib/CodeGen/SelectionDAG/SelectionDAG.cpp Mon Feb 11 11:24:50 2008 @@ -344,7 +344,7 @@ break; case ISD::TargetConstantFP: case ISD::ConstantFP: { - ID.AddAPFloat(cast(N)->getValueAPF()); + ID.Add(cast(N)->getValueAPF()); break; } case ISD::TargetGlobalAddress: @@ -724,7 +724,7 @@ unsigned Opc = isT ? ISD::TargetConstant : ISD::Constant; FoldingSetNodeID ID; AddNodeIDNode(ID, Opc, getVTList(EltVT), 0, 0); - ID.AddAPInt(Val); + ID.Add(Val); void *IP = 0; SDNode *N = NULL; if ((N = CSEMap.FindNodeOrInsertPos(ID, IP))) @@ -763,7 +763,7 @@ unsigned Opc = isTarget ? ISD::TargetConstantFP : ISD::ConstantFP; FoldingSetNodeID ID; AddNodeIDNode(ID, Opc, getVTList(EltVT), 0, 0); - ID.AddAPFloat(V); + ID.Add(V); void *IP = 0; SDNode *N = NULL; if ((N = CSEMap.FindNodeOrInsertPos(ID, IP))) Modified: llvm/trunk/lib/Support/APFloat.cpp URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/lib/Support/APFloat.cpp?rev=46957&r1=46956&r2=46957&view=diff ============================================================================== --- llvm/trunk/lib/Support/APFloat.cpp (original) +++ llvm/trunk/lib/Support/APFloat.cpp Mon Feb 11 11:24:50 2008 @@ -13,6 +13,7 @@ //===----------------------------------------------------------------------===// #include "llvm/ADT/APFloat.h" +#include "llvm/ADT/FoldingSet.h" #include #include #include "llvm/Support/MathExtras.h" @@ -691,6 +692,11 @@ freeSignificand(); } +// Profile - This method 'profiles' an APFloat for use with FoldingSet. +void APFloat::Profile(FoldingSetNodeID& ID) const { + ID.Add(convertToAPInt()); +} + unsigned int APFloat::partCount() const { Modified: llvm/trunk/lib/Support/FoldingSet.cpp URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/lib/Support/FoldingSet.cpp?rev=46957&r1=46956&r2=46957&view=diff ============================================================================== --- llvm/trunk/lib/Support/FoldingSet.cpp (original) +++ llvm/trunk/lib/Support/FoldingSet.cpp Mon Feb 11 11:24:50 2008 @@ -15,8 +15,6 @@ //===----------------------------------------------------------------------===// #include "llvm/ADT/FoldingSet.h" -#include "llvm/ADT/APFloat.h" -#include "llvm/ADT/APInt.h" #include "llvm/Support/MathExtras.h" #include using namespace llvm; @@ -58,15 +56,6 @@ void FoldingSetNodeID::AddDouble(double D) { AddInteger(DoubleToBits(D)); } -void FoldingSetNodeID::AddAPFloat(const APFloat& apf) { - APInt api = apf.convertToAPInt(); - AddAPInt(api); -} -void FoldingSetNodeID::AddAPInt(const APInt& api) { - const uint64_t *p = api.getRawData(); - for (unsigned i=0; i Author: johannes Date: Mon Feb 11 12:03:06 2008 New Revision: 46958 URL: http://llvm.org/viewvc/llvm-project?rev=46958&view=rev Log: Choose an SSE vector-containing type for the constructed type that represents a union, if the union contains such a type. Modified: llvm-gcc-4.2/trunk/gcc/config/i386/llvm-i386-target.h llvm-gcc-4.2/trunk/gcc/llvm-types.cpp Modified: llvm-gcc-4.2/trunk/gcc/config/i386/llvm-i386-target.h URL: http://llvm.org/viewvc/llvm-project/llvm-gcc-4.2/trunk/gcc/config/i386/llvm-i386-target.h?rev=46958&r1=46957&r2=46958&view=diff ============================================================================== --- llvm-gcc-4.2/trunk/gcc/config/i386/llvm-i386-target.h (original) +++ llvm-gcc-4.2/trunk/gcc/config/i386/llvm-i386-target.h Mon Feb 11 12:03:06 2008 @@ -83,6 +83,15 @@ } \ } +/* Aggregates containing SSE vectors are aligned at 16 bytes as parameters; + while long double has GCC alignment of 16 bytes (correct for struct layout) + but is only 4 byte aligned as a parameter. So if a union type contains an + SSE vector, use that as the basis for the constructed LLVM struct. */ +#define TARGET_LLVM_COMPARE_UNION_FIELDS(curType, newType, curAlign, newAlign) \ + (newAlign==curAlign && TARGET_SSE && \ + TheTarget->getTargetLowering()->getByValTypeAlignment(newType) > \ + TheTarget->getTargetLowering()->getByValTypeAlignment(curType)) + #ifdef LLVM_ABI_H extern bool llvm_x86_should_pass_aggregate_in_memory(tree, const Type *); Modified: llvm-gcc-4.2/trunk/gcc/llvm-types.cpp URL: http://llvm.org/viewvc/llvm-project/llvm-gcc-4.2/trunk/gcc/llvm-types.cpp?rev=46958&r1=46957&r2=46958&view=diff ============================================================================== --- llvm-gcc-4.2/trunk/gcc/llvm-types.cpp (original) +++ llvm-gcc-4.2/trunk/gcc/llvm-types.cpp Mon Feb 11 12:03:06 2008 @@ -33,6 +33,7 @@ #include "llvm/TypeSymbolTable.h" #include "llvm/Target/TargetData.h" #include "llvm/Target/TargetMachine.h" +#include "llvm/Target/TargetLowering.h" #include "llvm/Assembly/Writer.h" #include "llvm/ADT/DenseMap.h" #include "llvm/ADT/StringExtras.h" @@ -1137,7 +1138,7 @@ // 'sret' functions cannot be 'readnone' or 'readonly'. if (ABIConverter.isStructReturn()) RAttributes &= ~(ParamAttr::ReadNone|ParamAttr::ReadOnly); - + // Compute whether the result needs to be zext or sext'd. RAttributes |= HandleArgumentExtension(TREE_TYPE(type)); @@ -2124,6 +2125,8 @@ /// ConvertUNION - We know that 'type' is a UNION_TYPE or a QUAL_UNION_TYPE: /// convert it to an LLVM type. +/// This involves creating a struct with the right size and alignment. In +/// some cases this is target dependent. const Type *TypeConverter::ConvertUNION(tree type, tree orig_type) { if (const Type *Ty = GET_TYPE_LLVM(type)) { // If we already compiled this type, and if it was not a forward @@ -2170,17 +2173,25 @@ // Select TheTy as union type if it meets one of the following criteria // 1) UnionTy is 0 // 2) TheTy alignment is more then UnionTy - // 3) TheTy size is greater than UnionTy size and TheTy alignment is equal to UnionTy + // 3) TheTy size is greater than UnionTy size and TheTy alignment is equal + // to UnionTy // 4) TheTy size is greater then UnionTy size and TheTy is packed + // FIXME there is no check for packed? bool useTheTy = false; if (UnionTy == 0) useTheTy = true; else if (Align > MaxAlign) useTheTy = true; +#ifdef TARGET_LLVM_COMPARE_UNION_FIELDS + else + useTheTy = TARGET_LLVM_COMPARE_UNION_FIELDS(UnionTy, TheTy, + Align, MaxAlign); +#else else if (MaxAlign == Align && Size > MaxSize) useTheTy = true; - else if (Size > MaxSize) + else if (Size > MaxSize) // FIXME really? Seems wrong to lower alignment useTheTy = true; +#endif if (useTheTy) { UnionTy = TheTy; From gohman at apple.com Mon Feb 11 12:04:09 2008 From: gohman at apple.com (Dan Gohman) Date: Mon, 11 Feb 2008 10:04:09 -0800 Subject: [llvm-commits] [llvm] r46850 - in /llvm/trunk: lib/Target/X86/X86ISelDAGToDAG.cpp lib/Target/X86/X86Instr64bit.td lib/Target/X86/X86InstrInfo.td lib/Target/X86/X86Subtarget.cpp lib/Target/X86/X86Subtarget.h test/CodeGen/X86/pic_jumptable.ll test/CodeGen/X86/x86-64-gv-offset.ll In-Reply-To: <200802070853.m178rosx029306@zion.cs.uiuc.edu> References: <200802070853.m178rosx029306@zion.cs.uiuc.edu> Message-ID: <38219D50-9CFE-4520-8668-065EB6DD15C9@apple.com> Hi Evan, This breaks these: test/CodeGen/X86/fold-mul-lohi.ll test/CodeGen/X86/stride-nine-with-base-reg.ll test/CodeGen/X86/stride-reuse.ll on Linux. These tests should probably explicitly set the relocation model to static so that they always test what they're intended to test. Dan On Feb 7, 2008, at 12:53 AM, Evan Cheng wrote: > Author: evancheng > Date: Thu Feb 7 02:53:49 2008 > New Revision: 46850 > > URL: http://llvm.org/viewvc/llvm-project?rev=46850&view=rev > Log: > Fix a x86-64 codegen deficiency. Allow gv + offset when using rip > addressing mode. > Before: > _main: > subq $8, %rsp > leaq _X(%rip), %rax > movsd 8(%rax), %xmm1 > movss _X(%rip), %xmm0 > call _t > xorl %ecx, %ecx > movl %ecx, %eax > addq $8, %rsp > ret > Now: > _main: > subq $8, %rsp > movsd _X+8(%rip), %xmm1 > movss _X(%rip), %xmm0 > call _t > xorl %ecx, %ecx > movl %ecx, %eax > addq $8, %rsp > ret > > Notice there is another idiotic codegen issue that needs to be fixed > asap: > xorl %ecx, %ecx > movl %ecx, %eax > > Added: > llvm/trunk/test/CodeGen/X86/x86-64-gv-offset.ll > Modified: > llvm/trunk/lib/Target/X86/X86ISelDAGToDAG.cpp > llvm/trunk/lib/Target/X86/X86Instr64bit.td > llvm/trunk/lib/Target/X86/X86InstrInfo.td > llvm/trunk/lib/Target/X86/X86Subtarget.cpp > llvm/trunk/lib/Target/X86/X86Subtarget.h > llvm/trunk/test/CodeGen/X86/pic_jumptable.ll > > Modified: llvm/trunk/lib/Target/X86/X86ISelDAGToDAG.cpp > URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/lib/Target/X86/X86ISelDAGToDAG.cpp?rev=46850&r1=46849&r2=46850&view=diff > > = > = > = > = > = > = > = > = > ====================================================================== > --- llvm/trunk/lib/Target/X86/X86ISelDAGToDAG.cpp (original) > +++ llvm/trunk/lib/Target/X86/X86ISelDAGToDAG.cpp Thu Feb 7 > 02:53:49 2008 > @@ -63,7 +63,7 @@ > int FrameIndex; > } Base; > > - bool isRIPRel; // RIP relative? > + bool isRIPRel; // RIP as base? > unsigned Scale; > SDOperand IndexReg; > unsigned Disp; > @@ -664,7 +664,9 @@ > case X86ISD::Wrapper: { > bool is64Bit = Subtarget->is64Bit(); > // Under X86-64 non-small code model, GV (and friends) are 64- > bits. > - if (is64Bit && TM.getCodeModel() != CodeModel::Small) > + // Also, base and index reg must be 0 in order to use rip as > base. > + if (is64Bit && (TM.getCodeModel() != CodeModel::Small || > + AM.Base.Reg.Val || AM.IndexReg.Val)) > break; > if (AM.GV != 0 || AM.CP != 0 || AM.ES != 0 || AM.JT != -1) > break; > @@ -672,39 +674,27 @@ > // been picked, we can't fit the result available in the > register in the > // addressing mode. Duplicate GlobalAddress or ConstantPool as > displacement. > if (!AlreadySelected || (AM.Base.Reg.Val && AM.IndexReg.Val)) { > - bool isStatic = TM.getRelocationModel() == Reloc::Static; > SDOperand N0 = N.getOperand(0); > - // Mac OS X X86-64 lower 4G address is not available. > - bool isAbs32 = !is64Bit || > - (isStatic && Subtarget->hasLow4GUserSpaceAddress()); > if (GlobalAddressSDNode *G = > dyn_cast(N0)) { > GlobalValue *GV = G->getGlobal(); > - if (isAbs32 || isRoot) { > - AM.GV = GV; > - AM.Disp += G->getOffset(); > - AM.isRIPRel = !isAbs32; > - return false; > - } > + AM.GV = GV; > + AM.Disp += G->getOffset(); > + AM.isRIPRel = is64Bit; > + return false; > } else if (ConstantPoolSDNode *CP = > dyn_cast(N0)) { > - if (isAbs32 || isRoot) { > - AM.CP = CP->getConstVal(); > - AM.Align = CP->getAlignment(); > - AM.Disp += CP->getOffset(); > - AM.isRIPRel = !isAbs32; > - return false; > - } > + AM.CP = CP->getConstVal(); > + AM.Align = CP->getAlignment(); > + AM.Disp += CP->getOffset(); > + AM.isRIPRel = is64Bit; > + return false; > } else if (ExternalSymbolSDNode *S > =dyn_cast(N0)) { > - if (isAbs32 || isRoot) { > - AM.ES = S->getSymbol(); > - AM.isRIPRel = !isAbs32; > - return false; > - } > + AM.ES = S->getSymbol(); > + AM.isRIPRel = is64Bit; > + return false; > } else if (JumpTableSDNode *J = dyn_cast(N0)) { > - if (isAbs32 || isRoot) { > - AM.JT = J->getIndex(); > - AM.isRIPRel = !isAbs32; > - return false; > - } > + AM.JT = J->getIndex(); > + AM.isRIPRel = is64Bit; > + return false; > } > } > break; > @@ -719,7 +709,7 @@ > break; > > case ISD::SHL: > - if (AlreadySelected || AM.IndexReg.Val != 0 || AM.Scale != 1) > + if (AlreadySelected || AM.IndexReg.Val != 0 || AM.Scale != 1 || > AM.isRIPRel) > break; > > if (ConstantSDNode *CN = dyn_cast(N.Val- > >getOperand(1))) { > @@ -759,7 +749,8 @@ > if (!AlreadySelected && > AM.BaseType == X86ISelAddressMode::RegBase && > AM.Base.Reg.Val == 0 && > - AM.IndexReg.Val == 0) { > + AM.IndexReg.Val == 0 && > + !AM.isRIPRel) { > if (ConstantSDNode *CN = dyn_cast(N.Val- > >getOperand(1))) > if (CN->getValue() == 3 || CN->getValue() == 5 || CN- > >getValue() == 9) { > AM.Scale = unsigned(CN->getValue())-1; > @@ -834,6 +825,9 @@ > > // Scale must not be used already. > if (AM.IndexReg.Val != 0 || AM.Scale != 1) break; > + > + // Not when RIP is used as the base. > + if (AM.isRIPRel) break; > > ConstantSDNode *C2 = dyn_cast(N.getOperand(1)); > ConstantSDNode *C1 = > dyn_cast(Shift.getOperand(1)); > @@ -874,7 +868,7 @@ > // Is the base register already occupied? > if (AM.BaseType != X86ISelAddressMode::RegBase || AM.Base.Reg.Val) { > // If so, check to see if the scale index register is set. > - if (AM.IndexReg.Val == 0) { > + if (AM.IndexReg.Val == 0 && !AM.isRIPRel) { > AM.IndexReg = N; > AM.Scale = 1; > return false; > > Modified: llvm/trunk/lib/Target/X86/X86Instr64bit.td > URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/lib/Target/X86/X86Instr64bit.td?rev=46850&r1=46849&r2=46850&view=diff > > = > = > = > = > = > = > = > = > ====================================================================== > --- llvm/trunk/lib/Target/X86/X86Instr64bit.td (original) > +++ llvm/trunk/lib/Target/X86/X86Instr64bit.td Thu Feb 7 02:53:49 > 2008 > @@ -1125,16 +1125,16 @@ > > def : Pat<(store (i64 (X86Wrapper tconstpool:$src)), addr:$dst), > (MOV64mi32 addr:$dst, tconstpool:$src)>, > - Requires<[SmallCode, HasLow4G, IsStatic]>; > + Requires<[SmallCode, IsStatic]>; > def : Pat<(store (i64 (X86Wrapper tjumptable:$src)), addr:$dst), > (MOV64mi32 addr:$dst, tjumptable:$src)>, > - Requires<[SmallCode, HasLow4G, IsStatic]>; > + Requires<[SmallCode, IsStatic]>; > def : Pat<(store (i64 (X86Wrapper tglobaladdr:$src)), addr:$dst), > (MOV64mi32 addr:$dst, tglobaladdr:$src)>, > - Requires<[SmallCode, HasLow4G, IsStatic]>; > + Requires<[SmallCode, IsStatic]>; > def : Pat<(store (i64 (X86Wrapper texternalsym:$src)), addr:$dst), > (MOV64mi32 addr:$dst, texternalsym:$src)>, > - Requires<[SmallCode, HasLow4G, IsStatic]>; > + Requires<[SmallCode, IsStatic]>; > > // Calls > // Direct PC relative function call for small code model. 32-bit > displacement > > Modified: llvm/trunk/lib/Target/X86/X86InstrInfo.td > URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/lib/Target/X86/X86InstrInfo.td?rev=46850&r1=46849&r2=46850&view=diff > > = > = > = > = > = > = > = > = > ====================================================================== > --- llvm/trunk/lib/Target/X86/X86InstrInfo.td (original) > +++ llvm/trunk/lib/Target/X86/X86InstrInfo.td Thu Feb 7 02:53:49 2008 > @@ -172,7 +172,6 @@ > def FPStackf64 : Predicate<"!Subtarget->hasSSE2()">; > def In32BitMode : Predicate<"!Subtarget->is64Bit()">; > def In64BitMode : Predicate<"Subtarget->is64Bit()">; > -def HasLow4G : Predicate<"Subtarget- > >hasLow4GUserSpaceAddress()">; > def SmallCode : Predicate<"TM.getCodeModel() == CodeModel::Small">; > def NotSmallCode : Predicate<"TM.getCodeModel() != CodeModel::Small">; > def IsStatic : Predicate<"TM.getRelocationModel() == > Reloc::Static">; > > Modified: llvm/trunk/lib/Target/X86/X86Subtarget.cpp > URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/lib/Target/X86/X86Subtarget.cpp?rev=46850&r1=46849&r2=46850&view=diff > > = > = > = > = > = > = > = > = > ====================================================================== > --- llvm/trunk/lib/Target/X86/X86Subtarget.cpp (original) > +++ llvm/trunk/lib/Target/X86/X86Subtarget.cpp Thu Feb 7 02:53:49 > 2008 > @@ -228,7 +228,6 @@ > // FIXME: this is a known good value for Yonah. How about others? > , MaxInlineSizeThreshold(128) > , Is64Bit(is64Bit) > - , HasLow4GUserAddress(true) > , TargetType(isELF) { // Default to ELF unless otherwise specified. > > // Determine default and user specified characteristics > @@ -300,9 +299,6 @@ > ? X86Subtarget::Intel : X86Subtarget::ATT; > } > > - if (TargetType == isDarwin && Is64Bit) > - HasLow4GUserAddress = false; > - > if (TargetType == isDarwin || > TargetType == isCygwin || > TargetType == isMingw || > > Modified: llvm/trunk/lib/Target/X86/X86Subtarget.h > URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/lib/Target/X86/X86Subtarget.h?rev=46850&r1=46849&r2=46850&view=diff > > = > = > = > = > = > = > = > = > ====================================================================== > --- llvm/trunk/lib/Target/X86/X86Subtarget.h (original) > +++ llvm/trunk/lib/Target/X86/X86Subtarget.h Thu Feb 7 02:53:49 2008 > @@ -82,10 +82,6 @@ > /// pointer size is 64 bit. > bool Is64Bit; > > - /// HasLow4GUserAddress - True if the low 4G user-space address > is available. > - /// > - bool HasLow4GUserAddress; > - > public: > enum { > isELF, isCygwin, isDarwin, isWindows, isMingw > @@ -115,10 +111,6 @@ > > bool is64Bit() const { return Is64Bit; } > > - /// hasLow4GUserSpaceAddress - True if lower 4G user-space > address is > - /// available. > - bool hasLow4GUserSpaceAddress() const { return > HasLow4GUserAddress; } > - > PICStyle::Style getPICStyle() const { return PICStyle; } > void setPICStyle(PICStyle::Style Style) { PICStyle = Style; } > > > Modified: llvm/trunk/test/CodeGen/X86/pic_jumptable.ll > URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/test/CodeGen/X86/pic_jumptable.ll?rev=46850&r1=46849&r2=46850&view=diff > > = > = > = > = > = > = > = > = > ====================================================================== > --- llvm/trunk/test/CodeGen/X86/pic_jumptable.ll (original) > +++ llvm/trunk/test/CodeGen/X86/pic_jumptable.ll Thu Feb 7 02:53:49 > 2008 > @@ -1,36 +1,35 @@ > -; RUN: llvm-upgrade < %s | llvm-as | llc -relocation-model=pic - > mtriple=i386-linux-gnu | not grep -F .text > -; RUN: llvm-upgrade < %s | llvm-as | llc -relocation-model=pic - > mtriple=i686-apple-darwin | not grep lea > +; RUN: llvm-as < %s | llc -relocation-model=pic -mtriple=i386-linux- > gnu | not grep -F .text > +; RUN: llvm-as < %s | llc -relocation-model=pic -mtriple=i686-apple- > darwin | not grep lea > +; RUN: llvm-as < %s | llc -relocation-model=pic -mtriple=i686-apple- > darwin | grep add | count 2 > > -implementation ; Functions: > +declare void @_Z3bari(i32) > > -declare void %_Z3bari( int ) > - > -linkonce void %_Z3fooILi1EEvi(int %Y) { > +define linkonce void @_Z3fooILi1EEvi(i32 %Y) { > entry: > - %Y_addr = alloca int ; [#uses=2] > - "alloca point" = cast int 0 to int ; [#uses=0] > - store int %Y, int* %Y_addr > - %tmp = load int* %Y_addr ; [#uses=1] > - switch int %tmp, label %bb10 [ > - int 0, label %bb3 > - int 1, label %bb > - int 2, label %bb > - int 3, label %bb > - int 4, label %bb > - int 5, label %bb > - int 6, label %bb > - int 7, label %bb > - int 8, label %bb > - int 9, label %bb > - int 10, label %bb > - int 12, label %bb1 > - int 13, label %bb5 > - int 14, label %bb6 > - int 16, label %bb2 > - int 17, label %bb4 > - int 23, label %bb8 > - int 27, label %bb7 > - int 34, label %bb9 > + %Y_addr = alloca i32 ; [#uses=2] > + %"alloca point" = bitcast i32 0 to i32 ; [#uses=0] > + store i32 %Y, i32* %Y_addr > + %tmp = load i32* %Y_addr ; [#uses=1] > + switch i32 %tmp, label %bb10 [ > + i32 0, label %bb3 > + i32 1, label %bb > + i32 2, label %bb > + i32 3, label %bb > + i32 4, label %bb > + i32 5, label %bb > + i32 6, label %bb > + i32 7, label %bb > + i32 8, label %bb > + i32 9, label %bb > + i32 10, label %bb > + i32 12, label %bb1 > + i32 13, label %bb5 > + i32 14, label %bb6 > + i32 16, label %bb2 > + i32 17, label %bb4 > + i32 23, label %bb8 > + i32 27, label %bb7 > + i32 34, label %bb9 > ] > > bb: ; preds = %entry, %entry, %entry, %entry, %entry, %entry, > %entry, %entry, %entry, %entry > @@ -40,7 +39,7 @@ > br label %bb2 > > bb2: ; preds = %bb1, %entry > - call void %_Z3bari( int 1 ) > + call void @_Z3bari( i32 1 ) > br label %bb11 > > bb3: ; preds = %entry > @@ -53,7 +52,7 @@ > br label %bb6 > > bb6: ; preds = %bb5, %entry > - call void %_Z3bari( int 2 ) > + call void @_Z3bari( i32 2 ) > br label %bb11 > > bb7: ; preds = %entry > @@ -63,7 +62,7 @@ > br label %bb9 > > bb9: ; preds = %bb8, %entry > - call void %_Z3bari( int 3 ) > + call void @_Z3bari( i32 3 ) > br label %bb11 > > bb10: ; preds = %entry > > Added: llvm/trunk/test/CodeGen/X86/x86-64-gv-offset.ll > URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/test/CodeGen/X86/x86-64-gv-offset.ll?rev=46850&view=auto > > = > = > = > = > = > = > = > = > ====================================================================== > --- llvm/trunk/test/CodeGen/X86/x86-64-gv-offset.ll (added) > +++ llvm/trunk/test/CodeGen/X86/x86-64-gv-offset.ll Thu Feb 7 > 02:53:49 2008 > @@ -0,0 +1,14 @@ > +; RUN: llvm-as < %s | llc -mtriple=x86_64-apple-darwin | not grep lea > + > + %struct.x = type { float, double } > + at X = global %struct.x { float 1.000000e+00, double 2.000000e+00 }, > align 16 ; <%struct.x*> [#uses=2] > + > +define i32 @main() nounwind { > +entry: > + %tmp2 = load float* getelementptr (%struct.x* @X, i32 0, i32 0), > align 16 ; [#uses=1] > + %tmp4 = load double* getelementptr (%struct.x* @X, i32 0, i32 1), > align 8 ; [#uses=1] > + tail call void @t( float %tmp2, double %tmp4 ) nounwind > + ret i32 0 > +} > + > +declare void @t(float, double) > > > _______________________________________________ > llvm-commits mailing list > llvm-commits at cs.uiuc.edu > http://lists.cs.uiuc.edu/mailman/listinfo/llvm-commits From dalej at apple.com Mon Feb 11 12:15:47 2008 From: dalej at apple.com (Dale Johannesen) Date: Mon, 11 Feb 2008 10:15:47 -0800 Subject: [llvm-commits] [llvm-gcc-4.2] r46958 - in /llvm-gcc-4.2/trunk/gcc: config/i386/llvm-i386-target.h llvm-types.cpp In-Reply-To: <200802111803.m1BI37vh009539@zion.cs.uiuc.edu> References: <200802111803.m1BI37vh009539@zion.cs.uiuc.edu> Message-ID: This fixes an ABI issue with unions on i386 (Darwin for sure, and I hope Linux as well). I believe the FIXMEs I added indicate a latent bug, but I'm not sure what the intent was, so could whoever wrote this code originally take a look? (As an aside, assuming that there is a struct type that gets passed the same way as any union type strikes me as dangerous. I don't think there's any reason such a struct needs to exist.) On Feb 11, 2008, at 10:03 AM, Dale Johannesen wrote: > Author: johannes > Date: Mon Feb 11 12:03:06 2008 > New Revision: 46958 > > URL: http://llvm.org/viewvc/llvm-project?rev=46958&view=rev > Log: > Choose an SSE vector-containing type for the constructed > type that represents a union, if the union contains such > a type. > > > Modified: > llvm-gcc-4.2/trunk/gcc/config/i386/llvm-i386-target.h > llvm-gcc-4.2/trunk/gcc/llvm-types.cpp > > Modified: llvm-gcc-4.2/trunk/gcc/config/i386/llvm-i386-target.h > URL: http://llvm.org/viewvc/llvm-project/llvm-gcc-4.2/trunk/gcc/config/i386/llvm-i386-target.h?rev=46958&r1=46957&r2=46958&view=diff > > = > = > = > = > = > = > = > = > ====================================================================== > --- llvm-gcc-4.2/trunk/gcc/config/i386/llvm-i386-target.h (original) > +++ llvm-gcc-4.2/trunk/gcc/config/i386/llvm-i386-target.h Mon Feb 11 > 12:03:06 2008 > @@ -83,6 +83,15 @@ > } \ > } > > +/* Aggregates containing SSE vectors are aligned at 16 bytes as > parameters; > + while long double has GCC alignment of 16 bytes (correct for > struct layout) > + but is only 4 byte aligned as a parameter. So if a union type > contains an > + SSE vector, use that as the basis for the constructed LLVM > struct. */ > +#define TARGET_LLVM_COMPARE_UNION_FIELDS(curType, newType, > curAlign, newAlign) \ > + (newAlign==curAlign && TARGET_SSE > && \ > + TheTarget->getTargetLowering()->getByValTypeAlignment(newType) > > \ > + TheTarget->getTargetLowering()->getByValTypeAlignment(curType)) > + > #ifdef LLVM_ABI_H > extern bool llvm_x86_should_pass_aggregate_in_memory(tree, const > Type *); > > > Modified: llvm-gcc-4.2/trunk/gcc/llvm-types.cpp > URL: http://llvm.org/viewvc/llvm-project/llvm-gcc-4.2/trunk/gcc/llvm-types.cpp?rev=46958&r1=46957&r2=46958&view=diff > > = > = > = > = > = > = > = > = > ====================================================================== > --- llvm-gcc-4.2/trunk/gcc/llvm-types.cpp (original) > +++ llvm-gcc-4.2/trunk/gcc/llvm-types.cpp Mon Feb 11 12:03:06 2008 > @@ -33,6 +33,7 @@ > #include "llvm/TypeSymbolTable.h" > #include "llvm/Target/TargetData.h" > #include "llvm/Target/TargetMachine.h" > +#include "llvm/Target/TargetLowering.h" > #include "llvm/Assembly/Writer.h" > #include "llvm/ADT/DenseMap.h" > #include "llvm/ADT/StringExtras.h" > @@ -1137,7 +1138,7 @@ > // 'sret' functions cannot be 'readnone' or 'readonly'. > if (ABIConverter.isStructReturn()) > RAttributes &= ~(ParamAttr::ReadNone|ParamAttr::ReadOnly); > - > + > // Compute whether the result needs to be zext or sext'd. > RAttributes |= HandleArgumentExtension(TREE_TYPE(type)); > > @@ -2124,6 +2125,8 @@ > > /// ConvertUNION - We know that 'type' is a UNION_TYPE or a > QUAL_UNION_TYPE: > /// convert it to an LLVM type. > +/// This involves creating a struct with the right size and > alignment. In > +/// some cases this is target dependent. > const Type *TypeConverter::ConvertUNION(tree type, tree orig_type) { > if (const Type *Ty = GET_TYPE_LLVM(type)) { > // If we already compiled this type, and if it was not a forward > @@ -2170,17 +2173,25 @@ > // Select TheTy as union type if it meets one of the following > criteria > // 1) UnionTy is 0 > // 2) TheTy alignment is more then UnionTy > - // 3) TheTy size is greater than UnionTy size and TheTy > alignment is equal to UnionTy > + // 3) TheTy size is greater than UnionTy size and TheTy > alignment is equal > + // to UnionTy > // 4) TheTy size is greater then UnionTy size and TheTy is packed > + // FIXME there is no check for packed? > bool useTheTy = false; > if (UnionTy == 0) > useTheTy = true; > else if (Align > MaxAlign) > useTheTy = true; > +#ifdef TARGET_LLVM_COMPARE_UNION_FIELDS > + else > + useTheTy = TARGET_LLVM_COMPARE_UNION_FIELDS(UnionTy, TheTy, > + Align, MaxAlign); > +#else > else if (MaxAlign == Align && Size > MaxSize) > useTheTy = true; > - else if (Size > MaxSize) > + else if (Size > MaxSize) // FIXME really? Seems wrong to > lower alignment > useTheTy = true; > +#endif > > if (useTheTy) { > UnionTy = TheTy; > > > _______________________________________________ > llvm-commits mailing list > llvm-commits at cs.uiuc.edu > http://lists.cs.uiuc.edu/mailman/listinfo/llvm-commits From wmatyjewicz at fastmail.fm Mon Feb 11 12:37:40 2008 From: wmatyjewicz at fastmail.fm (Wojciech Matyjewicz) Date: Mon, 11 Feb 2008 18:37:40 -0000 Subject: [llvm-commits] [llvm] r46959 - in /llvm/trunk: lib/Analysis/ScalarEvolution.cpp test/Analysis/ScalarEvolution/2008-02-11-ReversedCondition.ll Message-ID: <200802111837.m1BIbfdk010478@zion.cs.uiuc.edu> Author: wmat Date: Mon Feb 11 12:37:34 2008 New Revision: 46959 URL: http://llvm.org/viewvc/llvm-project?rev=46959&view=rev Log: If the LHS of the comparison is a loop-invariant we also want to move it to the RHS. This simple change allows to compute loop iteration count for loops with condition similar to the one in the testcase (which seems to be quite common). Added: llvm/trunk/test/Analysis/ScalarEvolution/2008-02-11-ReversedCondition.ll Modified: llvm/trunk/lib/Analysis/ScalarEvolution.cpp Modified: llvm/trunk/lib/Analysis/ScalarEvolution.cpp URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/lib/Analysis/ScalarEvolution.cpp?rev=46959&r1=46958&r2=46959&view=diff ============================================================================== --- llvm/trunk/lib/Analysis/ScalarEvolution.cpp (original) +++ llvm/trunk/lib/Analysis/ScalarEvolution.cpp Mon Feb 11 12:37:34 2008 @@ -1819,8 +1819,8 @@ // At this point, we would like to compute how many iterations of the // loop the predicate will return true for these inputs. - if (isa(LHS) && !isa(RHS)) { - // If there is a constant, force it into the RHS. + if (LHS->isLoopInvariant(L) && !RHS->isLoopInvariant(L)) { + // If there is a loop-invariant, force it into the RHS. std::swap(LHS, RHS); Cond = ICmpInst::getSwappedPredicate(Cond); } Added: llvm/trunk/test/Analysis/ScalarEvolution/2008-02-11-ReversedCondition.ll URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/test/Analysis/ScalarEvolution/2008-02-11-ReversedCondition.ll?rev=46959&view=auto ============================================================================== --- llvm/trunk/test/Analysis/ScalarEvolution/2008-02-11-ReversedCondition.ll (added) +++ llvm/trunk/test/Analysis/ScalarEvolution/2008-02-11-ReversedCondition.ll Mon Feb 11 12:37:34 2008 @@ -0,0 +1,15 @@ +; RUN: llvm-as < %s | opt -scalar-evolution -analyze | not grep Unpredictable + +define void @foo(i32 %n) { +entry: + br label %header +header: + %i = phi i32 [ 0, %entry ], [ %i.inc, %next ] + %cond = icmp sgt i32 %n, %i + br i1 %cond, label %next, label %return +next: + %i.inc = add i32 %i, 1 + br label %header +return: + ret void +} From gohman at apple.com Mon Feb 11 12:57:03 2008 From: gohman at apple.com (Dan Gohman) Date: Mon, 11 Feb 2008 18:57:03 -0000 Subject: [llvm-commits] [llvm] r46960 - /llvm/trunk/include/llvm/CodeGen/SelectionDAGNodes.h Message-ID: <200802111857.m1BIv6l6011006@zion.cs.uiuc.edu> Author: djg Date: Mon Feb 11 12:56:50 2008 New Revision: 46960 URL: http://llvm.org/viewvc/llvm-project?rev=46960&view=rev Log: >From Chris' review: change MemOperandSDNode's constructor to pass its argument by reference, rather than by value. Modified: llvm/trunk/include/llvm/CodeGen/SelectionDAGNodes.h Modified: llvm/trunk/include/llvm/CodeGen/SelectionDAGNodes.h URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/include/llvm/CodeGen/SelectionDAGNodes.h?rev=46960&r1=46959&r2=46960&view=diff ============================================================================== --- llvm/trunk/include/llvm/CodeGen/SelectionDAGNodes.h (original) +++ llvm/trunk/include/llvm/CodeGen/SelectionDAGNodes.h Mon Feb 11 12:56:50 2008 @@ -1425,7 +1425,7 @@ protected: friend class SelectionDAG; /// Create a MemOperand node - explicit MemOperandSDNode(MemOperand mo) + explicit MemOperandSDNode(const MemOperand &mo) : SDNode(ISD::MEMOPERAND, getSDVTList(MVT::Other)), MO(mo) {} public: From gohman at apple.com Mon Feb 11 12:57:44 2008 From: gohman at apple.com (Dan Gohman) Date: Mon, 11 Feb 2008 18:57:44 -0000 Subject: [llvm-commits] [llvm] r46961 - /llvm/trunk/lib/CodeGen/PseudoSourceValue.cpp Message-ID: <200802111857.m1BIviGM011035@zion.cs.uiuc.edu> Author: djg Date: Mon Feb 11 12:57:43 2008 New Revision: 46961 URL: http://llvm.org/viewvc/llvm-project?rev=46961&view=rev Log: >From Chris' review: fix 80 column violations Modified: llvm/trunk/lib/CodeGen/PseudoSourceValue.cpp Modified: llvm/trunk/lib/CodeGen/PseudoSourceValue.cpp URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/lib/CodeGen/PseudoSourceValue.cpp?rev=46961&r1=46960&r2=46961&view=diff ============================================================================== --- llvm/trunk/lib/CodeGen/PseudoSourceValue.cpp (original) +++ llvm/trunk/lib/CodeGen/PseudoSourceValue.cpp Mon Feb 11 12:57:43 2008 @@ -18,11 +18,16 @@ namespace llvm { static ManagedStatic PSVs; - const PseudoSourceValue *PseudoSourceValue::getFixedStack() { return &(*PSVs)[0]; } - const PseudoSourceValue *PseudoSourceValue::getStack() { return &(*PSVs)[1]; } - const PseudoSourceValue *PseudoSourceValue::getGOT() { return &(*PSVs)[2]; } - const PseudoSourceValue *PseudoSourceValue::getConstantPool() { return &(*PSVs)[3]; } - const PseudoSourceValue *PseudoSourceValue::getJumpTable() { return &(*PSVs)[4]; } + const PseudoSourceValue *PseudoSourceValue::getFixedStack() + { return &(*PSVs)[0]; } + const PseudoSourceValue *PseudoSourceValue::getStack() + { return &(*PSVs)[1]; } + const PseudoSourceValue *PseudoSourceValue::getGOT() + { return &(*PSVs)[2]; } + const PseudoSourceValue *PseudoSourceValue::getConstantPool() + { return &(*PSVs)[3]; } + const PseudoSourceValue *PseudoSourceValue::getJumpTable() + { return &(*PSVs)[4]; } static const char *PSVNames[] = { "FixedStack", From gohman at apple.com Mon Feb 11 12:58:43 2008 From: gohman at apple.com (Dan Gohman) Date: Mon, 11 Feb 2008 18:58:43 -0000 Subject: [llvm-commits] [llvm] r46962 - /llvm/trunk/lib/CodeGen/SelectionDAG/LegalizeDAG.cpp Message-ID: <200802111858.m1BIwhas011074@zion.cs.uiuc.edu> Author: djg Date: Mon Feb 11 12:58:42 2008 New Revision: 46962 URL: http://llvm.org/viewvc/llvm-project?rev=46962&view=rev Log: >From Chris' review: use cast instead of dyn_cast with an assert. Modified: llvm/trunk/lib/CodeGen/SelectionDAG/LegalizeDAG.cpp Modified: llvm/trunk/lib/CodeGen/SelectionDAG/LegalizeDAG.cpp URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/lib/CodeGen/SelectionDAG/LegalizeDAG.cpp?rev=46962&r1=46961&r2=46962&view=diff ============================================================================== --- llvm/trunk/lib/CodeGen/SelectionDAG/LegalizeDAG.cpp (original) +++ llvm/trunk/lib/CodeGen/SelectionDAG/LegalizeDAG.cpp Mon Feb 11 12:58:42 2008 @@ -1321,8 +1321,7 @@ MVT::ValueType PtrVT = TLI.getPointerTy(); SDOperand StackPtr = DAG.CreateStackTemporary(VT); - FrameIndexSDNode *StackPtrFI = dyn_cast(StackPtr.Val); - assert(StackPtrFI); + FrameIndexSDNode *StackPtrFI = cast(StackPtr.Val); int SPFI = StackPtrFI->getIndex(); // Store the vector. @@ -4759,8 +4758,7 @@ // Create the stack frame object. SDOperand FIPtr = DAG.CreateStackTemporary(SlotVT); - FrameIndexSDNode *StackPtrFI = dyn_cast(FIPtr); - assert(StackPtrFI); + FrameIndexSDNode *StackPtrFI = cast(FIPtr); int SPFI = StackPtrFI->getIndex(); unsigned SrcSize = MVT::getSizeInBits(SrcOp.getValueType()); @@ -4794,8 +4792,7 @@ // then load the whole vector back out. SDOperand StackPtr = DAG.CreateStackTemporary(Node->getValueType(0)); - FrameIndexSDNode *StackPtrFI = dyn_cast(StackPtr); - assert(StackPtrFI); + FrameIndexSDNode *StackPtrFI = cast(StackPtr); int SPFI = StackPtrFI->getIndex(); SDOperand Ch = DAG.getStore(DAG.getEntryNode(), Node->getOperand(0), StackPtr, @@ -6773,8 +6770,7 @@ // Lower to a store/load so that it can be split. // FIXME: this could be improved probably. SDOperand Ptr = DAG.CreateStackTemporary(InOp.getValueType()); - FrameIndexSDNode *FI = dyn_cast(Ptr.Val); - assert(FI && "Expecting CreateStackTemporary to return a frame index.\n"); + FrameIndexSDNode *FI = cast(Ptr.Val); SDOperand St = DAG.getStore(DAG.getEntryNode(), InOp, Ptr, From gohman at apple.com Mon Feb 11 13:00:05 2008 From: gohman at apple.com (Dan Gohman) Date: Mon, 11 Feb 2008 19:00:05 -0000 Subject: [llvm-commits] [llvm] r46963 - /llvm/trunk/lib/CodeGen/SelectionDAG/ScheduleDAG.cpp Message-ID: <200802111900.m1BJ05jE011128@zion.cs.uiuc.edu> Author: djg Date: Mon Feb 11 13:00:03 2008 New Revision: 46963 URL: http://llvm.org/viewvc/llvm-project?rev=46963&view=rev Log: >From Chris' review: minor corrections in comments. Modified: llvm/trunk/lib/CodeGen/SelectionDAG/ScheduleDAG.cpp Modified: llvm/trunk/lib/CodeGen/SelectionDAG/ScheduleDAG.cpp URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/lib/CodeGen/SelectionDAG/ScheduleDAG.cpp?rev=46963&r1=46962&r2=46963&view=diff ============================================================================== --- llvm/trunk/lib/CodeGen/SelectionDAG/ScheduleDAG.cpp (original) +++ llvm/trunk/lib/CodeGen/SelectionDAG/ScheduleDAG.cpp Mon Feb 11 13:00:03 2008 @@ -267,7 +267,7 @@ /// CountResults - The results of target nodes have register or immediate /// operands first, then an optional chain, and optional flag operands (which do -/// not go into the machine instrs.) +/// not go into the resulting MachineInstr). unsigned ScheduleDAG::CountResults(SDNode *Node) { unsigned N = Node->getNumValues(); while (N && Node->getValueType(N - 1) == MVT::Flag) @@ -279,7 +279,8 @@ /// CountOperands - The inputs to target nodes have any actual inputs first, /// followed by optional memory operands chain operand, then flag operands. -/// Compute the number of actual operands that will go into the machine istr. +/// Compute the number of actual operands that will go into the resulting +/// MachineInstr. unsigned ScheduleDAG::CountOperands(SDNode *Node) { unsigned N = Node->getNumOperands(); while (N && Node->getOperand(N - 1).getValueType() == MVT::Flag) From gohman at apple.com Mon Feb 11 13:00:34 2008 From: gohman at apple.com (Dan Gohman) Date: Mon, 11 Feb 2008 19:00:34 -0000 Subject: [llvm-commits] [llvm] r46964 - /llvm/trunk/lib/CodeGen/SelectionDAG/ScheduleDAG.cpp Message-ID: <200802111900.m1BJ0ZBa011154@zion.cs.uiuc.edu> Author: djg Date: Mon Feb 11 13:00:34 2008 New Revision: 46964 URL: http://llvm.org/viewvc/llvm-project?rev=46964&view=rev Log: >From Chris' review: use isa instead of explicitly using classof. Modified: llvm/trunk/lib/CodeGen/SelectionDAG/ScheduleDAG.cpp Modified: llvm/trunk/lib/CodeGen/SelectionDAG/ScheduleDAG.cpp URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/lib/CodeGen/SelectionDAG/ScheduleDAG.cpp?rev=46964&r1=46963&r2=46964&view=diff ============================================================================== --- llvm/trunk/lib/CodeGen/SelectionDAG/ScheduleDAG.cpp (original) +++ llvm/trunk/lib/CodeGen/SelectionDAG/ScheduleDAG.cpp Mon Feb 11 13:00:34 2008 @@ -287,7 +287,7 @@ --N; if (N && Node->getOperand(N - 1).getValueType() == MVT::Other) --N; // Ignore chain if it exists. - while (N && MemOperandSDNode::classof(Node->getOperand(N - 1).Val)) + while (N && isa(Node->getOperand(N - 1).Val)) --N; // Ignore MemOperand nodes return N; } From dalej at apple.com Mon Feb 11 13:45:48 2008 From: dalej at apple.com (Dale Johannesen) Date: Mon, 11 Feb 2008 19:45:48 -0000 Subject: [llvm-commits] [llvm-gcc-4.2] r46966 - in /llvm-gcc-4.2/trunk/gcc: config/i386/i386.h config/rs6000/rs6000.h llvm-abi.h Message-ID: <200802111945.m1BJjnf0012511@zion.cs.uiuc.edu> Author: johannes Date: Mon Feb 11 13:45:46 2008 New Revision: 46966 URL: http://llvm.org/viewvc/llvm-project?rev=46966&view=rev Log: Treat struct { long long: 29; }; as int sized and aligned, rather than long long. ABI issue. Remove nonfunctional target-specific versions of LLVM_SHOULD_PASS_AGGREGATE_IN_INTEGER_REGS. Modified: llvm-gcc-4.2/trunk/gcc/config/i386/i386.h llvm-gcc-4.2/trunk/gcc/config/rs6000/rs6000.h llvm-gcc-4.2/trunk/gcc/llvm-abi.h Modified: llvm-gcc-4.2/trunk/gcc/config/i386/i386.h URL: http://llvm.org/viewvc/llvm-project/llvm-gcc-4.2/trunk/gcc/config/i386/i386.h?rev=46966&r1=46965&r2=46966&view=diff ============================================================================== --- llvm-gcc-4.2/trunk/gcc/config/i386/i386.h (original) +++ llvm-gcc-4.2/trunk/gcc/config/i386/i386.h Mon Feb 11 13:45:46 2008 @@ -3744,13 +3744,6 @@ /* LLVM ABI definition macros. */ -/* LLVM_SHOULD_PASS_AGGREGATE_IN_INTEGER_REGS - Return true if we should - * "bitconvert" the specified aggregate tree type info a sequence of integer - * values. - */ -#define LLVM_SHOULD_PASS_AGGREGATE_IN_INTEGER_REGS(type) \ - !isSingleElementStructOrArray(type) - /* When -m64 is specified, set the architecture to x86_64-os-blah even if the * compiler was configured for i[3456]86-os-blah. */ Modified: llvm-gcc-4.2/trunk/gcc/config/rs6000/rs6000.h URL: http://llvm.org/viewvc/llvm-project/llvm-gcc-4.2/trunk/gcc/config/rs6000/rs6000.h?rev=46966&r1=46965&r2=46966&view=diff ============================================================================== --- llvm-gcc-4.2/trunk/gcc/config/rs6000/rs6000.h (original) +++ llvm-gcc-4.2/trunk/gcc/config/rs6000/rs6000.h Mon Feb 11 13:45:46 2008 @@ -3458,13 +3458,6 @@ F.AddFeature("64bit", TARGET_POWERPC64); \ } -/* GCC passes single-element structs and arrays in registers. Other structs - * are forced into integer registers, e.g. complex float is passed in two - * 32-bit GPR's. - */ -#define LLVM_SHOULD_PASS_AGGREGATE_IN_INTEGER_REGS(type) \ - !isSingleElementStructOrArray(type) - /* When -m64 is specified, set the architecture to powerpc64-os-blah even if the * compiler was configured for powerpc-os-blah. */ Modified: llvm-gcc-4.2/trunk/gcc/llvm-abi.h URL: http://llvm.org/viewvc/llvm-project/llvm-gcc-4.2/trunk/gcc/llvm-abi.h?rev=46966&r1=46965&r2=46966&view=diff ============================================================================== --- llvm-gcc-4.2/trunk/gcc/llvm-abi.h (original) +++ llvm-gcc-4.2/trunk/gcc/llvm-abi.h Mon Feb 11 13:45:46 2008 @@ -87,8 +87,9 @@ /// isSingleElementStructOrArray - If this is (recursively) a structure with one /// field or an array with one element, return the field type, otherwise return -/// null. -static tree isSingleElementStructOrArray(tree type) { +/// null. If rejectFatBitField, and the single element is a bitfield of a type +/// that's bigger than the struct, return null anyway. +static tree isSingleElementStructOrArray(tree type, bool rejectFatBitfield) { // Scalars are good. if (!isAggregateTreeType(type)) return type; @@ -106,17 +107,22 @@ for (tree Field = TYPE_FIELDS(type); Field; Field = TREE_CHAIN(Field)) if (TREE_CODE(Field) == FIELD_DECL) { - if (!FoundField) + if (!FoundField) { + if (rejectFatBitfield && + TREE_CODE(TYPE_SIZE(type)) == INTEGER_CST && + TREE_INT_CST_LOW(TYPE_SIZE(getDeclaredType(Field))) > + TREE_INT_CST_LOW(TYPE_SIZE(type))) + return 0; FoundField = getDeclaredType(Field); - else + } else return 0; // More than one field. } - return FoundField ? isSingleElementStructOrArray(FoundField) : 0; + return FoundField ? isSingleElementStructOrArray(FoundField, false) : 0; case ARRAY_TYPE: const ArrayType *Ty = dyn_cast(ConvertType(type)); if (!Ty || Ty->getNumElements() != 1) return 0; - return isSingleElementStructOrArray(TREE_TYPE(type)); + return isSingleElementStructOrArray(TREE_TYPE(type), false); } } @@ -151,10 +157,12 @@ // value should be passed in integer registers. By default, we do this for all // values that are not single-element structs. This ensures that things like // {short,short} are passed in one 32-bit chunk, not as two arguments (which -// would often be 64-bits). +// would often be 64-bits). We also do it for single-element structs when the +// single element is a bitfield of a type bigger than the struct; the code +// for field-by-field struct passing does not handle this one right. #ifndef LLVM_SHOULD_PASS_AGGREGATE_IN_INTEGER_REGS #define LLVM_SHOULD_PASS_AGGREGATE_IN_INTEGER_REGS(X) \ - !isSingleElementStructOrArray(X) + !isSingleElementStructOrArray(X, true) #endif /// DefaultABI - This class implements the default LLVM ABI where structures are @@ -184,7 +192,7 @@ // FIXME: this is a hack around returning 'complex double' by-val // which returns in r3/r4/r5/r6 on PowerPC. TREE_INT_CST_LOW(TYPE_SIZE_UNIT(type)) <= 8) { - if (tree SingleElt = isSingleElementStructOrArray(type)) { + if (tree SingleElt = isSingleElementStructOrArray(type, false)) { C.HandleAggregateResultAsScalar(ConvertType(SingleElt)); } else { // Otherwise return as an integer value large enough to hold the entire From baldrick at free.fr Mon Feb 11 14:10:14 2008 From: baldrick at free.fr (Duncan Sands) Date: Mon, 11 Feb 2008 21:10:14 +0100 Subject: [llvm-commits] [llvm-gcc-4.2] r46966 - in /llvm-gcc-4.2/trunk/gcc: config/i386/i386.h config/rs6000/rs6000.h llvm-abi.h In-Reply-To: <200802111945.m1BJjnf0012511@zion.cs.uiuc.edu> References: <200802111945.m1BJjnf0012511@zion.cs.uiuc.edu> Message-ID: <200802112110.14593.baldrick@free.fr> Hi Dale, > Treat struct { long long: 29; }; as int sized and > aligned, rather than long long. ABI issue. if you look at the DECL_SIZE of the bitfield, rather than the type size, I think it gives you 29. If so, DECL_SIZE should simplify things for you. In fact as far as I can see you should never use the type size for a record field. For example the struct conversion stuff uses DECL_SIZE everywhere (except at one point in the field indexing - I have a patch to fix that which I'll apply at some point). Not using the type size makes all these "it's a big type shoved in a small place" problems magically go away. Ciao, Duncan. From baldrick at free.fr Mon Feb 11 14:58:36 2008 From: baldrick at free.fr (Duncan Sands) Date: Mon, 11 Feb 2008 20:58:36 -0000 Subject: [llvm-commits] [llvm] r46967 - /llvm/trunk/lib/CodeGen/SelectionDAG/SelectionDAGISel.cpp Message-ID: <200802112058.m1BKwaCM014735@zion.cs.uiuc.edu> Author: baldrick Date: Mon Feb 11 14:58:28 2008 New Revision: 46967 URL: http://llvm.org/viewvc/llvm-project?rev=46967&view=rev Log: Generalize the handling of call and return arguments, in preparation for apint support. These changes are intended to have no functional effect. Modified: llvm/trunk/lib/CodeGen/SelectionDAG/SelectionDAGISel.cpp Modified: llvm/trunk/lib/CodeGen/SelectionDAG/SelectionDAGISel.cpp URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/lib/CodeGen/SelectionDAG/SelectionDAGISel.cpp?rev=46967&r1=46966&r2=46967&view=diff ============================================================================== --- llvm/trunk/lib/CodeGen/SelectionDAG/SelectionDAGISel.cpp (original) +++ llvm/trunk/lib/CodeGen/SelectionDAG/SelectionDAGISel.cpp Mon Feb 11 14:58:28 2008 @@ -620,14 +620,19 @@ } // end namespace llvm -/// getCopyFromParts - Create a value that contains the -/// specified legal parts combined into the value they represent. +/// getCopyFromParts - Create a value that contains the specified legal parts +/// combined into the value they represent. If the parts combine to a type +/// larger then ValueVT then AssertOp can be used to specify whether the extra +/// bits are known to be zero (ISD::AssertZext) or sign extended from ValueVT +/// (ISD::AssertSext). Likewise TruncExact is used for floating point types to +/// indicate that the extra bits can be discarded without losing precision. static SDOperand getCopyFromParts(SelectionDAG &DAG, const SDOperand *Parts, unsigned NumParts, MVT::ValueType PartVT, MVT::ValueType ValueVT, - ISD::NodeType AssertOp = ISD::DELETED_NODE) { + ISD::NodeType AssertOp = ISD::DELETED_NODE, + bool TruncExact = false) { if (!MVT::isVector(ValueVT) || NumParts == 1) { SDOperand Val = Parts[0]; @@ -675,7 +680,8 @@ } if (MVT::isFloatingPoint(PartVT) && MVT::isFloatingPoint(ValueVT)) - return DAG.getNode(ISD::FP_ROUND, ValueVT, Val, DAG.getIntPtrConstant(0)); + return DAG.getNode(ISD::FP_ROUND, ValueVT, Val, + DAG.getIntPtrConstant(TruncExact)); if (MVT::getSizeInBits(PartVT) == MVT::getSizeInBits(ValueVT)) return DAG.getNode(ISD::BIT_CONVERT, ValueVT, Val); @@ -723,13 +729,15 @@ ValueVT, &Ops[0], NumIntermediates); } -/// getCopyToParts - Create a series of nodes that contain the -/// specified value split into legal parts. +/// getCopyToParts - Create a series of nodes that contain the specified value +/// split into legal parts. If the parts contain more bits than Val, then, for +/// integers, ExtendKind can be used to specify how to generate the extra bits. static void getCopyToParts(SelectionDAG &DAG, SDOperand Val, SDOperand *Parts, unsigned NumParts, - MVT::ValueType PartVT) { + MVT::ValueType PartVT, + ISD::NodeType ExtendKind = ISD::ANY_EXTEND) { TargetLowering &TLI = DAG.getTargetLoweringInfo(); MVT::ValueType PtrVT = TLI.getPointerTy(); MVT::ValueType ValueVT = Val.getValueType(); @@ -763,7 +771,7 @@ if (PartVT < ValueVT) Val = DAG.getNode(ISD::TRUNCATE, PartVT, Val); else - Val = DAG.getNode(ISD::ANY_EXTEND, PartVT, Val); + Val = DAG.getNode(ExtendKind, PartVT, Val); } else if (MVT::isFloatingPoint(PartVT) && MVT::isFloatingPoint(ValueVT)) { Val = DAG.getNode(ISD::FP_EXTEND, PartVT, Val); @@ -919,38 +927,32 @@ NewValues.push_back(getRoot()); for (unsigned i = 0, e = I.getNumOperands(); i != e; ++i) { SDOperand RetOp = getValue(I.getOperand(i)); - - // If this is an integer return value, we need to promote it ourselves to - // the full width of a register, since getCopyToParts and Legalize will use - // ANY_EXTEND rather than sign/zero. + MVT::ValueType VT = RetOp.getValueType(); + // FIXME: C calling convention requires the return type to be promoted to // at least 32-bit. But this is not necessary for non-C calling conventions. - if (MVT::isInteger(RetOp.getValueType()) && - RetOp.getValueType() < MVT::i64) { - MVT::ValueType TmpVT; - if (TLI.getTypeAction(MVT::i32) == TargetLowering::Promote) - TmpVT = TLI.getTypeToTransformTo(MVT::i32); - else - TmpVT = MVT::i32; - const Function *F = I.getParent()->getParent(); - ISD::NodeType ExtendKind = ISD::ANY_EXTEND; - if (F->paramHasAttr(0, ParamAttr::SExt)) - ExtendKind = ISD::SIGN_EXTEND; - if (F->paramHasAttr(0, ParamAttr::ZExt)) - ExtendKind = ISD::ZERO_EXTEND; - RetOp = DAG.getNode(ExtendKind, TmpVT, RetOp); - NewValues.push_back(RetOp); + if (MVT::isInteger(VT)) { + MVT::ValueType MinVT = TLI.getRegisterType(MVT::i32); + if (MVT::getSizeInBits(VT) < MVT::getSizeInBits(MinVT)) + VT = MinVT; + } + + unsigned NumParts = TLI.getNumRegisters(VT); + MVT::ValueType PartVT = TLI.getRegisterType(VT); + SmallVector Parts(NumParts); + ISD::NodeType ExtendKind = ISD::ANY_EXTEND; + + const Function *F = I.getParent()->getParent(); + if (F->paramHasAttr(0, ParamAttr::SExt)) + ExtendKind = ISD::SIGN_EXTEND; + else if (F->paramHasAttr(0, ParamAttr::ZExt)) + ExtendKind = ISD::ZERO_EXTEND; + + getCopyToParts(DAG, RetOp, &Parts[0], NumParts, PartVT, ExtendKind); + + for (unsigned i = 0; i < NumParts; ++i) { + NewValues.push_back(Parts[i]); NewValues.push_back(DAG.getConstant(false, MVT::i32)); - } else { - MVT::ValueType VT = RetOp.getValueType(); - unsigned NumParts = TLI.getNumRegisters(VT); - MVT::ValueType PartVT = TLI.getRegisterType(VT); - SmallVector Parts(NumParts); - getCopyToParts(DAG, RetOp, &Parts[0], NumParts, PartVT); - for (unsigned i = 0; i < NumParts; ++i) { - NewValues.push_back(Parts[i]); - NewValues.push_back(DAG.getConstant(false, MVT::i32)); - } } } DAG.setRoot(DAG.getNode(ISD::RET, MVT::Other, @@ -3953,32 +3955,16 @@ if (F.paramHasAttr(j, ParamAttr::Nest)) Flags |= ISD::ParamFlags::Nest; Flags |= (OriginalAlignment << ISD::ParamFlags::OrigAlignmentOffs); - - switch (getTypeAction(VT)) { - default: assert(0 && "Unknown type action!"); - case Legal: - RetVals.push_back(VT); - Ops.push_back(DAG.getConstant(Flags, MVT::i32)); - break; - case Promote: - RetVals.push_back(getTypeToTransformTo(VT)); + + MVT::ValueType RegisterVT = getRegisterType(VT); + unsigned NumRegs = getNumRegisters(VT); + for (unsigned i = 0; i != NumRegs; ++i) { + RetVals.push_back(RegisterVT); + // if it isn't first piece, alignment must be 1 + if (i > 0) + Flags = (Flags & (~ISD::ParamFlags::OrigAlignment)) | + (1 << ISD::ParamFlags::OrigAlignmentOffs); Ops.push_back(DAG.getConstant(Flags, MVT::i32)); - break; - case Expand: { - // If this is an illegal type, it needs to be broken up to fit into - // registers. - MVT::ValueType RegisterVT = getRegisterType(VT); - unsigned NumRegs = getNumRegisters(VT); - for (unsigned i = 0; i != NumRegs; ++i) { - RetVals.push_back(RegisterVT); - // if it isn't first piece, alignment must be 1 - if (i > 0) - Flags = (Flags & (~ISD::ParamFlags::OrigAlignment)) | - (1 << ISD::ParamFlags::OrigAlignmentOffs); - Ops.push_back(DAG.getConstant(Flags, MVT::i32)); - } - break; - } } } @@ -3998,39 +3984,21 @@ for (Function::arg_iterator I = F.arg_begin(), E = F.arg_end(); I != E; ++I, ++Idx) { MVT::ValueType VT = getValueType(I->getType()); - - switch (getTypeAction(VT)) { - default: assert(0 && "Unknown type action!"); - case Legal: - Ops.push_back(SDOperand(Result, i++)); - break; - case Promote: { - SDOperand Op(Result, i++); - if (MVT::isInteger(VT)) { - if (F.paramHasAttr(Idx, ParamAttr::SExt)) - Op = DAG.getNode(ISD::AssertSext, Op.getValueType(), Op, - DAG.getValueType(VT)); - else if (F.paramHasAttr(Idx, ParamAttr::ZExt)) - Op = DAG.getNode(ISD::AssertZext, Op.getValueType(), Op, - DAG.getValueType(VT)); - Op = DAG.getNode(ISD::TRUNCATE, VT, Op); - } else { - assert(MVT::isFloatingPoint(VT) && "Not int or FP?"); - Op = DAG.getNode(ISD::FP_ROUND, VT, Op, DAG.getIntPtrConstant(1)); - } - Ops.push_back(Op); - break; - } - case Expand: { - MVT::ValueType PartVT = getRegisterType(VT); - unsigned NumParts = getNumRegisters(VT); - SmallVector Parts(NumParts); - for (unsigned j = 0; j != NumParts; ++j) - Parts[j] = SDOperand(Result, i++); - Ops.push_back(getCopyFromParts(DAG, &Parts[0], NumParts, PartVT, VT)); - break; - } - } + MVT::ValueType PartVT = getRegisterType(VT); + + unsigned NumParts = getNumRegisters(VT); + SmallVector Parts(NumParts); + for (unsigned j = 0; j != NumParts; ++j) + Parts[j] = SDOperand(Result, i++); + + ISD::NodeType AssertOp = ISD::DELETED_NODE; + if (F.paramHasAttr(Idx, ParamAttr::SExt)) + AssertOp = ISD::AssertSext; + else if (F.paramHasAttr(Idx, ParamAttr::ZExt)) + AssertOp = ISD::AssertZext; + + Ops.push_back(getCopyFromParts(DAG, &Parts[0], NumParts, PartVT, VT, + AssertOp, true)); } assert(i == NumArgRegs && "Argument register count mismatch!"); return Ops; @@ -4082,47 +4050,28 @@ if (Args[i].isNest) Flags |= ISD::ParamFlags::Nest; Flags |= OriginalAlignment << ISD::ParamFlags::OrigAlignmentOffs; - - switch (getTypeAction(VT)) { - default: assert(0 && "Unknown type action!"); - case Legal: - Ops.push_back(Op); - Ops.push_back(DAG.getConstant(Flags, MVT::i32)); - break; - case Promote: - if (MVT::isInteger(VT)) { - unsigned ExtOp; - if (Args[i].isSExt) - ExtOp = ISD::SIGN_EXTEND; - else if (Args[i].isZExt) - ExtOp = ISD::ZERO_EXTEND; - else - ExtOp = ISD::ANY_EXTEND; - Op = DAG.getNode(ExtOp, getTypeToTransformTo(VT), Op); - } else { - assert(MVT::isFloatingPoint(VT) && "Not int or FP?"); - Op = DAG.getNode(ISD::FP_EXTEND, getTypeToTransformTo(VT), Op); - } - Ops.push_back(Op); - Ops.push_back(DAG.getConstant(Flags, MVT::i32)); - break; - case Expand: { - MVT::ValueType PartVT = getRegisterType(VT); - unsigned NumParts = getNumRegisters(VT); - SmallVector Parts(NumParts); - getCopyToParts(DAG, Op, &Parts[0], NumParts, PartVT); - for (unsigned i = 0; i != NumParts; ++i) { - // if it isn't first piece, alignment must be 1 - unsigned MyFlags = Flags; - if (i != 0) - MyFlags = (MyFlags & (~ISD::ParamFlags::OrigAlignment)) | - (1 << ISD::ParamFlags::OrigAlignmentOffs); - Ops.push_back(Parts[i]); - Ops.push_back(DAG.getConstant(MyFlags, MVT::i32)); - } - break; - } + MVT::ValueType PartVT = getRegisterType(VT); + unsigned NumParts = getNumRegisters(VT); + SmallVector Parts(NumParts); + ISD::NodeType ExtendKind = ISD::ANY_EXTEND; + + if (Args[i].isSExt) + ExtendKind = ISD::SIGN_EXTEND; + else if (Args[i].isZExt) + ExtendKind = ISD::ZERO_EXTEND; + + getCopyToParts(DAG, Op, &Parts[0], NumParts, PartVT, ExtendKind); + + for (unsigned i = 0; i != NumParts; ++i) { + // if it isn't first piece, alignment must be 1 + unsigned MyFlags = Flags; + if (i != 0) + MyFlags = (MyFlags & (~ISD::ParamFlags::OrigAlignment)) | + (1 << ISD::ParamFlags::OrigAlignmentOffs); + + Ops.push_back(Parts[i]); + Ops.push_back(DAG.getConstant(MyFlags, MVT::i32)); } } From scottm at aero.org Mon Feb 11 15:05:47 2008 From: scottm at aero.org (Scott Michel) Date: Mon, 11 Feb 2008 21:05:47 -0000 Subject: [llvm-commits] [llvm] r46968 - /llvm/trunk/docs/ReleaseNotes.html Message-ID: <200802112105.m1BL5lMw014969@zion.cs.uiuc.edu> Author: pingbak Date: Mon Feb 11 15:05:47 2008 New Revision: 46968 URL: http://llvm.org/viewvc/llvm-project?rev=46968&view=rev Log: Added blurb for CellSPU progress Modified: llvm/trunk/docs/ReleaseNotes.html Modified: llvm/trunk/docs/ReleaseNotes.html URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/ReleaseNotes.html?rev=46968&r1=46967&r2=46968&view=diff ============================================================================== --- llvm/trunk/docs/ReleaseNotes.html (original) +++ llvm/trunk/docs/ReleaseNotes.html Mon Feb 11 15:05:47 2008 @@ -124,8 +124,13 @@

    LLVM 2.2 includes several major new capabilities:

      -
    • Scott Michel contributed an SPU backend, which generates code for the -vector coprocessors on the Cell processor. (Status?)
      • +
    • A research team led by Scott Michel in the Computer Systems Research +Department at The Aerospace Corporation contributed the CellSPU backend, which +generates code for the vector coprocessors on the Sony/Toshiba/IBM Cell BE +processor. llvm-gcc 4.2 supports CellSPU as a 'configure' target and progress +is being made so that libgcc.a compiles cleanly. Notable pieces still in +development include full 64-bit integer and full double precision floating +point support.
    • Anton and Duncan significantly improved llvm-gcc 4.2 support for the GCC Ada (GNAT) and Fortran (gfortran) front-ends. These front-ends should still be considered From dalej at apple.com Mon Feb 11 15:39:46 2008 From: dalej at apple.com (Dale Johannesen) Date: Mon, 11 Feb 2008 13:39:46 -0800 Subject: [llvm-commits] [llvm-gcc-4.2] r46966 - in /llvm-gcc-4.2/trunk/gcc: config/i386/i386.h config/rs6000/rs6000.h llvm-abi.h In-Reply-To: <200802112110.14593.baldrick@free.fr> References: <200802111945.m1BJjnf0012511@zion.cs.uiuc.edu> <200802112110.14593.baldrick@free.fr> Message-ID: On Feb 11, 2008, at 12:10 PM, Duncan Sands wrote: > Hi Dale, > >> Treat struct { long long: 29; }; as int sized and >> aligned, rather than long long. ABI issue. > > if you look at the DECL_SIZE of the bitfield, rather than > the type size, I think it gives you 29. If so, DECL_SIZE > should simplify things for you. In fact as far as I can > see you should never use the type size for a record field. > For example the struct conversion stuff uses DECL_SIZE everywhere > (except at one point in the field indexing - I have a patch to fix > that which I'll apply at some point). Not using the type size > makes all these "it's a big type shoved in a small place" problems > magically go away. I'm not sure what your suggestion is exactly; the issue isn't the size, it is that the code in HandleArgument for general RECORD_TYPEs is looking at getDeclaredType, not the type in the field. (So what this patch does is use the INTEGER_REGS case instead.) The wide use of getDeclaredType and the comments describing it make me think it would be unsafe in general to change that. It would certainly be more elegant if it works, though. From lauro.venancio at gmail.com Mon Feb 11 15:45:53 2008 From: lauro.venancio at gmail.com (Lauro Ramos Venancio) Date: Mon, 11 Feb 2008 21:45:53 -0000 Subject: [llvm-commits] [test-suite] r46969 - in /test-suite/trunk/MultiSource/Applications/SIBsim4: Makefile x-small.fa y-small.fa Message-ID: <200802112145.m1BLjsAO016350@zion.cs.uiuc.edu> Author: laurov Date: Mon Feb 11 15:45:48 2008 New Revision: 46969 URL: http://llvm.org/viewvc/llvm-project?rev=46969&view=rev Log: Define SMALL_PROBLEM_SIZE. Added: test-suite/trunk/MultiSource/Applications/SIBsim4/x-small.fa test-suite/trunk/MultiSource/Applications/SIBsim4/y-small.fa Modified: test-suite/trunk/MultiSource/Applications/SIBsim4/Makefile Modified: test-suite/trunk/MultiSource/Applications/SIBsim4/Makefile URL: http://llvm.org/viewvc/llvm-project/test-suite/trunk/MultiSource/Applications/SIBsim4/Makefile?rev=46969&r1=46968&r2=46969&view=diff ============================================================================== --- test-suite/trunk/MultiSource/Applications/SIBsim4/Makefile (original) +++ test-suite/trunk/MultiSource/Applications/SIBsim4/Makefile Mon Feb 11 15:45:48 2008 @@ -4,6 +4,10 @@ CPPFLAGS = LDFLAGS = +ifdef SMALL_PROBLEM_SIZE +RUN_OPTIONS= -A4 $(PROJ_SRC_DIR)/x-small.fa $(PROJ_SRC_DIR)/y-small.fa +else RUN_OPTIONS= -A4 $(PROJ_SRC_DIR)/x.fa $(PROJ_SRC_DIR)/y.fa +endif include ../../Makefile.multisrc Added: test-suite/trunk/MultiSource/Applications/SIBsim4/x-small.fa URL: http://llvm.org/viewvc/llvm-project/test-suite/trunk/MultiSource/Applications/SIBsim4/x-small.fa?rev=46969&view=auto ============================================================================== --- test-suite/trunk/MultiSource/Applications/SIBsim4/x-small.fa (added) +++ test-suite/trunk/MultiSource/Applications/SIBsim4/x-small.fa Mon Feb 11 15:45:48 2008 @@ -0,0 +1,886 @@ +>4.143962167-143965267 Slice, no description +GGCGCGGGCAGCGGGCAGAGCTGGTCACGTTGTGCTGGGGGGGGTCCGCGCGCCCTGCAG +TCCCGAACCCGCTACGCGCTCCGTCGGCCCGCCCGCCCGCCATGGAGCCTGGCCCCGACG +GCCCAGCCGCGCCCGGCCCCGCCGCCATCCGTGAGGGCTGGTTCCGAGAGACCTGCAGCC +TGTGGCCCGGCCAGGCCCTGTCGCTGCAAGTGGAGCAGCTGCTTCACCACCGGCGATCGC +GGTACCAAGACATCCTCGTCTTCCGCAGGTATGGCCCGCCGCGCGCCGGTGCAGCTGTCA +GAAGTTCTGCGCTGGGCCCGGCCCTGCGTCCACGTGTCACTATCGGGACACGTCAGCCGA +GGGGACCCCGGGACCCACCCAGCCCCCACACGTGGCTCGCCTGCCACGTGTCACCCCGAA +TGCCCACCCCTGGACCCCATGGCGGCCACGTGCACGCCCAGGGAGGACAGGGACCTAACC +TCCCAGTGTCCCAGGACCCACGTCCCCGACTGTCTCTGCCCGCAGTAAAACCTACGGCAA +CGTGCTGGTTCTGGATGGCGTCATCCAGTGTACTGAGAGGGATGAGTTCTCCTACCAGGA +GATGATCGCCAACCTGCCGCTCTGCAGCCACCCCAACCCGCGGAAGGTACCGCATTGCCC +CTGGGTTCAGCCCTGAGCTCGGGGTCCTAGAAAAGCATGTCGGGCTGACACTAGGTGAGG +ATGTTTGGGGGCAGATGCTACCCAGATGACTGTCAGAAAATGCGGGTCGGTCAGGATGAA +TAGAGCTCCTGGGAGAGCTGGTCTCCTTAGAAGCCCCGAGAGGGGAACCCAGGCTGCCAG +GAAGGACCCCGTGGCACAGAAGCGTTCTGGAGAGTAGAGAATGACTCAGAGTCCTGTAGC +TGGGAAGATCAGGTTCTGTGGGAGTGGGCCTGCTCAGTCCTGACTTGTCCTTCCCTGGCC +CAGGTGCTGATCATCGGGGGTGGAGATGGGGGCGTCCTACGGGAAGTGGTGAAGCACCCC +TCTGTGGAGTCGGTGGTCCAGTGCGAGATTGATGAGGTGGGTGCAGTCCAGGAGGCCTGG +ATTTGAGTCACCAGAGTCAGCTCTGTCCCATCCTGACTCTGCACCCCGAGGCGCAATGTT +CTTACCATCCCTGCCCTGTTTCCTCAGTCTGAAAAGAGGGTTCAGTAGGAAAACCAGATT +GTTAAGGCCTGGCACACACCACACCATGGATGTTAACTCTTAGTGCTTTCAGAGCCCAGG +CAGAGCCAGAGAGCTCAACAACTTATGGCATCTCCCCTTGAGACCCAGCATGGTTTTAGT +GAGCACTTACTGTATGCTGAGTGTTACCCAAGGTGCTGGGTTGATACGGCCATGGACAGG +TGAGCCCCTGAGTGTAGAGCTGGTGTTTGGGTTGGAGAAGACACCATAACACAGCATGAC +ATGATGAGGCCAGACAGGGATAAAAGATATGGAGAACACAGGCTGATAGGAAGTGTGCAG +CCACGCATGCTTACAGCCCCAGCACTTGGGTAGAAGCAGGACGATCAAGAGTTTGAGGCC +AGCGTGAGTTATCTGAGACCATCTCTCAAAAATGCAGAAGCTCAGATGGGACTTGGTCTG +CAGGGAGTTGAGGCCTGAAAACCATGAAGAGCTGAGGTGGTGTAGATCTGGGGGAAAGGG +TTTTCAAAAGAGAAGACTTGTCCAAAGAAACCCCACCAGGAGTCCCCAGCCTCTAGTCCA +GCCCAGCCCTTCCTCTCCCCCCTCTTCAGGATGTCATTGAAGTCTCTAAGAAGTTCCTGC +CTGGCATGGCCGTTGGCTTCTCCAGCTCAAAGCTGACTCTCCACGTGGGCGATGGCTTTG +AGTTCATGAAACAGAACCAAGATGCCTTTGACGTCATCATCACCGACTCCTCAGACCCCA +TGGGTGAGCCAGGGCACGCGCGTCCTGCAGCACACAGCAGCCCCAGACTAGAGCCATGTG +ATGATGGAGGCCTGAGGACGGTGGGGGTCTAGCCTTGGTCCATAGTGACCTCTGCTTCCT +CTTTGGCTTCTTCCCTGTGCTTGTTGGCCAGCATCCGGGTGTGCTATGGTGCAGTGGGGG +AGGGTTTGAATGCAGGGCCTCCCAGGTGCTAAGGCAGTAGGGGGCCACATCCCACAAACA +TGGGTCCAGCACCTGCTTTGCCACTGAGCTGCTGTGGGTGACTGTGGCCTGGAGGTCTCA +GGCAGGATGGCCATGCTCTACCCCTCTAGGCCCTGCTGAGAGCCTCTTCAAGGAGTCCTA +TTACCAGCTCATGAAGACAGCACTCAAAGAAGATGGCATCCTGTGCTGCCAGGGTGAGTG +CCAGTGGCTGCACCTGGACCTCATCAAGGAGATGAGGCACTTCTGCAAATCTCTCTTCCC +CGTGGTGGACTACGCCTACTGTAGCATTCCTACCTATCCCAGCGGCCAGATCGGCTTCAT +GCTGTGTAGCAAAAACCCGGTGAGCTGGGGGTGACTGCCTGCAGGGTGGGGCGAGGGCAG +GCACTAAGAGCCCCATCTTGATGCTCTTTGTCCCTGGTTCCCAGAGCACCAACTTCCGGG +AGCCAGTGCAGCAGTTGACACAGGCCCAGGTGGAGCAGATGCAGCTGAAATACTATAACT +CGGACATGCACCGTGCCGCCTTCGTACTGCCCGAGTTCACCCGGAAGGTGAGTGGCCTGC +CAGGCTCCCTGCTGGGCCTCATCCTGCACAGCTTGCACATCCTCCTGACTGCCTTCATGT +CCCACCAGGCCCTCAATGACATAAGCTGAATCCAGGTGCCACTGTGACACCACCCGAGAC +CTCAATCGGATTGGACCAAGGATCTTCCAAGTTGTCTGGGGACCACCAGTCCTGGACCAG +ACTCCCAGATGACTCTTGCCCACCAACCAAGTGTTACAGGCCCCACGATGCTGCCTGGCC +TGGCCTGGCCTGGCCTGCCCTGCTGGGTGGACTCAGTCTCTGTCTGTCTATCTCTGTGGC +GTTCAGCCCCACGCCTATACCAGCTCTGTACAGCACCGCCTATGCCCTGTGACCCAACAA +AATACATGTGTATTTATAACAAGCTCAGTCATGACCTCTGA +CGACAATGCACGACAGAGGAAGCAGAACAGATATTTAGATTGCCTCTCATTTTCTCTCCCATATTATAGG +GAGAAATATGATCGCGTATGCGAGAGTAGTGCCAACATATTGTGCTCTTTGATTTTTTGGCAACCCAAAA +TGGTGGCGGATGAACGAGATGATAATATATTCAAGTTGCCGCTAATCAGAAATAAATTCATTGCAACGTT +AAATACAGCACAATATATGATCGCGTATGCGAGAGTAGTGCCAACATATTGTGCTAATGAGTGCCTCTCG +TTCTCTGTCTTATATTACCGCAAACCCAAAAAGACAATACACGACAGAGAGAGAGAGCAGCGGAGATATT +TAGATTGCCTATTAAATATGATCGCGTATGCGAGAGTAGTGCCAACATATTGTGCTCTCTATATAATGAC +TGCCTCTCATTCTGTCTTATTTTACCGCAAACCCAAATCGACAATGCACGACAGAGGAAGCAGAACAGAT +ATTTAGATTGCCTCTCATTTTCTCTCCCATATTATAGGGAGAAATATGATCGCGTATGCGAGAGTAGTGC +CAACATATTGTGCTCTTTGATTTTTTGGCAACCCAAAATGGTGGCGGATGAACGAGATGATAATATATTC +AAGTTGCCGCTAATCAGAAATAAATTCATTGCAACGTTAAATACAGCACAATATATGATCGCGTATGCGA +GAGTAGTGCCAACATATTGTGCTAATGAGTGCCTCTCGTTCTCTGTCTTATATTACCGCAAACCCAAAAA +GACAATACACGACAGAGAGAGAGAGCAGCGGAGATATTTAGATTGCCTATTAAATATGATCGCGTATGCG +AGAGTAGTGCCAACATATTGTGCTCTCTATATAATGACTGCCTCTCATTCTGTCTTATTTTACCGCAAAC +CCAAATCGACAATGCACGACAGAGGAAGCAGAACAGATATTTAGATTGCCTCTCATTTTCTCTCCCATAT +TATAGGGAGAAATATGATCGCGTATGCGAGAGTAGTGCCAACATATTGTGCTCTTTGATTTTTTGGCAAC +CCAAAATGGTGGCGGATGAACGAGATGATAATATATTCAAGTTGCCGCTAATCAGAAATAAATTCATTGC +AACGTTAAATACAGCACAATATATGATCGCGTATGCGAGAGTAGTGCCAACATATTGTGCTAATGAGTGC +CTCTCGTTCTCTGTCTTATATTACCGCAAACCCAAAAAGACAATACACGACAGAGAGAGAGAGCAGCGGA +GATATTTAGATTGCCTATTAAATATGATCGCGTATGCGAGAGTAGTGCCAACATATTGTGCTCTCTATAT +AATGACTGCCTCTCATTCTGTCTTATTTTACCGCAAACCCAAATCGACAATGCACGACAGAGGAAGCAGA +ACAGATATTTAGATTGCCTCTCATTTTCTCTCCCATATTATAGGGAGAAATATGATCGCGTATGCGAGAG +TAGTGCCAACATATTGTGCTCTTTGATTTTTTGGCAACCCAAAATGGTGGCGGATGAACGAGATGATAAT +ATATTCAAGTTGCCGCTAATCAGAAATAAATTCATTGCAACGTTAAATACAGCACAATATATGATCGCGT +ATGCGAGAGTAGTGCCAACATATTGTGCTAATGAGTGCCTCTCGTTCTCTGTCTTATATTACCGCAAACC +CAAAAAGACAATACACGACAGAGAGAGAGAGCAGCGGAGATATTTAGATTGCCTATTAAATATGATCGCG +TATGCGAGAGTAGTGCCAACATATTGTGCTCTCTATATAATGACTGCCTCTCATTCTGTCTTATTTTACC +GCAAACCCAAATCGACAATGCACGACAGAGGAAGCAGAACAGATATTTAGATTGCCTCTCATTTTCTCTC +CCATATTATAGGGAGAAATATGATCGCGTATGCGAGAGTAGTGCCAACATATTGTGCTCTTTGATTTTTT +GGCAACCCAAAATGGTGGCGGATGAACGAGATGATAATATATTCAAGTTGCCGCTAATCAGAAATAAATT +CATTGCAACGTTAAATACAGCACAATATATGATCGCGTATGCGAGAGTAGTGCCAACATATTGTGCTAAT +GAGTGCCTCTCGTTCTCTGTCTTATATTACCGCAAACCCAAAAAGACAATACACGACAGAGAGAGAGAGC +AGCGGAGATATTTAGATTGCCTATTAAATATGATCGCGTATGCGAGAGTAGTGCCAACATATTGTGCTCT +CTATATAATGACTGCCTCTCATTCTGTCTTATTTTACCGCAAACCCAAATCGACAATGCACGACAGAGGA +AGCAGAACAGATATTTAGATTGCCTCTCATTTTCTCTCCCATATTATAGGGAGAAATATGATCGCGTATG +CGAGAGTAGTGCCAACATATTGTGCTCTTTGATTTTTTGGCAACCCAAAATGGTGGCGGATGAACGAGAT +GATAATATATTCAAGTTGCCGCTAATCAGAAATAAATTCATTGCAACGTTAAATACAGCACAATATATGA +TCGCGTATGCGAGAGTAGTGCCAACATATTGTGCTAATGAGTGCCTCTCGTTCTCTGTCTTATATTACCG +CAAACCCAAAAAGACAATACACGACAGAGAGAGAGAGCAGCGGAGATATTTAGATTGCCTATTAAATATG +ATCGCGTATGCGAGAGTAGTGCCAACATATTGTGCTCTCTATATAATGACTGCCTCTCATTCTGTCTTAT +TTTACCGCAAACCCAAATCGACAATGCACGACAGAGGAAGCAGAACAGATATTTAGATTGCCTCTCATTT +TCTCTCCCATATTATAGGGAGAAATATGATCGCGTATGCGAGAGTAGTGCCAACATATTGTGCTCTTTGA +TTTTTTGGCAACCCAAAATGGTGGCGGATGAACGAGATGATAATATATTCAAGTTGCCGCTAATCAGAAA +TAAATTCATTGCAACGTTAAATACAGCACAATATATGATCGCGTATGCGAGAGTAGTGCCAACATATTGT +GCTAATGAGTGCCTCTCGTTCTCTGTCTTATATTACCGCAAACCCAAAAAGACAATACACGACAGAGAGA +GAGAGCAGCGGAGATATTTAGATTGCCTATTAAATATGATCGCGTATGCGAGAGTAGTGCCAACATATTG +TGCTCTCTATATAATGACTGCCTCTCATTCTGTCTTATTTTACCGCAAACCCAAATCGACAATGCACGAC +AGAGGAAGCAGAACAGATATTTAGATTGCCTCTCATTTTCTCTCCCATATTATAGGGAGAAATATGATCG +CGTATGCGAGAGTAGTGCCAACATATTGTGCTCTTTGATTTTTTGGCAACCCAAAATGGTGGCGGATGAA +CGAGATGATAATATATTCAAGTTGCCGCTAATCAGAAATAAATTCATTGCAACGTTAAATACAGCACAAT +ATATGATCGCGTATGCGAGAGTAGTGCCAACATATTGTGCTAATGAGTGCCTCTCGTTCTCTGTCTTATA +TTACCGCAAACCCAAAAAGACAATACACGACAGAGAGAGAGAGCAGCGGAGATATTTAGATTGCCTATTA +AATATGATCGCGTATGCGAGAGTAGTGCCAACATATTGTGCTCTCTATATAATGACTGCCTCTCATTCTG +TCTTATTTTACCGCAAACCCAAATCGACAATGCACGACAGAGGAAGCAGAACAGATATTTAGATTGCCTC +TCATTTTCTCTCCCATATTATAGGGAGAAATATGATCGCGTATGCGAGAGTAGTGCCAACATATTGTGCT +CTTTGATTTTTTGGCAACCCAAAATGGTGGCGGATGAACGAGATGATAATATATTCAAGTTGCCGCTAAT +CAGAAATAAATTCATTGCAACGTTAAATACAGCACAATATATGATCGCGTATGCGAGAGTAGTGCCAACA +TATTGTGCTAATGAGTGCCTCTCGTTCTCTGTCTTATATTACCGCAAACCCAAAAAGACAATACACGACA +GAGAGAGAGAGCAGCGGAGATATTTAGATTGCCTATTAAATATGATCGCGTATGCGAGAGTAGTGCCAAC +ATATTGTGCTCTCTATATAATGACTGCCTCTCATTCTGTCTTATTTTACCGCAAACCCAAATCGACAATG +CACGACAGAGGAAGCAGAACAGATATTTAGATTGCCTCTCATTTTCTCTCCCATATTATAGGGAGAAATA +TGATCGCGTATGCGAGAGTAGTGCCAACATATTGTGCTCTTTGATTTTTTGGCAACCCAAAATGGTGGCG +GATGAACGAGATGATAATATATTCAAGTTGCCGCTAATCAGAAATAAATTCATTGCAACGTTAAATACAG +CACAATATATGATCGCGTATGCGAGAGTAGTGCCAACATATTGTGCTAATGAGTGCCTCTCGTTCTCTGT +CTTATATTACCGCAAACCCAAAAAGACAATACACGACAGAGAGAGAGAGCAGCGGAGATATTTAGATTGC +CTATTAAATATGATCGCGTATGCGAGAGTAGTGCCAACATATTGTGCTCTCTATATAATGACTGCCTCTC +ATTCTGTCTTATTTTACCGCAAACCCAAATCGACAATGCACGACAGAGGAAGCAGAACAGATATTTAGAT +TGCCTCTCATTTTCTCTCCCATATTATAGGGAGAAATATGATCGCGTATGCGAGAGTAGTGCCAACATAT +TGTGCTCTTTGATTTTTTGGCAACCCAAAATGGTGGCGGATGAACGAGATGATAATATATTCAAGTTGCC +GCTAATCAGAAATAAATTCATTGCAACGTTAAATACAGCACAATATATGATCGCGTATGCGAGAGTAGTG +CCAACATATTGTGCTAATGAGTGCCTCTCGTTCTCTGTCTTATATTACCGCAAACCCAAAAAGACAATAC +ACGACAGAGAGAGAGAGCAGCGGAGATATTTAGATTGCCTATTAAATATGATCGCGTATGCGAGAGTAGT +GCCAACATATTGTGCTCTCTATATAATGACTGCCTCTCATTCTGTCTTATTTTACCGCAAACCCAAATCG +ACAATGCACGACAGAGGAAGCAGAACAGATATTTAGATTGCCTCTCATTTTCTCTCCCATATTATAGGGT +GAAATATGATCGCGTATGCGAGAGTAGTGCCAACATATTGTGATCTTCGATTTTTTGGCAACCCAAAATG +GAGGCGGACGAACGAGATGATAATGATAAGATGATTCAAAAAGACAATGCACGACAGAGAGAGCAGAAAA +GATAATTAAATTGCCCCTCATTTTCTCTGGCAAATTGTAGGGTGAATTATGATCGCGTATGCGAGAGTGG +TGCCAACATATTGTGCTCTTCGATTTTTTGGCAACCCAAAATGGAGGCGGATGAACGAGATGATAATATT +TTCAAGTTGCCGCTAATCAAAAATAAATTCCTTGCAACATAAAATAAAGCACAAAATGCCCGCTCAAAAA +AAGGCATGAATATATAAGCTCGAACATAGAACATAGGCTTGAACATATAATGACTGCCTTTCATTCTCTA +TCTTATATTACCGCAAACACAAAATGACAATGCACGACATAGAGAGAAAGAGAGATATTCAGATTGCCTC +TCATTGTCTCACCCATATTATGGGAACCAAATATGAGCACGTATGCGAGAGGAGTGCCAACATATTGTGC +TCTACGATTTTTTTGCAACCCAAAATGGCGGCGTACGAACGAGATGATAATATATTCAAATTGCCGCTAA +TCAGAAGCAAGTTTATTGCAATGTTCAGTGCAGCGCAAAATGGCCGCTCAAGAAAAGGCTCGAATATATA +TTGCCTGCCTCTCATTCACTCTCTTTTATTACCGCAAGACCAAAATGACAATGTACAACAGAGAGAGCAA +GAGAGATATTTAGATTGCCTCTCCTTGTCTCTCCCATATTATAGAGACCGAAAATGATTGCGTATGCGAG +AAGAGTGCCATTGTATTGAGCTCCTCGACCCAAAATAGCGTCGGACGAACGAGATTATATATTTAAAATG +CCGATCATTTTCTCATCCATATAAATACTACCGAAAATGACTGTCTAAAGGTACTCATCGACTATATTTA +AATCTGTGTATTTCTGTGAATAGATTGACCTTTGCAATTTTTAACGGCATTGTCTATTAAATTAATATAA +TTTTCTTTTTTGATGAATATTTAACCGAACATTTACTTGAAATTAAATTATAAAATTGGTTAAATAATGT +TGAAATCTTACTTTCAGCTAAATGGGGCTATTTTGCAAGGGTTCCATCATGACATTGGTAAATAATTTTT +AAAGAATTAATTGTAAGTTCCAATAGACTGGAAATTATTTTGCAATATCATTCTTATCCCTATTTCCAAA +AGCGAATTATTAGTTGCGTGAAAATCAGAAGGAAAATTATTTAACGTGTTATGCCACGCCAAATAGCCGC +GCAATAGGAAGCTAGACTATATAATGACTGCAACGAAAATTGTAAATTCCAATTAAAAGGATATTATTGT +GCGATTTCACTTTAATTCTTATTTCAAAAAAGTTAATTATTAGTTGACGGAAATCAGAACGAATTTCACC +GCAACGTCTTATGCAGCACAAAATGGCGGCGCAAAAGGATGGTTGCATATACAATAACTTCATCTCATTC +AATCTCTCCTATATTACCGCAAACTCGAAAGCCAAAACACGAATGATGAAGAGGGATAGATTTTATTGGG +ACAAAAATGATAGGTCACGCGAGAGGAGTGGTCTAAATTTTACTCTCACAAAAATGTTGGCAATACAAAA +TGGCGGCGGAATGAAGAGGTGAAAATATATTAAAATTGCCGCTCATTTTCTTCGCGGTAGAATTAGGACT +GAACGTTGCCGGGTATAGGATCTCTATTGATGGCCTTTACTTATAAAGTGTATTTCTACAGATCAAATTA +CTTTTTACTCTTTATCAATATTTAAATATTATAAATTGATTTAGTTAAAATACAATTCGAACAATCTTTT +CTCCAAATAATAATAATGTTTAATACCTATTTGCGCATATGCGTTTATTTTTGGGATTTAATTTTAACAT +TTTTCAACAAAACCGTTACAAATGTAATTTTAAATCAGGAAACGACTTTGGTATGAAAATATGTTTTTTT +GTGCGCTTTTAAACATGTAACTGCTCTTTTGTGCTGTTTTATTGAATGCTATCACAGCGTAAAATTTTAG +TTTTAATACCAATACATTGGGAATAATTTGCGATTTCATTCTATTCTTATGCCCAAATAAGGAAATAGTT +TCCGGCAAAAAATCAGAATTTAGCTTTTACAAAAACTAGAGAGGAGAGGACAATATTATAATTGTAGACC +GTTTTAAACACTTTAAAATGTTTAACCATTTATCAATTATTCTACTAAATGTAGGTGATTTTATTTATTA +GAATACGAATTCTTTATCTGAATCGAACTAAGTAAGCCTAAGCGCTTAGGAAAAATACATACTTGACGAG +TAGAGTGAAATAATTACAAATATTAGACATATCCATTGCTACTCGCATGTAGAGATTTCCACTTATGTTT +TCTCTACTTTCAGCAACCGAGAAGAGAACCCACGTTTGAACAAGTATCGGCGTGTGGACAACAGCTATCC +CCGCTTCATAACGAATGAGGCTGCCGAGGACCTGATTTACAAGAAGTCCATGGGCGAGCGGGATCAGCCA +CAGAGCTCAGAGCGGATCTCAATATTTAATCCGCCAGTATACACGCAGCACCAGGTGCGCAATGAAGCCC +CCTACATACCCACCACATTTGACCTCCTCTCAGACGATGAGGAGTCGTCACAGAGAGTTGCCAACGCCGG +GCCATCTTTCAGGCCCTTGACTTACTCGGATGCTGTGCGTCTAAGCCAGAATGGCTTCGCCAACTCCCGC +GTAAGTGGGCACTCCAGCTATACGGTGCGCAGACCACCGGCACTAGTTGACAGAAGCATTCTATCCCAGG +AAATGGAGCGCATGGACCAAGAGCAGTATATCTACCTTATCCGTACCGCAGCCCAAAGTAATTCCGTGGG +CAGTCACTACGCCGAACCGGTTACTGATAACTCGGAGGTCAAGAAAGTCAGTGAAACCAACAAAAGGTAA +ATAAATTTTTTATATCCATCCATATCCGAATCAGTGGCAATAATGCAAAATGCTGATTTTATCACCAATT +AGTGACGCACCACAGCCGTTAACCCCTCAACCTACCAGACTCACCAGAACAGAATCCTTGCACCGTCGTT +TTGCCAGCTGCGTCAACTTAAATGATGACTTCGCCGAGCAATTTAAAGCAAGAGCGGCGGACTGTGAAGA +GAAATCCAAACATCGTCTTAGATTAGCTGAAGAGCAGAGGCTTTTTTCGAATTTCAGTGCTATAAAGAAC +ATAGATGAACTCCGTGCCTATGAACGAAAAGTAGTGGAAAACATATTCCAGTCTTGTATCGCCCACAAGC +CCATTTTTGTACTCGGGCCCTTGGACAAGCCAAATGTGAAGAAAGTGACCAAGCTCATTCCGTTAACAGA +GGAGCACCACGATCGCTTTAACGAAATTACACAGGATGATAAATCGACGGTATGGCAACGAATATATTGA +TGTCTTTCGTACCCATTGAAAACGTTGTGGTGCTTGCGCTTTAAAATCTTATATTAGGAAATTATTTTTA +AATTTAACCTACACATAACTACCGAAGACATATGCACGTTTATTAATGGGAAATGGCTTAACGACGAGGT +CATTAACTTTTACATGTCCTTGCTGACAGAACGGTCGGAGAAGAGATCTGGCGTACTTCCCGCCACTTAC +GCCATAAACACATTCTTCGTGCCCCGCCTCCTGCAAGCTGGGCATGCAGGCATTAAGCGCTGGACTCGCA +AAGTGGACTTGTTCAGCAAGGACATAATCCCGGTACCAGTGCACTGCAACGGCGTCCACTGGTGCATGGC +CATCATACACTTGCGGAACAAGACAATCCGGTATTATGACTCAAAGGGAAAGCCAAACCGACCAGTGCTG +GACGCTCTAGAGAAATATCTACGCGAAGAGTCAATATTCAAGCCCAAAAAGCAGTTTGATACCAGCGATT +TTGTTATTGAGAGCGTGCAGAATATACCACGACAGTTAGATGGCAGCGATTGCGGTATCTTCAGCTGCAT +GTTCGCCGAGTATATAACGTGTGATGTGCCAATTACCTTTACCCAGTCGGAAATGTTGTACTTCCGCAAG +AAGATGGCTCTAGAAATCGTCGACGGAGAGTTGTGACAGTAGAATCACACAGCTACGCAAGAATGTGGAG +AATCCAGTTTAGTTATTTTTACAAATCTTACGTAAACACTCCAAGCATGAATTCGCAACAAGTGCTTAGC +TATTTAATTGAATTGAGCTGGCCGAGAGATGTGCTGGTGCAATAACTTGTTCTCATATCTGATTGTAACA +GAGAATCTAGTTTTTCAATAAAATTTCCCCAAGTAAAAACAATGCGAATAGGGACGTATTAATTGCCGAA +TCTCTTCGAGTTAATAATTAATTTTTACAATACAGCAAGCTGAGAATATGCAATTGTAATGTCCAATTCA +ATATTTGTAATTTACTATTTTAAGCCTAACTCTTATCTAGGGATTACTCGATTCCAACTATATTAGAGTA +GAAGAAAACAATTTATTGTAACGAAGTACAAAGATCATTCTAGAAAATCACTCATACAAACCTCTAAGGC +TCAAAACCGAGGTATGATCTTTAAATAAGTCAAAATTAGGAGTTTTCAGTTTGAGACCTACAACTAAATA +GATCGGTGTTCTTCCACAAAATATTGTAAAGCCAGTTTGTTAAATAAAATACATGTTTTATTAATAATCC +TAAGCTAAATACTCAATTATATACTTTATATGGTCGGAAAAGCTTCCTTCTGCCTGTAACATACTTCTCA +ACGAATCTACAATACTATTGTATATACTATACCTTTTACTATACGAGTAACGGAGTAACGGAGGAGAATG +CAAAAAAGCTAAGAACAAAACAATTACTACAAATCGTCAGGAATTTTAAAATACTTTACAATTGAATATA +AAGCCGTAGGATTTCTAAAATTAAATTACATTATGTACTAAAGTACTTGAAGGCTCATTAACTTACTTCT +CATATTGACATATTTTCTTCCCTCTAAAACTCATAAAAACCATAATTTTTTAATTGCACCTGTGTAGAAT +GCAAAAATTACATTTGTGAGTATCATCAAAATGTAGCCTTTTTTAACTGACGTATTAGCCAAAGAATTAA +ATACATGTAATTTCGTGCTAAAAAAGTTTGCAATTTCATTTTACGAAATATTCTACAATTAATTTGAAAC +ACGCTTTTAATTTTAAGTAGTTTTCTTATTGAGGATTTGATACAACAAATTCTTTTGAACTTCAAGGTCT +TTTTTCTCCCCATCCTTGCATCAGGCTATTTTTTGTACTCCTAATTTGTTCATCATAATAAAGCAAATTG +TTGTTGTCCTAATTTTGTAAGGGCATTTTTTTGTATCACAATATTTTAACCGAAAATAAAAGAAATTTAA +AAAATGTGGGCACGACAATTTTTTTATAATCTTTGAACGGTCATACGAACGGAAATGAAAGACACCAGCG +CTGTTTCTATCCCTTAAAACCCAAATGTTCCTATATAATTTGAATTATTTATCCAAAATAAAGACCATTT +TAATATACAATTTATTAAATGGGGACGGACCAATTTATCGGTATTTGTGTTTATACGGACGAACAGAAGT +AATTAATCGGCATGTTATCCAGGTTGCGTTTTAATATTTTACAATCGGCCTTAAATGTCAACTTTTATCC +TTTGTACCTTTCTACAAATATCATGTTTCGTTTCATCATACGGGTAAAGGGTATAAAGTCACTACGCGAA +AATACATGAAAACATTACATAAAATCATAAATAATTATATGGTTTTGGAACAACAACATCGCTTAAGCCA +AATAAAAAATGAATATTTTATATTATCATTCTGTCATTTCTGTTTGTATGTAAATCGCGTTTAATTTAAT +TTAATTTTTTTGCGTTCCTATTTTGCTGTCCCCGTTCGATTTTTAGTGAGACATGTTTGTAATTATAGAT +TAAATTACATCAGGACTAGTACTCGTTTGCGTCGTATTTCTGTAAAGGTATAAAATAATTAGTAGGTTAC +GGCTTCTGTCAATGTTAAAATTGGCTTTCTTCAGGCGCTGTTTTTGGCGTTCCTATTTTGTTGTCTCCGT +TCGTTTTTTCATGAGAAATGTTTGTAATTATAGATTTAATTACAACAGAACTAGTACTCGTTTCCGTCGT +ATTTCTGTTAGGTAAAAAAAAAAAATTAGTAGGTTAAAGCTTATGTCAATGTTTCTTGTAGAAGCACACC +TTTTCGATTCCAAGTCCTCTAAATTAGAAATATTAATATTTGGAATTTCACTCATGTTTACGGTAGTACT +GGCTTTGTTGGTTTGCGTGCTAAGTACAGATAGGCGACCTACATTTTCATAGAGATGACAGAAAAAAAAA +GTTATGTACAGATATAATGTGGGCCCGTGCTTTTAAAATAAGATAAAAGTATATATTTAAAGTTGTTTGG +TGCGTATACTTAAAATCAAGTTTTTAAAAAGTAAATTTTTATAAGAATTATGTTGCCGAAAGTAACTAAT +GTCGAAACGAAAACATTTAAATGTAGATACGTACAAAACAGCAAATTAAAATAGGTGGAATAATGTTAGT +AAATAAATGATTACTCACCAATGGTTTCCTCTGTATTAATAGAACACAAAGTGGTGGTCGTCATATTTAA +ATGGTCGCGCACCGAGTCAACGGTAATATCGCCAATAGAGCTGCTGATAGTCTCGTTAGCTTGATTAGGT +GAATTTGAAATGTTGACTCCATTAACTTGCTGAACACTATTTCTTCCAACGTTTTCCTCTGCAGGCCTTG +TGCATATTGAAATGCCTGATGGATTTTTAATTTCATATGTATTCACAACTTCATCACATGCGTAGGTTTC +CTTATTATTCTCTGCATCATTTTCTTCCAACACAGACTCTTCATTTTCTAATGGTTCTACTGGAACAACG +CCAGTGGGTTGCACGACTCTGGACGTGGCTAAAGCAATACGCTGCAGTTCAGAAGAAGACATCATATACA +GTGCTTCTCCAGAGTTTGTAAAGCAAAGTGACGAAACTCCACTGAAAAGTTAAAATACAGTATTAGGTCC +AAAAAATTAAAATAATAGCACTATGCGTGACTTACTTAATGTCTTCCCGTCGCACTGCTGCGGCATTCAG +CTGTCTTTTTAATTCAGGTACTGATAAAACCATGATATCGCCCATATTCGTTAAACATATCAATGCTGTT +TCGTTATATACATCTCCACGACTTACAGCCAAGCTTCCACTGATATTAGGATCCGCCTCTCCATCGCCAT +GTGAACGCGTGGACTTAGTTGGGCTACAACCGTGCATACTCTGCAGTGTTTCCGGGGATATGCGACAACT +AAACGAACCAAAATGGATGCGGCGAATCCGAGCACCTTCGTTAGCGGTAAGCTTATATTTGTTAATCGGC +TTTAGTTGCGGAAGTGAAAACACCTTGAACTGTTCCTCGGAAGCAATAAGTACACGATGCGGTGGACTCC +CGTTTTCACCGGCGTTCAGCTGATCGACAGGGCTACCCGCCTGATCAAAAATAGAAATACCCACCACAGG +AGCACGATGTTTTAATTGTATTTCTTTAGCAAGCTGCGCAGAAATTCGGCGGGGCATGTGTGGTGGTGCA +TTGCCACTTGCCGACGGGACGGCAGTTGCCGCGGTCTGCGCTGGTGGCAAATGCAGAAGGAAAACCGAGA +CTGTACTGGCATTTGTTGCTGACCACAAAGTTGGCGACGTTATGTTGACTGAAAATGTAAAAATTATACA +ACAAATTAGATGTACATATACAGAACACCAAAAGAATAGACGCTACAGTCGAGTTACCCATTACAGAAAT +AGTAGGAGGATAGGTGAAATTTTAAAAACAAAATTTGCCATATAGATCGAAATCGCGAAAACAAAAAGAC +TATGATTTAATTAGTTTAAGAACTGTTTTCCAACTAGTAAATGAAACGAAATCAATATCAATAAAATATA +TTGTCAAACCAGAGTAAATGCAAAAGCACTTTTAACACTTATAGCATATCGATAGACTAGCAAGGAATAT +TGTAATGACTGAATTTCTTTCTAAGGACGGACATAGTCAAATGTAGTCGGCTGTTTAAACTGATCATAAA +TACATATACCTTTAAAACTTTGATCAATATATCCAATGCATAAAAATTTGTTGCACAAAAATATAATTAA +AGCTCTGGGCGTCCCAAAATGAAAAGCACTGTATGTTTTTAGCTTTTGGGTTCAATTCTCGCGAGGCCGT +GGTTCAGAGACTATTTCCGTTACCTTTTTTTTTTTTTATCGTTACATCAAAACTAATAACAGTACAAAAT +GTTGATTACCATTAGTAACATAAGTTTTGGCAAATAGTAAACATCGCACCATGGATCCTAGCCCGTCATC +TGCACAACGAGCCTCTATTTGCCTCTCGACGGGTCTTGCTTCCAGCTGTAGGATTGTGAATTTAATATAA +AAGACTAGTTGAGTATATATTATCTTACTAACCGTTGTTGGTACTTGATTGCTCTGGTTGGTCCTGGTCG +ATCGACCCTTGCGAAGCTTTCTAAATGACTCCCTCAATGATTTCTTAAAAGACTTTCGACGAGACAGCTG +CTCTCCTGCTCCAGTAAGATCATTTGGGTTTAAAGTGCAGCGATGAAATACTGGAACAAAGTTTTTGAAG +TCAAAGAGAACTAAGCCGTGCGCAGTCCCACCAGATACTAGGCCCCAGCTTGCTTCGAGTGCCATGCATG +TTATGCTGGCTGGCGGCAAAACTTGCAGTACTCCCGATATATTTACACCACGTTCCGTCGTAGGAATTGC +TTCTCCGTCTAATAAGTTCGATCGCACGTTTAACTGATCGTGACCCTTCCACACAAATCCATCACGATCG +CTGACCAAATTCATTGAAATGTATTTTAAAGACACTTTTTCGGGTAAGTCTATGAAGTCGGCTATAACTA +TTTGGCCCGCTGTGCCACCAACAATAAGTTGTCCGGTTTTTGGGCAGAATGCTATTTTCTTCACTGCTAA +ACGAGGGTCATCTGAATAAGGATCAAAAAGTCCTGATTTCCGAAATGGCGGTTCTCCTTCATCGACTTGT +TCCGCACTCATATCTGCAGCTGCGTCATCTCGGAAGTCTGACTCACTTCCAAAAATGCTGCTAGTTTTAA +AATTATAAATTGGTTTAAGCAACACTCCAGTGCAGTCCCAAAATTTAACAGAACCATCTTCGTGACCAGT +TAACAAAATCTCATAAAGCTTAGTCGCGTCCTCTTCTACAGATTCTTCTAAGTTATCCGGGAGAGTACCG +CCAGTGATAGGCCAGCTAATATTGCTATAGTCAATGTCTTGTTCATCTCCAGCTCTTAAAATACTTTCAT +ATACCGACTGTACGACTTCAGAAGCAAGGTAATTGCAAGTGACAGCTGATGCATGGACAGAGTGAAGATA +TGGCGCTTTGATAGCACAAATATTAGGGTCAGTAAGATCGTAAGCGCAGAGTTCCTCTTCAAGTAGTACA +ACAAGAACTTCAGCGACATCTCTATTATTTTCAAAGGTCACAAAAAAGTCAATCACTTTAGACGTAAAGT +CAAGACACACTTTGTGTCCATCGCTGGCGTGAACGGACACACAATTGTGATCACCATATGCTGACCGTGG +CATGCCGCCGGAAAAAACAATTACATCGTTGGATCTAAAAGAACGAGAAATTAGTACACATCTAAAAAAC +TTTGTGTTTAAGTTATATTAACCTTCGCTTGCCTTTGTACAGTCGATTTATGCTTTTGCATGGATCAGGT +CCATAAGGCACATAATTAACATTCGACGGCGGTTCTGGGTTATCTATGCTCCAAGTGGCGTATGAACCAT +CAGCGTGGTACCAGGTAAATTCAGATCCTTCGAAGTTCACTGTAAGACCAACGCTCTGTCCATGTCCAGG +GGCTATGTATGCTCGCTGGACAGATGCGCTTTCAAAATCCCACAAAACACAAAGGCCGCGATTGTATGCA +ACTAGAAGTTTGCTAGGGGAGTTTGGAAGTTGGCGGATTGACTCAATTGCACCAGGATTTAGCTTGTAGG +CTGGTGGCACCTGCTCTAGCACAACGTCATGGTAAATTACAGGCTCCTTAATGGTAAATGTATGTAAATC +CAGTTGATAGATGTTTCCACCTTCTGTTCCAATCCATAGCAGATCCTTACTGAGAGAACAGCACAGCGAT +GAAACTTTTTTAAGTTTGCCGTCAAACGGTAGTGTTTTGATTGGCAGCAACGTTGCTCCAACTGGCTCCC +ATAGAATTAATTGATTCGCTGCCGTCAACGAAAGTATGCGACCAGTTCCATACACCCATTCAAGTAATTG +TACATTAAGCTCCGATGCTGAATTGTTTAACAAAGTATGCTGACCGTACAATTCAACTCCGGGTTGACCG +AAAACTTTTAAAGCCCCTGTTTGCGTCCCTATTGCCATAAGTTTCAAAACTGGATCATACGCAAGAGCCG +AAGGCTTATGAGGAAAGCCATGCTGTGCCGTCTAAAAGAAAAAAATATTAAAAAGTTTCAAAAAGCAATT +ACAGATTCTTAATAATTCAAAATTGTTTGGTTCATTTCTTAATTGTAAAAGGGTTTTCCAAAACATTCTA +GTTTTTTCAGTTCCCAAGATCTGGTAAATCGTCAGATTACTTGCCACTTTATAGAGTCGGGAACGCTTTC +TTAAACCATTTACATACTTTTACCGAATCTAATACAGCATTTTTCTTTACAATTAACGGGAATAAAAACC +TCAATAAATATTGAGGTTTGAATTTAAATTAAGTTCAAAAAGCGCCCAAAGCTTTAAATGCTGCTCTTAA +GTATGTCTCTTATAAACATCACTGTAGACAGCAGTCCCTACTATCATACTATATTTACATTGATCGAAAA +AAGGTTTGGTAAATCTTATCTAATTGTATAAATTGTATTTTTATACAAAAAAAGTTTTAAGAAGTTGCTA +TCAGATCTCGTTATGAGTTGATTTTGTTTGATTCATATTGCAGGTGTATTTGGATTTCTAACGCAGTTAC +AGGCGAATAAATTCTTTTTCTTTTGACTTTAAAATCTTATCAATTTTACGCCGTCTATGACATACTTATT +TTGTGCCTGAAATAAGGGTGTTTGTGAAACCAAGCCATTTACCCAACCCATTAAGCACATAAAAGCAATC +TTATCAGCTCCCCCCTCTTTCTGGAGCTGGATGGCGATTACCTCTGACCTACTTTTATTTGTTTAATAAC +ATGTTTATACTAACATGGGATAAAAAAAATTCTTATAAAATTTCATATACGTATATTTATTAAACTATTA +TGGTAATAGGGAAACATCTATGGTATATTTAATTCGAAAATATTTAAAAGGAATGGACAACATTACGAGC +ACAACGATATAATAGAATTTTTAAAGTAGCCAAAAACAGGCGGTGGAAAAAGACACTCACAAAATCAACA +AAGCTTCAGGTACCTCCTCATATTTGGCACCGCATAGAAGGAGTGCACAAAAGAAACGAGCAAAAAAGCA +CCGTAACCTTTTTTATGCGGTGCTTTGTGGCGCGAGTCTACAAAATACTGTGTGTGTATGCGGTTTACTT +GTAGTTGCGGTGGAAAAAATTTACCTAAATGTTAATGCCCAAAAGTATGCACATAGGAGAAGACATAACA +AAAGATTGAAAAGGAGGTATTTATTTATTCTTAATAAATTATAAGCTTTCTTCTAACTTCCATAAAAATG +TATTTACCACCCAGGATCAAAATAAATGACACCCCACAAAATATACCAATCGGCTACATATACGAAAAAA +AAAAAATAAAATAGAATGGAAAGAGAAAATTGTTTGTTGTACCTTACGATAAGCAAAAAGGTCCTTCTGT +AGGCGGTGTCTGTCAGCACTGGGCTGCTGCCCTTTTCCTCTGATAAACTTTAACATAATTGGTTATGCTC +TTGTGGTGGGTTGGTTTCGATGAATAAATATGTATACTAATTGTGGCCGTATTTATTCTAAACTGAAAAT +AATAAATAAAAATTAATCACATTTTCAATAAGTAAAAAATTAAAAAGGAACTTGTATATTTTTTCACTCT +TATGAATAAAACCGAGAAATTAAATTTAGGTAATACTATTAATACCTTTTATAGATACGGACGATACGTT +TAATATTATTCTGGTATACTTTAATCAAAATTTGTTTAACAAAAAGGGTTTTACATTCTTGGTCATAGGA +AATTCAGTGGACAGATAGATCTTGGCTCCCAAGATTTTCCAAACTAGTTGTGCTTATTTTCTTAAAACTT +CAAAGATTTGCATGTAGGCAGTTTAATAAACATGTTTGTACATATGTATATGTACATTAGGAAAAATGAG +ATGCAAGATGAGCGATCTGTACTCTTTGCAATGTGTATGTATGTACATATGTACCTCCCTTTAATGAACT +AGCAATTCCGTCACGCACACGAAATATTTTTTTATTTGTAAATCTTTTTTTAAGTTTGTTTAAACAATTT +AGTTACTATTAAAGCTCTGAAATTCATAAATAAATAATAATAAATGTATTAATTATGACAAAAAACAACT +TAAAACATATACGTTTATTTTTGTAAAAGCGTTTTAGGCAAACGCTAGCTGGTCGGTACTAATATTTTTT +CGAAGACTGTATACCGTATACATACATTTATGTACGTAGGTATGTATCCGTGAGTAAGCTGAGGTGCAAA +ACCGTATCACCATTTGCTTTTCGGCTGATAACCAATACCAAGTAAGTCAACTGTTTCCCAAATGTATCTG +CATAACAAGGTGATGACCTAATTTTGAGTACATACCGATCTTTACAGTTGACCAGCTTTGCGATTGCATA +CCGGTATCTGTTTATTCACATATACACACACAAATTGCGTGTTAGACAGACAGCAAAATGACGACTGTTA +ACTGTTGGCGTGGCTGACTCACCGACTACGCCTCTATGCTAAGAACATACATATTTGTGGACACTTTATT +TAAGAAGTTTGAAATATAAATCAATTGCCTAATCAGTAATACTGTTGTTGAGCCCTTTACCTTTATGTAT +TTCCGTTTGTACGGTTAAGGCGGTGGCCGAGTAATTTTTTGAACTATTTTATTTGCTCACCAACACGCAT +AAGTTTGTATGTATTCTTATGTTGAGAAACGCCCGCACTGTTCTTCACATCGTTGCTTTAAATGAGAATA +AATGAAATAAACGTGTCAACCAAGAACACACAGATAATAATACGACCGGTCAGAGCTTAACCGTGTATCT +GTTTTATAAAACGTGAACAATATTATTAGCCCAAAACGATATGCGCGTCATTTTAACACACACAAAGTCG +CGATCGGTGGGTCTAGTGTGCCCGTGTATCTCTATCGAAAAAATCATATATTTTTTAGAAGGTATATTTT +CCATGACTGACTGGAATGGGTGGAGAACATCGCTTTGGGAGTGAAACTCCGCTATAAATTGTCATTTGTT +TTTATAGCAACCTTTTTGATATGGTCGCCAACTTTTATATAATTATAATAATAATTTTTGTAATTAATCA +CCGCTGTCGCACGAAAAATTTAGGAAATGTGCCAACGAGCGGAATTTTTCGGAACGATCGATGTTTTACC +ATAACCTGCTATATAAATTGTGAACCACATTTTCAACACAAAACTAGATGTGCTTCATTTATAACGCAAT +GTCGTGATTTTGTGGGCAGTGTGACCATGTCCAATCTGCGTTCAAGTAAAACCATATTTAGTGACACAAA +CTTTCCATTACAAAATACCAAACAACTTTAAATTTGTTGTTGCATCAAACTTTTTCTTTCTATACATATA +ATATTGCGGGTGTATTTGGATTTCTAACGCAGTTACAGGCGAATAAACTCATTTTCTTTTGACTTTAAAA +TCTTATCAATTTTACGCCGTCTATGACATACTTATTTTGTACCTGAAATAAGGGTGTTTGTGAAACCAAG +CCACTTACCCAACCCATTAGGTACATAAACGCAATCTTATCAGCTCCCCCCTCTTTCTGGAGCTGGATGG +CGATTACCTCTGACCTACTTTTATTTGTTGAATAACATGTTTATACTAACATAGGATAAAAAAAATTTCA +TATACGTATATTTATTAAACTATTATGGTAATAGGGAAACATCTATGGTATATTTAATTCGAAAATATTT +AAAAGGAATGGACAACATTACGAGCACAACGATATAATAGAATTTTTAAAGTAGCCAATACACAAAAATA +TGCTGTGGAAAAAGACACTCACAAAATCAACCAAGCTTCAGGTACCTCCTCATATTTGGCACCGCATAGA +AGGAGTGCACAAAAGAAACGAGCAAAAAAGCACCGTAACCTTTTTTATGCGGTGCTTTGTGGCGCGAGTC +TACAAAATACTGTGTGTGTATGCGGTTTACTTGTAGTTGCGGTGGAAAAAATTTACCTAAATGTTAATGC +CCAAAAGTATGCACATAGGAGAAGACATAACAAAAGATTCAAAAGGAGGTATTTATTTATTCCTCATAAA +TTATAAGCTTTCTTCTAACTTCCATAAAAATGTATTTACCACCCAAGATCAAAATAAATGACCCCACAAA +ATATACCAATCGGCTACAAATACTTAAAAAAAAAAAAATAGAACGGAAAGAGAAAATTGTTTGTTTTACC +TTACGATGTAGCGTTGTCTGTCAGCACTGGGCTGCTGCCCTTTTCCTCTGATAAACTTTAACATGATTGG +TTATGCTCTTGTGGTGGTTTGGTTTTGATGAATAAATAAGTATATTAATTGTGGCCGAATTTATTCTAAA +CTGAAAATAATAATAAAAATTAATCAAATTTTCAATAAGTAAAAAATTAAAAAGGAACTTGTATATTTTT +TCACTCTTATGAATAAAACCGAGAATTTAAATTTAGGTAATACTATTAATACCTTTTATAGATACGGACG +ATACGTTTAATATTATTCTGGTATACTTTAATCAAAATTTGTTTAACAAAAAGGGTTTTACATTCTTGAA +GTCATAGGAAAATCAGTGGACAGATAGATCTTGGCTCCCAAGATTTTCCAAACTAGTTGTGCTTATTTTC +TTAAAACTTCAAAGATTTGCATGTAGGCAGTTTAATAAACATGTTTGTACATATGTATATGTACATTAGG +AAAAATGAAATGATGAGCGATCTGTACTCTTTGCAATGTGTATGTATGTACATATGTACCTCCCTTTAAT +GAACTAGCAATTCCGTCACGCACACGAAATATTTTTTTATTTGTAAATCTTTTTTAAAGTTTGTTTAAAC +AATTTAGTTACTATTAAAGCTCTAAAATTCATAAATAAATAATAATAAATGTATTAATTAGGACAAAAAA +CAACTTAAAACATATACGTTTATTTTTGTAAAAGCGTTTTAGGCAAACGCTAGCTGGTCGGTACTAATAT +TTTTTCTAAGACTGTATACCGTATACATACATTTATGTACGTAGGTATGTATCCGTGAGTAAGCTGAGGT +GCAAAACCGTATCACCATTTGCTTTTCGGCTGATAACCAATACCAAGTAAGTCAACTGTTTCCCAAATGT +ATCTGCATAACAAGGTGATGACCTAATTTTGAGTACATACCGATCTTTACAGTTGACCAGCTTTGCGATT +GCATACCGGTATCTGTTTATTCACATATACACACACAAATTGCGTGTTAGACAGACAGCAAAATGACGAC +TGTTAACTGTTGGCGTGGCTGACTCACCGACTACGCCTCTATGCTAAGAACATACATATTTGTGGACACT +TTATTTAAGAAGTTTGAAATATAAATCAATTGCCTAATCAGTAATACTGTTGTTGAGCCCTTTACCTTTA +TGTATTTCCGTTTGTACGGTTAAGGCGGTGGCCGAGTAATTTTTTGAACTATTTTATTTGCTCACCATCA +CGCATAAGTTTGTATGTATTCTTATGTTGAGAAACGCCCGCACTGTTCTTCACATCGTTGCTTTAAATGA +GAATAAATGAAATAAACGTGTCAACCAAGAACACACAGATAATAATACGACCGGTCAGAGCTTAACCGTG +TATCTGTTTTATAAAACGTGAACAATATTATTAGCCCAAAACGATATGCGCGTCATTTTAACACACACAA +AGTCGCGATCGGTGGGTCTAGTGTGCCCGTGTATCTCTATCGAAAAAATCATATATTTTTTAGAAGGTAT +ATTTACCATGACTGACTGGAATGGGTGGAGAACATCGCTTTGGGAGTGAAACTCCGCTATAAATTGCCAT +TTGTTTTTATAGCAACCTTTTTGATATGGTCGCCAACTTTTATATAATTATAATAATTTTTGTATATATA +ATCATAATAATATCATATAATAATCACCGCTGTCGCACGAAAAATTTAGAAAATGTGCCAACGAGCGGAA +TTTTTCGGAACGATCGATGTTTTACCATAACCTGCTATATAAATTGTGAACCACTTTCTTAACACAAAAC +TAGATGTGCTTCATTTATAACGCAATGTTGTGATTTGTGGGCAGTGTGACCATGTCCAATCCGCTTTCAA +GTAAAACCATATATTGCCACAAACTTTCCCATACAAAATACCAAACAACTGTAAAATTTGTTGTTGCATC +AAACTTTTTATTTCAATACATATAATTTCATGTGCACTAAAGTGATTATTTTGTATTTGCATTTAAAAAT +TTCTGTGATTAATTGTCAATACGGAATGTATGTGAGGAAGGATTGCCGTCGTTATCCATCTGGTCCATAA +ATTCGTCTAAACGCTGCAGAGATTCAAGAGCTTCCCGAGATTCTTCGTCTTCAATATTATTTAATTTTGC +AGAACTGTTTGGAAACTCAGTGTGGACGATGTCTAGCTGACCATGATCTGTTTCAGGTGCCCCGTAGCTT +CCGTATATTTCCCGAAGCGTTGCGCGGGTAAGATTTAACTCGCGCATTCCAAAACTCATTTTTTGAGCAA +CCTCAGCAGCCTCGCGTCTATTGGCCTTTCGCTTATCATGGGAAAGTTGCTCGGCATTAGTGCGAAGCAT +TGACCCACTTGACGCCGACGACCAAGAGGAGGCGGCCGACTTGCGGGAGCGCTTGATTATTTGGCGGCAC +TTGTTGGTAATCCCACCGACGATCTCGGATACCAGGGCTGTGGCTCCTAGAAAGTAGCCCAGTGCCATGA +GCAGGAACATTCCTTCTGTGTCCGCTGTAGTCAATTGGCGCTCTTCCTGAATTATTTCGCGTAAGGAATT +CGAAGAACTTGCCTGGAGCAGGCGTCCTGAAGATGATCGCTGCATGACCCAGCTTACCTCGTTATTGATT +TTTGCAATAAGACCACTTTGCTGGGCAAGTAATATCATCGAGTCGATTTTGATTTTATACACTGACTCTC +GGGGAAACAGAAATCCTATTTGGAAAAGAGCAAAACACTCTTCACTCAAATGAAGCGCCGATCGGCGGGA +AATATTTCTAAAAGAGGATATCGTTTACGGTGGGAAGATTAAAAATAAAGGATCGATCTTACTCATCTGA +AAAATTTGACTGCACCAGGTATTCGAGCTGAGCCTTTGAGCCAAGAAAGGCATAGTTCCAAAAGAAGCTC +TGGGTAACGTTGCCAATGCCCTCATCTACGGACCCGACAAACTCCATTTTCTTGTACAATCTAGACGTCG +GTATATGGGTCGAGTTCTGGAACCAGGTCTCCCAGCCACCATTGTCTTTAAGTAAGAAGCCCAAATATTA +TATACAAATGTAGCGAGCCTAACCTTTTCTTACTCAGGGTTCCAACGCGAAAGAACAATCCCAGCAGATC +CAACACAGAGTCAACGGTGTCCGGAAAAGCTGGCAACGTTACGAATGCTATGATGGAACCTGTGTAGCAA +GATGTAATGATAATTGTAAAGAGCCAATATGCTCCAATTAGAAGGCGTGTGGAATTTTTCCGCGTGTTGC +TCCACGAGTATTTTCCGGTGAAGGAGAAAGCGTTTGTGAACATGCCAAATACATACCAGAACATGTTTTC +TACCTCACCCCAATTACCCATTAAATGGCTAAGTGTCAAACGGTCGGTAAAAACTATCGGAAATATTCCA +CCGAGGTAAACGCAAATCAGAGCGACCCAGACTGGCCATTGGAACGGTCCCATTATGGCTCTGTATTTCG +GCAGCGCCTTCGATGCAAGTGTTATGAAAGCTGCACAATCGGGTGAGTGCCCCACCGACATGGCTGAGTC +CATCAGCCGTTCCTGTGTTATATATATACCGGACATACCAATGTCTACTGTTCTTTCTATAATCTGTTCC +TGGATGGTGTCTACTACCCCGCGCGTATTCGACCGTGTTGGGGTCTCAGTGATATCTATCGAAAAGTTTA +GCCGCTTAGATATCATTGTCAGCAGACGAAATTCAACTCCGTCCCAACGCAACTGGCCCATTCCTGAGGA +ATCTAAAGTGCGAATTCGAAAAATAAACGGCGGCTGATTTGCGGCTGAAATTTGAAATCTGTGTCCCGCA +AACCCAAATTGAAACTTCGATGGGAAAAGATTTATATGTGGACGTGACAAAGCTCCCTTTATCCAGCTGG +TTAGCACTACCGGAGTGTTTGAGCCAAGTCCATCTGCATAGAGCTTGTGGGTGTAGAGTACGTATGGGCG +CTCCTGTGTGAAGCGCATTATTTGTTACAAAAACGTATCCCTATTAAGCAATACTCACGCGCATCGGGTC +AGCCATGAGCGATTCCCCAATAACTAGTAAATTTACAATGTTTGAGGATAGCTCCGAAGACAAAAAATCA +CGAAGTCTCCATTGGGTGGACCTTGAGACAAGAACTACACGACTTTCAGTTTGCGGGCCTAAAATCTTTC +GCGTCATTAATGGGTCCGAAAGGAAAAGAATGTAGCTTTTGCAATTGCAATCTATATGGCTCGTAAAACG +TTTATTTTTTGCTTCGTAGTCTGCATTGATTTCCCCGTGGTAGAAAGTAATAGGAATAGTCTGAAAAGTA +AATAAAATTGTATTCATACCCGTTATTCGTAGAGTAAAAGGGTATACGAGATTCTTTAAAATAAATGTTA +CAAGTACAAGGGAGCGTTTTCGACTATGTAAAGTATATACATTCTACATACATATTGATTCTATAAGGAT +CAATAGCCAAGTCGATATGGTCCGTATGAACGTCGAAATCCCAGGAACTATAAAAGCTAGAAATTTGAGA +TTAAGCACTCACATTCCAAAAACAAAGACGCAGCGAATGTTTGTTAAATGATGTAACTAATGATTTTATG +CTATATAATTTTGATATATCTGCGAGAACCTATTTAAACACGATTACTAACGAATGTCTGTTGCTTATAC +GGATACGATATGGCCTGATATGGCTATCGCCCAGTTCAGGTCCATAAGGTGTACAGATTACATGTAAATA +CCTATATTGATAAAAAATGTAGTGAACTCATTATATAACCTTAGTTTGATATTTTAAATGCAATGTTCTT +ATGTATTAGTGCACTAAAGGCTTCTTTCGAGCTTACCTTGAACAAATTCTCTAGAATTAATCCGTCAGAT +TTTTCCACAAAGCTATCATAATATATGACCGGTGGGCATTTATTGAGGTACTCTTGGGCAATTTTGTTAA +CCAACCCAACCAATGAGTTAGTCTGCTCGAAGTTATAGGAATTTACGTGAAACTTACTGGCCAAAAGTTC +ACCTCGTGGCCTTGGATTGCCTTGAAATGTAGGGACAATACGGCGTTTTTGACGGAACTCGTTTTCATTA +TTACCATCGCACATTCCCACACCAAAAATTTCTTTGTTTAATTGATAATGGTTGATAAGCCGTCGGCTAA +TACACTTCTCTTGATAACTAGCGGATCTATCCCCTTCAATTGAAAAGGCTTGCGCGGTAAATAAGACCAG +AGCTACCCAATAATATGACATATCGAGCGCAAGTTTGGAGTTCGATGTGTTTTCAGCTGTGAGCCTTTTC +CCCTTTTATACCCCTATATAGATTGAAAGCTTGCACGCTAGGGTTCATCACCTCCATAATTATATAGGGT +TTATTATCGTGGTTAATGCAAGAACGGTAATTGTAACACCTGCAGCAAATATTTCATGTCGGTACAATCA +GAATCAGACTTTTTTTTTGCTGTATTTAGAAATATTCCAATGTTGAAAAATAATAAAAATTGTAATATTT +CATTTTATTGTTACATTTATATTGTTACAAAATCTAGCATAAAATATTTAATTCACTCGCATTTCTATTT +TTTTTATTTTGCGCCTGCTCTTTAAGTTTAAATTATATTTTTTGCGTGCCCTTATTAGTTATCCCGCTTG +CACTATTTAATCACCATGTCTAATTATTGGATGTGGAATCCTCGTAATACTTTCGCATATTATTGAATGG +TTCACGGCAGGCGTGCATGTCGTTTCATTTAACTAAATTAAATAATTTAATTTGCAGAGACCGTCTCAAT +TCTGGGAATCAACTTATTTACCCTTTTTCGCGTTTTTTATTCTCTTCAATTGACTGCCTTTGCGTATCCA +TTAGTTAGGACTAAGGCTATAAAGTTTTTGTTAAACTTTTTAAAGATTTTAATTTAAAAAATAATACATT +ACGACTAAACAAATTTAGCGCTCATTATTTTTAGACTCACACCAATAAAATAACTTAAACTTGAAACCGC +ACTGGTTAATCTTAATGCACCCAAACCCAATACCAATTTGGCTTTGACAATATTTTCATTAAAAATACGC +AGTTTAAGTGGGAAAAAGGAGGCTTGAGCCAATCTAATAATACATAAATTCAGCTGTATCTCTTTATCAC +ATGTAAACAAAAAATTATATTAGCCTAATACCTAAATGCGTTCTTGGTGTGTGGACTTGATGCATCCAAA +TCATACTTGTAATTTTATTATTTTCAAAGACTCGGTGCACCAATTACGCCTTTTATTAGTACTTATTAAA +ATAGGGTTCTATGCCTAATTGATTTCCGTTTACAAGGGTCGTGCAGCGATTGCGTGCTCAATGTATCGTA +AATATCTATAGGAATATACAGAATGGTATGGAGTATGCAAAAGGGAATAAATAATTTGTATTAACATGCT +GCAAAAATGTAACTAGGCTCCTTTTAAAGAATTAGCTAAAATGACGAAATTGTTAGAAAACATTTTAACG +AGTGAACTCCGTATTTTGAGCTCAAATGTTTATCGCTTTTATATTTCAGTATCTTGGATTGTCAGGTGTC +CCTTTTGCCTATTGATGGTCCATCCGCAAATGGTCAACGCGAGACTATTGATTTCCAGTCTTACGCTGCC +GGCTCTTCAACTTCATTATCGATTCGGGAAGATCGAATTCCAGATTTTCCAGTCCAGGGGTAAATGTCGG +GGCATGGTTGACACGTTTTCATGTACCGGACGCCGGACTTGTGCCACAAATTACACACTTTTGGGTTGTT +GCAGCGTTTGGGCCGATCCTTGTTGATATTCAATTGTTTTTTTTGGTTTTAATTGGTTTCCTGAACTAGA +TTGTTAATCAACTGTGTATACCTACCGAATAATCGCACTGAAATGGTTGGAATGAGTTTATGCGTGATAT +CGGTGTAGGGTCTCGCACCCATTGAAGCGCTTGCCAGTTGGTTATTATCCACACATCTTGCATTGCATTG +ATGGCATCAAGAAATTTAATAAAGCCCTCTTTGTGATGGGGCTGGGTAAACCATGCAGCGTGGTAAAACA +AGCCAAATGGTGCTCTAAAATACATAGATGAAGAAATTAAATAAGCCATAGGGCCATTGTTTCAAATTTA +AACCTAAATTAAGAGTTTCAGTAGAGGTTTACCTGTTTGTAGTGTAATGACGTTCAAAGTTCTTCATAAT +CATCTTTGTCACTCCATCTGCATCACTAGGGTTGGAACAGGCATCGCCCATAGAACAGCGGCCTCCGTTA +AGGTCCTGCCACATGACCATAGGTACCTGCCACACCCCAGGATAGGAACGGGTCGGGCAAGGCGGAATCA +TGCAGTCGTGGAATATCTTGTAGTCAAGCGTGTAGGGCCAGGAGGGTGGTCGGTTTTCGTAGACAGGCAT +GGAAGAGTCGTAGGTGAAGTTTGAGTCGTACAGCATTTTGTACATTTTGTTTCCGCCCACCGACAGGAAA +GGAGCACGCATGCCTCGAACATCCGACATCTTGACACCGCCGTACGCAGCAAGGATCTCACGCTGTCCGG +CAATTTCACGAGTCCACTTCTTCTGGGAGAACTGCTCGCCAAAGCTGTGACTGTAGATCAATGCCTTTAT +AGTTATTTCTATTGTTAGCAAGTGAGAACGCTATAGTCAATTTACTCGACTATTAGATACCCGGTGTTGA +GATAGTGGAAGTACAAACGGAACGTTTTGTAAAATCAAAAATTAAGTCAAGAAATCTTTCAAAGCGATGG +GCATGACTGTTTTCGGCTGTTTAAGAGTCTAAGAGTGGGCGTGTCCATCTTCTGAATAAATTCATGTTTA +GTCTTAGCTTTAGAGCTTTTATATTTATTAAGATTCGACGTTCATACGGACTATTAGAGAGACAGACGAG +CTAGTGGTAAACGGTCCCTTCCACATGTTACACTCTTTCCAAAGGACAGGTATATAAATAAGTGTTATTT +TTTGTAAACAAAGCGATTTGGGTTTATTCTGTGTGAGATTTGTTATGAGAGGTGATTGACTACATATGTA +AGTACCGTGATTCGGCGATACCTCTACTAGTTGACTTTATTGTGTATTTCATTGTCGGGTCAAAAACTTG +TTCCATCTACTTACGAAACTGTATGCGAAGCCATTTCATGTCCATCGGCGTAAAGATTCTGCACTTGACT +GTAGTCAGTCCACTCGTGGGAAACGTAAAAAGTGGCTGTGATGGGACAGCCGTTTGGATTGACGCGACCT +TTTTCAAAAAGATCCGTGTACAACTGCTTGTTTAGGTCATTAACGGAATCGTCAAAGGTCAAGAGAACGA +TCTGAGGGATGCTTTCAACAGGTAGCTCGCCTAACAATGTAGATGAAATGTGGGTGAAAAAAGTAAGAAA +ATCATAGCAGATGGATATAGAACGAGTAACCATTTTAGCCAAGAACAAGATACCGATGTGGACTGTGATC +AAGAGGCGCTTTAGGAGAATGAGACCCTCGAAAATGGCAACACGGTTTAACGCAACTTACGAAACGGTGT +GGGAGGCCATTTCATGCCCTTGCGAGTACAAATCCTGTACCATGACGTAGTCCGTCCACTCGTGTGATAG +GTAAAAAGTTCCGCGCCAAGAACAACCGTTGGGATTTTTCCGCGACTTATTATTAAAGAGTTCCTCGTAA +AGATCAATATTAATGGTATTGACGGCATCATCGAACGTCATAAGTACGAATTGCGGGGTCTCTGAGGCGT +TTAATCCGCCTACACATTGGTTTGCATTATTGTTATTATTTAGCATAAGGGCTATTGTTTCTGCACTAAA +ATCGTGATCTACCTAACTGGGCGTGTACTTACCAGGAATATCTCTTCCTCCGCAATAGCAGTCAGGCAAA +AGGCATACGTCCTTTCGGCATTTGGCTGCCGTTTTATCTGGCATAGGCTGTGGGTAAATAGGGTCAGGGC +GGGACGGTGGGTAACGGTATATATCCACAAACTCTTGAGCCTTTGATACAATTGTTCCCGATGGCTTAAG +TGTTGGCCGCGTTCGTCTTAAAAAATTTTACGTTATCTTACTGCGCAACAAAATATTAGACGATTCCTTA +CGGAGGATGAGTTCCGCGGTTGGGCGTGGATATCACGTCTCGATCCTGATTACTGTACATGGCACTGCCC +CGGTTCCTGTTGTTGTTTCTAGATGAGGTTTGTCGATATAGTTGTTTATGAAAAGGTTTGAGTTGGTAGG +GTCATAGCTTCTCTACTCAAATATAATTTAATTTAAATGGCATTTACTAATTTGTGCTGCACAAATACAC +AAGAGATACTAAGGAACGCAAGATTAACTGTTTGAATGGTATATGTTGGTTAGTAATCATTACAAACTTT +TAATTTTAACTTTTTATCACCTTCACCGACAAAAGCAACATAATATAATAGCCCAATTCATTAACTTTTT +TCTATAGTGAGAACCAAAAAGTTTTATAGCATACTAATGTGTTTCGTTTTAAACGACAATACAGACTGAG +AAAATACAAATAATTGTATTATTTATGCGTAAAGACTTCATGAGCAATCATTCACAATAAGTTGCACAAA +TAGTCTGATTTATTTATTGTTGAAGTTTTTAATCTAAGCAGTAGAGATTTATACTTAAAGACAATTGCGT +AGACTATCTAGAGGATTTACTATGGGGTCTAAATATTATTTTCTTGTAACAACACACAAGCGTGTACCAA +ATTTATGCTCGGTAAAATGTGCGAAAAATTTGATTTAGTTTTGTTTGCCTTTTATCGGTGTCGTATATGA +AAATGTTTCAATTAATTTGTTTATTCCGTTTTTTATATATGATCTATATATCCATTTTGCATACAAATTA +AAAATGTAAACTAAAAAATATGAATTTCTTTAATATTTAACTTATTGGTTATTGATGACATTTAAAAATT +TGGAAAACCAATTGACGTGAATATAGAATAAAAAAATTTTGTAGGGATATACTTAACTATCCACCACCGC +TAGGAATATAACGATAACCAGCGATCGGTTGACGGAATTTTATAATGACAACTTTCTACAATTTATTTAC +TAAAGTATTTGCAACATTTTAACCAGCAGTTAAATTGTAGTAAGAACTTGTGTGCTTTGCATAATGTCAC +CGAGTAATTTTCTGTAAAATAGAACACTACTTTGAATATTTACATATAAGTACATTAATCAAACACTGTT +CAATAGGTATTGGGTTTCAAGCAAAGAAAACTGTTGACAGGATGAAGTCAACAATCAACACCAACCAAAT +GGAAGAGTTACTATAAATATGTAATTAGAGGTGGGTAGATGGGGGTGGTATGAGAGACTAGAGAAAGCTT +GAAAACAGTATAATAAAAACAGTACAGTGTTGGGGCTTGGTTTGTTGTGTACAAAACGAAATTACGGTGA +TTCTAATAAAGGAATAAAGAGAGCAATAAGATAGTAGATCGACTGAACTTAGAAGCAAGATTGCTTGATA +CGGGTATCTATACCTTGAAGAGATTTCGTTGCATTTGGCGTTTAGTGTGCTATCGGAGCACTTCACAGAG +GCTGAGGCTGCGGGCCCATTATGGTTGATGCTGCTCTTTTGGAGTTGGTGATTTTTATTGTTGGTAGCGA +AGCCGATTTGAAACTTTTGGGTTTTACCCGCTGACACTGGTGGCTGATAGGTTGAGGTGCTAGGGCCTAG +GGCAGCGGCAGCAATCGACGACTTAATATCATTATTCACCCTCGAAGCGCGCGCAGTGTGCGGTGCAAAT +GAGGAGGGTGTAGCTGTACCGGTGGGAATAGTGGGGACAGTAGTTAGAGAAACTGGAGGGGTTTTGAGGG +TTCTAGGGGTACTAAAATCAGGAGTGCTTGACGTTGTTCTTTCTGTTAAAGTGGAATTAGCGGTCAAGAT +GTTAAGAGACGGTAAAACGGATACTCCCTTGATTCGGATTGGAAATAGTGTGGCAATAGGCGTGGTATCA +GGATGCAACGTAGTCGTGCTAGATTTTAAAGTGGTCGTTGCTGGCCGGTCGTTGGGCAAGTACAGTTTCT +TGATTTCACCGATAGCGGACCTTAATTCGGGGAGTGAATACTCATTAACGAATTGGGAATTGGCACTCTC +ATCGCTTTTGCTGTTGCTGTCACTGCCGGAAAGAAATTGCCTCAGTTGATCAAGGACGTTGGCGGATCTG +AACTTCTGTGACGACCCGTTAGGCGATGTTATGTAGCCGGAGTTTTGAAGACTATCTGCTAGAGTGTGCT +CCGCCGTTTGCTGTCGGTATTTGTTAGAGTAAAGGAACTTGACAGTTGGACGTTCTGTTATTGCCACCAC +GTGTTCGGTGGAGCTGTAATCTATTGCAGTTTCTTTTTCATTAATGCCATTTTGATAACTGTCCTCCAAA +GGCTTGCTTATTAACGCCTCGGCTCTTGGCTCGTCCGAAACGCTGGCTTCATTTTCGATTGCTTTATGTT +TAAGCGACTTGCTTAGTATATTTTGGGAGCCAAAGGCGAGATCTCTGGCGTGCAATGTGCCCTTTATTTC +CCTATACTTTTCATGTGGCATTGCTGTTGGCCCACCTAACAAAGACCTCTGATTGCCGATCACTTGTACT +CGTTGGGGCTTGGTTTTAGGCAGCGGAATGGGATCATATCCGCGGAGCAATCTAAGCTTGGGTGCATAAG +TCGTGGGCTCGTCCCCGCTGTCCCCGAGACTGTTTAAAGTGGCCGCCGTGTATCGAGAGCGCCCACGCGC +AGGCTTTGGGGACTGTGATATTTGGATGGCAGAGGAAGCGATTATGGCAGAAACGGTTGTTGAATCTTCA +GTCGACGTTATTCCTAGGGGAGGTGGTCTCATGGTAGTAGTTGTTGTAGTCGTGGTAGTGGTTCGCAGCA +TACTTGGGGCAGGACGCTGAGGACTGAATGTGCTTAGTATAGCGTCGCTGACACTAAAGTTGCGAGCGTT +TCCTGTCTCCATTGTGGCCAAAACATCTTTACTAGAGTTTCTAACAGACGCCATCATAAAAAGATTCTTT +CGTGATTTTGCCGTAGTCTGGAGGAACTCCGGAAAGGCAGGAGAATTTGTGTAGCGGGGTCTGGTTGTAG +TCCGTAGTTGGTGATGGTGGTGCTGGCGATCTTCATGAAGCAAGTTCTCAAGGCTTTTGAACGGTGAGAC +AAAATGCATAGCAGGGTTGGCTGTTACTCGATTTGGACTTTCCTTGAAATAATTGGAACGGGGCAAATAA +CCTGCCCTTGGTAGAAAATTCTGTTCTCGGCTGGGCTGCGCCGCAGATTTTGATGCTGTAATGGCCCTGG +TAGTGCTGCTAGACTCAGCTACATCTTTAGAAGTTGTAGGAGGAGATGTAGTTGTAGTAACGCTAGTAGA +TGTGATGAAAGTTGCGACTGTTGGTCTATGAAGTGCTTGTTGAATGATGGGCCTTCCACTACGCCAAATG +AGAAGTGGTGGAGCGTAAGTTGTAGGTTTGATGTCGACGAACTTCTGAAATAAGTCCGCCAGTGTTGTTG +AGCTAGTTGTGGTTGTGCTTGTGGAAAAACTTTTCGTCTTTGCGATCATTGGCTCCACATGCAAACTAAA +ACCTTTTGATCCACTTTGAAGACTATATTGTAGGGGCTTACTTGGCCTGGTTGTGCTTGTGCTTTCCATT +TCTTCCGTTGGTGCTCGCATTCCACCCTTTGTGGGAACTTTAAAACTTTGTGGAGGTACATCAGAATCTA +CGTACTTCTGAAAACGTTTGGGCTCTGGTTCTGTGTTCGGTGAGCTCGACTCAAACGAGTTGTCCTTGTC +TCGAAAAGGAATATCCTTGTTAACAAGATTATCTGGCACTTCATTCAGCCGAATGCCACTCGGGCTTGTA +CCATACGCTGCGGCATTAATAAAATCTAGGAACTTTGACGATGTGGTCGTTTCAAAGGAGCGACTCTTTG +GCGGATCAACCGTCTGATTAATTGTATGACTCTTGTCAAAGGCACTGTCAACGTTGTCCGGGCTGCTATT +ACTGGAGTTGTCCTTTACCAAGGGCCTTTGCGTGGTGGTGGGCGGGGGAATTAGGGAAATAATTTGACCG +GAAACTTGGTCAGGAACTGATTCCAAACTTGTGGACTGGTGGGGCGAGTTTGTAAGGTTTTGAGCTTGAG +GGTAACCGGTAAAATTTATCCTAGGTTGACTGCTTGGCACTACTCTTGCCAACGACTTAGCAACTTGTTG +TAGTTTCGATTGGAGAAAAGGATTTGAACTATAAGTAAGGTGATTAGGAAAAGGTGTGGAGCTGGTCGTG +GTCATGTAAGATGTACTGGAAGCTTTTGTGGTTGTTTTTGACTTGTCAGGAATATGTTGTTTATATGGCT +TATTTGCATGCGCTTTCGAGCTGTTGAAGAGACGTGTATTGGAATAAGTAATCACATAAGTGTTAGTAAC +TTATTTAAATACGTATAGAGTCGCCTATTTGCCTAGCCTTTTGGTTCTCAGATTTTTTAATTAATTTTGG +TTTTTGGTTATCGTTTTCGGTTGGGCTGTAATCTGAGACAACTGCATTTAACGGATAGAAGCATGCTCAT +GCGTACCTATATTTCGAATCACCTAAACGTTATCTTATGAATAGTCATGCAATATATGTGAGTAAATAAT +CATATTAGAAAGATAAACAAAAACAAAATTAAGTAACAAAAGTGTCTAAACAGTCAGCATAGCTTTTGAT +CCCTGTCACGACGCAAAAAAGTGTGTAACTTTGCTGACGCTGTATATATCATTACATTGCTATAAGGGTG +TAACTGTGTGATAGCCAAAATTTTAAGCTGCAAATGGTTTGTAAATATGATATATTACAAGCTTCATGAA +AATCGGTTTATGACTGATCCGCGATTACGTTGAAAGGCGACTGGCAGAGATACTTTTGTTCAGATGTTTT +TTCAGGTAGCGATTCCAATGAATAGGTAAAATACCTTGCAAGTTTTGTTGTTGTCGTTGGAGGAAATGTG +GATGTGGTTGTTATTGTTGAGGACTTTGTAAACGTAACAGCATGTGTTGTGGTGTTGGAACTCCTTGCAT +GGCTTCCGTTATGTGGCGGCGTCGATTTCGTTTTTTGCGATCGTGTTGGTGGAGTTCCGGTGGTCTTGTC +GGTATGGCCCACAACATTGGCAATTAGGTCAAAGTCTTCCGTACCGGTATGGGGCCTTGACTTGACTTCG +GTTAGTAAACGGTCCCTCTGGTCATAGTCTTCTATCGACCCATAGCCGTAGTCGCTAGACCCGCCCTTCG +GAGCATAGGCTGTGGTCAGCGTTTCGTAGTATGTGAGTACTTCCGGTTGAGATGCTGGCGTTGTTAGAGT +GAGTGTGCTCGAGTGGCTGGCTCGGGTATCCAGTTTTTGTATGGCCACATGTTCTGCCCTGATAGATAAA +TGTATTGTGGTTTGGTGTATACGTATTGGCTTGGTGGTTGTGTAAAAATTTTGATGCATGTGTAGTGAGA +ATATGAAGTTTTACACTTGTTAGGGTTCTAACTAGTTTTGCGGGATACTTCTTATTGCAGGAACTTTTCA +TGCTTGCAAGGCTGACTGTTTTTCTGGGATTGAGTTTTTTCGTGGATGATCTCTTTTAAAATGCTTTTTA +AATTAACGAATGCCGTGGCTTCAAAGCATTTAAATGGAATTACTTACCTTTGAGGAGTACGTGTTGGATG +ATCGTACGCATTATCCTGTTCAATCTAAAATTATGGGTAAACATAAAATTCGTAGTATTTAAATATATAT +ATAGTTTGTGAAAAGAAACGGTATTTAAAAGTTACAATATGAGAAATACTAATATAGATTTTTCTGTACC +TGGCTATTAATATCCTCATCGTAGTCTGTATTGTACGCTGGCTGGTTTTCGTAAGAGGGGGGCTTCGGAG +TGGCGGGAAGCTCTAAGGGGCGGTAGGTTGGGTGGGCCTGCTGTTGGCGCACTGCCGACTGATACTGCGG +CGTAGGTGTTTTCTGCTGCTCCTGTGACTGTTGCTGATGGTACTCTATATCCCTATATAAATCGATATCG +TCGTCGTAAACCGAATAATAGGATGTGTCATATGAATGTGTTGGGGCTTGTGCCTGCTGCTGATGTTGTT +CTTGTGGTTGCGCTTGTTGGAATGGTGTTGGTTGTGGCTGTTGTTGTTGGTTTTGCTGCTGTGGTTGGTA +GCTGCCCCCATGATTAAATGTAGATGCATTGTAGTAGTTACGATTGGGCTCTGACTGTTGCGGCGGGGCT +GCTGACGTGGGCTGTACAAATATATTAGCGGGTTGCGGTGTCCCTAGCGATGACGGTGAAGGCGACTCAA +CTCTGTTCAAGTTGTTGTTTTTGTTGTTGATGGTTTGTGAGAGTAGAGTTGTCGAATAAATAGCAAAAAT +TATATACATTGCCAAAAATTCAAAAAATGTTATAGGGTACATTAATGAGAGACATGTGGTTTTTATAAAT +AGGAAAGATAAAAGTAAAATAAGATTTTAAGAAAATTTCTACAAATTTTACAAAATAATAAGTACAAAAG +ATGGATGAAAAGATTGAAGCGATTAGCACAAGAAATTAGCTGGGGTTAGCGTTAAAATTATGGTTATAGT +TAAAGGAGCCCAGTCCAGAACATTTGTTTAGTCAACTGTACAGCTTGATAATTTCGTTACGTGAATTGCT +TAGTAGTGGGTCTTATCGTATACGTATAAACGGTGTTGCCGCCGAGTTGGGCGGAGCGGTGTAGAATATA +TGGTATATTTACATAGAGGAGCACTTGGTTTCTGTATTCACTAAATTCTTGTGTATCTGTGTAGCGGCAT +TATAGAATTCAACAATCAGAGATTTGTCTCGGCTCATATAGCTACCTGTGTCTTTCTGGACTTGAGCCGG +CATGTATTGAGTTTAGAGGAATGCCGCCCGGGTTGCTCTGCTTGCTTGAGTTTAAGACAACGGTATTGCT +TTCGGTATGATTATTTATTTCCTTTTGTTCTTGGACTGGTGACGTCGTATTCCATTTTTGTTGTCCTCGT +ATGCGTGGTCGGATAGTTGTATAACGCACTCGAGTTGACTGCTGTTCTGTACTGGAGGCGATAGGCCTTG +GATGGGAGGTTGGGCGCACACTGCGTGGAGTTGTGAGTATTTTGGTACTGGATTGTGGGGCGTTGGATTC +CGGGAGCTTGGGCAGCCGTTGCTTTAGTTCTTGGAAAATGTCACTAGGAAAGCTTATAAATGAGGGCACG +TCGGCCTCAGCAGCTGCTTGCTTCTCCTGGGTGAAGTTGGGAAACGGACGTCGGGTTGTTGTTGCCTCCA +GAAACCCCGTCTGGAAATTGGCTGGACCTTTCCCTGGCGACTCAGTATTGGGTCTTACTGTAGCCAAATG +TCGGCGGGGAGGGGCCATGGTCTCGGAGACTGGCATATAAGGAGGCATTTGAGACGGAGGCAATATGTCA +TCATCCTCTTCGTAATCCTCGTCATAATAGTCGACACTCTTGATGGTCGTGGTGGTTGGCATTCGTATTA +AAGTGGTTGATGTGTTGTAGACGGTACTTTGGCTAGAGTTCCGCGAGTTGAGTTGATTCTGTATGCCCTT +AATAAAATGTTCGTAGCCTTTCAGAATCCTCATTGTAGTCGGAGTGCTCTGCGTGGGGAGTGTCGGCTCA +GGTCTTATGCGTTTTTTGTACGCTGGTGTGTTCGGCGTGATGTCTACCTGGGGGGTCGTAGCTGTGCTGT +TCAAGGTGCTGGTACTCCCAGTTACGGGGCGACGATTAACCAGCGGATTGGGTAAATTTTTATTTCCGTT +ATCGTCAGTACTAAGATCTTTCAAATATTTGATCAACGGATTAACAGCCGGGTTGACACTGGCCAAATCG +CTTTCCTTAAGATTGGCCATGAACTCGTTGATGTTAAACTGAAAGTTTGTCAGTTTTGACTTAGGCGTTG +TAGTAAGCATATCCGCCAGCAGTGTTGCTGATGTGCTGACTGATTTAGTGAAAGTTTGGTAGGATTCTGG +AATGGTGCTGTTGATGGCGTAGCTAATGCCTTCGGGAAATAGAGCAAATGGGGCTTGCTGCAGACGATTA +GGTATTCTGTAGGTCAAATTTGGGGCAGAGACCACGTTAATACTCTGAGTCACATGCAGCGGCGTGACTG +GGGGCCGAACTTTAACTGCAGAATGATCAATCTGGTTTGGCGGAGCTGTGCTAAACACACCCTTCATCTT +CTGGTTAGCAACAATGTTGTACTGAAAGTAGTTGCTTTCCGTCGTGCTGTCATGTCCGTTAGAGGCAATA +CTATACTGGGATATCAACTTGCCGGGATAGTTGGGATTAAAGGAGGCTTGACCCGGTTTTTGGTTGTTGT +AGAATCCGCCCATTGTGCTGTATTGACCATTTGATGTAACCTGTTGTGAGAGCTTGGACGGGTCTACTGG +GGAGTAGTAAGTGGTGCTAATTGTGGGTACGGGTGTGACTGCTTGATTGGGTACCGGACTTATTGGCTGA +TTGTCCAGACGGAAGTACGCAAAGTTATCACTCTGGTGCTTGCGCTGTTCTTTTAGCTCCTTCAACTGTT +GTATCAGATAAGGGAGCAGGTCGCCAGCGTTAGAATGGTGCTGTTTGCTGTTGGGCGAACGAGGACTAGT +TTGAGCTGCACCGGCAGCTTCGTAGTAGCTACCTGCTATGGGACGAAAGTCATCCTCCAGCGGCGGGGGA +GGCAACGAAAGATTGTAGCCGGTGTAAGCCAATTTGTGCTTTTTCTGAGAGAATGGCCCAGCAGAAGCCA +ATTGTTGTTGCTGATGCACGTATGAGTGGTAGCCGGGTAGATGATTATAGTTAGGGTTGCCGTATGGCTG +TTGATTGTGGACAGGATTAGTATTGGGTGGTGTGAGGTATGGATTATAATTTCCAAAGCTGTATCCCGCT +TGCTGAGAAACCTGTGGAAGAGGGGGTGCGTCAATGGCGCGGTAGTTTTGTCCCGGCCACTTCAGTGATG +TATGTGAAATAGGTCGTAGCTGGCGTGGTCGTCTCTTCGACTCACCCGTGGCCACATCATCCTCGTCTTC +ATATCCTTCCATCAACTGGCTGTCTTCGCCAGGAATTTCTTTGTAGTCGAATTCCATTGCGTTCTCGCTC +TTTAGCTGACGTATTTTGGAAGAGTATTTACACATCCTACCAATTGCCGGCGCACCATCGTTTAAGCGTT +CTTGAGAACTGTATGAAATATTTGAAGTCTCAGTAGAAACAGAAAGCGCGGTAGGGCTAGTGCGCTCAAA +CACTACGCTTGAACAATTTGAGTCGTTGCGATTTTTTTCTTCTGAAACTTTCGTCGGCTGGGCACTAAGG +TCGCGGCGTTTGCGTCGCCTACTTTCATCAAGTCGGTTGTAGGACAGTTCGTGAGTATGGTCGTCCTGCA +GGCTTTCGCTGTTCGTGTACAGTGTTTTTTCCAAAAGCGTAAAGGTTGTCCGGGTTTAAGTCGGAGTGTA +GATGTGTCGGTGTCGGGTGGTGCAAAAAGATAGCGCAGTATGCGTTGTATGAGAGAAAAGAGCATGTAAC +ATAATGAGTTGCTTGGAATTTTGCTGGCATCAAAAAGTAGTGTCATCGATTAGAAAGCAACGATTGTGAG +ATCTGAGCTACTTGTGGCAGGAATAACAGCTTACCTATAGGCGGTTCCAAAAGCGTAAGATCCGATTTTT +CCAGTTTGAGGAATAGAATTAATACTAGCTTGGTGAATAATACCATCGCGATCGCGTTGAACTTGACTAA +CGGTACTGGGTTGGCCTCGATACACTCTCTGCTGACGGTCGGACTCCTCTTCTTCCACAGGCGGCAATGA +TTCCTGCGCATCAGCATACAGCTAAATTACATAAAATATTTACATTTTATTTCGGTTTTAAAAGTTCATT +TGTGTGAAAATTTTAAAATTAGAAATCACTAGATGGAAAGCTTACGTACCTACCAGGAAAGTGTGTGAAG +TCGACTACTATGTACTATATATACACGAAGAAACAAAAATCTGCTGTTCGATATTAAGGAGTAATACAAA +AATCGAAGGGTATCGTAAAAACTAACGAGAATGCATACCAACACTTAATAGTTTACGAGAAAAAGCGGCG +AAAGCGTAATATTTGAAATATTGAAATTGTGGTTATGGGTCTGTAAAAAGAGCGCATCGATTGACACCTG +AATCATATAATTATTCAAAAGATATTGTTCTAATTTTGATTTTTTTTTAAACATTCCCTCGCAAACATCG +ATTTTTTTTTGTTTTTTAATTTAATCACTGCAAGGGTATATAAACCTCGACTTGCTTAGTTCTTATATTA +TTTTTTTTTCAATTATATTATATGAATTCGGAGAATTGAAAGAATGATCCCCCAAAATAAATCCTCAGTT +TGTCTTCGAATTCATGTTCTTTTGAGTTACCTTTGCAATGTCCTCCTGGGAGTCGATCAGCGGTTTTGGT +TGACCACGCGACGTGATTACCGGGTTTGGTGACACTCGCAGCTCCGGTGGGGGAGGAGGTATATTCTGCA +CCTGCGCCTGTATTACCTGTGGTGGAGAACGATGGTACTGTGGCGGCACTGTGGCCGTCTTCTGTGTGCC +ACCCTGACTGCTGAAAGCGGCTCCAAAACGTACTCGGCTTGGCACGTGCTGTGCATGGGGTTCTCTTTGC +CTCTGGACCTGGCTTTGTGCAAGGTTGCGCTCGGAGGATGTGTCCGCCAACTCGCAGCCGACGTTTCGCG +GCCAGTCGCAGGTCTGCAGGTCGTGCGAGTACATCAAGCCGCCAGTGCAACTTTCAAGCAGCGCTCCTCC +AAAGACGCACACGTAGTATTGGGTGCAATCCGATGGGTGCGGATAGTATCCGAACTCCTCAGGGCAGTCG +AAGCTAGGGCCATTGGAAGTGTCGGTCTTGATGTTGGTCCCGAAGCTGCGGGAGCTGGTTACGCGCGAGG +TTCGTTTGTTTTGTGCCTCTGTGGGTGCTAGAAAAAAGATTGTATTTAAATGAGTGTTTGGTTTTTTGGG +AACACATTTTGGAATCACGAGAATCACGCAGGAATATAATGTCAATTGTTCACGTATTTTGACGATGTGG +AAAAATACAAGTTATTCCTTGTGTAAGAGTCCATGTTACTTTTTCCCTTTTCACGTAATCATACAAAATA +TGACATTAAAGTACATATGACCAATGGCTTTTTTTGGTTGATGGTGTTATTTCCTCAGTCGTTGTAAAAG +GCCTCTTACTTAGCTCAAGAATTTGGTACATTAAGTAGGTAAAACAAATTTATAGCGATGAAATAAATGG +ATCCTAAGGGACACAATATATGATTTTTGCGAGATAGTGTCAAGGCTTCAAGTAGGCATTTAGCTTTATT +TACAATTGAGTTACCACGCTCCAAAAAGTCATCAAGTATGCATCTCCCTCTAGACCTCTGCTCTGATGTG +AATACTTGCTACAGTCTGCTATATTGACGAATCCAATGATATATTAACATAAATATGTACGTTGGAGGTA +GATATAAAAATCCAATCACGTGCCAATGGTTACTGACCATGCAAGAGAGCTAGACCTGCCAACAGCATTT +GCTATTGTGCTCGTGGCGCTGTCGCTACCAATGCTAAGCAATCAGACAGTCTGCTCCACTGAACAATACC +ACTTTGTACGCTTCGTATTGTACTTCGAAGCCAGATCAAAAGCTATATCTTGAATCGAAGCAAGGCATGA +AAGCTCTGTTGTAACGCAGCTCGCAGTAATTCGAACACAATCTTGACTGGTTTTGCTTGGCATTTGTTGC +TTGTGTTCGCTTAATATTTATTACTTTATTGGTGTATCTAGGACTAATAATAGTCCTAATAATAACTTTG +TACTGGAAACTCTTACCTTCAGGTAATGGAGAAAGATAGCTCATGTGATCACAGTTTTCTCTTTACCGTA +CCGCGCACCGAGCAAGAAAGACAGAATCAAAAGCCTGACAATTCCGACCATTGTTCGGCTTACTCTTTTT +GTATGCTATGCTATATGCATATATACACGCGAACAACAAGCCATATACGTGGTTTGAAGATGAACTTGAC +TTTTATGTCAGTCGGAAGCAACACTTAAACATGGTACTAATGGCTCTTTCCCAAAGTACCGGCTCAAAAA +ACAAATTTAGATGAATAATAATTTTGCATATGATTGTTGCTTTGGAAATGCTGAGCTTTAAAAACCAATG +AAGCTCTCCATTATTTGTTTGTTAAAGAAATAAAAGCCAACTCTGCATGCTTCTATGTTTTTGTCCAGAA +AATACACAACCTTACATCGCGCGATAGCTTTCGTAGGTTTTACTTTTTCGTGCTCAAGGCGATAGTATAT +GTAAAACACAATTTTTTTTAATATTATACTGGGTGATGATACCCGGTGCGACTTAGATGTGTCACTGCTG +CCTGGCCCAAAATAGTACGAGAAATAAGATGGCTTGAAAAAGCGGCATTTCAACATCGCCTCTAAAGCCA +TTAAATTGGTAACCGCCAATAGCATGGCCAAATTTAGACAAATGGCGCAAATCATTGCACTAATTGCCAC +CTCGTTTGGCAGCGTCAAATGGATCTTATTTATGCCATCCTCAATGAGCTGTTAGTCAACACTGCAGTTG +GTAAAAGAGGTAGTTAGGTCAAATAACATTAAGCCTTTAAATAAATCTGTTCAATTACGTTACGTGGATA +AAGTTGGAAGTCTTTTCAATATTTATTTTATTTCTTTCACTTCTAATTACTTATAAGTTGGTTAATAATA +TTAGTTTAGGTCAAGATGAATGTTGAAACTTTAATAACGGTCTTTGTTATATTCAGTTATATAGTCAGGG +CCTGCTTGAGTGCCTTAATAAAATTTCCCTTTTTCGTGTTACGCGTTTGAACTTTTAATTACACGTAGCT +TGTTGTTAAAGACTTCCATTTCACTGGGTCCGGTTCAAAATTAAACGCGCGCCGAGCACACCCGCCAGAT +AAAAATATAAATTACTCAGTGCAAAAGCGATCAATTCAATTGCTTGTTGCATTCCGACATTACTTTGATA +ATTAAACATAACCCATATGACCACAAACACAATATTTTCCTTTGCAGGCATACGTCAATGTTAGTCCGTA +CTGATCAGCATTTTATTATTGTGTTTCCGGTATATAAATATCATTCATGCTTTTTCTTCTCGGGTCAAAC +ACATAAACCCAAACAAAAAGATATGGGTTCTCAAATGTAAAGAAATCATTTCGTGTTGTCAAAATAAACC +AATTTTGACTTTACATTGCAGTAAAATCTCTGATATAGGAGGCTTCAGTTGTCTTAGATAGTAAGAAATA +AAAGTGAATAGCAGCAGTGTGCCTAAAGAGAAACAAAACAGGAAATATCCACCTCTTTCTCTTGCCCCAT +GCCTCTTCTCCCGGGTACTTTTATTTTCGTAGCTGTGGGCAACATTCAAATACTAAGCGAAGCTCCGGCA +TGAAGTGCTTATGGACTGTTATGCAACTAGCCAATGGGCTTATGTTTCCACTCATACTCGAACAATCGAA +AATATACTTTCTACTGTATCTCAACAGTGGCTTAGTTTACCTCCCAACAATTTTTTGGGGGAGAATGCTT +CAGTTTTCAGTAAAAAGCTGTGTCGGCGGTTTTACGTATATACTACAAGCATAGCTAAGTTTATTTGTTT +CGAAGTGAAGAGAGAGCGGCCCGGTAGTAGGACACTTGTGTGGATAATTTGAATTATTGTCTACGTATTA +GAAACTGTCATTGTGAGTCTAGTTTTACCGCCTGACTTTGCCTATTGGTATTCAGTTAACTGCTTTAACT +AAGATAAGGAGAATTTAATCGCTTATTATACCTGCGGGTTCTAACCGCTTCTAAAAGAATGAATGCCGAA +AAGGGTGAGAATTCGCAACATACTGTGTTTTGGGCTGTTTTTTTTATAGACTTAGTCATATGCAACGGCC +ACCTGTACCATGTCAGAAAGCAGACACGAAAAAAAAAGACTTTGCTGGCACGCAGCATATTTGCAGTTGA +GTGCAACAAGCCGTCCAGTATGTGCACTCGTTATGACTGGCAATATGACTCTTGTGGCACACGTTATTAT +CAACTGGGCAACTTTTTAAAATGGTAATTGGCAGCTAACTTTCAAAATTTTTTCGATATATAGTGTAGTC +GTAAGAGCTTTCCGTTTTCCTCTAGACTGCTCTAAACTTCAGGTGTGTAAGATGGCTAATCGAACCAATG +GCTGTTCTAAGGATTCCAAAATTATTTCTGGCCATAGTTTGCATTTGAGTTGCCCGAAAGTGAATGCTGG +CCAAGCATTGGCGACAAAGACCTCAAGTAAACGGACCGAAAGTGGGTCAGACAGAGAATGTTGCATAACC +ATCAAATACACAACTCGCTGGTGAACGAGACATTCGTGCTTGCTCCACTGTGTGTGTAAGTATCTGAGAT +CTTTTTGCTAGAGGCCGTAGCTAGACCGACTGCAACGACAGCGACAACGCTACATTGTGGTACTAGCCTC +ACCACGCCCTCTTTAAATTTGATCACTTTCGCTTCGTGTAACTGCAACTACGATTTATGTGCTATGCAAT +GTCCGTCGTTCATGTGTCGCATTAGCAATAAGGCTACCATATCTTGTGTGCTCTACACTAGCTAGCCAAC +AACAATCCATACTGGAGACGGAACGGAGACTTCAAAATAAGTTTCCGAGCAGTGACTGTATCGAATCTAT +GTAGAGCACGGATTGGGTGCTACCCCAGACGGCAAAGCTGGAATTGCACCATAAATTGGAAACCGATTTT +GATGTTGTAAAACGCTTCGAGGGCGAAAAACTGCTACTGCATGGTAGTCGCATTAAGTGCTACATAACGG +CAGTGTAAAAAGTCTTAAATAATTATAAATTGGGTAATTCCACTAAAATCCGATTCGCAACTCCATTTGA +ATGATGACTATCTTGTTCCCCACAAGAAGCTAACCTCAACTCAGAACCCGTGCCTGTAAAGAGGTCATGG +CCTATTCAATGCATTCAGCAAAAAAAAGGAAGCTAAAATTATAAAAGGGTTACAACAAATTGAAAGTCGA +GTAACCATAAATTTTTGGCGAAACATCCAACCGAAAAGTAGTCAACACTGAAGAAGATTTACATCCTTTT +AAATTTATGTACATATATTTATACCTATGCGGCGTTGTTATGGCATTTGCAGTGCAGCGCTGCCGGTATA +TGAATGCATGCTCCAGCGGATAACGGTTCGTTTAACTTCTTCGCAGGTCAAGGTACCAAGTAGATATGTA +CATATGTATGTATGTATATCAGATTGGCTCAAAAACAGTGTTTATTGAGCAGCAACCAATTTACGACTGG +CATAGAGTCATACGGTCATAAGACCGTTGTGGCAATAACCATTTTCCTTTCTCTTTTAATTTAAATTAAT +TTGATAAGCACCAGGGCAACAGTAGACTGCAACAATGACCAGATCGGCCTGAACCACTAATCCAAGCCAC +AGACAGGTCGTTTACAGCGAAAATACTCGATGATGCCGGAAATATGTGCATAGTGTTGCCAGGCAGTCGT +CTAGTTTTTACATTGCTTGCTTAGTATTTACAAAAGTACCAGCAGTCAAATATTTTTATTAATATATCTA +CATATTAAATTTGACATTTTTGTAGATCGATTTGTCGCATCGATTATTTTTTTTTATTTTATTCTTTTTA +TTTTATTCTCAAGAACAACATCATATTGCTGAATCTGGTAAATTAGTTCTTATTATATTCTGAATTAGTT +AACACCTTGGTAATGCTTAACAGTCTGAACCTTGGCGAGCTTCTTGAACCCAAGGCAATCAGTTCAGTTT +CAACTTTTCAGATGGGACTTCGATTTCCGCTTATTGTTTCACACTTCCGCTTTTCACAAACAATTGAAAA +AAAAACCTTTATAGCTTATATGCATTTTTAGCTTTCAAACAATTGAAATGAGAGGATGATGCCAAATTTT +ACATTGCTCCAGCTGCCTTTGTGGGCTGCGCTCTTATTGTCACAGTGGCATTGGTGTGATGGTTCAAGCT +ACCAATGGCTTTCCGGTAGCCGAGATGCACTGAAAGTGAATAATTCCTCCTAATACATTTTTAAGCGCCA +TTACTTATTTGTAATTCAGTGCACCCGGAAAACACCAACTGCAGACACTCATAATATGGACATCGTCGTC +TGGACATTAAAATCGTCCGCATTAAACAAAATAAGTATGTTGAATTTCACAAACACAATACCTAATTGAA +TTCCGAGCGTATTTACTAGGGCAGAAGGCTGTTAAGAATTAGCCAGTATGTGTTAACCGTAAAATAAGAT +ATGAATATTGGGCTGTCGTAAAGCACATGTATTCTACTGCGATCCAATGGGATATATTTTCGCCAGGAAT +GTTGGTGGGTATCTTTTTGCAACCGTTAGCAATAATCTTTCTGAATGATAATACAGTTTGTTATTAACAT +TCCTGGACCGCAGTTCCCGGGTTTAAGTAATCGGGTAGAAATGAATTACAATATCAAATTCGCACGGTCG +CATACTCGGTCCGCAGCATACAGTTTGTACCTGGGAACTCCCCGTCTTTGGTCTAGGGCGTATATAGCAG +GCGCATTGTTTAGCAGCGGTGTTACTGATGGAAAACTCCATTTGCTTGTTTGAGAAATAAAATGGTTTGT +ATGCATTCAAAATTTAAATAAAAATGAACGCTATACGAACACGAAGTCCATCGTTGTGGCAAACAAACTT +AGTCAACAAATTATAGCAACAAAACCCAAGGATAGCATTTGCAATGATAGTATTCCTAAGCTGGTGACTT +GGGATTACAATCTAAAAGTGAACGTCGTGTCGGCTTATGTGTTGGTCTGGTCGAAAAAATTTTTTGGGTG +TGTCACAAAAGCTACAAAATTGTTGGGCTCAGTACAAAAGAACATAAGAAACCTTTAAACTTGTGCACTA +ACAACATATCGAAATTCGGATAACTTCAATGATTTGTAGCATTTAGATAATTTTGCATCGCCATAACTTT +TAAGTTACATTCTGTATTGCGATACATTTAAAACTATTTGTCTAGAACGTAAAGCCACAATTACATTACT +ACATCAGTGCTTAAAAGTCGGACCAGAAACTAATTCAGGGTCACTTAACGCCCTGGCGTGTCTGCCAGCT +GCTGCGGTCTATAAATGGCAGCTTCGCGACTGCTTGTTGCGCAAGAGAACTTAACAACCAACCGCCTATG +TGCAGCTTATGAATAAAAAGCTATAGCCATTATGGTTTCCATGTAGACCTGCGTCGGCGTCTGGTCTAGG +CTTAGCCAAACAAAACAATGAAAATGCGGCTTTTATAGACAACGCAAACAATTATAATAGCAAAAATGAA +CTATGTCCAATGGTGTATTGCTTATAAAATCAAATGGAGCTGAAAATAATTGAGTTCAGAAGATTGAAAA +AAAAAGAATTACATTATTTTTAGTATTTCTTTATTTATAAATCTGTCTTCTACTATTGTGATTAAAAAAA +AAAACTTAGAGGGAATATAGATTTTAATCCGATAACCGATTTACCTATGTATATCCGCTGTCAGTCCATC +CATTTCTACGCAAAGTGCGCTCTCAGTCTTAAAGATTTCCGCATAAAACTTTCTTTATATTGCAGGTAGC +TTATTAGTCGGAAAATAAGGTTCAATATTAGAAATCATAAATTCTTTTATTCGACAAATACCAGTTCCGT +TTATAGCAACCGTAAAACCTACAACTTTAATTGTATTTCTTCATGATTTTGCCAAATTTGCTGAGTCGAG +ACATAGCTATAATCTATTTTTTGCGTGGCTGTGGTGCAGCCAGTTCTAGCTCAACGTGTATGCTCCGATG +CTAAGTGAGAAGCTTGAGGGTGTGCCCGCTCTACCAAACTTAATATAACTGGCTTGTTGTTTACAATTAA +TGTGAACCAATTAAAACCAGGTCCGCACAATGTCGTTAAAATAGTTCACAGCCAGCTGCAGCTGCATTGG +AGTTTATAAGCAAGACAAAAGACCTGCGCAACATCTTGTCTAAATGCCATTTTTTGCTCACCTTTGCTAC +GCACCCTTGCTAGTTAATATGTGTATGTGTTTAATTTGGTAAACGGAAACATATCCACCATTCAGGTCGT +GATTATAAAGTTCTGGTTTCATGTTTTCTTTGATTGTTCGTGATTCTATCTATGTTTGGGTAGCTGGAAG +CAATACTTGGTTCTTTTTTGTGACGAAACGATGTGAAGGTTAGGTCTTCATTTAACAGCTAAATATGGTA +ATGAGTAAAGCACTTGTCTCAGCTTGCGCAGAGCTTGTGCAGCAGCTTATGCCAGGGAGTCTGAACTGTC +TCCATGTACTATAATTAAATTTATAAGTCCGACCAGTTAAGAGAAACCAAAAGAGAATTAAAGACGTGCC +ACGGATCTTCACATTGGTGATGTCATCAAAATGTGTTTGTGTTGTTATGTGTTTCGGCAACCTCCCGACA +GAGTCGCCACCTTGTCCTCTCTGTAGTTGAACTTGAACCGATGCTCCAAGCTTGGATGGTAAAAGAAATC +AGTAAAAGCTGCATCAATAGCAACAAATATGCACGAAAAACGAACACATATTGAAAAGCATTCGCATGGG +AGATGAGCAATCGAGTGGACGTGTTCACAGAAGTCGCGGATAAAACAAAAACGTAATTGTGATCCATCAC +AAACATTTGCGCAGATCGTGTGCTTATCTCACAAACAAAATCTATTTTTAGTCACTGCATAACGGTGACG +GCTTCGGTTCGCGAAACTTATCAGCAACTAGCAATTTCTAAGCTGTGTTGTTTTTGCCCCTCGCCCTGCG +CGCTGCGCAAGCGGGAGGTTGTTACAATTTACCTTACAAGTAAACCGGTAAATCTTATCGTGTTTAGTAA +ATATCAATTGCATTATACGGCATAAGTATAAAGACAATTGATATAATGGAGAATTCATTTGCTCAATCGC +GACCTAGCAATGGGTGCGATAAATTTGAGAAAATGAGGAAAGTAGCAGGTGTTGAGCCAGGAGAATTACG +CTCCCAACTCCGCGCCAGCTGTGCAGTTGTTTCCCCTAACCTGGAAGGTATGCCAACTCAATCTACGGTC +TCCAGCTTAATGGTGACAATCAGCAGCAACACCAATGCAAGTGTTACCTGCACTATTTCTAACGTACAGG +CCAACATGATCTGTACTCCTACATACACTGATTGCACAACCGTGACCACTAGCATTTGCCCAACTACGCC +TTATGACAATGGACTGCCGACACCTCTGTCATCACTGCCCAATAAGCCATCTAAAGCGAAATGCCCCTTT +CAAGCACATGATCGTACTGTCAACAGGAAACGAAAAGGCGTGTCTCAGCCCCCATTACCTATCCTCACCC +CTTCTCCAAGCCGTAAAACTAAAAGGCAGGCCACTATGCCACTCAATGAGGAGGCCTCTACCTCCACTGC +AGCAGCATTAAATAACAATCGCTTCGCGCTTTTGTCTGCTGAAACGGAGAATATGGAGCAAGACGTGTCG +GATGCTGATTCTGACATTGAAGACTCTGCTGCCCGAGATGGTGGTGGACAATCCGCTAAATATAGCAAAC +CCCCAGCCATATGCGTACCAAGTGTAAGTGATCCGGTCACCTTGGAACGGGCTCTTAATCTGAGTATTGG +CTCCTCAAACTACTACATCCGCACCTCTAGATTTGGTGTATCCAGAATCTATACAGCCAACCCTGATGCT +TTCCGCACCGCTGTAAAAGAACTAAATAAGTTAAATTGTCAATTCTGGCATCACCAACTTAAAGAAGAAA +AACCCTACAGAGTAGTGCTTAAAGGAATCCATGCTAATGTTCCTAGTTCGCAGATAGAACAAGCATTTAG +TGATCACGGCTATGAGGTCCTTAATATCTATTGCCCCAGAAAGTCTGACTGGAAGAACATTCAGGTAAAC +GAAGATGATAATGAAGCTACAAAAAACTTCAAAACTAGACAAAATTTGTTTTATATTAATCTTAAACAAG +GCCCGAATGTTAAAGAGTCTCTTAAGATAACTCGACTTGGCAGATACAGAGTCACTGTTGAGCGCGCTAC +ACGTAGAAAAGAACTGCTACAATGTCAAAGATGCCAAATTTTTGGACACTCTAAGAACTATTGCGCCCAG +GATCCTATTTGTGGTAAATGTAGTGGTCCCCATATGACCGGGTCCGCTTTGTGCATAAGTGACGTATGTC +TGTGTATAAATTGTGGTGGTGATCATGTCTCGACAGACAAAAGCTGCCCTGTCAGAGCAGAGAAAGCCAA +GAAGCTAAAACCAAGGTCCAGGCTACCGATGACTAATAATATTGCCACACTCAAACCTCCACAACGTTCT +TCAAGCGGTTACATACCAGCTGAGGCATTAAGAACCAACATCTCTTATGCTGATATTGCTCGACGCAACA +CGACTCAATCTAGGGCTCGTGCTACTGTGCAGGCTGAAGTTATACCAACGTCGGACAATAGCCTTAACAA +TAAATTTATGACGTTAGACAACTCCATTCGGGCCATCAATACGAGAATGGACGAACTATTTAAGCTTATA +CACGAAACTGTAGAGGCTAATAAAGCTTTCAGAGAACTGGTTCAGGTTCTAATTACACGTATTCCTAAAT +GACTCAACCAACCTTAAAAATCGGATTGTGGAACGCTCGCGGATTAACAAGGGGCTCTGAGGAGCTTCGG +ATATTCCTCAGCGATCACGATATAGACGTAATGCTTACCACGGAAACACACATGCGAGTTGGTCAGCGCA +TCTATCTCCCAGGGTATCTTATGTATCACGCCCACCACCCCAGTGGTACCAGTAGAGGTGGCTCTGCAGT +CATCATAAAATCTAGACTTTGTCACAGCCCTCTGACACCTATCTCTACTAATGACAGGCAGATAGCGAGA +GTGCACCTGCAAACATCGGTTGGGACCGTCACTGTAGCTGCTGTTTATCTACCTCCAGCAGAAAGATGGA +TAGTAGATGACTTCAAATCCATGTTTGCTGCGTTAGGCAACAAATTTATTGCTGGTGGTGATTACAATGC +CAAACATGCATGGTGGGGGAACCCAAGATCCTGTCCTAGAGGTAAAATGTTGCAAGAAGTCATTGCACAT +GGGCAATACCAAGTTCTGGCTACGGGCGAACCCACTTTCTACTCTTACAACCCTTTGTTAACACCATCAG +CCCTTGATTTTTTTATAACCTGTGGGTACGGCATGGGCAGGCTAGATGTACAAACTCTCCAGGAACTCTC +GTCGGACCATCTTCCTATTCTGGCTGTATTGCACGCTACGCCGTTAAAGAAACCACAACGCGTACGACTA +CTTGCCCATAATGCTGACATAAACATATTCAAAACCCATCTTGAACAGCTGAGTGAGGTAAATATGCAAA +TTCTGGAGGCGGTGGACATTGATAATGCCACAAGCCTTTTCATGAGCAAACTAAGTGAGGCTGCTCAGCT +TGCTGCACCGAGAAATCGGCATGAAGTAGAGGCCTCCAGACCACTTCAACTTCCTCCCAGTATATTGGCA +CTGCTCAGGCTAAAACGAAGAGTTCGAAAAGAATATGCTAGAACAGGTGATCCCCGCATGCAACAGATCC +ACAGTAGACTGGCCAACTGCCTGCATAAGGCCCTTGCTCGAAGAAAGCAGGCCCAAATAGATACCTTCTT +GGATAACTTGGGTGCTGACGCGAGCACAAATTACTCACTGTGGCGTATCACGAAACGGTTCAAAGCTCAG +CCCACCCCAAAATCAGCAATCAAAAATCCGTCTGGTGGCTGGTGTCGCACTAGCTTGGAAAAAACTGAAG +TGTTCGCTAACAACCTTGAGCAACGTTTTACACCCTATAACTATGCACCGGAAAGTCTCTGTCGTCAGGT +TGAAGAATACTTGGAATCGCCCTTTCAAATGAGCCTGCCTCCGAGTGCTGTCACACTGGAAGAAGTGAAG +AATTTAATAGCCAAGCTGCCACTTAAGAAAGCTCCTGGAGAAGATCTTCTTGATAATAGAACCATTAGAC +TTCTCCCAGATCAAGCATTGCAGTTCCTTGCCTTAATATTCAACAGCGTTCTTGATGTTGGCTACTTTCC +GAAAGCTTGGAAATCGGCGAGCATAATTATGATCCATAAGACTGGAAAAACACCGACAGACGTTGACTCG +TACAGGCCCATCAGCTTACTCCCATCTCTGGGTAAAATTATGGAGAGGCTGATCCTAAACAGGCTGCTCA +CATGCAAGGATGTTACCAAAGCGATTCCCAAATTTCAGTTTGGCTTCCGGTTGCAGCACGGTACTCCTGA +GCAACTACATAGAGTAGTGAACTTTGCTCTGGAAGCTATGGAAAACAAGGAGTATGCAGTAGGTGCCTTT +CTTGATATTCAACAGGCATTTGACAGAGTCTGGCACCCTGGGCTCCTGTACAAAGCGAAGAGGCTGTTCC +CGCCGCAGCTATATTTGGTTGTTAAAAGTTTCCTGGAAGAACGCACATTCCACGTCTCTGTTGATGGGTA +CAAATCATCAATCAAGCCAATTGCAGCTGGAGTTCCTCAAGGAAGCGTTCTTGGCCCAACCCTATACTCA +GTTTTTGCTTCGGACATGCCTACTCACACACCAGTCACAGAGGTAGACGAAGAAGATGTGCTCATAGCCA +CCTACGCTGACGATACTGCTGTGCTCACGAAAAGTAAAAGTATCCTGGCTGCCACTTCTGGTCTACAGGA +ATACCTGGATGCATTCCAGCAATGGGCTGAGAACTGGAATGTGCGCATCAACGCCGAGAAGTGTGCCAAT +GTGACGTTCGCCAACCGAACAGGTAGCTGTCCGGGTGTCAGTCTGAATGGGAGACTGATCAGACACCATC +AGGCTTATAAATACCTTGGTATTACCCTCGATAGGAAGCTCACCTTCAGCAGGCACATCACAAGTATTCA +GCAAGCGTTCAGGACCAAGGTTGCTCGGATGTCTTGGCTCATTGCACCACGCAACAAACTGTCGCTTGGC +TGCAAGGTCAATATTTACAAGTCCATATTGGCCCCCTGCCTGTTCTACGGCCTGCAGGTATACGGCATTG +CTGCGAAGAGTCACCTTAATAAGATCCGGATCTTACAGGCGAAGACCTTAAGAAGAATTTCGGGGGCTCC +TTGGTATATGAGAACAAGAGACATCGAACGCGACCTCAAGGTGCCCAAATTAGGAGACAAGCTCCAGAAC +ATCGCCCAAAAATATATGGAAAGGCTTAATGTACACCCCAACAGCCTAGCAAGGAAGCTAGGAACTGCAG +CTGTGGTCAATGCTGACCCTCGGACTAGAGTCAAAAGAAGACTCAAGCGACACCACCCTCATGACCTCCC +TAACCTGGTTTTGACCTAGAAAGTCTTAGTTTTAAAATTCATTAGAATAATCAAATAAATAATAATTACT +ATGTTATATCAACTATTATAATTCTCCCTATCATTTTTAGGATTAAAAATCTGTTAGTCTTAAGTAACCA +AGACACATTGTAAAATAAAATAATTTAAGCAGATCAAATTAAGTTGCCGCATGGGTAACAGTGCGTTGAT +CAAATAATAAAAACATCATCATATAATTTGATAGAAAAAAAAAAAAAAAAAAAAAAAAAATATTGAAAAG +CGAAAACAGGAGAAGCAATAAAGTGGCATTTTAACAGCATCTGGTGAATGGTTAGCGATGGTACTGTTAC +GAGGTATTAAATAGTAGTGGCCATGACACTGAGGAGGAATGTATCATTTGCTTAACTGCCAGAAACGCTT +TTAGAAGTTGCAGTTAAACAATATATATTGTTATTTTTATTTGTTTATAGGAAGCCTACTTGGATAAGAC +ACGAAAACCCTAATAGCCTAAAAATTCAATATAAGTGTTCCGATGTTTATATTTACTGCGTGTTGTGAGA +CAGTTGAGTCTGCGTTTGTTCGATTTTTGGCTGTTTGACTTAATTAACTGGTTTTAATGTCTAATTGGCA +ATATAAACAGTGAAGGCAACGATTATAAGCAAGAATCCAATACGTAAATGAAAATAAAAGAAACAAAATT +AAAATGAACCCCGAAAATATGGAGGAAATTACAAATGAATTTTAAGAGTTACAGGCATAAAATATATCAA +CAAATATTTAAGCTTACCGAACGCAGATAATAGTTGTAAGTCTGAGTCTGGGGCTTATAATTACGTATAG +GCTCCTCTCCTGATCGTTAAGACAAATGTTCCTCAGATGACGCATGTTTTCAGCAAGCGTTTACTTTGCT +TCATTTGTACACATCACCTGCCGCCTCTATTGGGAATTTTTGATGATCCGACATCAGTTCTTCTAGTTAT +CGTATTCTTAAATTATGGGATATTTCTATCCGGTTTTCTCGATTGATTCGATCCACCAGCTTAAAAACTT +AAACTCTCGATAAATTATGCGTATTTAATATTCGGTTTCTGTGTGTTTTTCGTTATGATCAGGTAAAAAA +AATGTAAGGCTTATTCGTTTTCATTAGTCACTAAAAAATGAGCAGGCACAACCTCCTGGGGTAGCAAATA +GGCTTGTAAACAGAAAATAGACTACATGAATAAAAATTCTTATAAAATGCAGCTTCAAATGTAGCCCACA +TCAGCCCAAACATCTCCTTGTTAGTTATTAAGTATAGAAAAAGTATATAAATTGGTTATCGGTGTCACAT +AAATAAATTATGCCTGTCGAGTTTACTGTAGAGCACCAGGACATAACGCTGTCATTTCAGACCCCAAAGA +AATATTGCTCGTATGCAATCAGACCAAAAACATCTCATAAAATACAAGGCAGGGCCGTACGCAACACATA +GTTTCCAATCCGCATCGCCTGTCGTGCATGGAAAAAAAATAGCTGGGAATGAAGTACATTGTTAGCAAGT +CCTACGCGCTGTCGCTTCGCTATTTATGCGATGCCTTTGGGCAAGGCTATAATAAATGTATGGCATTTTC +GTGTAAGTAACAATTGAGACATTGCTATGCACTGGCAGCCGGATGATCGCCTTACATTTCTGATAGATTC +TATAAACAAACTAATACATATTTAAAATTTAATTTTTATTATTTACCTATTGCTCGTAGAGTATAAGAAG +AAACTTGGGGATCTTGATTATCGCGTTCTCTCTTGTTCTTATTTATTAAATATTAAAATGATTATACAGA +AATATAATTTTTTATCCGGCCTATATTTTATAAACTCATATGGATTAGTATTTAAAAAGACTACAGTTTT +CCCACGCTAAATGGGGCTTACTGGACCACACCCTAAGCAACTGAGAGTGCAGCAACTCATAGGTGACGGC +AGCGTGACCATGCAAATTAGCCATTCGTGGCTTAAATGTCAACTTTTTATAAAACAATTGGAGCGGCCAC +TAGTAAGACAAGTGAAGCTAATTTAATTATTCCCTTAAGAATAAGGATTTGTGTTTGTATCGATTTCCCA +GCTACTGTGTGAATGGTAAATTGTGTTGCTCATAGAAAATATAATAATATAATATAATATAATATAATAT +ATAATAATATAATAATATAATTTATCTTTTGCTATTTTTAGTAAAAAATACTCCATCAAAACTGCACTGG +TCTGAGCTTTGTCCCTACTGCTGTACTAACCCACCCATAGTTAAATTTTACTAGAAATCAAATAACAAAC +TTTTCCAAATAACGTCATCAAACTATCAAATTTATATAAAACCTGTTCCTTTTTTTAAGAGGCTGCTAAG +TGACAATAAAAAATGTAATTGGTAGTGTGGCGAGTTCGCCAAAAGCAGTGCATTGAGCCGTGGTACCCGA +AAGTAAAATTGGTTAAAGAGACAAAATCAACACAAATAGTAAATACCTAGCATTATACCTTTATACCCTT +ACAATTATTCACATAATGCGCGGACGAATTAAAATGCACTGTTCTTATGGTATTCGAATACCCGACGGCA +GCCTGCTAAGTATTACGTTTAAAACCAAGCACTTAATGATGCTCTAACGAAACAGATGAGTGCGATTATG +CAATCACAGGGCACCGCTAATCGATAGGCTCACATAATCGTACCGTGCCGGCCAACATTTTGTCACTATG +AGGCCGACAACCGTTATTAAAGCGAGCTCACTAATACGTATTGGAGTCATATTGGGTTTGGTGAAAGTGA +AAGGTGAACAGCATACCATTTTGCGGTGCCGTAAAATATATTATAAATGAAAAAGTTGCGTATCCGAGTG +CTTAACAGAGGAGAGCAGCTGACCTGCTGCAGTTTGCCCTTGAGAGCCTTTAGCGTCAATTCCACTTAAA +TTTACCAAGCAGTGGTCTACGAAACAAACACAAAACACAACAACAAAAACGGAATCCCAACGGCAATCTC +GTCAAGGTCGATGCATTCAACATCTGCAAAATCCAGTTTATACCCACAAAGGAGACGAAAAAGCCTCGAC +TGACATAAGCAAACCGTGTGCCGGACCATCGATTGCCAAGCAAAACAATCACAATTAACTTCTGTAAAAA +AAAGAGCGAGCTAAGGAAATATTTGTGTTAGAAAATCCTTCAAGTATCAGTAAAATCTTCAATCTTAATA +AAAATTATATGGACATTGGAAGCTAGCTTCGACAAGCCGAATCATCTAAACCCTTCGAATAATCGAATAA +GAAAAATGTTATGATCAAAAAGGTTTATGCAGCAAATAGCATTAAAACTGTGAGATCAGTTTGCGTAGAA +ATAGACGAACGGACACGGCTATATAGAGCCGGCCGTTGATACTGCTCAATTAATGTGGTCGTAGATATAG +GATAGAAAGGCTATACAAAATAAAAGTTTACAGCGGCTTTTTGCCGTAAAAGAAAGTTACTTTGCCGTAA +CAAGATTGGTGTAAGAGGGTTAAGTGGAGCAGCTGCGTCGGGCCCCATTTAATTTCACGATACGGTGCAT +AGAGACGTCAAGAGCTCTATTTACATGTGCTACGGATATGGACGTCGTCGGCTTAACGCAATGTTTTAAT +AGATTGCCCATTTCGTAGCAAAAATAATTTTCAACTGTAATGCGTAAGCATTTCAAGGTGAGTAGCGCCG +TAAACAACAAGCTTGTAAGGGCAGGCGCAGAAGCTAAGAAAAGTTGGGTGTTGCCGTTTGGTAGTCTATT +GGTACTCCTCGTACTGTGCCGACAACAATTTCGACGTCCAATTCAACGCAAATTATCTGGAGCCTTGCGA +AATCCAGGGATTACCATTGCTGTGTGCAAATTTATTCAAGCTTGCCTCAGACTCGCTGGAATACTGCTTG +AAAGCGAAAGTGCACTGTGTGCATGCAAAACAAAGTTGCGCCATGCCAATGGTCGTACATGCTCGTATAA +AGTGTTCAGGTTACAGTCAAAGACCTAGCGAAGTAATTTAATGACGATCTTCCGCGTGCGCCAAAACTTT +CGCACGGTAAGCATTGACACTGCCTGCGGTAAAAAAGAGACGAAATGATTAGGTCGAGGCGTGACCACCA +TACTAATGGTTTAACTGGCATTGAAACTGAATTATGATTAAAACCCCTTTGTTATACTATTCATTAAACA +CGCGCTTAAACAAATGTTCTTGCAAATGTTCAACTTTCGCCATTGGCCTCGTCCGCCTCAAACCTTTTTC +TTTCAGCCATCGACATTCGCATTAAACCAGTAGTACATCAAATGTTTTAACACAAATTTCCTAGCAATTA +CGCATGAAAATATTTCCATGGCGGCATATCTAAGGTTTTACCCAAATATATATTTCTGTGGCTTAAAAAA +ACACCACTCAAAACACTGAGAAAGTTCATCAAAATGGAAAGTGTTGCCACTATGCCTAAACCAAGTCATG +CAAGTCTTCATACCCTTGCGGAGGGTACATTCACTTAAGTCAGAAATTTCAAAGCTGTGAAGGACACAAT +TGTGCCCATATATGGTATATATATTTCTTGCTAAGTATCAACGACCGAATCGGTATAGCAGATAGATTAT +AAATTGTTTAAAAGAGGACGATCGGACAGCCGGGCTTGGCTATTTCAAGTTCGCTGTTTTTACTAATATG +TTATGAATAAGATACATATATGCACTTTATAAGGCCACAAAGGTAATACAAAAAATCTATCTCAAAACAA +TTTAGCCGTCTAATGCTGTTATTATAATTTTAATAGTGTTAATCCTTACCACGTTATCTAAGCAATTTTC +GTAGTTCCCAATTTGTTTTCTCAAATTTTGCATATATATCATTCATAAAAAATGTCTGAACAATTAAGCA +AACTGTTTTAAAAATTATCAACAGTTATTATAGCCACAATTTGCTCGGTTACACCGATACACTCACTCAC +TTAGTGAACCTATTCAATCGAGTCAGCGAGCTGTATGCAATTAATATCTGTGTCATAAGCTGCTTGGTTG +GCTGCTGGCTGATAACTTACATAATTCCATTACCATTACCCAGCAGTATGGTGAGTAGACAGCCCAAGTG +ACCAATAGTTGGACACGGTAAGGCTTGTTATGGTCGAAATGCTTGATTATGTTATTGTTCGCTGGTAAAT +AGAGCAGTTGATCAGACCATGTATTTACCTCCATACATACCCTAATGTAAATACTCTTACTTTTTATATA +TCCTAACACATTTCGCAGTAAAATGTCTTAATATATATATATATATATATATATTAAAATAAATATACAT +TTTTGGACATATTAAGAAACTCGTTTAGCCGGAGCCGGAGTATCCACAATAGAGCTCAACACAAGTGGTT +AACAGCTGGTGGTTTGACTTCTTCTACGGTGATTGAATTTGACATTAGACTATTGCGAGCTCGTACATGG +CAGCCGGAACAGTGTTCAAAACAAGTTTGGCTTTATTTGCGGAACATAATATTTCTATCACGAAGTTTCG +AATATGATTGAGGAAAAGAAGAATCCATAGTACTGTAAAAACAATTCACTTAAAAATAAAACTTTTTCGG +ATCTACGTTTAAAAAAAGATTTCAGTTCATACATGAACTGAATACTTATCCATGGTTGTCTTAAAATCTG +GTTAAGTGCTAACTCTTCTAGGACTAGTGGGTAAAGTGTGTAAGCCCTTTGCTCTTTTAAGTTTTTGCCT +CCATTTGTATTTCTAGCAGAGTGTTCTTCACTGAAGTGGGCATTACTCACCTGTTTTAAAAAGCAGTAGG +CACAATCCCAGCAGGCACAGAATGTTTATTCGACTTGTTGAATACTTCATATTGCAGGTATGGCGTGTCG + + Added: test-suite/trunk/MultiSource/Applications/SIBsim4/y-small.fa URL: http://llvm.org/viewvc/llvm-project/test-suite/trunk/MultiSource/Applications/SIBsim4/y-small.fa?rev=46969&view=auto ============================================================================== --- test-suite/trunk/MultiSource/Applications/SIBsim4/y-small.fa (added) +++ test-suite/trunk/MultiSource/Applications/SIBsim4/y-small.fa Mon Feb 11 15:45:48 2008 @@ -0,0 +1,892 @@ +>MUSSPSYN Mouse spermidine synthase mRNA, complete cds. +CGGGTTGTGCTGGGGGGGTCCGCGCGCCCTGCAGTCCCGAACCCGCTACGCGCTCCGTCG +GCCCGCCCGCCCGCCATGGAGCCTGGCCCCGACGGCCCAGCCGCGCCCGGCCCCGCCGCC +ATCCGTGAGGGCTGGTTCCGAGAGACCTGCAGCCTGTGGCCCGGCCAGGCCCTGTCGCTG +CAAGTGGAGCAGCTGCTTCACCACCGGCGATCGCGGTACCAAGACATCCTCGTCTTCCGC +AGTAAAACCTACGGCAACGTGCTGGTTCTGGATGGCGTCATCCAGTGTACTGAGAGGGAT +GAGTTCTCCTACCAGGAGATGATCGCCAACCTGCCGCTCTGCAGCCACCCCAACCCGCGG +AAGGTGCTGATCATCGGGGGTGGAGATGGGGGCGTCCTACGGGAAGTGGTGAAGCACCCC +TCTGTGGAGTCGGTGGTCCAGTGCGAGATTGATGAGGATGTCATTGAAGTCTCTAAGAAG +TTCCTGCCTGGCATGGCCGTTGGCTTCTCCAGCTCAAAGCTGACTCTCCACGTGGGCGAT +GGCTTTGAGTTCATGAAACAGAACCAAGATGCCTTTGACGTCATCATCACCGACTCCTCA +GACCCCATGGGCCCTGCTGAGAGCCTCTTCAAGGAGTCCTATTACCAGCTCATGAAGACA +GCACTCAAAGAAGATGGCATCCTGTGCTGCCAGGGTGAGTGCCAGTGGCTGCACCTGGAC +CTCATCAAGGAGATGAGGCACTTCTGCAAATCTCTCTTCCCCGTGGTGGACTACGCCTAC +TGTAGCATTCCTACCTATCCCAGCGGCCAGATCGGCTTCATGCTGTGTAGCAAAAACCCG +AGCACCAACTTCCGGGAGCCAGTGCAGCAGTTGACACAGGCCCAGGTGGAGCAGATGCAG +CTGAAATACTATAACTCGGACATGCACCGTGCCGCCTTCGTACTGCCTGAGTTCACCCGG +AAGGCCCTCAATGACATAAGCTGAATCCAGGTGCCACTGTGACACCACCCGAGACCTCAA +TCGGATTGGACCAAGGATCTTCCAAGTTGTCTGGGGACCACCAGTCCTGGACCAGACTCC +CAGATGACTCTTGCCCACCAACCAAGTGTTACAGGCCCCATGATGCTGCCTGGCCTGGCC +TGGCCTGGCCTGGCCTGGCCTGCCCTGCTGGGTGGACTCAGTCTCTGTCTGTCTATCTCT +GTGGCGTTCAGCCCCACGCCTATACCAGCTCTGTACAGCACCGCCTATGCCCTGTGACCC +AACAAAATACATGTGTATTCCG +>MUSSPSYN Mouse spermidine synthase mRNA, complete cds. +CGGGTTGTGCTGGGGGGGTCCGCGCGCCCTGCAGTCCCGAACCCGCTACGCGCTCCGTCG +GCCCGCCCGCCCGCCATGGAGCCTGGCCCCGACGGCCCAGCCGCGCCCGGCCCCGCCGCC +ATCCGTGAGGGCTGGTTCCGAGAGACCTGCAGCCTGTGGCCCGGCCAGGCCCTGTCGCTG +CAAGTGGAGCAGCTGCTTCACCACCGGCGATCGCGGTACCAAGACATCCTCGTCTTCCGC +AGTAAAACCTACGGCAACGTGCTGGTTCTGGATGGCGTCATCCAGTGTACTGAGAGGGAT +GAGTTCTCCTACCAGGAGATGATCGCCAACCTGCCGCTCTGCAGCCACCCCAACCCGCGG +AAGGTGCTGATCATCGGGGGTGGAGATGGGGGCGTCCTACGGGAAGTGGTGAAGCACCCC +TCTGTGGAGTCGGTGGTCCAGTGCGAGATTGATGAGGATGTCATTGAAGTCTCTAAGAAG +TTCCTGCCTGGCATGGCCGTTGGCTTCTCCAGCTCAAAGCTGACTCTCCACGTGGGCGAT +GGCTTTGAGTTCATGAAACAGAACCAAGATGCCTTTGACGTCATCATCACCGACTCCTCA +GACCCCATGGGCCCTGCTGAGAGCCTCTTCAAGGAGTCCTATTACCAGCTCATGAAGACA +GCACTCAAAGAAGATGGCATCCTGTGCTGCCAGGGTGAGTGCCAGTGGCTGCACCTGGAC +CTCATCAAGGAGATGAGGCACTTCTGCAAATCTCTCTTCCCCGTGGTGGACTACGCCTAC +TGTAGCATTCCTACCTATCCCAGCGGCCAGATCGGCTTCATGCTGTGTAGCAAAAACCCG +AGCACCAACTTCCGGGAGCCAGTGCAGCAGTTGACACAGGCCCAGGTGGAGCAGATGCAG +CTGAAATACTATAACTCGGACATGCACCGTGCCGCCTTCGTACTGCCTGAGTTCACCCGG +AAGGCCCTCAATGACATAAGCTGAATCCAGGTGCCACTGTGACACCACCCGAGACCTCAA +TCGGATTGGACCAAGGATCTTCCAAGTTGTCTGGGGACCACCAGTCCTGGACCAGACTCC +CAGATGACTCTTGCCCACCAACCAAGTGTTACAGGCCCCATGATGCTGCCTGGCCTGGCC +TGGCCTGGCCTGGCCTGGCCTGCCCTGCTGGGTGGACTCAGTCTCTGTCTGTCTATCTCT +GTGGCGTTCAGCCCCACGCCTATACCAGCTCTGTACAGCACCGCCTATGCCCTGTGACCC +AACAAAATACATGTGTATTCCG +>ref|NT_037436.3|:1-300000 Drosophila melanogaster chromosome 3L +TAGGGAGAAATATGATCGCGTATGCGAGAGTAGTGCCAACATATTGTGCTCTTTGATTTTTTGGCAACCC +AAAATGGTGGCGGATGAACGAGATGATAATATATTCAAGTTGCCGCTAATCAGAAATAAATTCATTGCAA +CGTTAAATACAGCACAATATATGATCGCGTATGCGAGAGTAGTGCCAACATATTGTGCTAATGAGTGCCT +CTCGTTCTCTGTCTTATATTACCGCAAACCCAAAAAGACAATACACGACAGAGAGAGAGAGCAGCGGAGA +TATTTAGATTGCCTATTAAATATGATCGCGTATGCGAGAGTAGTGCCAACATATTCTGCTCTCTATATAA +TGACTGCCTCTCATTCTGTCTTATTTTACCGCAAACCCAAATCGACAATGCACGACAGAGGAAGCAGAAC +AGATATTTAGATTGCCTCTCATTTTCTCTCCCATATTATAGGGAGAAATATGATCGCGTATGCGAGAGTA +GTGCCAACATATTGTGCTCTTTGATTTTTTGGCAACCCAAAATGGTGGCGGATGAACGAGATGATAATAT +ATTCAAGTTGCCGCTAATCAGAAATAAATTCATTGCAACGTTAAATACAGCACAATATATGATCGCGTAT +GCGAGAGTAGTGCCAACATATTGTGCTAATGAGTGCCTCTCGTTCTCTGTCTTATATTACCGCAAACCCA +AAAAGACAATACACGACAGAGAGAGAGAGCAGCGGAGATATTTAGATTGCCTATTAAATATGATCGCGTA +TGCGAGAGTAGTGCCAACATATTCTGCTCTCTACATAATGACTGCCTCTCATTCTGTCTTATTTTACCGC +AAACCCAAATCGACAATGCACGACAGAGGAAGCAGAACAGATATTTAGATTGCCTCTCATTTTCTCTCCC +ATATTATAGGGAGAAATATGATCGCGTATGCGAGAGTAGTGCCAACATATTGTGCTCTTTGATTTTTTGG +CAACCCAAAATGGTGGCGGATGAACGAGATGATAATATATTCAAGTTGCCGCTAATCAGAAATAAATTCA +TTGCAACGTTAAATACAGCACAATATATGATCGCGTATGCGAGAGTAGTGCCAACATATTGTGCTAATGA +GTGCCTCTCGTTCTCTGTCTTATATTACCGCAAACCCAAAAAGACAATACACGACAGAGAGAGAGAGCAG +CGGAGATATTTAGATTGCCTATTAAATATGATCGCGTATGCGAGAGTAGTGCCAACATATTCTGCTCTCT +ATATAATGACTGCCTCTCATTCTGTCTTATTTTACCGCAAACCCAAATCGACAATGCACGACAGAGGAAG +CAGAACAGATATTTAGATTGCCTCTCATTTTCTCTCCCATATTATAGGGAGAAATATGATCGCGTATGCG +AGAGTAGTGCCAACATATTGTGCTCTTTGATTTTTTGGCAACCCAAAATGGTGGCGGATGAACGAGATGA +TAATATATTCAAGTTGCCGCTAATCAGAAATAAATTCATTGCAACGTTAAATACAGCACAATATATGATC +GCGTATGCGAGAGTAGTGCCAACATATTGTGCTAATGAGTGCCTCTCGTTCTCTGTCTTATATTACCGCA +AACCCAAAAAGACAATACACGACAGAGAGAGAGAGCAGCGGAGATATTTAGATTGCCTATTAAATATGAT +CGCGTATGCGAGAGTAGTGCCAACATATTCTGCTCTCTATATAATGACTGCCTCTCATTCTGTCTTATTT +TACCGCAAACCCAAATCGACAATGCACGACAGAGGAAGCAGAACAGATATTTAGATTGCCTCTCATTTTC +TCTCCCATATTATAGGGAGAAATATGATCGCGTATGCGAGAGTAGTGCCAACATATTGTGCTCTTTGATT +TTTTGGCAACCCAAAATGGTGGCGGATGAACGAGATGATAATATATTCAAGTTGCCGCTAATCAGAAATA +AATTCATTGCAACGTTAAATACAGCACAATATATGATCGCGTATGCGAGAGTAGTGCCAACATATTGTGC +TAATGAGTGCCTCTCGTTCTCTGTCTTATATTACCGCAAACCCAAAAAGACAATACACGACAGAGAGAGA +GAGCAGCGGAGATATTTAGATTGCCTATTAAATATGATCGCGTATGCGAGAGTAGTGCCAACATATTCTG +CTCTCTATATAATGACTGCCTCTCATTCTGTCTTATTTTACCGCAAACCCAAATCGACAATGCACGACAG +AGGAAGCAGAACAGATATTTAGATTGCCTCTCATTTTCTCTCCCATATTATAGGGAGAAATATGATCGCG +TATGCGAGAGTAGTGCCAACATATTGTGCTCTTTGATTTTTTGGCAACCCAAAATGGTGGCGGATGAACG +AGATGATAATATATTCAAGTTGCCGCTAATCAGAAATAAATTCATTGCAACGTTAAATACAGCACAATAT +ATGATCGCGTATGCGAGAGTAGTGCCAACATATTGTGCTAATGAGTGCCTCTCGTTCTCTGTCTTATATT +ACCGCAAACCCAAAAAGACAATACACGACAGAGAGAGCAGCGGAGATATTTAGATTGCCTATTAAATATG +ATCGCGTATGCGAGAGTAGTGCCAACATATTCTGCTCTCTATATAATGACTGCCTCTCATTCTGTCTTAT +TTTACCGCAAACCCAAATCGACAATGCACGACAGAGGAAGCAGAACAGATATTTAGATTGCCTCTCATTT +TCTCTCCCATATTATAGGGAGAAATATGATCGCGTATGCGAGAGTAGTGCCAACATATTGTGCTCTTTGA +TTTTTTGGCAACCCAAAATGGTGGCGGATGAACGAGATGATAATATATTCAAGTTGCCGCTAATCAGAAA +TAAATTCATTGCAACGTTAAATACAGCACAATATATGATCGCGTATGCGAGAGTAGTGCCAACATATTGT +GCTAATGAGTGCCTCTCGTTCTCTGTCTTATATTACCGCAAACCCAAAAAGACAATACACGACAGAGAGA +GAGAGCAGCGGAGATATTTAGATTGCCTATTAAATATGATCGCGTATGCGAGAGTAGTGCCAACATATTC +TGCTCTCTATATAATGACTGCCTCTCATTCTGTCTTATTTTACCGCAAACCCAAATCGACAATGCACGAC +AGAGGAAGCAGAACAGATATTTAGATTGCCTCTCATTTTCTCTCCCATATTATAGGGAGAAATATGATCG +CGTATGCGAGAGTAGTGCCAACATATTGTGCTCTTTGATTTTTTGGCAACCCAAAATGGTGGCGGATGAA +CGAGATGATAATATATTCAAGTTGCCGCTAATCAGAAATAAATTCATTGCAACGTTAAATACAGCACAAT +ATATGATCGCGTATGCGAGAGTAGTGCCAACATATTGTGCTAATGAGTGCCTCTCGTTCTCTGTCTTATA +TTACCGCAAACCCAAAAAGACAATACACGACAGAGAGAGAGAGCAGCGGAGATATTTAGATTGCCTATTA +AATATGATCGCGTATGCGAGAGTAGTGCCAACATATTCTGCTCTCTATATAATGACTGCCTCTCATTCTG +TCTTATTTTACCGCAAACCCAAATCGACAATGCACGACAGAGGAAGCAGAACAGATATTTAGATTGCCTC +TCATTTTCTCTCCCATATTATAGGGAGAAATATGATCGCGTATGCGAGAGTAGTGCCAACATATTGTGCT +CTTTGATTTTTTGGCAACCCAAAATGGTGGCGGATGAACGAGATGATAATATATTCAAGTTGCCGCTAAT +CAGAAATAAATTCATTGCAACGTTAAATACAGCACAATATATGATCGCGTATGCGAGAGTAGTGCCAACA +TATTGTGCTAATGAGTGCCTCTCGTTCTCTGTCTTATATTACCGCAAACCCAAAAAGACAATACACGACA +GAGAGAGAGAGCAGCGGAGATATTTAGATTGCCTATTAAATATGATCGCGTATGCGAGAGTAGTGCCAAC +ATATTCTGCTCTCTACATAATGACTGCCTCTCATTCTGTCTTATTTTACCGCAAACCCAAATCGACAATG +CACGACAGAGGAAGCAGAACAGATATTTAGATTGCCTCTCATTTTCTCTCCCATATTATAGGGAGAAATA +TGATCGCGTATGCGAGAGTAGTGCCAACATATTGTGCTCTTTGATTTTTTGGCAACCCAAAATGGTGGCG +GATGAACGAGATGATAATATATTCAAGTTGCCGCTAATCAGAAATAAATTCATTGCAACGTTAAATACAG +CACAATATATGATCGCGTATGCGAGAGTAGTGCCAACATATTGTGCTAATGAGTGCCTCTCGTTCTCTGT +CTTATATTACCGCAAACCCAAAAAGACAATACACGACAGAGAGAGAGAGCAGCGGAGATATTTAGATTGC +CTATTAAATATGATCGCGTATGCGAGAGTAGTGCCAACATATTCTGCTCTCTATATAATGACTGCCTCTC +ATTCTGTCTTATTTTACCGCAAACCCAAATCGACAATGCACGACAGAGGAAGCAGAACAGATATTTAGAT +TGCCTCTCATTTTCTCTCCCATATTATAGGGAGAAATATGATCGCGTATGCGAGAGTAGTGCCAACATAT +TGTGCTCTTTGATTTTTTGGCAACCCAAAATGGTGGCGGATGAACGAGATGATAATATATTCAAGTTGCC +GCTAATCAGAAATAAATTCATTGCAACGTTAAATACAGCACAATATATGATCGCGTATGCGAGAGTAGTG +CCAACATATTGTGCTAATGAGTGCCTCTCGTTCTCTGTCTTATATTACCGCAAACCCAAAAAGACAATAC +ACGACAGAGAGAGAGAGCAGCGGAGATATTTAGATTGCCTATTAAATATGATCGCGTATGCGAGAGTAGT +GCCAACATATTCTGCTCTCTATATAATGACTGCCTCTCATTCTGTCTTATTTTACCGCAAACCCAAATCG +ACAATGCACGACAGAGGAAGCAGAACAGATATTTAGATTGCCTCTCATTTTCTCTCCCATATTATAGGGA +GAAATATGATCGCGTATGCGAGAGTAGTGCCAACATATTGTGCTCTTTGATTTTTTGGCAACCCAAAATG +GTGGCGGATGAACGAGATGATAATATATTCAAGTTGCCGCTAATCAGAAATAAATTCATTGCAACGTTAA +ATACAGCACAATATATGATCGCGTATGCGAGAGTAGTGCCAACATATTGTGCTAATGAGTGCCTCTCGTT +CTCTGTCTTATATTACCGCAAACCCAAAAAGACAATACACGACAGAGAGAGAGAGCAGCGGAGATATTTA +GATTGCCTATTAAATATGATCGCGTATGCGAGAGTAGTGCCAACATATTCTGCTCTCTATATAATGACTG +CCTCTCATTCTGTCTTATTTTACCGCAAACCCAAATCGACAATGCACGACAGAGGAAGCAGAACAGATAT +TTAGATTGCCTCTCATTTTCTCTCCCATATTATAGGGAGAAATATGATCGCGTATGCGAGAGTAGTGCCA +ACATATTGTGCTCTTTGATTTTTTGGCAACCCAAAATGGTGGCGGATGAACGAGATGATAATATATTCAA +GTTGCCGCTAATCAGAAATAAATTCATTGCAACGTTAAATACAGCACAATATATGATCGCGTATGCGAGA +GTAGTGCCAACATATTGTGCTAATGAGTGCCTCTCGTTCTCTGTCTTATATTACCGCAAACCCAAAAAGA +CAATACACGACAGAGAGAGCAGCGGAGATATTTAGATTGCCTATTAAATATGATCGCGTATGCGAGAGTA +GTGCCAACATATTCTGCTCTCTATATAATGACTGCCTCTCATTCTGTCTTATTTTACCGCAAACCCAAAT +CGACAATGCACGACAGAGGAAGCAGAACAGATATTTAGATTGCCTCTCATTTTCTCTCCCATATTATAGG +GAGAAATATGATCGCGTATGCGAGAGTAGTGCCAACATATTGTGCTCTTTGATTTTTTGGCAACCCAAAA +TGGTGGCGGATGAACGAGATGATAATATATTCAAGTTGCCGCTAATCAGAAATAAATTCATTGCAACGTT +AAATACAGCACAATATATGATCGCGTATGCGAGAGTAGTGCCAACATATTGTGCTAATGAGTGCCTCTCG +TTCTCTGTCTTATATTACCGCAAACCCAAAAAGACAATACACGACAGAGAGAGAGAGCAGCGGAGATATT +TAGATTGCCTATTAAATATGATCGCGTATGCGAGAGTAGTGCCAACATATTCTGCTCTCTATATAATGAC +TGCCTCTCATTCTGTCTTATTTTACCGCAAACCCAAATCGACAATGCACGACAGAGGAAGCAGAACAGAT +ATTTAGATTGCCTCTCATTTTCTCTCCCATATTATAGGGAGAAATATGATCGCGTATGCGAGAGTAGTGC +CAACATATTGTGCTCTTTGATTTTTTGGCAACCCAAAATGGTGGCGGATGAACGAGATGATAATATATTC +AAGTTGCCGCTAATCAGAAATAAATTCATTGCAACGTTAAATACAGCACAATATATGATCGCGTATGCGA +GAGTAGTGCCAACATATTGTGCTAATGAGTGCCTCTCGTTCTCTGTCTTATATTACCGCAAACCCAAAAA +GACAATACACGACAGAGAGAGAGAGCAGCGGAGATATTTAGATTGCCTATTAAATATGATCGCGTATGCG +AGAGTAGTGCCAACATATTCTGCTCTCTATATAATGACTGCCTCTCATTCTGTCTTATTTTACCGCAAAC +CCAAATCGACAATGCACGACAGAGGAAGCAGAACAGATATTTAGATTGCCTCTCATTTTCTCTCCCATAT +TATAGGGAGAAATATGATCGCGTATGCGAGAGTAGTGCCAACATATTGTGCTCTTTGATTTTTTGGCAAC +CCAAAATGGTGGCGGATGAACGAGATGATAATATATTCAAGTTGCCGCTAATCAGAAATAAATTCATTGC +AACGTTAAATACAGCACAATATATGATCGCGTATGCGAGAGTAGTGCCAACATATTGTGCTAATGAGTGC +CTCTCGTTCTCTGTCTTATATTACCGCAAACCCAAAAAGACAATACACGACAGAGAGAGAGAGCAGCGGA +GATATTTAGATTGCCTATTAAATATGATCGCGTATGCGAGAGTAGTGCCAACATATTCTGCTCTCTACAT +AATGACTGCCTCTCATTCTGTCTTATTTTACCGCAAACCCAAATCGACAATGCACGACAGAGGAAGCAGA +ACAGATATTTAGATTGCCTCTCATTTTCTCTCCCATATTATAGGGAGAAATATGATCGCGTATGCGAGAG +TAGTGCCAACATATTGTGCTCTTTGATTTTTTGGCAACCCAAAATGGTGGCGGATGAACGAGATGATAAT +ATATTCAAGTTGCCGCTAATCAGAAATAAATTCATTGCAACGTTAAATACAGCACAATATATGATCGCGT +ATGCGAGAGTAGTGCCAACATATTGTGCTAATGAGTGCCTCTCGTTCTCTGTCTTATATTACCGCAAACC +CAAAAAGACAATACACGACAGAGAGAGAGAGCAGCGGAGATATTTAGATTGCCTATTAAATATGATCGCG +TATGCGAGAGTAGTGCCAACATATTCTGCTCTCTATATAATGACTGCCTCTCATTCTGTCTTATTTTACC +GCAAACCCAAATCGACAATGCACGACAGAGGAAGCAGAACAGATATTTAGATTGCCTCTCATTTTCTCTC +CCATATTATAGGGAGAAATATGATCGCGTATGCGAGAGTAGTGCCAACATATTGTGCTCTTTGATTTTTT +GGCAACCCAAAATGGTGGCGGATGAACGAGATGATAATATATTCAAGTTGCCGCTAATCAGAAATAAATT +CATTGCAACGTTAAATACAGCACAATATATGATCGCGTATGCGAGAGTAGTGCCAACATATTGTGCTAAT +GAGTGCCTCTCGTTCTCTGTCTTATATTACCGCAAACCCAAAAAGACAATACACGACAGAGAGAGAGAGC +AGCGGAGATATTTAGATTGCCTATTAAATATGATCGCGTATGCGAGAGTAGTGCCAACATATTCTGCTCT +CTATATAATGACTGCCTCTCATTCTGTCTTATTTTACCGCAAACCCAAATCGACAATGCACGACAGAGGA +AGCAGAACAGATATTTAGATTGCCTCTCATTTTCTCTCCCATATTATAGGGAGAAATATGATCGCGTATG +CGAGAGTAGTGCCAACATATTGTGCTCTTTGATTTTTTGGCAACCCAAAATGGTGGCGGATGAACGAGAT +GATAATATATTCAAGTTGCCGCTAATCAGAAATAAATTCATTGCAACGTTAAATACAGCACAATATATGA +TCGCGTATGCGAGAGTAGTGCCAACATATTGTGCTAATGAGTGCCTCTCGTTCTCTGTCTTATATTACCG +CAAACCCAAAAAGACAATACACGACAGAGAGAGAGAGCAGCGGAGATATTTAGATTGCCTATTAAATATG +ATCGCGTATGCGAGAGTAGTGCCAACATATTCTGCTCTCTATATAATGACTGCCTCTCATTCTGTCTTAT +TTTACCGCAAACCCAAATCGACAATGCACGACAGAGGAAGCAGAACAGATATTTAGATTGCCTCTCATTT +TCTCTCCCATATTATAGGGAGAAATATGATCGCGTATGCGAGAGTAGTGCCAACATATTGTGCTCTTTGA +TTTTTTGGCAACCCAAAATGGTGGCGGATGAACGAGATGATAATATATTCAAGTTGCCGCTAATCAGAAA +TAAATTCATTGCAACGTTAAATACAGCACAATATATGATCGCGTATGCGAGAGTAGTGCCAACATATTGT +GCTAATGAGTGCCTCTCGTTCTCTGTCTTATATTACCGCAAACCCAAAAAGACAATACACGACAGAGAGA +GCAGCGGAGATATTTAGATTGCCTATTAAATATGATCGCGTATGCGAGAGTAGTGCCAACATATTCTGCT +CTCTATATAATGACTGCCTCTCATTCTGTCTTATTTTACCGCAAACCCAAATCGACAATGCACGACAGAG +GAAGCAGAACAGATATTTAGATTGCCTCTCATTTTCTCTCCCATATTATAGGGAGAAATATGATCGCGTA +TGCGAGAGTAGTGCCAACATATTGTGCTCTTTGATTTTTTGGCAACCCAAAATGGTGGCGGATGAACGAG +ATGATAATATATTCAAGTTGCCGCTAATCAGAAATAAATTCATTGCAACGTTAAATACAGCACAATATAT +GATCGCGTATGCGAGAGTAGTGCCAACATATTGTGCTAATGAGTGCCTCTCGTTCTCTGTCTTATATTAC +CGCAAACCCAAAAAGACAATACACGACAGAGAGAGAGAGCAGCGGAGATATTTAGATTGCCTATTAAATA +TGATCGCGTATGCGAGAGTAGTGCCAACATATTCTGCTCTCTATATAATGACTGCCTCTCATTCTGTCTT +ATTTTACCGCAAACCCAAATCGACAATGCACGACAGAGGAAGCAGAACAGATATTTAGATTGCCTCTCAT +TTTCTCTCCCATATTATAGGGAGAAATATGATCGCGTATGCGAGAGTAGTGCCAACATATTGTGCTCTTT +GATTTTTTGGCAACCCAAAATGGTGGCGGATGAACGAGATGATAATATATTCAAGTTGCCGCTAATCAGA +AATAAATTCATTGCAACGTTAAATACAGCACAATATATGATCGCGTATGCGAGAGTAGTGCCAACATATT +GTGCTAATGAGTGCCTCTCGTTCTCTGTCTTATATTACCGCAAACCCAAAAAGACAATACACGACAGAGA +GAGAGAGCAGCGGAGATATTTAGATTGCCTATTAAATATGATCGCGTATGCGAGAGTAGTGCCAACATAT +TCTGCTCTCTATATAATGACTGCCTCTCATTCTGTCTTATTTTACCGCAAACCCAAATCGACAATGCACG +ACAGAGGAAGCAGAACAGATATTTAGATTGCCTCTCATTTTCTCTCCCATATTATAGGGAGAAATATGAT +CGCGTATGCGAGAGTAGTGCCAACATATTGTGCTCTTTGATTTTTTGGCAACCCAAAATGGTGGCGGATG +AACGAGATGATAATATATTCAAGTTGCCGCTAATCAGAAATAAATTCATTGCAACGTTAAATACAGCACA +ATATATGATCGCGTATGCGAGAGTAGTGCCAACATATTGTGCTAATGAGTGCCTCTCGTTCTCTGTCTTA +TATTACCGCAAACCCAAAAAGACAATACACGACAGAGAGAGAGAGCAGCGGAGATATTTAGATTGCCTAT +TAAATATGATCGCGTATGCGAGAGTAGTGCCAACATATTCTGCTCTCTACATAATGACTGCCTCTCATTC +TGTCTTATTTTACCGCAAACCCAAATCGACAATGCACGACAGAGGAAGCAGAACAGATATTTAGATTGCC +TCTCATTTTCTCTCCCATATTATAGGGAGAAATATGATCGCGTATGCGAGAGTAGTGCCAACATATTGTG +CTCTTTGATTTTTTGGCAACCCAAAATGGTGGCGGATGAACGAGATGATAATATATTCAAGTTGCCGCTA +ATCAGAAATAAATTCATTGCAACGTTAAATACAGCACAATATATGATCGCGTATGCGAGAGTAGTGCCAA +CATATTGTGCTAATGAGTGCCTCTCGTTCTCTGTCTTATATTACCGCAAACCCAAAAAGACAATACACGA +CAGAGAGAGAGAGCAGCGGAGATATTTAGATTGCCTATTAAATATGATCGCGTATGCGAGAGTAGTGCCA +ACATATTCTGCTCTCTATATAATGACTGCCTCTCATTCTGTCTTATTTTACCGCAAACCCAAATCGACAA +TGCACGACAGAGGAAGCAGAACAGATATTTAGATTGCCTCTCATTTTCTCTCCCATATTATAGGGAGAAA +TATGATCGCGTATGCGAGAGTAGTGCCAACATATTGTGCTCTTTGATTTTTTGGCAACCCAAAATGGTGG +CGGATGAACGAGATGATAATATATTCAAGTTGCCGCTAATCAGAAATAAATTCATTGCAACGTTAAATAC +AGCACAATATATGATCGCGTATGCGAGAGTAGTGCCAACATATTGTGCTAATGAGTGCCTCTCGTTCTCT +GTCTTATATTACCGCAAACCCAAAAAGACAATACACGACAGAGAGAGAGAGCAGCGGAGATATTTAGATT +GCCTATTAAATATGATCGCGTATGCGAGAGTAGTGCCAACATATTCTGCTCTCTATATAATGACTGCCTC +TCATTCTGTCTTATTTTACCGCAAACCCAAATCGACAATGCACGACAGAGGAAGCAGAACAGATATTTAG +ATTGCCTCTCATTTTCTCTCCCATATTATAGGGAGAAATATGATCGCGTATGCGAGAGTAGTGCCAACAT +ATTGTGCTCTTTGATTTTTTGGCAACCCAAAATGGTGGCGGATGAACGAGATGATAATATATTCAAGTTG +CCGCTAATCAGAAATAAATTCATTGCAACGTTAAATACAGCACAATATATGATCGCGTATGCGAGAGTAG +TGCCAACATATTGTGCTAATGAGTGCCTCTCGTTCTCTGTCTTATATTACCGCAAACCCAAAAAGACAAT +ACACGACAGAGAGAGAGAGCAGCGGAGATATTTAGATTGCCTATTAAATATGATCGCGTATGCGAGAGTA +GTGCCAACATATTCTGCTCTCTATATAATGACTGCCTCTCATTCTGTCTTATTTTACCGCAAACCCAAAT +CGACAATGCACGACAGAGGAAGCAGAACAGATATTTAGATTGCCTCTCATTTTCTCTCCCATATTATAGG +GAGAAATATGATCGCGTATGCGAGAGTAGTGCCAACATATTGTGCTCTTTGATTTTTTGGCAACCCAAAA +TGGTGGCGGATGAACGAGATGATAATATATTCAAGTTGCCGCTAATCAGAAATAAATTCATTGCAACGTT +AAATACAGCACAATATATGATCGCGTATGCGAGAGTAGTGCCAACATATTGTGCTAATGAGTGCCTCTCG +TTCTCTGTCTTATATTACCGCAAACCCAAAAAGACAATACACGACAGAGAGAGCAGCGGAGATATTTAGA +TTGCCTATTAAATATGATCGCGTATGCGAGAGTAGTGCCAACATATTCTGCTCTCTATATAATGACTGCC +TCTCATTCTGTCTTATTTTACCGCAAACCCAAATCGACAATGCACGACAGAGGAAGCAGAACAGATATTT +AGATTGCCTCTCATTTTCTCTCCCATATTATAGGGAGAAATATGATCGCGTATGCGAGAGTAGTGCCAAC +ATATTGTGCTCTTTGATTTTTTGGCAACCCAAAATGGTGGCGGATGAACGAGATGATAATATATTCAAGT +TGCCGCTAATCAGAAATAAATTCATTGCAACGTTAAATACAGCACAATATATGATCGCGTATGCGAGAGT +AGTGCCAACATATTGTGCTAATGAGTGCCTCTCGTTCTCTGTCTTATATTACCGCAAACCCAAAAAGACA +ATACACGACAGAGAGAGAGAGCAGCGGAGATATTTAGATTGCCTATTAAATATGATCGCGTATGCGAGAG +TAGTGCCAACATATTCTGCTCTCTATATAATGACTGCCTCTCATTCTGTCTTATTTTACCGCAAACCCAA +ATCGACAATGCACGACAGAGGAAGCAGAACAGATATTTAGATTGCCTCTCATTTTCTCTCCCATATTATA +GGGAGAAATATGATCGCGTATGCGAGAGTAGTGCCAACATATTGTGCTCTTTGATTTTTTGGCAACCCAA +AATGGTGGCGGATGAACGAGATGATAATATATTCAAGTTGCCGCTAATCAGAAATAAATTCATTGCAACG +TTAAATACAGCACAATATATGATCGCGTATGCGAGAGTAGTGCCAACATATTGTGCTAATGAGTGCCTCT +CGTTCTCTGTCTTATATTACCGCAAACCCAAAAAGACAATACACGACAGAGAGAGAGAGCAGCGGAGATA +TTTAGATTGCCTATTAAATATGATCGCGTATGCGAGAGTAGTGCCAACATATTCTGCTCTCTATATAATG +ACTGCCTCTCATTCTGTCTTATTTTACCGCAAACCCAAATCGACAATGCACGACAGAGGAAGCAGAACAG +ATATTTAGATTGCCTCTCATTTTCTCTCCCATATTATAGGGAGAAATATGATCGCGTATGCGAGAGTAGT +GCCAACATATTGTGCTCTTTGATTTTTTGGCAACCCAAAATGGTGGCGGATGAACGAGATGATAATATAT +TCAAGTTGCCGCTAATCAGAAATAAATTCATTGCAACGTTAAATACAGCACAATATATGATCGCGTATGC +GAGAGTAGTGCCAACATATTGTGCTAATGAGTGCCTCTCGTTCTCTGTCTTATATTACCGCAAACCCAAA +AAGACAATACACGACAGAGAGAGAGAGCAGCGGAGATATTTAGATTGCCTATTAAATATGATCGCGTATG +CGAGAGTAGTGCCAACATATTCTGCTCTCTACATAATGACTGCCTCTCATTCTGTCTTATTTTACCGCAA +ACCCAAATCGACAATGCACGACAGAGGAAGCAGAACAGATATTTAGATTGCCTCTCATTTTCTCTCCCAT +ATTATAGGGAGAAATATGATCGCGTATGCGAGAGTAGTGCCAACATATTGTGCTCTTTGATTTTTTGGCA +ACCCAAAATGGTGGCGGATGAACGAGATGATAATATATTCAAGTTGCCGCTAATCAGAAATAAATTCATT +GCAACGTTAAATACAGCACAATATATGATCGCGTATGCGAGAGTAGTGCCAACATATTGTGCTAATGAGT +GCCTCTCGTTCTCTGTCTTATATTACCGCAAACCCAAAAAGACAATACACGACAGAGAGAGAGAGCAGCG +GAGATATTTAGATTGCCTATTAAATATGATCGCGTATGCGAGAGTAGTGCCAACATATTCTGCTCTCTAT +ATAATGACTGCCTCTCATTCTGTCTTATTTTACCGCAAACCCAAATCGACAATGCACGACAGAGGAAGCA +GAACAGATATTTAGATTGCCTCTCATTTTCTCTCCCATATTATAGGGAGAAATATGATCGCGTATGCGAG +AGTAGTGCCAACATATTGTGCTCTTTGATTTTTTGGCAACCCAAAATGGTGGCGGATGAACGAGATGATA +ATATATTCAAGTTGCCGCTAATCAGAAATAAATTCATTGCAACGTTAAATACAGCACAATATATGATCGC +GTATGCGAGAGTAGTGCCAACATATTGTGCTAATGAGTGCCTCTCGTTCTCTGTCTTATATTACCGCAAA +CCCAAAAAGACAATACACGACAGAGAGAGAGAGCAGCGGAGATATTTAGATTGCCTATTAAATATGATCG +CGTATGCGAGAGTAGTGCCAACATATTCTGCTCTCTATATAATGACTGCCTCTCATTCTGTCTTATTTTA +CCGCAAACCCAAATCGACAATGCACGACAGAGGAAGCAGAACAGATATTTAGATTGCCTCTCATTTTCTC +TCCCATATTATAGGGAGAAATATGATCGCGTATGCGAGAGTAGTGCCAACATATTGTGCTCTTTGATTTT +TTGGCAACCCAAAATGGTGGCGGATGAACGAGATGATAATATATTCAAGTTGCCGCTAATCAGAAATAAA +TTCATTGCAACGTTAAATACAGCACAATATATGATCGCGTATGCGAGAGTAGTGCCAACATATTGTGCTA +ATGAGTGCCTCTCGTTCTCTGTCTTATATTACCGCAAACCCAAAAAGACAATACACGACAGAGAGAGAGA +GCAGCGGAGATATTTAGATTGCCTATTAAATATGATCGCGTATGCGAGAGTAGTGCCAACATATTCTGCT +CTCTATATAATGACTGCCTCTCATTCTGTCTTATTTTACCGCAAACCCAAATCGACAATGCACGACAGAG +GAAGCAGAACAGATATTTAGATTGCCTCTCATTTTCTCTCCCATATTATAGGGAGAAATATGATCGCGTA +TGCGAGAGTAGTGCCAACATATTGTGCTCTTTGATTTTTTGGCAACCCAAAATGGTGGCGGATGAACGAG +ATGATAATATATTCAAGTTGCCGCTAATCAGAAATAAATTCATTGCAACGTTAAATACAGCACAATATAT +GATCGCGTATGCGAGAGTAGTGCCAACATATTGTGCTAATGAGTGCCTCTCGTTCTCTGTCTTATATTAC +CGCAAACCCAAAAAGACAATACACGACAGAGAGAGCAGCGGAGATATTTAGATTGCCTATTAAATATGAT +CGCGTATGCGAGAGTAGTGCCAACATATTCTGCTCTCTATATAATGACTGCCTCTCATTCTGTCTTATTT +TACCGCAAACCCAAATCGACAATGCACGACAGAGGAAGCAGAACAGATATTTAGATTGCCTCTCATTTTC +TCTCCCATATTATAGGGAGAAATATGATCGCGTATGCGAGAGTAGTGCCAACATATTGTGCTCTTTGATT +TTTTGGCAACCCAAAATGGTGGCGGATGAACGAGATGATAATATATTCAAGTTGCCGCTAATCAGAAATA +AATTCATTGCAACGTTAAATACAGCACAATATATGATCGCGTATGCGAGAGTAGTGCCAACATATTGTGC +TAATGAGTGCCTCTCGTTCTCTGTCTTATATTACCGCAAACCCAAAAAGACAATACACGACAGAGAGAGA +GAGCAGCGGAGATATTTAGATTGCCTATTAAATATGATCGCGTATGCGAGAGTAGTGCCAACATATTCTG +CTCTCTATATAATGACTGCCTCTCATTCTGTCTTATTTTACCGCAAACCCAAATCGACAATGCACGACAG +AGGAAGCAGAACAGATATTTAGATTGCCTCTCATTTTCTCTCCCATATTATAGGGAGAAATATGATCGCG +TATGCGAGAGTAGTGCCAACATATTGTGCTCTTTGATTTTTTGGCAACCCAAAATGGTGGCGGATGAACG +AGATGATAATATATTCAAGTTGCCGCTAATCAGAAATAAATTCATTGCAACGTTAAATACAGCACAATAT +ATGATCGCGTATGCGAGAGTAGTGCCAACATATTGTGCTAATGAGTGCCTCTCGTTCTCTGTCTTATATT +ACCGCAAACCCAAAAAGACAATACACGACAGAGAGAGAGAGCAGCGGAGATATTTAGATTGCCTATTAAA +TATGATCGCGTATGCGAGAGTAGTGCCAACATATTCTGCTCTCTATATAATGACTGCCTCTCATTCTGTC +TTATTTTACCGCAAACCCAAATCGACAATGCACGACAGAGGAAGCAGAACAGATATTTAGATTGCCTCTC +ATTTTCTCTCCCATATTATAGGGAGAAATATGATCGCGTATGCGAGAGTAGTGCCAACATATTGTGCTCT +TTGATTTTTTGGCAACCCAAAATGGTGGCGGATGAACGAGATGATAATATATTCAAGTTGCCGCTAATCA +GAAATAAATTCATTGCAACGTTAAATACAGCACAATATATGATCGCGTATGCGAGAGTAGTGCCAACATA +TTGTGCTAATGAGTGCCTCTCGTTCTCTGTCTTATATTACCGCAAACCCAAAAAGACAATACACGACAGA +GAGAGAGAGCAGCGGAGATATTTAGATTGCCTATTAAATATGATCGCGTATGCGAGAGTAGTGCCAACAT +ATTCTGCTCTCTATATAATGACTGCCTCTCATTCTGTCTTATTTTACCGCAAACCCAAATCGACAATGCA +CGACAGAGGAAGCAGAACAGATATTTAGATTGCCTCTCATTTTCTCTCCCATATTATAGGGAGAAATATG +ATCGCGTATGCGAGAGTAGTGCCAACATATTGTGCTCTTTGATTTTTTGGCAACCCAAAATGGTGGCGGA +TGAACGAGATGATAATATATTCAAGTTGCCGCTAATCAGAAATAAATTCATTGCAACGTTAAATACAGCA +CAATATATGATCGCGTATGCGAGAGTAGTGCCAACATATTGTGCTAATGAGTGCCTCTCGTTCTCTGTCT +TATATTACCGCAAACCCAAAAAGACAATACACGACAGAGAGAGAGAGCAGCGGAGATATTTAGATTGCCT +ATTAAATATGATCGCGTATGCGAGAGTAGTGCCAACATATTCTGCTCTCTACATAATGACTGCCTCTCAT +TCTGTCTTATTTTACCGCAAACCCAAATCGACAATGCACGACAGAGGAAGCAGAACAGATATTTAGATTG +CCTCTCATTTTCTCTCCCATATTATAGGGAGAAATATGATCGCGTATGCGAGAGTAGTGCCAACATATTG +TGCTCTTTGATTTTTTGGCAACCCAAAATGGTGGCGGATGAACGAGATGATAATATATTCAAGTTGCCGC +TAATCAGAAATAAATTCATTGCAACGTTAAATACAGCACAATATATGATCGCGTATGCGAGAGTAGTGCC +AACATATTGTGCTAATGAGTGCCTCTCGTTCTCTGTCTTATATTACCGCAAACCCAAAAAGACAATACAC +GACAGAGAGAGAGAGCAGCGGAGATATTTAGATTGCCTATTAAATATGATCGCGTATGCGAGAGTAGTGC +CAACATATTCTGCTCTCTATATAATGACTGCCTCTCATTCTGTCTTATTTTACCGCAAACCCAAATCGAC +AATGCACGACAGAGGAAGCAGAACAGATATTTAGATTGCCTCTCATTTTCTCTCCCATATTATAGGGAGA +AATATGATCGCGTATGCGAGAGTAGTGCCAACATATTGTGCTCTTTGATTTTTTGGCAACCCAAAATGGT +GGCGGATGAACGAGATGATAATATATTCAAGTTGCCGCTAATCAGAAATAAATTCATTGCAACGTTAAAT +ACAGCACAATATATGATCGCGTATGCGAGAGTAGTGCCAACATATTGTGCTAATGAGTGCCTCTCGTTCT +CTGTCTTATATTACCGCAAACCCAAAAAGACAATACACGACAGAGAGAGAGAGCAGCGGAGATATTTAGA +TTGCCTATTAAATATGATCGCGTATGCGAGAGTAGTGCCAACATATTCTGCTCTCTATATAATGACTGCC +TCTCATTCTGTCTTATTTTACCGCAAACCCAAATCGACAATGCACGACAGAGGAAGCAGAACAGATATTT +AGATTGCCTCTCATTTTCTCTCCCATATTATAGGGAGAAATATGATCGCGTATGCGAGAGTAGTGCCAAC +ATATTGTGCTCTTTGATTTTTTGGCAACCCAAAATGGTGGCGGATGAACGAGATGATAATATATTCAAGT +TGCCGCTAATCAGAAATAAATTCATTGCAACGTTAAATACAGCACAATATATGATCGCGTATGCGAGAGT +AGTGCCAACATATTGTGCTAATGAGTGCCTCTCGTTCTCTGTCTTATATTACCGCAAACCCAAAAAGACA +ATACACGACAGAGAGAGAGAGCAGCGGAGATATTTAGATTGCCTATTAAATATGATCGCGTATGCGAGAG +TAGTGCCAACATATTCTGCTCTCTATATAATGACTGCCTCTCATTCTGTCTTATTTTACCGCAAACCCAA +ATCGACAATGCACGACAGAGGAAGCAGAACAGATATTTAGATTGCCTCTCATTTTCTCTCCCATATTATA +GGGAGAAATATGATCCGCGTATGCGAGAGTAGTGCCAACATATTGTGCTCTTTGATTTTTTGGCAACCCA +AAATGGTGGCGGATGAACGAGATGATAATATATTCAAGTTGCCGCTAATCAGAAATAAATTCATTGCAAC +GTTAAATACAGCACAATATATGATCGCGTATGCGAGAGTAGTGCCAACATATTGTGCTAATGAGTGCCTC +TCGTTCTCTGTCTTATATTACCGCAAACCCAAAAAGACAATACACGACAGAGAGAGCAGCGGAGATATTT +AGATTGCCTATTAAATATGATCGCGTATGCGAGAGTAGTGCCAACATATTCTGCTCTCTATATAATGACT +GCCTCTCATTCTGTCTTATTTTACCGCAAACCCAAATCGACAATGCACGACAGAGGAAGCAGAACAGATA +TTTAGATTGCCTCTCATTTTCTCTCCCATATTATAGGGAGAAATATGATCGCGTATGCGAGAGTAGTGCC +AACATATTGTGCTCTTTGATTTTTTGGCAACCCAAAATGGTGGCGGATGAACGAGATGATAATATATTCA +AGTTGCCGCTAATCAGAAATAAATTCATTGCAACGTTAAATACAGCACAATATATGATCGCGTATGCGAG +AGTAGTGCCAACATATTGTGCTAATGAGTGCCTCTCGTTCTCTGTCTTATATTACCGCAAACCCAAAAAG +ACAATACACGACAGAGAGAGAGAGCAGCGGAGATATTTAGATTGCCTATTAAATATGATCGCGTATGCGA +GAGTAGTGCCAACATATTCTGCTCTCTATATAATGACTGCCTCTCATTCTGTCTTATTTTACCGCAAACC +CAAATCGACAATGCACGACAGAGGAAGCAGAACAGATATTTAGATTGCCTCTCATTTTCTCTCCCATATT +ATAGGGAGAAATATGATCGCGTATGCGAGAGTAGTGCCAACATATTGTGCTCTTTGATTTTTTGGCAACC +CAAAATGGTGGCGGATGAACGAGATGATAATATATTCAAGTTGCCGCTAATCAGAAATAAATTCATTGCA +ACGTTAAATACATCACAAAATGGCCGCTCAAAAACAGGCTTGAACATATAATGACTGCCTCTCATTCTCT +GTTTCATTTTCACTCCCATATTATAGGGTGAAATATAATCGCGTATGCGAGAGTAGTGGCAACATATTGT +GCTCTTCGATTTTTTGGCAACCCAAATTGGAGGCAGACGAACGAGATGATACCATATGCAAATTGTAGCT +AATTTTCTCTCCCATATATATAAGACCGAAAACGGCTGTTTAAAAGTTCCCAATAGATTGCCAATATTTA +AGTCTATATATTTCTGAGAATAAATTGACCAGATTAAATATTAAAGGCCATGTTTTTGTATTGCTTTTTT +TATACCCCTTACTCATATATTTAAAGGGGTACACTATATTCGTTGAAGAGTATGTAACAAACAGTATGAA +ATGTCTCCGACTATATAAAGTATATATATTTTTGATCATAATCAAAAGCCGAGGCGATCTAGCCATGTCC +GTCTGTTCGTATGAACGTCGAGATCTCAAGAACTATAAAATCAAGAAGGTTGAGATTAAGCAGCATATAG +ATTCTAGAGACAAGGACGCAGTGCAAGTTTGGTGACCCATGTTGTCACGCCCATTCTAACGTCCACAAAC +CGCACAAAACTGCCATGCCCACATTTTTAAACCATTTTTCCTATTTTTTTCACATTTTATTAACTTTGTA +AATTTCTATCACTCTTCAAAAAAAAATTTGCCATGCCCACATTTTTTAACCATTCTTCGATATTTTTTCA +AAATTTAATAAATAACAGCCCAAAACAGCTACGCCCACATTTTTGAACCATTTTTCAATATTTTAATATA +ATTTTAGTAGTCGTGTAGATTTCTATCGACTTGCCAAAAAACTTTTTTCCACGCCCACTCTAGCGCCCTA +AAGCAGCCGAACCGGTTACGCCCACACTTTCTAACAATCGTTAAATTTTTTCTTATTTTATTGCCAGTAT +CTTTCGATATCCCAGAAAAATGATGAAATTTCGTTCACACGAACGGGTTTCTGATATTTGGGGAACTCGA +ATATAGCATTTTTATGTTGTTTCTTCTCGTAAATCTGTGGAAACAAATCGATTCCTTTTCCTATTTTATA +ATATAAAAAACTTGTACGCTAATCTTGGTACATTTTAACTGCGGTTACAGATCATGAATAGACTATATCA +AAAATTACTTGCAAAAAATCGAACAAAATAAACTATGCTTATATTATAAACTTTAACCTTTTCCGTAACA +ATGCAACCGTTCCCAAAATCTTTATTTTTAACAAATAGAAAATTTTGAATATAAATAAATTTTTCGTATT +ATGAACTAAATTTTGTATTTAGGTACATATATGTATTAGGGTATTAGCTAATATATTTTTGTTTTTTTTT +TTTTTTAATTAAGTTGTGAATATCTATTGAAATGTCTGAAGCAATTCCGCTCCTACCAATACTTTTATAA +AAAAGTTCAATATTTTTTTAAATTTCCTGCCATTTCTATTCTATTGAAATTTTTCTATCTTACTCCCACC +AGACGTGTAACATATTTTAATTGCTTGAAGATTGACTTTCGCTCACATCCACAGGGAAAACAAGAGAGAA +TGCAGTAGTCGAGCTCCTGACTCCAGGTACCAGTTAATCAGTTAGAAGCGTAAAAGAGAAATTTAAATAT +TTTTTAGGAATATTGGTAGAAATGGGGAAAAAATAATACAATAAAAATTAATTTAAATATTGTTCAAAAG +TGTGGGCATAACAGTTTTGTGTGGTTTGTGTGCGTCTGAGTGGGCCTGCCCAAACAATTTTTGGCTAGCC +GATAGAAGTTTGCAAGACTAAAAAAATATATAAAAAAATATCAAAACATTTTTCAAAAGACGGGTTCCTA +AGATCTAATCTTTATACCGACAGACGGACGAACATGGCCAGATCGACTCGACAATTGATCCTGATCAGAA +ATATATATACTTTATAAGTTCGGAAACGCTTCCTTCTACCAGTTACATACATTTCATTGACACTAGTATA +ACCCTTTACGCTAGGAGTGCGTATAACAAAGTTACCATATCTGGTTTGTGTAAAAATACTGATGACAGAC +CGTTCGTCAAGAAATACTGACAGTTATTGTATAATTAGGTTAATTTAAAAATTAATTGAATTTTAGGACG +GCTTATATTTGAAATATACTACAAAAACATAAAACTTGGTAAATTTATGAACGGTCTGCTTTCGGAATTT +CAGCAGAATCGGTTGGCAAGCAATTCACAACGAAGAGCTATCAGAGCAAACCGAAAACACAAATCAACAA +TGTTGCAGCAAGAGTTAATACGTTGGTGTAAGTTTACAAATCAGTATTCATTAAATCTAGATAGCTCTTT +GCGCTAAGAGTGCGTAAAACAAACAGTTACCATATCTGGGTTGTGTAAAAATACTGAGGACAGACCGTTC +GTCAAGAAATACTGACAGTTGTATAATTAGGTTTATTGAAAATTATCGAATTATCGGACGGCTGATATTT +GACATATACTAAAAACATAAAATTTGGTATATTTATGAACGGTCTGCTGTCGGTATTTCATCAGAATCGG +TTGGCAAGCAATTCACAACAAAGAGCCATCAGAGTTAACCGAAAACACAAGCCTTTTATGCAGCAAGAGT +TAATACGTTGGTGTAAGTGTACAAATCAGTAGGGACCACAAATTAACGTTCTTTTACGTATACAATATTT +CAGATAAATCCCACAGGTATGGAACACCATAAAGACACCGGTCAATTGCACCACTACGTGCAGTACGGAC +TTTCCGAAAGTGCACAGATTTTCGGATGCGCAAAAGAGCATCACATCTTGAAGACGCTCTGAGGAAAACT +GCTCCAAATCTAGTCCACCAGCATTAAACTACCGGTGGCTTCAATCTGGTTTAGGAAGAAGACCACAATA +AAGTGATCAAAGATAATCAGGTCTTCACCAATTTAAAGTCTACTACTTCAACGAATGAGATAGTCGTCCT +GCAGGCAAGGAGTCATACCAGTTGGCCGAGCAATATCAACAGCAGCAGATGGAATCGCGTGATGAATCTA +GTATCTCCGTCAGGAAGACGGGCACGTGTACAGCGAGGACAACAGTGATTTTGGAGTGGAACAGGTGGAA +AACCAATCCCAGTTGAAAACCAATCCCAGTTCGATCCCAATGTTGTGGCCTTTGTGCCTAGCTTTGACGC +ACAGAAATCCTCTCCCCCGCAGCCTGTTGCGGAAGTTTATCTACTTGGTGTTCAGCCCCGCTAACTTTTA +CCGCATGGCACCCTTGACGACCTTGTTGTGGAAAGTCTGCGTAAAGAATTTCAAAATTTCTGGAAGGGGA +AACCTGTAGATGCAGCTGAGCTGTTAAATGATTTACAAACAAGCCGACATCTCGGGAACCATTAAAGAGA +CATTTAAAGTCAAAAAGTGGCCAACTGAAACCCGTTAAAATCCGCTTGCGACCGCAACTTGGCCCGACTA +AGGCAAAAAATAACATAATCCTGTCAAGTCATGCAGACAGGGCGATTTACATTATAATTTTAAATGGCAA +TGGATTAGTCATCATCAGTACCTGCTTATCTGGTTTTCCTGATTTTTAAATCAAATCTGTGACTGTATCT +CTTACCTTTCCTCTTGTACCTCGTTATTATAAAATGCGAAAACCCTCTGCCAAAGGACACTATAAAACGA +ATTTTTTAAAAGACGCCAAACAAAATGGCACTTTTTGTTGAGAAGAAAATATGCCGATAAGAACGTTTTA +CTTGTAAGACGCTGCAGAAAGATTAGGAACGAAAACTATCGACAATGTTTACTTGTATAATCTGAGCTTT +CTAAAACACAAAAATAGTGTACTTTTACCATACGCTTAATTTCGAAATTAATCCGGGATATACAGTTGGG +GATCCAGATTTTAAATTCGTGAACACAGCTGCTGGAGTAGGGCATTTCCTGATCGATCTGTTAGTTTTCG +GACTTTTACTTTGGTTGTTGTAAACAATATCCGCAAGTTTCTCGCAAAGTGGGTTGCGTTGTGCCGTGCC +TCAGTAGAGCACTACACACTACCTTCGATTGAGTTCGCTGGGATTTGGATTTCGTTCACAGTCCAAGTTT +GGACCGTGCTAGGAGAAGATAATGATCCGATCACTCAATTAACTTCATGCACCCAGTGACGTCATCAGTG +CTTTACTATTCGGTGTCTATATAGTCTATTTTGTTTAATTTCTTACACCCTACATTTCGATACGATTCGA +TTTTCGTTTGGAAATTGTCTGAAGGTAAACAAGCATAAATTGGACGTTCAAGCGTAAACAAATCGGTTTT +CGGAGCAAAATACAAAAATCGTCAGTTGAGAAAGTCTCTCAAATGGCGCAGTTCTGCATTCTTGGAGTCC +TCCTCATTCTTTCTGGAACACACTGCTCGTGGGGATTCCATGAAGAGACACATTATCCGTGTGCCTTTAT +CGATACGGCAAACATAACGGGGAGCTACGGCTTAGATGGCCCATTTGTGCACAACTGGACGGTGATTCCC +CGTCACTTCGTAGCCGTGTACGACTTTGTCATCGAAAATGGCATCCGCATCCCCGCAAGCAGGCATCTCA +GAGCCTGTGTCTGTAAGACCAAACCCTGTGTACGGATTTGCTGTTTACGGGGAGAAATCTACGACCTGGA +GAAGAGGCAGTGCTTAGTCCCTGTGGCCGGGGTGTCCAGCCTTCCCTCCCATAGCCATATGGAGGTGGAG +TTGGGCAACGGCAGTCTGCGTCTAGTGAAACTGCAACCCCGTTTTAGCATCCACGTGGAAACACCATGTG +AGCACATGAAAGCCGTAACCAAGGGCTCGGAATACGTTCACTGGACACTTCATGAGGTCGGTTGTGAAAT +AAACCTTCCATCACATTAATGGCTTTACATCGCCTTTTCAGAACGGAACCATCAGCCACCGAGGACACAT +ATTTTCTAAGCATTACTGCTTCACTCCGCTGCTCCATGGGAACTCCACCTGGGAGTGGCAGCCATTGGCC +TGTGCACCAGAAAAACTATATTTCGTCTTGGGGGTGCGGGAGTGGACATACGCCATATGTAAGTAGCAAG +AGGAAACATTTTTCCAGCAACTTTCAGCAATTCATTATCCCAAATATGCACAATACTGTTTTCACAACAA +TACATAAAAGTAATTGCTAAAGCACCAAAAAACAATCGATGATAGCATTAATAGTTTGATAGTCAGAATT +TAATTTACCCAGCGTATTCACTTTCCAGGTCTCTTGATAGCTATTCTATCAATGTTTATCGTGCTGATGG +TCTACCTTATGTGTTCGGAAATGCGCAACAGTTTCTACGGTGTGGCCATAAAGGCGTACGCCATTTGTAT +GATCTTGGGATATGCCCTACTGGCTTATCTCACGCTCCACAACCCAGCAAATCTCTCAAATGCGGCTTGT +CGTATTCTACGTAAGTGGTAAATTTGAGTATTCTGTGATATTTAAACATTCCCTTCTTTTTTTTTTTTAG +CAAGTTTGGCGTTGATGAACTTGGTGCTTTCCTTTTACATTCTGAGCTTTATTGCATTTAAGCTGTACTT +GAGCTTTTATGGCGTTGTCTTCACAAAACTGATGTTTTGGCTAATATTTACTCCCATCGTACTGGTAGCC +GTGGGCTGGTCTTTCTTTGTGGGTTTCAGTTATTACGGCTCTAGGCTCATCTTCGGAGGCGATACATGCT +GGTTTGATCGTAAGCACTGCCAATCCATATATGTTTTATAATAATTAATTGGTATTCCACATCGCTAGCA +CGCAATTGGTCCGTTATGATATATTTTTACGCTCCTGTTTTCGTGGCTTGCGCCATTAGCGGTTTCTTCT +ATGTCCTGAGCCAGATCTACATCCGTGATCAGCCAGATATCGAGACGGAGAAGAGCTTCGAGTCCATAGA +GAAGAACCGATTCAAATCATTTTGGAAGTACTTTGGCTACACGGCAGTCGTATGGGTCGTTTGCATATGC +TCCTTTGCCTTTAACTACTACTGGGAGAACAGATCCCACCTTAACTACGCTGTAAGCTTCTGCATGGCCT +TCCACGGGTTTGCGGCCCTCTATGCGCTGATTGGAAAGAATCAGCAAATCCAAAATTTTCTGCGGCGCAT +AGATAAGTAAGTTGATAACTATGAATTTTAAGTACTACTGTTAATATATACTGTTGCAGTGGCGAAGATA +CCTGTGAAAACTCAGTTCCGCTCTCGAGTTTTGGTTAACTTTTCTTGTTGTGCCCACTGTAGCGTTAGTG +TAACTGGAAGCAGTTGAGTGTATCGACAATATCTGTGCAATGTTTTTAAAATCACTTATCAGCATAGACA +AAAACCATGTATTTTAAATGTAAAATTTTGTAGGATGTGTGTAAAATATATTTGTAAAATTTGAACTCGA +ACAAAAAAGTACACTTCTACCCTTTAAACGAAATTACGATAATAAAGATACAAAAAATAAATATATCTGA +AAAAAAAATCAGGTCTGGAATTTCTACAATTGTTAAATATGATAACAAGTCCCAACAATCCTTTCAGTAT +AGAACAAAACATGGAATATACTTAAGCCATGTGAAAGAACACATAACATATTAATATTCTAAACAATTTG +AGCAGTTTTCTTGAGTTTACGCCTCCAACAATTTATCCTTCACCTTTCTTGAGTTCCAAATTCCTGGACC +GTGATCAAGTTTCTCCAGTCTTATTTCAAGTCCCGATTTTACTGTACCCTATCCGCATCGCCAAGCCCGG +TGTTACTTCCCCGATCTCTCTATATTATAAATGTGCGCCGATTTTATTTAACATCAGAGGTCAATGGCCG +CAAAACAGACAGAGAGAGAGAGAGAGAAAGTTGGTCAGAGCCACGAGAACTGCATCCCGACAGGGGGCTG +TCAAGAGCAAGGAATCAAGTGGAATGTTGGTGGTGCTCTTTTGAAAAGGCTTCGCAAACTTTCCCCCTGT +ACACCCCCTTGCCAAGGCCTAATCGCAGAAAACCCACCCGGGTCGGAGTCCCCAATTCATTTTCATGCCG +ATTATGCTTCGGGTTTTGGTCCTGCTCTTTTTGGCTGGGCGTACAGCAGCAGGACTCGGGGTACACACTA +AGAGAGGTCTAAGAATATAGAGATAGACAAGGAAAGCAGATGGATCGATAAAACGTAGTAAAAATGCTCG +TAGTAATGGAAGCTGGAAATAACATGGCACAAACAGGCCCCAAACTGCATCGACAACACCATCACAATCC +AGACGTGCGCACTGGAAAATCCCGAGAGGTAGGACATGTTTGGCGCGTTTTTCGACTGCATGTGTGCGAG +TGTTCTGTTTTGGTTAGATACGTATGAAAAAGTGAAAAAGCCTATATTGACCGCGCCCGGTAGATCGCAT +AGGCAATATCGATATGGGAAATCATTGACTAACATTTGCAGACATTTAGTTTGGGACACATTAAAGTTAA +TTTGACTCGCACTATCAGAAGTGGAATCGACTTCTATTACACAGAGTTAAAGGTTTAGATCTTTTTTTTA +TGAATAAAAGAAAATGAACTTTTAAATATTCAACACAAAACACTCTTATAGAACATTGAAAACTCTTCCA +CTTAGAGGAACATCCGATCACTTTTCGGTCCCTCCAATGAATAGTTCCTCCACCTCCTTATAAACTCACT +TCCTACTAAAGCAAACGCACTACAATAACTTTTAATTTAACAATTTTTCAAAAATGCAAGCGTTACACTT +TTTATGCGGTTTATTTAAACATTTTTCAAAATGTTTAATGTTACCATTGTCACATTGGCTTGGAAACATA +CTACAGTATAATTCGCTTAGCTGCATCGATAGTTAGCTGCATCGGCAAGATATCTGCATTATTTTTCCAT +TTTTTTGTGTGAATAGAAAATTTGTACGAAAATTCATACGTTTGCTGCATCGCAGATAACAGCCTTTTTA +ACTTAAGTGCATCATATCAGCTGTTTTTTTTGCCAATTTCAATGAATATCATCAAAGTTAGCTGCGCCAT +CTATGAATCATTTTTGCATATCTAAAAGATGGCAAGAATGCCAACTCGTTTCAGTATCTGCGCATGTCCG +TTTTTGTTTTTGCTTTGATCGTGATTTTTGTGTTTTTGTTTCTTATGACACAAAGTTATTAAAATGGGTA +AAACAAAGCGTGTCGTTGGACTAACACTAAAGGAAAAGCTTCAAATAATCGAGTTAGTGACCAACAAAGT +GGACAAAAAGGAAATTTGTGCCAAGTTCAAATGCGACAGATCCACAGTCAACCGCATTTTACAAAAAACA +AATGAAATTCATGAAGCTGTGGCCGCGTCAGGTTTAAAAAGAAAGCGTCAAAGAAAAGGAGACACCATTG +CTGAAAAAGACAAACAATGCGTAGAAGTTGACATTGTATCGAATATTAATTGGAATGAATATGCCAATGT +TGATGCAGATGAGGCTTGCCATGGTCAATTAGATGATGATGAAATCGTGCGCTCTTTAGTTCAAGATGCA +AAAACCAGCGATAACGAAGAAAGCCATAGTGATGAAGATGTGGACGATACTGAGCGTCCTACTTTTAAGG +ATGGGTTTGCAGCAATTAAGGCTTTAAAGTCCATTTTTATGCGAAACAATAATGATGAGTTTTTGCAAAA +CTTGAATTCTATGGAAGACAAGCTGTTTAATTTACATATAAACTCAGCTGTATTGCAAAAAAAAATTACT +GACTATTTTTAAGTTAGTTTTAAAAAGTGTTTTAATCAATTCACCATCACTTAAATTTATATGTCGATCT +TACTTATCATTAAGAATGAAATTATCAGTTCCTTTTATGTTTAACATTGTTATAAAGAAATAAATTCTTT +ATTTTTCCTTAAAAAAAAAAAATTAAGTTAGCTGCATTTTTAAGTTACCTGCATCGAGGCATTGTGCAAA +GTACTCGAGGCAGCTAAGCGAATTATACTGTAATGCAAAAGAGAGTGCTATAGTCGAGTTACCCGATTAT +CAGATATCCGTTACACAACTAGTGTGAATGAAAACGCGTAATTTCATAATCCTTCTGCAAAATCGATAAA +ATGAGAACAAATTTTATAATTGTTCAAAAGTGTGGGCGTGACCGGTTTGGCGGCTTTAGGGCGTTAGAGT +GGACGTGGCAAAAAGTTTTTTGGCAAATCGATAAAAATTTACAAATCTAAAAAATTATGAAAAAATATCA +AAACATTTTCAAAAATGTGGGCATGGCAGTTTTTGGCGGTTTTAGGACGTTAGAGTGGGCGTGGCCAAAC +ATTTTTCTTGCGAATTGATTTTCGCTAACTAAATCGGTTTTTGTAAGCGATTACTAAGCCTTAAGAAAAT +TGTTTTTAAAAGTACTTACATTTCAAATGATTTAGCAACTGGCAGGAAACAGTTCATCGGATAAATTTTT +TGTCATGTGATTATTTATTTTAGTTTCAAGGTGCTTCAATGGTACAAGTACCAACACGGACCTGTTAGAC +CTCTGAGGCGATTGCTAACCTCTTCGCCAATTTGAGACTCTCAAATCAAAGAAAAATTCACAATTGTAGA +CCATCCACTTCAGGGCCCCCCAAAACTGTACAATCTTATATGGTTGCGACACGTGTTAATGCTTAACACA +ATTTTAAAGATCTCTTTTTTAGAAGTTTTCGTTATGCTTTCTATGGGAAATACGTCATAGTCCCCCCCTT +AAGTGTTGAGAGAAATACGAAAGCAATTAAAGCTACACAGTTTGGAGTGAAGAACTTAAGGCAACCACCG +CATTATTGGTTGCGTTATCGATCATTGGTCTCTTTCTTCCCGGTCTGAAAAATTTTAAACGGCCGATGAA +GATGTTTGTATTATCATTAGCCATTGGTAAACGTTTGTCCAACGCTCAATTAAGGAAAAAACTCCACCGC +CGATGTTGCAGCATTCCATCTTGCAACTAAACCGCGGTAACTCTCCATCCAAGGAAGATTCGACTACAGC +GACATCATTGCAGTCCAAAATTCCCATGCAACAATGTTGCAGAAGAGCAAAAGCATATCGTGCCGGCATT +GGCAGCAAAGACAACAAACACAGCTACGGTAACAGCGACATCATCGCGGCATGAGTGTGCGTTTTTTGTA +CATGCCCTCGGGTTTTACAGGTTATTTAAAGGAGTATGCGCGTTTGGGTGGGCAAAAAACACGGGAATAG +TTTATTAAGGGAAACTCAAAAATAATATTATTTTCATAGATCCCATTTAAAAAACAAAAGCAAATTTAAA +ACTTTTAAATTCCAAAATGGCGTCCTTTGGTCGACCTGACTTTTTGGTCTTTTAAATGCTTTAAGCCATT +GATATCGTTAAAGGAATTCCAGCGTCTGGCGAACGCTTTCTTTGCGGGTCAACAAAAGATTAAGAAGGGG +AACAACCGAGATAAGGTGAGATAGTCGGCCACTATGCGAATTTGTAACTAGGAACATGAACCTGCACGGT +ATTGGGCAGCCGCCTAAATGTTGCCTTGCGGCAACAATGTTGCAACTTCAACAAAGACAACGATGGCGGC +ACGTTAATGAAGTGATTTGCACTTTTTACCAGCTACTTTCTGGCCACCAGCGGTCGAGCAATCCCCGTTT +CCAGGAACAATCCCATCGAGGCGGTGGGTGAAATTTATGACAGCGGCTGTGGATCATCGTGTCAGTTTTC +AGAGCTAAAAAAAAAACTTGAAAAATCAGATTCCAAATGCGGTTTGTTTTGTACGAAGGCTAAAAGACCT +GATCAAGGAATCAATTCCGACATGGCGAAATAGAGCACTCTTCTCGAAGTAGAGGAAAGCTGAATCGATT +ATTATGATCTAAAGATGGGTGACGCGGATTTTTTGGATAAAAACTTAAACCATATGCAAACCAATAATAT +TTAGTATACAATAATTTGTATTCGATCTAAAGGCTTTTTCCAATAAAAATGAAAGCTCACTGATGATCTA +TTTGTTCAGTCAATGCCGATCGTGATCGATGCCAGATATATTGCATTTTTGGCTTCCAGAAAGCCTCTCG +TTCTCTCTATTGTTCTCGAACACGATTCTCTCCAAACCAATTTCTTTTGGGATTCAGTTTTAGCTTCTCC +AGAAAAGCTTTAGCTTCTACCATTGCCAGACTGAGACAAACATGAAAACGGGAGCATATTTCACATTTCC +AATGCAGAAGTACCCCATCCTTGTGTTTTCTAGGTCCTAAGCTTATGCTGGATATGGCTGGCCGAGAGTT +AACCATTTTTTAACATGTCAACATCTCTATTAGAAAACAGCTGAGAATCAAAAAAGTAAGGAACGAAAAA +TTAGTCAGTTGCTTTAGGCAGCTGCGTATCCTTACAAATTACATTAACATTTACTGGGGCCTTCTAACAG +CGCCATCTGTTCTGTCTCAAGAGGAGTAGCAACTCACATTTATGGGCCACACCACTCCCCCTTCCTTTTG +CCGCGTTAAATATGCAAGGATTTTGTTTAGCATTTTTCGGAAAAACTGAAAACAACATTTACTCAATTTA +AAGTCGTGTCAAAGAAACTTCTTCACTAGTGGAGATTCAGAGGATCAAGAAACATTGAAGGCTCTTTAGA +ATTTCTTCTGAAAACCCCCTAATAGCCCCATCTCAATAACCTTCGCTCTTTGACAAGCAAAACGTTTGCG +CTTCATTTGACATTTTCCTATTCTTACATCGTGGCAACTTAAATGGGTTAAGGTTACTACCTGACAGTCA +ATACAGGACTAGCAGCTTTACATTCCCCACTCCATGCCCCATAGCCGAAACTTTTACCCACTGCATCCCC +GACCACGAAACTTTATTTCGCTCTTTCATCAAAGACGTCGCACTTTTTTTTTCCATCCTCTATACTTTCT +TTTACAGTACTGATATATTTCCTAGGTTTTGTATTTACTATACTATAATGTAAAGGTATAATATTTCTAA +TTTTTGAAAACCTTATTTATCTTGTTAATAACAATTCGCCGAAATGTTGTTTATTATTATATAGTTGGAT +TAAGAGCTATGACAAGTCTTTTTAATTCCTAATAGCTGCGACCCAGACTTCTTACTGGGCTATACTGCCT +ATAGTCGAAAAGCAATTCAGCATTAATCTGAAGGCGAAAAGGTAACCATTTGGGCGTGGCCCGCTTACAG +ACTCGAAAAAATAGAACAGTGTAATGTAAGAACAGTGAAACTACAGGCCCAGACGAGTTGGCCAGGAGTA +GGAAGAAGCCACCCACAGGAACTGGCGACCAAAGTACAGTCGGCAACAGTGGCGACAGCCATAAAGACGT +CTGCTGCAGGCCGGCAATTGGCGCGGGCGTTGAGCCTGGGATCGGAGTGGGGACTGCTGCACTGCCCACG +AAAAACGACATCTGCCCAAATAACCTGCCAGTTTCCACTGACGCCGCATCCGAAAGCTAACTACACTATC +GTTTGACTTCGTAAGTTTCGCATGAAAGCTGGAATTTTTGATGCGTTCTCTATCCTATAAAGTTCGCTTA +CCTACTTGAGAGATCCACCAGAAACATTATTCATACACATCTAACTACCAAACTATGCGAAGTGATATCT +CACACAAAACAAGTAACGAATGTAAAAAAAATATTTCTGATAATTAGACGAAGAACAAAAGAATACAAAA +TGCTATGAAAATAGTGAGTTGGAGAAATTGTATTACCTAAGCTTTATGTACTTATGTACATATTTTGAGC +CGAAATCATAAAGCTTATGTATATTAGTTATTATTAAAAATAAACATAAACTTACTAGTTTAATGCACAA +GTCGCTGTAATCTTAAAAAATAAAAATAACTACAAATAATAAAGGTGCCTCAGAAATCATAAAGAATTGG +ACATTAAGGCTGGTTAATCTGTAAATTTAAATAACATAATAACGTAACAACAAATCTGTGTTCCATTTTT +TCTGCAGCAATCCCGATTTGCTGCGTACTTTAGTTTACTACCTTTTTTTTGTTGGATGTGCCCTTGGCTT +GTCTGGAGTTTGCAATTTTGGGTTCGTTGATAAGTACGGGTACCAACGCAGGCGCGCAGGAGATCTGACT +GTGCGTTGGTGATGCTAGTGAATATGTGTGGATGAGAATCTGTGTGATTTTGAGCAGGGCATTGTACTCC +ATTCACGCAGTGAGACTTTCACATTACATTATTCGGACCCGAAATTTAAATTCCATTTGGCAATCCTCCC +CGCCGTGAAAGCTCTCTGGCTCTCTCTCTTTGTTTCAGCAACCCAGCATATTCTCTTTGTGTACAGAGAA +GGGGCTCGTACCCGGACATCCCTCACCATAATTACAAGATAAGTGTTTAATGTCAGCGGCGCTCAGACCC +CAAAAGGTGGTCCCATTACGGCTTCCCACAGCCAAATGCGACTACTGGCATTCATGAATGAATTCCGTTT +GTGGAGCTACTTGGGTACGACTCCTTGATGCCTGGTGAATATTTACGGAATCGATAAGTTCAAATTGATT +GGAAATTTCAAAAGCGTCCTGGAGGCCAAATTTCCTTTGGGACTAAAGGCTAACCAAATACATTGAAATC +AATAAAATAACTTATTGATCGACCACTTAGATATTATAGAAAGACTTCTTAAATGAGATCGTATAATACT +ACATATCCTACAAAACTGCACACTCCCATACACGTCCTTTGCTTGTCGGGTTACAATTTCCACCGCCCGT +CCGGGATTTTCAGCGTACGGCGCTCAGAAACAACAAGAACCAACAACAAACGCAGTCACAGTAGCAACAA +CGAAAGAGAGGCTGCGTTACAAGCCTACCGTAAACCAAACAAAGATGTTGGGGCGGCTGGTGCCTGTGAA +TTAAGTGTGGTTCGGTTCGAAGAGGCATAGAATAATGGTGGAGGCTGGTCCAGAGAAGTGGAAACAAAGT +GAATATCGATTTTTGGACGACAGATACAACACCACTATCGATTGATAACAAGAGGCAATACTATAGTCGA +GTTCCCAAACTATCAGATATCCGTTACTCAGATGGAAGTGTGAACAAGAAATTGTAATATTTTTTGGAAT +ATCGGTAGAAATTAAAAAACAAAATTAAAAAAAAGGATTGTTCATAAGTGGGGGCATGTCAGTTTTAGGT +GGTTTGTGTGCGTTAGAGTGGTCGTTACCAAAAACTTTTTTGACAAAACAATAGAAATTTACAAGACTAA +TAAAAACATGATCGACTCAACTATTGATCCTGATCAAGATTATATATACTTTATATGGTCCGAAACGCTT +CCTTCTACCTGTTACGTACTTTTCAGTATAGTATAGTATACTCTTTTATTATACGTGTAACGTCTGTAAA +AATTCCCATAATTGCTTGCTCTCTTCCGTTTTCATTCTCCGTATTTGTTTTGCTCCTCTTTCATTCTTGC +ACATGGCATGGGGCGGTAATGGGTGTAGGGTTTACAGTAATTCCCCATTGCTCTTTTAACTGTCAGAAAA +TTGTCTCCGGCGTTCAGAGAAACACGCAGAATGCAAATGATTTTTCCCGCTCAAACATCGAAAATCAGCT +TGCATTTGTCGGGTTTTCTTGTTCAGCATCTTTTTGATCTTTGATCTAGTACGACTTTAAGAAGGGGTCA +TTCTTGGGTGCCCACTTGAGGATCGTAATAATAAATTAGTTGGAATAATTATGCCAAATTATGTAAGCAA +AGGCCGAGGTTGACTAACTTGACGGACTAACTTGATAAAGGTACGAACATCTTGCTCAATCAACTGGTCC +GAATACAGCTGGTGGAAAACTGCGCAGTCGTTTTACATGCAACACCACAAGCACGAAAAAAAGAAGACTT +GCAGACAGCGAAACTTGACCCAATTCCAGTTCGTGAATCATGCCTCAAAATCTCCGTTTTTGAGTGTCTC +ACTTCTCGGATTGTGTATGTTTGCTTTCCATTCTGGTAAAAAATGTCGTTTATAACGCGCCTTTTGTGTT +TGGCTTGTGGCTACCTCCATACTGCTATTCGCTCCACTCAACACTGCTTCCGTTTCCGCACTTGAATGGC +GTGCGCCACAATGGCAGCTCCCTTGGACTTTCACCATACCATACCATCTGTCCACTTTGACATAAACGGG +AAACGGAAACGTAAATTTTGCGCCCATGCGTAAAAATAGGCTGTAAAACATAGGGAGTGCGCTTGCGAAT +GTTCCAGGATGCGGTCCTGTGGCCCTTTGTGTCTACATAAGGATGTGTGACAATAGCACCGACTTAACAT +CCCCCGTTGACCAAAACTCGGGCCTACTATTTTTAAAACGCTACAAAGTTTTGTTTCAATGGACTTTTTT +TCGTTTTGTTGCGTGTGGAGATGGACTAACCGCGAAGGTGGAGATGTTCGTCATGTCACCCACGCCAATC +CAAAAGTAAAATTTAAACCTAAGATGTGGACTCCGGAAACTATTATTGTGCCTTGAAACATCTTGTAATA +ATAAAATCAAATTAGCTATGGATGGAGCTCAGAATGTAACAATATTCGTTAATTTTATAAGTTTAAAAAT +GGAATAAATGGAATTCAATATTTTTTTTGTAAGTGTAGTACTTCAATGTAATTCAGGAAATTATCGATAC +TTTATCATTGGTAATCTCTCGCCCCCACCCTTTTGTTTTTAGCAGAATGATATAATAATGATGAATGATA +TATATAAAACTAACCCATATCAAAAGTTTTAATAATATGTAAATTATTCTTTCCCCGATTTTGATAAACG +TCTAAACGTGATAAACTTTTGTTTCAGTTTTTTTTAGTTCTCACTATTTTTTCAATGAGTTTGATTGGCT +TCTTTCTGGCATGTCCTCCCTTTTTCATGTTTGCTTTTTTTTTTTGCCCTGGGGCTTTCGTGGTTGTGTC +CATATATTATTCATAGTTGACAAGAAATGTGTAACAAATCGTTATTGAGTTATCCATGTGAAATAAGAAG +TTAACGGATGTAAAAAGAAAAGGGAAAGCATAGCAGGTCCTAATAGTTTCAGAACACGTCGCCTGCTTCA +AACCAAAAATTAATAAATATTCTCAACATTTCCGAAGTTTTCCTGGGGTGTGGGCTGATATCAGATCTAC +TAAAGTTGAAGCGTTTTTGGGGTAGCCCTTAGAAAAATGTGAGACGTTAAATAGTGTATGAAAATTTATC +TCAGATGAAGGTTGTATTAACTACGACGCCTATCAATAAATCATTTGTTTGGAAATTTTCAATATTAAAA +ACTAATTTTAATACTCTAATGTGTAGGCGGGATAGATTTGGGTGGTTTTTAGAGGTCAGAGTGGGCGTGG +ACAAAATGTTTTCAGCGTATCGATTAACGGGTATAACATTTCCTAAACAAGCGTACATTTATATGTAGGT +ATGTTTTCCCAGATGGAGCCCCAAAATTTTTGTGATGCTATTTTTTTTTTAAGAAAAGACAGAAAATAAC +ATCTAACAACATCTCTAATGGCACTTTTACCCTCAGTCTGTACCATAAAGTTGCAACTCTGCATTTGTTT +AGCACTTTTAAATTGCGCGCGCAAATTCAGATTAAAGGCACAGGGTTTCAGTTTTAAGCGTCACTTGCGA +GACAGATTTCGTTGGGCAAAATTTTTTTAAAAAAATTAAAAAAAAAATCAACGAATTATTATACTTAAAG +TATTCAACTAAATTAAATTTGATCGTATTTTATTTATCAATTAGTCTTCCTACATACTCCAACGAGAATT +TACCACAAAACATAAGTCAATTTTTTCCAGTGGAATGCGAGTCATTTGTCGTCTAAATTTTCGCATTGGC +AAAATTACTTTTATGCAAATGCATAGCACATAAATGCTTCACAGCATTGTTGTTACGACAAGTTTGCAGA +TGAGTCGCTAACTTGGGCGAGGGTGTCGAAGGGGCGATTAGCCACTTTCGCTTGAGGCGTAAAAAAACGT +TCGGTTCGATGTATTCGAGTGTCTTGGGCTCCAACGGCATCGAGAAAAAATCCTTGACCAGTTGGTTGGC +AGATATATAGTGTGCGGAGTTATATGTAGATGCTCGTAGGTGGGCCACAAACAGGAAATGTCTGAGATTG +TGTGGGAATGGCACCAAATGGAGGGGAAGGCAGTTACTAAGAGCCTGGGATATTCCATAATTAAAATGTG +GCACACCTATTGAGATTCCATTTGCCAACAGATTCTACAGATGTAGACAAGGAGCCAATTAGTTCAGAAC +GGTACCCACTCTAAAGTCCACAAATATCTACTCATGTCCTGCTAATTTCTCTTAAATTGCCGAAAATTTT +TTTTCATATATTTATAGCACTCCCACTATTTAAGAAGCGGGTATCTGATAGTCGAGAATTATTAAAATGT +GGCACACCTATTGTGATTCAATTTGCTAACAGATTCTACAGATGTAGACAAGGAGCCAATTAGTTCAGAA +CGGTACCCACTCTAAAGTCCACAAATATCTACTAATGTCCTGCTAATTTCTCTTAAATTGCCGAAAATTT +GTTTTAATATATTTATAGCACTCCCACTATTTGAGAAGCGGGTATCTGATAGTCGAGAACATGAATCTAT +ATAGCCACTATAGCCACAAATCTTTCGTTGGTTAATAATTGAGTTCATAATACACCATAGCTGATTTCAC +ACCGCACCCATCTACAGATCTCCCAAGATATCAACTTTCCGTACCTTGTGTCATGATCATCATTAATCAC +GGCCGCTCCATTTGATTATTCTCCTGGTATATTTCGGGTCGGACCGAGTAAGACATCTAGTCAGCCCAAA +GTCCCATAACTCATTCATAGCACGATGACATTCCGTACTCATATTCATTCTTGCGCTTGGCTCGAAGGCC +CGGGACTAAACGATCGTTTGGAGTGGAAAAAAGTGTCAAAAGTCAATGTACTTCTAGAAATCTTACTATC +GAATAAGGTAAAAATAACAAATTTATTAAAAACAAATTACTGAGTAAGTTGAATTTATTTGTGTGAAATA +AAATAAAATATAAAATAAAAATAAAAAATATCGAATAAGGTAAAAATAACAAATTTATTAAAAACAAATT +ACTGAGTAAGTTGAATTTATTTGTGTGAAATAAAATAAAATATAAAATAAAAATAAAAAAGTGTACCTCT +AAAGAAAGCGTTATTTATTATTTTGCCTTTAGAATCATAACAATTTCAATTTTTCAAATGTCTTATTAGT +TTAATTCAGCTATTTCTAGCGATGCATGAAGTCAGTTTTGGTCGAGTGCCGTTTGACGTGGTATTGAGCT +GTGTGTGCCAGTGTTATCGCTCTGTTTACACGCATCCAAAAAAGTAATGAACTATAGTAAACCCAAACAA +AAGCCGGGCAATGCAATGCGTGTGATTCAAAAACAGGGAAGCAAACCGAATTAAAAAACAACGCAATGTA +TGTCACGTACACGTTTAATGGCGAAATAAGTAACCGCAGTCTATAGAAGTCCAACTCCAACTCCGAAAAA +CCACTGCTTAAGAACGTCCGCTTTCTGAACTTCTTCTCACGAAAGCAGTTGGTCAAACCGATCACGTCTC +TTTATCTTTTACTATACCCGTTACTCATAGAGTAAAAGGGTATATTAGAATTGCTGAAAAGTATGTAACA +GGTAGAAGAAAGCGTTTTCGACTGTATAAAATATACATATCAATAGCCGAGTCGATCCGAGAACTCAGGA +ACTATAAAAGCTAGAAGGGTGAGATTCAGCATACAGATTCTAGAGACAAAGACGCAGCGCAAGTTTGTTG +ATCCGTGTTGCCACGCCGACTGTAACGACGACAAACCGCACAAAACTGCCACACCCACAGTTTTTAACCA +TTTTTCGACATTTGTTCATTATTTTCCTAGTCTCGTAAATTTCTATATGTTTGCAAGAAACTGCCACGCC +CATAATTTTTACATTTTTCTAATATTATTCGCCATAATCTATCGATATCCAAGAAAAAATATAAAATTTC +GTGATCGCATTCACACTAGCTGAGTAACGGGTATCTGATAGTCGGGGAACTCGAATATAGCATTCTCTCT +CTCTCATATCAATAGCCGAGTCGATCCGAGAACTCAGGAACTATAAAAGCTAGAAGGGTGAGATTCAGCA +TACAGATTCTAGAGACAAAGACGCAGCGCAAGTTTGTTGATCCGTGTTGCCACGCCGACTGTAACGACGA +CAAACCGCACAAAACTGCCACACCCACAGTTTTTAACCATTTTTCGACATTTGTTCATTATTTTCCTAGT +CTCGTAAATTTCTATATGTTTGCAAGAAACTGCCACGCCCATAATTTTTACATTTTTCTAATATTATTCG +CCATAATCTATCGATATCCAAGAAAAAATATAAAATTTCGTGATCGCATTCACACTAGCTGAGTAACGGG +TATCTGATAGTCGGGGAACTCGAATATAGCATTCTCTCTTGTTTTGATTAAAGTCGACCGGGGTCACGCG +ACGTCAGTTTTTATTAAGAGTTCTTTAAATATATTTAACACTACATTTGAAAGAGTGCTTCACATTTCAT +TTTAAAATTTTCAGTATTCCCAGTATATAATCACATATATATTCCATGTTATTATTACTTTAATTTATTA +AATGGATGTTGTTAAAATATCAAGATTATCTTCGACGAAATATGAAATAAGAATAATATCCCATGAAATT +TAGGAGTTAAGTTTTATTTTACACTTGAAAACGGTGCCTGAACCAATAGCCCCATGGTCATATTACATAT +ATACATACATATGTATGTATATAACAAACAAAACGGCCCCATCTTAAATCTCCAGATAGAAATGGATTTC +TAAGCAACACAAATTGTAAACAATTGTAATATCTGGTCAAATAAAAACAAGCAAAATAAGATACGGTTCC +TAACATAATAAATACAGTGGGTCAAAGAAAACCAGGTTTTTTAAAACTTCTAATAGTGTATCAATATCAA +TGTCCATTTTTCATCATCATATAAGAATTTTGTAATTGATATTTGTGTTTATGTTAAAATGTTAACCTTA +GAAATATTTGTATTTGCATTTTTCTACAATTTTATTTTACCACTTTCAAATACACGAAATACTACTAATA +AAACATGTATACAATTATTTATACATTTGTGAATACACTCGCGCTCGCATTAAAAATCAATTAATTAAGC +AACAACAAAAAGACAGCAAAACAACAAGACCGGCGTCATCAGTTTTGGAATCGGTTTCTTTACTCCCTTT +TTTGTTTTTATTTTGCCTTGTCTTGTGTCCCGCTCGCACATATTGTACCATATCGCATAGAACGAAGATT +TGTTGTTGTAAGTGAAATTGGCACGCGGCGCAGTCCGCGTCGCCGCTCCATTCAAATGTTGTGAAATTCC +AATTCCTCCCTCTCCCGTTTTGAAACTTTTTTCGCCCACAACAGCACACACACTTGCATAGCTTATAATT +GTTTGTTATTTTTTTGTCTCGCTTGCACACTGGTTATCGGATTTCAGCAGAAATATAATAAGGAAGGGGG +TACTCAAAATACTACTACCAATATTTCGCTCTCGCTCACAAACCACCACACCATTCCATTCATAGGAGCG +AAAAAATTATTTACGATTTATTTTGATTTTTACAGGACGGAAAGAATGAGAGAGTCGATGTAGAGAGAGA +GAGGGGTTTTGGTGTCATCGGGGACTGGGGTTGGGTACGAAACGAAATGGAAACATAGCCAAACACAATG +GTATAATTTGGTGCGCGCGGGCGCACAAATGTATTGTGGAACCAGAGTTCATCCACTCGTTGGTGTCATT +TCCACATCGTTCCTGAGTGTATATACTCTTTAGTTTTATTTCCACCATTCCTATGGACATCTACCAGCTC +TCTTTGTTCACCACGCTTGTTTTTATGTATTCTCTCTGTTTTTGCTTCTGCGCCGCTCCCCACTATTTTC +GTAACAAACTGTTTCATATTTTTGTAGACTGTACATATTTCGTTTTTTCATTACATATTTTTGTAGTAAT +AATATCTAAAAAAATAAATTAAATTTTTTTCCTATAGCTTGCATTCAGCGAACACTTCAATGACTCGAAA +AAAAATGTTTCCTCTATAAAACTACTGCAGTGTCTCCCAATTTAATTAATCTTCTTTTTTTGAAAGAAGT +GTTTTCGTTTCTTAATAAGTTTTTCGTTTGTTTTGTTTGATTTTTTATTATAATTGCCAAACGAGGCAAT +AAAGAAAATGGATAACTGAAGTGGCGGTGGGGTTCTGAGCGAGTATTGGATATTCGACAACCTGGGCGCT +ATCTACATAAATTTATTCGCATGTCACAAAAATGCGACATCCTCTCTGGAAAAGTTCAAGAATTTCTATA +ATTACGAAATTTTCCAGAATATGTACATATGTATATAAATTCGCATTACACAAGCCAATATATGTACATA +TTTTATACCTAGAATTAAACAATGATGATTTTTATGTAATGTACATACATATGTATATCCCATTTATTGT +ATATTGATTATAAATACAATATTTATTGAAGAAAAATAAATAATAAAACGAAAGAAAACATAGGTTAGCT +AATCGGATTAGACAAAATAAACTTCAAGACTCCCACATAACTTACGTGAAAAAAGTGAGTCGTAAAATAT +AAAGTGGCGGCATAAAAGGTTAACCCAGTCGGACTCAACTTTTATTTTATTATAAACAAAATCATTTGGA +GTATTTACCAGAGACAAACAACGAATCAATCAACCCTTGGAGGACTGTGCTTGTAATGTCTAACCCAAAT +ATGCGTGCCAGTGCGTGTTGAATCGAGTAGATCTCCGCTTGTATTTGTGTGCGTTCATGAGGGGGAAATG +TGGAGCGCGGTTTCTATGGCTTTACGTTTTCGAAACTGGGTCAAACAATTGGGTCAAGCAATGAAAATTG +TCTGGGCTTCCTAGCGGGTTTTCATTTTCCGGTCAGCACATCCTTTTCATGCAATCAGCATACATCACAG +TGTGAAAGTCAAGGGAAACCCAAGAAGATCAAAATGCCAGTTCAAATAAAAATCCGCATCCACATCAACA +GCAGATTCCGCATCATGGCGGGTTCGCGTGAGCGGTTCAAAGTCCACAATTTCAGCTCAGAGCACTCGGT +TGTAACGGACTGACTACAGTCGATCTCTCTCTTTAGCTGTTGCTTATTTTGTATTTTGTGTAAGATATCA +CAAGAGATTTGGAGAAGTCTGTATCATCTAAGCGGCAAAATGTAAGTTTTAAGATAAAAACTACAGAAAC +AATACTTGGGGCAGGGCTATAAATTATGTTCAATAATATTCATCAGGGTAAGGGTGTTTGACAAGTAGTC +TCCGGAAGTTTGACGGCCTTTAATTGGTATTTATCTTTAAGCTACAGTCTCAAAAAGTTGGCTTGGAGAT +TAGTTTATTTTTGCTCTGCGCTATGCCTTTTGTTATTGGTTTATTTTTGCACATTGCATAACTGTTCATT +AGCAAAGGCCTTAAGCAACAATAGCAGAAAAAAACAACAGCAAAAAATTAAACGAAAACAACAAAAATGT +GCCAAAGTACGTCACACAAAGCTTCAAACGCTTGAAAACGCTTTCGATCGACACACTCTCAAAATATTAT +TCATAGTTTTACTTTCAAGACCTGAAAATACTATGAAATTTTAAATCATTTGGGGACAACAATATATAAA +CTCAAAAAAACATTGAACAATTTGCATGCTAATGATTAACTGGAAATACTTGGGAACCCAATTTTATTAA +AGAGCGGGTAGTAAGTATACATGTACATATAGATGTTTGGGTTGTCTTTTACATTCTACTCAGCTTTAAT +TATCACAAAATGATCTTTACATGAACTCATCAGCACAAGAGATATTTCAAAGACTGTCGGTTTCGGTTAC +ATCTATTAATGCTTCCGGATTTTTATGTTGCTAAGGAGCAGGAGAAAAATAGTACTTTGTATATAAGCTG +TGCCAAAAGTGCTCGGTTTCCTTACCCTATCTCATACTTCAACTTAGATGACTGAACTTTTTCTCTTTTT +GCAGAACACAAAAAGCCATTTTATGAATTTAAAAATAAATGAATATGATAAAAATGAATGAACTGAATGA +ATGATAAGGTGACAGTAAAAGCACAATAAAAAGTGCCCCTAAAAACTTTTATACAATGTTATTTTTAATA +ATTTAGTTTTCCAATTTTCGTGCAGTGCCTTAAACTGACAGCTCTCTACTTGACACTTTTGTCACGTCTG +TCACTTGGCTGAGTCTAAGCCAAACGATGACAAATTACTTAGAAAGTGCAACAAAGTTGTAATAATGGGG +AGGGGGTAAAATGACAAGCTAAAAGGGGTAGTGTTGGGCGGGGTGCGGTTTAAGGTGGTCCAAAAATTCA +ATTTCCGCAAAAATGTGGTCCTTGAAACTGTTGCACAAAATCATAAGTAACATCCCCTCCCCGAACATAC +CCACCAAACCTCTTAGGCCCCTTGCTAGTCGGGGGTGGCAGTGGACAGTCGACAGCCGCGTTTACCCATC +CCGGTTTTCTTATATTTTGCCCATAATTGAATTTCGTAGCAGTGCAAACTAGGTTTGGCTTTGTGCATTC +GGGTGCGGCCATATCAGATGCCAGTTGCTAAGCTAGTGGAAGAGCAAACGAGAAATTTCATAATTTCCCT +GGCGTTGGAGAATAAAATGAGGAAAATTAAAAAATGGTTGTTGTGGTGGCCATAGTGTTTTTTGGTACAA +AAACAAATCAAAGAAATGTCAAAACATTTTTTAAAAGTGTGGGCGCGGACGTTTAAGGCGGTTTGTGGAA +GTTTTTTGGCATATCGATAGAAATTTACAAGACTAATACAAAAATCAAAAATTAGCAAAAACTTTTCCTT +TTTGGGCTCCTTGAAAATACTCTGCAGATCCTTCTGGATTGATTCATTCTTATTATTTTTAGATGTAATA +TTTACCATTTAATAAATTGTTGCGTGTATTATTTAAATTCTTACCTAGATCAATATCTGAATATTTGACA +ATTATTTACATCATATACATATGCAAACATATATTTATAAAACATAACATAAATTTATTCACCCTCCATA +TCTGCATGGAAACAATGAAGTGAGGCATAACCCCATACTACCAGATAGCAAATTAACAGTATACTAGATC +GTATTCCGGATGTTTTGTCGCAAAAATGTGCAGCGATGTAGCCAGCTCTTAAGCACTCGAGATGCCTTGG +ATACTTCAGTAGTGTACACGCGCCGACATTTGGTCTAGACCCCTCCGCATACACACTACCCCTGCTGCCA +CTAGGACTGCGGTTTTAAGTACCTGAAGCCCCCCGATTGCACCCTGCTACACCTTCCTTACCTGATTACA +CACGCGCCTCTTTCTGCATTTACGACCAAAAAAAAAATAATAAAAAGTAGGGAAATGGGAATTACGATAA +TGGTCTATGGCAAAAATAACGAACGGCATATGTACACTACAAGAAACGAACGTTTTTGGTAAGTTACAAA +TATGTTTCTGAGTTCATATCTTCAGAGTAAGCTAGAAATAAGTTTAGCCAATTCAAAGGGCTATTAAGTG +GAGGTACACTACTGCTAGTATGTTTAAATTGCTCAACCCCCATTTTATGTCATTTCTTGCATTGTATTCT +ATCTAGATAGATAGAAGGAATTGGTAGCCATTTGTGTGTAACGGTTCCTATTGTTCTTGTAGTTTTTACG +ATTTCCTTGTAGGTAAATGTCAAGTACAAATCAATACTCGAGTGATGAGTGAGTAAATAATAGGTCTGCA +CGTGTGAGTTTTTTACTTTGTATTAAAATGGCCTTGGCAACGTTTGTTCACCTTATTCTGATGAAGTTAC +ATCAGCAACAAATACACTAGCCACTTGACAAAATCGCATTCTTCTGTTAAATACCGCTTGGGCTTGATAC +CGTTAACAAACAGTGCGAAAAAGATGACCAATGCCAATAATGAATATTTACAAGCTCATTTAGTAAGTGG +TATTCTGCTATTGAGCAAGTGTAAATCAATTGTTTAAATTGAATTTTTTTGGGGTCAATTGTAAAAAGGC +TCAGTTAAGTTTGTTTATTAGATCATCGTAGTAGCCCAGTTTAACGTTGGAATTAAAGTAAAAAACATTG +CGAAAGAATTTATTTTGTCGCGTAAATGGTATGTATTATCAAATTAAAATAAATAAAAACCAATTACAAA +GAAAATACAAAATCAAACGGTTATTCTTTCTATCTTTGTTACACTATTTTACCATTTTGAATCTTTTGAT +ATGATCATATTTATTATCAATTAATGACAACATTTCAAACACATGCTTCCGAAAATTTTTCTTTTCGTCT +CAATCAATAATTCCCATGAAGCGGTACCCCTTCATGAACAGGCCCAAGGCCAAAATATTAAGTTCCATCG +TCTTCCACACATCTACAATCAAGATGGCCACAACCAAAGTCAATATCCTTTCTAGTGTATTTGCCCGGAC +GTTATGAGACATTTATTATATGTAGATAGAAAATTGTATTTTATGTTTGCAAAGCTTCCAGTCTTAACAA +AAACGACATAGGAGAAAATGCGTTTCAAGCAAGAAACGAACTTCATTATACCCGTTATTAGTAGAGTAAA +AAGAATGTAACAGGCAAAAGGAAGCGTTTCCGACTATATAAAGTATATCAGTATCAATAGCCGAGTCGAT +CTAGCCATGTCCGTATGAACGTCGAGATCTCAGGAATTATAAAAGATAGGTTGAGATTCAGCATATATTC +TAGAGACAAATACGCAGGGCAAGTTTATTGATCCATGTTACCACGCCCACTCCAACGCCCGCAAACCGCA +AAAACTTAAATTAAAATGTTTTCTCATTTGATACCCCAAAATCTATCGATATCCCAGAAAAATGATGAAA +TTTCGCGTTCGGACTCGGACTAGCTGATTAACGGGTATTTGATAGTTGGGGAACCCGACTATAGCATTCC +CTCTTGCTTTTTTTTGTTGGCCATTTCTACGCCTCACGCATTGCGAAACTTTTTGCCGATATGAATGAAA +AGCTACAACAAGGTAATGATGAAATATCTGTCTTTGCACTTCGCATTTTTATATCTAGATTTTTGAGTTT +TAGATCTACCGTTTTATCAATGTTCTGTTGGTACTATCAATGTTTTCGTTTTATAGCGGTATGAACGTGC +CAAAAATCGAAAGTTTCGATCGCAAAATGCGGTAATGCTGAAGCCAAAAGGTGTCACATTATATGTAGGT +GGCAAACGGACACGGGTCGTATGCGTAATGTTCTTGGCATTAGGTCATAAATGGCCATAAATAGCAATGC +CGTCGAGGAGCTTATGAAATTCTAAAAAAAAAGACGAGCAAGCGCGTTTATTTCGGCGTATGGGTCACTC +TTATAAGAATTTCATAAACCCTCGATTGTGCACGCGATTGGAGAATCAGGTTAGCATGATCAATAATTCT +ATGATTATAAGTTGAATATGCAGGTTAAATATTTAAAACTAGTAAACTCAAACAACGGAGAACCTGCAAC +AGTCGATTTCCTTGACTTTCAGAGAATTTCGTTTCTATTTCACAAATATCAACTCTATTTGCAGCAGTTT +GCTGTTCGTTCACAACAGGTAAAAAAAATAACTCAATAGAGATATCTTCGATTATCGGTATAAATACATA +TTAACCCCTTAGGCTGTTGGAATATTACGCTCGTAGCTTGGCAGATGTTGTTTCCCTACCGACTTTGGGG +GTATTCCCCCATTCAAAAGCAAAATCGCAGATGCGAAAAACGAAAGTTAACGAAACTATAAGCTAACGGA +AATTGCTGTTCGTTGATTACGAATTGTAATTAACACTCTGTCGCCGATCGGGCTTCAGGCGAAATCTATG +GAACTGAACTCTTAGAGCACACGAAAAAACGCGTGCCGATTCACAAACATTTTGTATCACAATTCACACA +CGGCCTCTAATCATTTTATTTGGCCAATAGTTTCCTACACACGTAATTAACGTGAAGGACAGAATATAAA +AAAACACAAAATTAATAACCAGCTCACAACTGTCAAATATTGCTAATGTTAAAAAACCCTTCTTTATTAT +TTGGATCATTACTTTTTCCTGGCACCACAACTTAAATAGGTTACAGCAATGCCGAAATAAAGAATATAAC +TCGAGTTCTATTCGGAAAAAAAATTGTCAATGTGTTTTATTTTCCAAACTATTAACCCCTAAAGACCATT +CTACAGATCGTCGGCGTTAGCTTTGCGTTTTATGGTCTTTTTTCTTATTTCAGGTGTGAAAAGTTGGAAG +ATAGTTACAAAAATCAAAAAACAAAGTTTCTCATGTAAAATAAGAATATAATTTTTTTATTTTTTATTTT +CATTTATCTTAGTCTGTTTTTTCGCAGATTCACACGGAGAACTTTTGCCAAGTGATTTTTGTGGCGAATG +TCGGGGAATCTGTTTTCGCTGTTCGTGCAATAAATAAGCAAATTTGCATTCAGCTCAAATACAAAAACAA +ATGCATAAATAAATTAAAGTAATTCGAAAAATTTCGCACACGACCTCAATGAGTCATCAGCGATGGAAGG +GGACATCAACATTTTCCCTTCTTTTCTGCGCAAGCTGAATTTAAAAACACAGTCCCAAAATGTGTAGGAA +AAAAAAACAAAAATAAAACATTGATTTATTTCGTAAACAAAAATTTTAACTGAAAAAACGTAAAAAAAAA +CCACAACAAAATTGTTGTCATGCCCGTTACCGAATCGGTAATCGCTTTTTTGATAGCTTCTACATTTTCC +TATAGTACTTAATGTGTGTTCTGTCTATATGGCTATCCCATGCGATCTTCACCTGCCTTCGATTTTCGCA +CGTCCTGTATTTATGCCCGCTGTTAGCGATGCTAACGATGACCTCAGAAAATCCATGTTTGCCCTCCATC +TTCCATCATCACACATAAATGCAGACCAGACAAAATGCACTTATCCTGCCTGGTGGGAGAGGCCTCAAAT +GAAGTAATAAGCAGACTCGAGGGGCATAATCGGCTACCACTGTGACTGACCAACACGCGGCAGGTGCTTG +ATATTTTCGTGTTGCGAAGTTTCTCGAGGACTAACTGAAATGACTGCAGGACTCCCTGCAAACGAGGCCA +TGCCATTTGGCCGCTTTCTTAGAGGAACAGGCTGCAGCTGCCATCTGATCCCTTCGTCAATACCGAACGC +AGCAACACGTGGCAGGGCAGGTGCGAGCAGCAGGCATTAAACGGCTGGTTTGCATTGTAACTGTGTCAGC +TGCCGTTGTCGTTGTACTTGTTATACTTGTGTTTGTTGTATTTATTGATCAATAATTTAACCAGAGCTTA +TTGTTTTGCGATATTGTTAAGTTACAAAATATATGATGTTGAATAATATCCTTATTGTTTTTTAAAAATG +ATAAAATAACAACTAACCAAACGAAAACGATAAGGTATCTTGTGTTCGAAATATACTTGTACACCGCTTG +TTTTGTTTTTATTTTTGTTTACCTTTGTGGCTGTGACAACTTATTAAGGATCCCAACGGTTAGTAACTTA +CGTTGATCCGTCGGAAGGTGAGGTTAAATAATTAGGATTTAAAGTATTTATTTGAAGGCAAACAAAGCAC +GAGCCGGGAATAAGCCATCAGAGTGGGTGGCAATAAGATGGCTTTTAAGCTTGAGTAGTTCCTGAGATCT +TGATACAGACGGAAATGGCCAGATCGAATCGGCCATTGGTCCTGATCAAAAATATATGTATACACTTTAC +CCTTTTACACCACTAAAGGTTTGAAGTTTACCAGATAGTCGAAAGTGAGAAAGCAGTCATGTTTGGTTAA +TGGCATTGAACTGTACATAATAATATCAGCGAAGTAAAAAAATTTTTTTCCCCGGATTATAATATCCTCG +CAATATGTAGTGGTTTGTCGTTTTAAAAAATACCCCTGAGTATCGAAAACATTTATTTTTGCCGTTGTGC +ATTCTAAGCATTTGTTAATTGTGTCAGCGACATTTTGATTGTACAACCAACGGAAACGAAACGGGACAGT +GATTGTCGCCCTAGCTTTCCCTCCCACCACGACATCCACAAGTCACCTGGCAATCAGGAATGTCAGCAAG +CGACTTTGTAGCCACAGTGTAGTAAAAACTCCGTTGGATTTGACTTGATTTTATTTTACCTGACAGCTGA +GCTGTCTTCCTCAGTGTCCGTTGCCTGATGTCTGGTGAAACCTCTTTAAAACCCCTATCTTCAGTTTCTT +GGGCCATCAGGTAATACATAATTTTGCTGATGCGGAACAGCGTCGTGTTCGCATTACATCCAAAGTTGCC +CCATGGATCATCATCGACTTTATGCTAACACAACCACTATCGCACACACGCCAACTATACTTTGACAAAT +TGCAACGTTTCAATGAATTCGAATCGTTTGGCATTGACACAAATAGCTTTCAAATTGCACAGACAAACAA +GCACACACACATGTTGAATGGGTTAAATGCTGCGGTGGGACAACGGGGCCTCATTGCATTGGGGCGTGTA +ATTATTGTTGCTGTAACAAAACAACATTCGCAGCAGATACTCCAAAATCAACAAATTGGAATCTTTAAAT +GGAATAGTACTAAGTGGGACCAAATCCAAAGTTAAAGAATTTTACGCATTTAAATATTTCTATCGATATT +AAAAATACGAAAAAATGTGTATACAACTAATAAAGCGAGCTTCGAAACAAGCCTACCAAAAAAATTGAGC +TTTAATATTTAATATTTAAAAAAAAATGGGGTGTCAGCAAAAGACTATAAGCCATACTGGTTTTCTCACA +AGGCGAAAATCTCATTGTACGTATGTACCTTAATATGAGTGCTGGTGCAAATTTTGCCATTAACAATAAC +AACCACATAACAGACACCATAGTGACCATATAACAGCAACAAGATCGGCAACAGCAATTGTCAGCAGTTG +CAACCTTCTCATCCCTTCTGCCCCTCTCACCACTTTGCCACCGACGCACTGTAGCCCCGTCCCGAATGCC +AGGAAAGACCCAAGGATAAACGTCTCGCTCGTGCACGCCTCATAGTGACCTAGTTTCCAAAGCGGAATGT +AAACACATTTGACCTGGAAAAAAGAGTTTTTGTTTTGTAAACAAACCCCGACTGCGCCAGAGACTGAGGA +GGCTCAAGGTGTGTGCATGTATGTATATATGTGTATAAACTGTGTTTTAGGCCTTATCGGCAACAAACGT +AAAATGCGTAAAAATGCGCCAGCAATATAATTTAGTTGGTGATGTTGTGACTTTAAAGTGTATGTTAAAT +AGTTATGTTCTTTTATGGAAGACCGAGAATAAGATTCGAGAAATGCTGATAAACACACTCAAGGGTGTTC +GAAAAAGGGACTTAGGGAGATTTAGGTTTAGACTTAGGTGCTCTAGGCTTTAGACTTAGGTGCTTTGAAA +TTTATGGGAAGATATGGAAAATGGCCTTAACTGAAGTATATCGAAATAATTAAAAAATAAACTGTAAAAT +CGCAAAAGAAAATTCTAATAAATTTCTGGGCATTTTCTTAACTTTCCGTTCTCTTATTATTAGTTTGTAA +AATGAGTTTGTTTTTTGTTGTTCTGTCTGTGTAGTTTGGGGGTTAGTTTTGCGTTTAATCTTGGGGTGCT +TTGGCGTTTTTAAATGTCGTTTTCACACGACTTTTCATCTTAGTTTTTTTCTGCAAATTTGTTATTTAGC +TTGTAGTTTCATCTTTTGCCAGTGCAATCGCAAAATTATTGTAATAGTATCATCTTTGCCATTCTTACCA +TTATATAAAGATAACCAAATTCTTAGTGGTAAGACTTGCGTTGTTAATTAAATTTTAATTGCATTGGTTC +CAACTTTTAATTAGCAACGGCAATCCCAAAAAAATGTGAAAAATATGAAAATGAAGACAAAAAATATCAG +GGGATGGGGAGGGGGAAATTCGCAGGAAAACAGCCAAACACAGAAAAAGAAAATGTGTGGCCAAAGCAGA +GGCTTGTTGTCAGCACAACCAAACAAAAGACAACAAAGGGGAACTACAAAAACAGCGCAACAGAAAACTG +AAAACCACACACAAATGGCAAGTGCAACAAAGCCAAACAAAATTTGCCATTCCCTTTTTTGCACATTTGC +CAGCACTTCACTTAGCAACATTGTTGCAGTCACAGACGAGTCGAATGAGGTTTAAGGGGCTGCCGACAGC +CAGCTCAATGGAAATGTATGCATTTGCAAAATAAAAAAGGTAGGCTTAAGACGGCAAAAAATGCAGATCG +ACTGCAAAAATTGTGCGCCTGTGCCACAGGCAGAATGTAAAAGATGATCGCGATTGCAGGCAAAGAAATC +CAAACAGATGAGGGTTTTGCGGGGGTAGAATATGGGTTCACAGAGGCCGAGCCGAAAGGACTGGGGGATG +TCGGTGCAAGCCAGTTGTCACAATGAGACCGTGGGCGTGTAAAATATATGACGTACTTTTGCATACCATA +TCCCTTGAGAAAGTAACACTATTTTAAAATGACTTAACGTTAAAGCTATCAAAACTGAAATAGGAATTAC +TTGTTTTGCTATTAGAGACAATTTCCACATTACTACACATTTTACGGTTAGGGTACTATGCAAAGAGTAT +CGAAATGTTAGCTAAACAATGACAATGATTTTATTGCCCAATGGTTATCTATGATTTTAAATGGGCTTGA +AAAAAAGCAGATATCAAAGTTTTATTTCACTCGCACTGTAGCCATCTCCTTTAACGTGCTAATGAGTTCA +ATGATTTGCAATTGTTGTCTAGCCTGAGGTCTGCAAACTGAGTCCAATTCGTTGAGGAACAGAAAACGGA +GGCTAGCATGATGGGACCATAATCATCATTAATACGTCGGCGTCGTTGGTCGCACTAAACTAAGTTTTTA +TCAGTCTGCCAAGGCAGCGGAAAGCTCGGGGTTAAGTTTGGCGGCAAAAAAGGGGGAGGGAGAGTTAAGC +AAAATTAAAATAAATAAAAACTTCAAGTTTAAGCGCTTAAGTTGTTTGTTTATCTCCACCTCTTGGGCAT +AATTCAACTGCAACATTGTTGCGCCTAATGCAGACAGACATAATGAAGGAGCTAGTCACAGACGGATTCA +AAAATGCGTTGAGATGGCGATTCGCAGTCTATTTGGCCATAGTATTTTGTGTCATGCGGCTGCTAATAAA +GCTAACACTGTAGAAAGGAACCACTGACAACTGATTGATAACCGAGTTGAGACAGGAACGAGGGTCCAAA +ATGGGAATCTGCTACATTGTCAAGTTCCTGTTAGAACGATTTCATATGTATCGTGCAATTTAAAAACTCG +AATGTTCTGTTAAAAATTACAATCAATGAAAGTCTTGCATGGACTAGACATAAAAAGTTAAAAGCATTTA +AATTCCATTTTCTAAAGTAAATTTATATTTAATATAAATTGTATTTAATTGAATTGCTCATATTGTATAT +AATGGTTCAATAAAATTCATACTCATACTGAAAGTTAGAAATATATATATTGGACACACAGATTCTGGTG +ACGACGTTGTTCAAGTATGTTTCAAAACGTAACGGCCTAACCTGCAACGCAATATCCTTTGAAAAATTGT +TATAAACATTTTTTTCAGTATGTCAACATAATTTTTAGATATCTACCCAACACTTCCAATAGCACCATAA +CGCGTATCTTATAGTCGAGGAAACCGACTATAGCGTTCTATGTTGTTATTAATTCGGGTGGCCGCAAAAG +GATTAAAAAAAGAAGCGGCCAGAGCATCAATCAAAGGAGGAGCGGTAATCGCCCTTTTTTGTACAAAATA +AAAAATTAAAAAAATGTACCCCCAAAATTACGCTAAATTTTTGTTGGCGAGTGTGCGCTTTTTTCTGCAT +GCCCAATTTAAATTTAGTCAGAAAGAAAATTTGATGGAGGCGAGGACATAAAATGCGGAGTTAAGGGAAT +AATGGGGATTTGTGACAGAAAAGGGGGGCTGCGGCCCCCATATGTGGATTTTGTAACAATAATGAACAAT +AACATATTCAGGCGCTGACATTAAAGAGTAGACGTTTCTCCTATGTTTTAATTGGCTTAGTAATCCATCA +AAGCGATCTTTAAAACTATCCCTAAAATAATAACGAAAAATTTAAGATCTACCTACAAAAGTTAATTAAA +ATGTTAACAGAAAGTCACTCCCTTCACTCCGCTGGCATTGCACGATAATCAAAACCTAATACGAAAGCCG +ATACACCCGCATTAGTCCCCATTTGAAGTTGATGAGGCAATCAAAAAAATTTCCTACTCCCTAGCTAGGG +GAGAGACAAGAATTTGTTAAGCACTCGCTGTCACGACCCTGTGAGCTAGCAATGCCAACATTAAATAAAT +ACTTGCGGCGTTGCCTAATTTTTGTACGCACTTGTTTACAACAAATATACATATCCTCCAGCTTTTTTCG +AACTTTACCGGTGGCTTGGGACTGACCGAGTCCATTGCCAGGAGTATAGAAAGCAAAGCAACTCGCTTGG +CCACTATCACCGTGTTTGTCGACTGGAACACCTTAAATACCAGTGGGGAGGGCGGAGAGGTGTCGTTACG +AAGAATAATCACTGCCCGCGGGACTGAAGAATTTACTAGGGGGTGGGGACAACTTAACGTGATTTAATGC +AGATAATAAAGCAAAACATATACTTTTGACTCCACATTTTTACGGTGGCGTTGTTAACCCAAAAGCTGTC +AAAAATCACTTAGGGGATCTTCGATCGTATTTCAAGAACTCGAAATACTGCTACGCTTGGGAAAGATAAT +TAAAACAAGTCATTTCGGATTGACCATAAAGTTTCCACTCAAAAAAAAAAAAAAAAAAAAAAAAAAAAAG +CAAAAGATAAACTTGATAGAGCGTAACCCAAACCAAAAATTTTCCATATTGAAAGCCAAAGTATTCCCAT +TCTTGCCAAAGAAAATTGAATTCAATGGAATATTAATTCACAATGGGTAATCAATTTATCTATATATATA +ACTTTTCCCTTTTATTGAAAAGTGAATATTTTTAGTAGTGTTGGAGCAAAACTTTATTGTTGGATTGTTT +TTAAATTAGAAACGTAACAAATATGGCGAAAAACTTGAACGTCGGCCAAACGCACTACGCTCTAGCATTG +AATGTACTTAGTTTTGTAACGATGTGTCCTAGGTGTTAATCGAGTATTTATTGTGTGGTGTGAAGTAATA +CTTATGCACTAATTAAATTTGCTTTACTGGGTTTAGGTGTATGTTTGGTGTAAATGGGTATTTTGCAAAT +GCAAAATGCAAAACGCAGTCGATAACAATGTTAGCCACATCCTTGAACAATTTTCACTCACAGAAAAAAG +TCACATGCACACTCACTCACACGACAACTGAAAACGTTCGACATACGATCCGTATGCACGCTAGTTGTTT +GCTGCTCTCCATTTCTGATTCTTCGTTCCCATTTCCCACGACATTTTTCACATTTCATTCCTGCTCGATT +GGATGTAGCCAAGTGTTATGCAACTGCTAAAGGACTTCATCTTGTAATTTCTTTGGTGATTTGCGTTGTT +TGAGTTGTGATTTGTGTGGTGTTGCCTTTTGTGCCTCATCTGGCGTCGATCTCCGCCTCATCCTAATCCT +GGTAAGGGGCCACATCCATTTTAGAGCAGATAGCATTTCCGCCGCCAGCAGGAGCAGGTGCAGTGCCCAT +GACGATAGTATCGGCAGAGGCACTTCAGATACTTATAGCCCGCACAGCAGTGATGCGAGTGCAAGTGAGA +ATGCGAGTGATAGTGGCTGTAGCAGGAGCTATCGTGCAGACAGTAGGAGTAGCAGCCGCAGTCGCACATA +TTTTTGCCTTGTGTAAGGTCCTTTTGCCTTCACTTGTCTGAAGTCTATATAATCTGGACTTCGCTGTGCG +TCCCAGCTCCTTTGCACGCTGTTGCCCAACTGATTTGTTGCCAACGCTTCCATTTTCCACTTGGCTTAGG +TTAGTTTGCTTCGACGGCCATCAAGTGGAATTGGTCTCTCATAGTTACGGGCACGGGCCCAAGTTTGATC +GATCACGAAGATACATTTGCGTATTTAGGGTTTAACATTCGTACCAAGAACCGGAGTGAGTTGTAATATA +TGGGTTAGCAATGTTGTTGTTATGGCAATTCATATGAAAACCATGTCAATTGATTTTAGCCAACTGCATC +GCCTCCGTGTCCAGAGTACGGGAGAATACGAGAAAACCGCATAAAATTAATCTTTTTTTTATGGGAATGA +AAGGTGGTTAAATAAATTTTCAAGGGTACATTTTTGATTTGTAGATATTTCCAGAGTATACCCTCGTCTA +GACCCATAACATGGTTTACCTAAACTTTTTTGCCTGGTACCGCACACATTACTCAACTCGAGTCGAATGA +TTAATTTGTAAAATTGTCGCTGATTTTATGACCGAAATATTTTTTGCATTTGGCGATATCAACCCGAAAT +AGACTTGGCCACATGCAAATTCATGTCTGACCCACATTGTCGACGGGGGTACGAGTCACCGTCGCCGGGG +ATATACAGATAGAGAGCTCTAACTGCTCTAGTGCTGCATTCGATGACACACGCGGCGAATGCACAGCTGA +CGCTTACACATCGTGTACGTTTACACAGACGCGCGGACTTACAAACTCTGACGGACTGCAAATGAGATCA +GATCGAGGAATCTGCACGTGATGAGCTCATAATTAGTTGTTGTTTGCTGTCGCTAAAACACCCGGATTAC +AGCTTTTAGTTCCCAATTTTTTCACGACCCATAGTTTTTACTCGCCCACATGCGAGTTGCTTATAAGATA +TCCCCATTTTTATTATCAATTTTATATTTTTGGGGGCATGTACATAAGTATAAGCAATGGGAAACGTTTT +TTCAGCTAGGCAAAACCGGGTTAAAAGAAAATAGCAGGGGTTTGAATGTTTTGTAGTCGAGAATGTTTTA +AGTGCACGGTTTTCAGCAGTTTAGTTGGAATGGTTTTAAGTAAGACTCAAGGGACAGTGAGGCACAGACA +AACAACGACTATAGAGATTTCTATAGTCGACTACCCCGTCTATCAGATAAGCATTACCCAGCTAATGAAT +TTGCTAGTGTTAAAAAATTTAATTGCATGACAGTTTGGGCGGTTTAAAGGTGTAAGAAAACTGTAAGAAA +ACAAAAACAACTGTTTTTGGTGTACCGGTAGACATTGGTAGAGTGGGCGTGGCCACATGAATCAACAAAC +TTGCACTGCGTCTATGTCTCTGGAAACTGTATGCCTAAGTGTGGAAGCTTTTAAGGAATAAAAATTAAGA +CTGCCAAAAAAAAAAAATTGTGTTATAAAACAGAATGCAGTGATTTGTTCAATACTCGTAGAGTATTGGT +AAAGTAAGGCGTTTACAATCCTACAAAAAATAAAAAAAGTAAAAGATTTGGATCACTAGCTGATTCAATC +TGGCTTTGTGCCATGAGCTCAACAAGTTAAAAAGTTCAATTTGGGCGTGCAGATCTAGTCGCGCTGTGAA +CACATCTTTTCCGAACGTTCCAACGCCAACTCTAACGCTCGCCAAAATGGCACGCCTACATTTTAGTATT +TGTCTTACCAATTTATACCCCAAAACACGATTTGGTCACACCCACTCCAACGTCTACAATTGCATTTTGG +GCAGTTTGGGGGTGGAAAAAGTTGTATGCCAAATCAATAGAAAATAACAAGACTAATAAACATATGAAAA +AATATAAAAACATTTTTTAAAAGTGTGAGCGTACGATTTTTGGGTCACTGGAAAAAAGTTTTTAGGTAGA +TAGATAGAAATTAAAAAAAATAGGGCACACAAAAACAAAATAAAAAAAGAACATGCGCTGCGTCTACTAT +GTACACACATTGTATGTATGTACATATGCATGTGTCTGGGATCTGCATGTCTAATTTTAACTCTCTAGCA +TTATTCGTTCATACGAACAGACGGACGGGCAGATGGACATGGCCAGATTGCTTCCGATCAAAAATATAGA +TACTACATATGTATATACTTTATATAATCGGAAAAGCTTTATTCTACCTGTTTCTTCTACTCTACGAGTA +ACGGAAATTAAAAAATAACGTTAAAAAAGAAAAAAGAAGGGGAGACCCTGCCTAGTTTAAAAATGTAAGT +AAACAAAATTAAATTTCCAACTGCAGTATCTCAACCCCCAGTTCGATTGCAGACTGGAAATCGGCTTGTC +GCCAGCGAATGCATTCCTTCATATCATATACGTTCAGCATAAATACAAACATATAAGAATTCTGTGGATT +ATCACATCACGTGGATAACCAGAGGGGCATGTCGGTGTTCCTGGAAAAAGTGGGAGAATATGGAGGGTTG +AACTGCAGAAACTGCCTGCTGGTATTTGGTTTGTCAAAGAGCGTGCGTAAACTTTGCAAAGTCCATATGA +CATTGACTGGCGGGGAATTGTGGGTGTATCTTGGAGACCATCAAGGCCAAAGTGGGGCAGATCAGATTTT +TATGTATATCGGGTTAGTAGTTTAATCCCAACAATTTTCAAAAGAACTTTTAGCGATGACACATTATGTA +TTTTATTGCTACCTGTCTACATTATATTAAAACCTCAATGTGAAAGTGTTTTAATAACATTCAAAAATAA +AACAGATATCACCATATATAACACGTCTTTATCGATGTAATTACATTTCTGATCATAGCCTTTGGATATC +ATAATATTATAACTTTAACGATTCGCGTCTGGTAAATACCATTACACACACGAACATTTGTATTATTTTT +CGAGCATAACGAACTTGTAACTACTATTCTCGAATCAACGGTCCCAAATGATGGCTTTCCATTCAAGAAT +AGGGTGCCCTTCCTTGAATGCAAGGTACATATAAAAAATCATATAGCGCAATGTAGCTAGTAATCAGAGA +AACCTATACCCCGCCGTCGGCCGATTATCACCTTTTCAAGTCTCGTGCTGTGCTCGCATTTGTCGTCATT +GCCTCATAGTGACCCCTTCGAAGAACCCAATTTGTTGAATTATCTGCGTCAACTTGTAATGGAAACTTTT +GTAAACTTTTCCATATAACCGCGGCAGGGGAAAACTACGACAAAAGTGACATAGCCCATAGAAAGGTGAA +ACGAAGAAAAGTATTTGCTCGAAAAGTGCAAAGTGGGTAAAATTCCATTAGACCTCGAGTTCAACAGATA +TTCGAATTATTTGCGCTGCTCATTAGTAAGCCGTTTATGCCAGTCCTAAGTCACAATAACACATAATTTT +AAATCGCCTCAATGAACATATAAGCAAATTGAATTGTATTTCAAAACAACTGCGTATTGACGTCAGTACA +GTCTGTCTGTGCCTGATGGATGCATTCATTGACATTTAGGCGAGACAAGAAACTCACCAGTCATAACTTA +ATGATCAAAACAACCGGTAAGTTAACGGGTTTAAATCTGAGTTCTCTATACGAAAACATGATATTTACCT +CTTTGAATTTTAAAAATAATAATGCTAATATTGTTTAGTCCAGAAATGCAATTATTAAACATTACATTTA +TTAATAAAAAGTTAAACTCTAACATGGCTTAAACAAATATTTTTTAATGAGTTAATTCCCATAGTTTAGT +AATTTTAATATATTCTGTTTAGTAATTTTAAAAATGAATTTTCCCTGTTTTACATGCGCTACGAAATATA +GAATATTTAGCTACGATTAAATTCAGCCAAGTTTTGCGGATGACTAATCACAAAAACTTTACAATAATGC +CAAACGGAAAGGGGAAATGCTGCGCCTGCACCCAAGTCAATTAGCATAAGTATGTTTTGTGTGAATTTGT +GAATATTAAAAAATTTCAGCGAGCTGTTTTTTTTCGGAAGCATATAATGGATGAGCAGATCCGAACTTTT +TCGCATTGTAGCTTCCTTCGCTTTTGTTAAGCACGATTAAAATGCGATTGCAATGCTGCAGGTACAAGCA +GCACCCTATATGAGTGGATCTATATCCTCTATACGAGTGGATCTCTCGAGTATGTGGCTTGAATGAAAAG +TTATGAATTCATTTTTTGTCAAATTATCTTGAACTTACAGACTTACGATCTATCGAAGCACACAAAAACA +AGATAAAGTCAACTTCATGAATGAGCCACGCCAAACAATGGAAAAAATGGTAAGACAAGAAAATACAATT + + From dalej at apple.com Mon Feb 11 15:53:29 2008 From: dalej at apple.com (Dale Johannesen) Date: Mon, 11 Feb 2008 21:53:29 -0000 Subject: [llvm-commits] [llvm-gcc-4.2] r46971 - in /llvm-gcc-4.2/trunk/gcc: config/i386/llvm-i386-target.h llvm-types.cpp Message-ID: <200802112153.m1BLrUFb016567@zion.cs.uiuc.edu> Author: johannes Date: Mon Feb 11 15:53:29 2008 New Revision: 46971 URL: http://llvm.org/viewvc/llvm-project?rev=46971&view=rev Log: Revert 46958 for the moment; it broke things, and there's a better way to solve the problem. Modified: llvm-gcc-4.2/trunk/gcc/config/i386/llvm-i386-target.h llvm-gcc-4.2/trunk/gcc/llvm-types.cpp Modified: llvm-gcc-4.2/trunk/gcc/config/i386/llvm-i386-target.h URL: http://llvm.org/viewvc/llvm-project/llvm-gcc-4.2/trunk/gcc/config/i386/llvm-i386-target.h?rev=46971&r1=46970&r2=46971&view=diff ============================================================================== --- llvm-gcc-4.2/trunk/gcc/config/i386/llvm-i386-target.h (original) +++ llvm-gcc-4.2/trunk/gcc/config/i386/llvm-i386-target.h Mon Feb 11 15:53:29 2008 @@ -83,15 +83,6 @@ } \ } -/* Aggregates containing SSE vectors are aligned at 16 bytes as parameters; - while long double has GCC alignment of 16 bytes (correct for struct layout) - but is only 4 byte aligned as a parameter. So if a union type contains an - SSE vector, use that as the basis for the constructed LLVM struct. */ -#define TARGET_LLVM_COMPARE_UNION_FIELDS(curType, newType, curAlign, newAlign) \ - (newAlign==curAlign && TARGET_SSE && \ - TheTarget->getTargetLowering()->getByValTypeAlignment(newType) > \ - TheTarget->getTargetLowering()->getByValTypeAlignment(curType)) - #ifdef LLVM_ABI_H extern bool llvm_x86_should_pass_aggregate_in_memory(tree, const Type *); Modified: llvm-gcc-4.2/trunk/gcc/llvm-types.cpp URL: http://llvm.org/viewvc/llvm-project/llvm-gcc-4.2/trunk/gcc/llvm-types.cpp?rev=46971&r1=46970&r2=46971&view=diff ============================================================================== --- llvm-gcc-4.2/trunk/gcc/llvm-types.cpp (original) +++ llvm-gcc-4.2/trunk/gcc/llvm-types.cpp Mon Feb 11 15:53:29 2008 @@ -33,7 +33,6 @@ #include "llvm/TypeSymbolTable.h" #include "llvm/Target/TargetData.h" #include "llvm/Target/TargetMachine.h" -#include "llvm/Target/TargetLowering.h" #include "llvm/Assembly/Writer.h" #include "llvm/ADT/DenseMap.h" #include "llvm/ADT/StringExtras.h" @@ -1138,7 +1137,7 @@ // 'sret' functions cannot be 'readnone' or 'readonly'. if (ABIConverter.isStructReturn()) RAttributes &= ~(ParamAttr::ReadNone|ParamAttr::ReadOnly); - + // Compute whether the result needs to be zext or sext'd. RAttributes |= HandleArgumentExtension(TREE_TYPE(type)); @@ -2125,8 +2124,6 @@ /// ConvertUNION - We know that 'type' is a UNION_TYPE or a QUAL_UNION_TYPE: /// convert it to an LLVM type. -/// This involves creating a struct with the right size and alignment. In -/// some cases this is target dependent. const Type *TypeConverter::ConvertUNION(tree type, tree orig_type) { if (const Type *Ty = GET_TYPE_LLVM(type)) { // If we already compiled this type, and if it was not a forward @@ -2173,25 +2170,17 @@ // Select TheTy as union type if it meets one of the following criteria // 1) UnionTy is 0 // 2) TheTy alignment is more then UnionTy - // 3) TheTy size is greater than UnionTy size and TheTy alignment is equal - // to UnionTy + // 3) TheTy size is greater than UnionTy size and TheTy alignment is equal to UnionTy // 4) TheTy size is greater then UnionTy size and TheTy is packed - // FIXME there is no check for packed? bool useTheTy = false; if (UnionTy == 0) useTheTy = true; else if (Align > MaxAlign) useTheTy = true; -#ifdef TARGET_LLVM_COMPARE_UNION_FIELDS - else - useTheTy = TARGET_LLVM_COMPARE_UNION_FIELDS(UnionTy, TheTy, - Align, MaxAlign); -#else else if (MaxAlign == Align && Size > MaxSize) useTheTy = true; - else if (Size > MaxSize) // FIXME really? Seems wrong to lower alignment + else if (Size > MaxSize) useTheTy = true; -#endif if (useTheTy) { UnionTy = TheTy; From kremenek at apple.com Mon Feb 11 17:11:13 2008 From: kremenek at apple.com (Ted Kremenek) Date: Mon, 11 Feb 2008 23:11:13 -0000 Subject: [llvm-commits] [llvm] r46975 - in /llvm/trunk/include/llvm/ADT: ImmutableMap.h ImmutableSet.h Message-ID: <200802112311.m1BNBDi2018796@zion.cs.uiuc.edu> Author: kremenek Date: Mon Feb 11 17:11:12 2008 New Revision: 46975 URL: http://llvm.org/viewvc/llvm-project?rev=46975&view=rev Log: The factories for ImutAVLTree/ImmutableSet/ImmutableMap now take an (optional) BumpPtrAllocator argument to their constructors. This BumpPtrAllocator will be used to allocate trees. If no BumpPtrAllocator is provided, one is created (as before). Modified: llvm/trunk/include/llvm/ADT/ImmutableMap.h llvm/trunk/include/llvm/ADT/ImmutableSet.h Modified: llvm/trunk/include/llvm/ADT/ImmutableMap.h URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/include/llvm/ADT/ImmutableMap.h?rev=46975&r1=46974&r2=46975&view=diff ============================================================================== --- llvm/trunk/include/llvm/ADT/ImmutableMap.h (original) +++ llvm/trunk/include/llvm/ADT/ImmutableMap.h Mon Feb 11 17:11:12 2008 @@ -84,6 +84,9 @@ public: Factory() {} + Factory(BumpPtrAllocator& Alloc) + : F(Alloc) {} + ImmutableMap GetEmptyMap() { return ImmutableMap(F.GetEmptyTree()); } ImmutableMap Add(ImmutableMap Old, key_type_ref K, data_type_ref D) { Modified: llvm/trunk/include/llvm/ADT/ImmutableSet.h URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/include/llvm/ADT/ImmutableSet.h?rev=46975&r1=46974&r2=46975&view=diff ============================================================================== --- llvm/trunk/include/llvm/ADT/ImmutableSet.h (original) +++ llvm/trunk/include/llvm/ADT/ImmutableSet.h Mon Feb 11 17:11:12 2008 @@ -16,6 +16,7 @@ #include "llvm/Support/Allocator.h" #include "llvm/ADT/FoldingSet.h" +#include "llvm/Support/DataTypes.h" #include namespace llvm { @@ -334,15 +335,31 @@ typedef FoldingSet CacheTy; - CacheTy Cache; - BumpPtrAllocator Allocator; + CacheTy Cache; + uintptr_t Allocator; + + bool ownsAllocator() const { + return Allocator & 0x1 ? false : true; + } + + BumpPtrAllocator& getAllocator() const { + return *reinterpret_cast(Allocator & ~0x1); + } //===--------------------------------------------------===// // Public interface. //===--------------------------------------------------===// public: - ImutAVLFactory() {} + ImutAVLFactory() + : Allocator(reinterpret_cast(new BumpPtrAllocator())) {} + + ImutAVLFactory(BumpPtrAllocator& Alloc) + : Allocator(reinterpret_cast(&Alloc) | 0x1) {} + + ~ImutAVLFactory() { + if (ownsAllocator()) delete &getAllocator(); + } TreeTy* Add(TreeTy* T, value_type_ref V) { T = Add_internal(V,T); @@ -358,8 +375,6 @@ TreeTy* GetEmptyTree() const { return NULL; } - BumpPtrAllocator& getAllocator() { return Allocator; } - //===--------------------------------------------------===// // A bunch of quick helper functions used for reasoning // about the properties of trees and their children. @@ -450,7 +465,8 @@ // Create it. // Allocate the new tree node and insert it into the cache. - TreeTy* T = (TreeTy*) Allocator.Allocate(); + BumpPtrAllocator& A = getAllocator(); + TreeTy* T = (TreeTy*) A.Allocate(); new (T) TreeTy(L,R,V,IncrementHeight(L,R)); // We do not insert 'T' into the FoldingSet here. This is because @@ -930,6 +946,9 @@ public: Factory() {} + Factory(BumpPtrAllocator& Alloc) + : F(Alloc) {} + /// GetEmptySet - Returns an immutable set that contains no elements. ImmutableSet GetEmptySet() { return ImmutableSet(F.GetEmptyTree()); } From jon at alacatialabs.com Mon Feb 11 17:24:49 2008 From: jon at alacatialabs.com (Jonathan Johnson) Date: Mon, 11 Feb 2008 17:24:49 -0600 Subject: [llvm-commits] CVS: llvm-www/devmtg/current/index.html Message-ID: <200802112324.m1BNOnlf019398@zion.cs.uiuc.edu> Changes in directory llvm-www/devmtg/current: index.html updated: 1.5 -> 1.6 --- Log message: Updated unconfirmed attendees list --- Diffs of the changes: (+7 -1) index.html | 8 +++++++- 1 files changed, 7 insertions(+), 1 deletion(-) Index: llvm-www/devmtg/current/index.html diff -u llvm-www/devmtg/current/index.html:1.5 llvm-www/devmtg/current/index.html:1.6 --- llvm-www/devmtg/current/index.html:1.5 Thu Jan 10 20:27:44 2008 +++ llvm-www/devmtg/current/index.html Mon Feb 11 17:24:15 2008 @@ -39,6 +39,9 @@ Owen AndersonApple, Inc. Chandler Carruth Evan ChengApple, Inc. + Eric ChristopherApple, Inc. + Samuel Crow + Kurt HarrimanGreenplum Robert HundtGoogle Dale JohannesenApple, Inc. Jonathan JohnsonAlacatia Labs, Inc. @@ -51,10 +54,13 @@ Devang PatelApple, Inc. Joseph RanieriAlacatia Labs, Inc. Chuck RoseAdobe Systems Incorporated + Robert StaudingerUniversity of Salzburg, Austria Mike StumpApple, Inc. Bill WendlingApple, Inc. + Robert Zeh + Chuck (Chengyan) ZhaoUniversity of Toronto -

      Total unconfirmed: 17

      +

      Total unconfirmed: 23

      If your name is misspelled, or organization affiliation isn't correct, please email us, and we'll correct it. From gohman at apple.com Mon Feb 11 17:45:15 2008 From: gohman at apple.com (Dan Gohman) Date: Mon, 11 Feb 2008 23:45:15 -0000 Subject: [llvm-commits] [llvm] r46978 - /llvm/trunk/include/llvm/ADT/APInt.h Message-ID: <200802112345.m1BNjFum020045@zion.cs.uiuc.edu> Author: djg Date: Mon Feb 11 17:45:14 2008 New Revision: 46978 URL: http://llvm.org/viewvc/llvm-project?rev=46978&view=rev Log: Correct the order of the arguments in the examples in the comments for APInt::getBitsSet. And fix an off-by-one bug in "wrapping" mode. Modified: llvm/trunk/include/llvm/ADT/APInt.h Modified: llvm/trunk/include/llvm/ADT/APInt.h URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/include/llvm/ADT/APInt.h?rev=46978&r1=46977&r2=46978&view=diff ============================================================================== --- llvm/trunk/include/llvm/ADT/APInt.h (original) +++ llvm/trunk/include/llvm/ADT/APInt.h Mon Feb 11 17:45:14 2008 @@ -371,9 +371,9 @@ /// Constructs an APInt value that has a contiguous range of bits set. The /// bits from loBit to hiBit will be set. All other bits will be zero. For - /// example, with parameters(32, 15, 0) you would get 0x0000FFFF. If hiBit is + /// example, with parameters(32, 0, 15) you would get 0x0000FFFF. If hiBit is /// less than loBit then the set bits "wrap". For example, with - /// parameters (32, 3, 28), you would get 0xF000000F. + /// parameters (32, 28, 3), you would get 0xF000000F. /// @param numBits the intended bit width of the result /// @param loBit the index of the lowest bit set. /// @param hiBit the index of the highest bit set. @@ -384,7 +384,7 @@ assert(loBit < numBits && "loBit out of range"); if (hiBit < loBit) return getLowBitsSet(numBits, hiBit+1) | - getHighBitsSet(numBits, numBits-loBit+1); + getHighBitsSet(numBits, numBits-loBit); return getLowBitsSet(numBits, hiBit-loBit+1).shl(loBit); } From natebegeman at mac.com Mon Feb 11 17:47:56 2008 From: natebegeman at mac.com (Nate Begeman) Date: Mon, 11 Feb 2008 23:47:56 -0000 Subject: [llvm-commits] [llvm] r46979 - /llvm/trunk/lib/Target/IA64/README Message-ID: <200802112347.m1BNluHv020133@zion.cs.uiuc.edu> Author: sampo Date: Mon Feb 11 17:47:56 2008 New Revision: 46979 URL: http://llvm.org/viewvc/llvm-project?rev=46979&view=rev Log: Stuff noticed while grepping code Modified: llvm/trunk/lib/Target/IA64/README Modified: llvm/trunk/lib/Target/IA64/README URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/lib/Target/IA64/README?rev=46979&r1=46978&r2=46979&view=diff ============================================================================== --- llvm/trunk/lib/Target/IA64/README (original) +++ llvm/trunk/lib/Target/IA64/README Mon Feb 11 17:47:56 2008 @@ -1,59 +1,11 @@ -*** README for the LLVM IA64 Backend "Version 0.01" - March 18, 2005 -*** Quote for this version: - - "Kaori and Hitomi are naughty!!" - - -Congratulations, you have found: - -**************************************************************** -* @@@ @@@ @@@ @@@ @@@@@@@@@@ * -* @@@ @@@ @@@ @@@ @@@@@@@@@@@ * -* @@! @@! @@! @@@ @@! @@! @@! * -* !@! !@! !@! @!@ !@! !@! !@! * -* @!! @!! @!@ !@! @!! !!@ @!@ * -* !!! !!! !@! !!! !@! ! !@! * -* !!: !!: :!: !!: !!: !!: * -* :!: :!: ::!!:! :!: :!: * -* :: :::: :: :::: :::: ::: :: * -* : :: : : : :: : : : : : * -* * -* * -* @@@@@@ @@@ @@@ @@@ @@@@@@ @@@@@@ @@@ * -* @@@@@@@@ @@@@ @@@ @@@ @@@@@@@@ @@@@@@@ @@@@ * -* @@! @@@ @@!@!@@@ @@! @@! @@@ !@@ @@!@! * -* !@! @!@ !@!!@!@! !@! !@! @!@ !@! !@!!@! * -* @!@ !@! @!@ !!@! !!@ @!@!@!@! !!@@!@! @!! @!! * -* !@! !!! !@! !!! !!! !!!@!!!! @!!@!!!! !!! !@! * -* !!: !!! !!: !!! !!: !!: !!! !:! !:! :!!:!:!!: * -* :!: !:! :!: !:! :!: :!: !:! :!: !:! !:::!!::: * -* ::::: :: :: :: :: :: ::: :::: ::: ::: * -* : : : :: : : : : : :: : : ::: * -* * -**************************************************************** -* Bow down, bow down, before the power of IA64! Or be crushed, * -* be crushed, by its jolly registers of doom!! * -**************************************************************** - -DEVELOPMENT PLAN: - - _ you are 2005 maybe 2005 2006 2006 and - / here | | | beyond - v v v v | - v -CLEAN UP ADD INSTRUCTION ADD PLAY WITH -INSTRUCTION --> SCHEDULING AND --> JIT --> DYNAMIC --> FUTURE WORK -SELECTION BUNDLING SUPPORT REOPTIMIZATION - -DISCLAIMER AND PROMISE: - -As of the time of this release, you are probably better off using Intel C/C++ -or GCC. The performance of the code emitted right now is, in a word, -terrible. Check back in a few months - the story will be different then, -I guarantee it. - TODO: - + - Un-bitrot ISel + - Hook up If-Conversion a la ARM target + - Hook up all branch analysis functions + - Instruction scheduling + - Bundling + - Dynamic Optimization + - Testing and bugfixing - stop passing FP args in both FP *and* integer regs when not required - allocate low (nonstacked) registers more aggressively - clean up and thoroughly test the isel patterns. @@ -65,14 +17,11 @@ (we will avoid the mess that is: http://gcc.gnu.org/ml/gcc/2003-12/msg00832.html ) - instruction scheduling (hmmmm! ;) - - write truly inspirational documentation - - if-conversion (predicate database/knowledge? etc etc) - counted loop support - make integer + FP mul/div more clever (we have fixed pseudocode atm) - track and use comparison complements INFO: - - we are strictly LP64 here, no support for ILP32 on HP-UX. Linux users don't need to worry about this. - i have instruction scheduling/bundling pseudocode, that really works @@ -80,7 +29,6 @@ so, before you go write your own, send me an email! KNOWN DEFECTS AT THE CURRENT TIME: - - C++ vtables contain naked function pointers, not function descriptors, which is bad. see http://llvm.cs.uiuc.edu/bugs/show_bug.cgi?id=406 - varargs are broken @@ -90,17 +38,11 @@ these will probably be fixed soon. ACKNOWLEDGEMENTS: - - Chris Lattner (x100) - Other LLVM developers ("hey, that looks familiar") CONTACT: - - You can email me at duraid at octopus.com.au. If you find a small bug, just email me. If you find a big bug, please file a bug report in bugzilla! http://llvm.cs.uiuc.edu is your one stop shop for all things LLVM. - - - - From tonic at nondot.org Mon Feb 11 20:42:55 2008 From: tonic at nondot.org (Tanya Lattner) Date: Tue, 12 Feb 2008 02:42:55 -0000 Subject: [llvm-commits] [llvm] r46981 - /llvm/trunk/docs/GettingStarted.html Message-ID: <200802120242.m1C2gtbr025036@zion.cs.uiuc.edu> Author: tbrethou Date: Mon Feb 11 20:42:55 2008 New Revision: 46981 URL: http://llvm.org/viewvc/llvm-project?rev=46981&view=rev Log: Add 2.2 release tag. Modified: llvm/trunk/docs/GettingStarted.html Modified: llvm/trunk/docs/GettingStarted.html URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/GettingStarted.html?rev=46981&r1=46980&r2=46981&view=diff ============================================================================== --- llvm/trunk/docs/GettingStarted.html (original) +++ llvm/trunk/docs/GettingStarted.html Mon Feb 11 20:42:55 2008 @@ -710,6 +710,7 @@ subdirectories of the 'tags' directory:

        +
      • Release 2.2: RELEASE_22
      • Release 2.1: RELEASE_21
      • Release 2.0: RELEASE_20
      • Release 1.9: RELEASE_19
        • From tonic at nondot.org Mon Feb 11 20:43:51 2008 From: tonic at nondot.org (Tanya Lattner) Date: Tue, 12 Feb 2008 02:43:51 -0000 Subject: [llvm-commits] [llvm] r46982 - /llvm/branches/release_22/docs/GettingStarted.html Message-ID: <200802120243.m1C2hpBJ025079@zion.cs.uiuc.edu> Author: tbrethou Date: Mon Feb 11 20:43:50 2008 New Revision: 46982 URL: http://llvm.org/viewvc/llvm-project?rev=46982&view=rev Log: release tag. Modified: llvm/branches/release_22/docs/GettingStarted.html Modified: llvm/branches/release_22/docs/GettingStarted.html URL: http://llvm.org/viewvc/llvm-project/llvm/branches/release_22/docs/GettingStarted.html?rev=46982&r1=46981&r2=46982&view=diff ============================================================================== --- llvm/branches/release_22/docs/GettingStarted.html (original) +++ llvm/branches/release_22/docs/GettingStarted.html Mon Feb 11 20:43:50 2008 @@ -710,6 +710,7 @@ subdirectories of the 'tags' directory:

          +
        • Release 2.2: RELEASE_22
        • Release 2.1: RELEASE_21
        • Release 2.0: RELEASE_20
        • Release 1.9: RELEASE_19
          • From tonic at nondot.org Mon Feb 11 20:50:24 2008 From: tonic at nondot.org (Tanya Lattner) Date: Tue, 12 Feb 2008 02:50:24 -0000 Subject: [llvm-commits] [llvm-gcc-4.2] r46983 - in /llvm-gcc-4.2/trunk/gcc: builtin-types.def builtins.def llvm-convert.cpp Message-ID: <200802120250.m1C2oPUK025290@zion.cs.uiuc.edu> Author: tbrethou Date: Mon Feb 11 20:50:24 2008 New Revision: 46983 URL: http://llvm.org/viewvc/llvm-project?rev=46983&view=rev Log: Port __builtin_annotation from llvm-gcc4.0. This is similar to llvm.var.annotation but is applied to expressions. Modified: llvm-gcc-4.2/trunk/gcc/builtin-types.def llvm-gcc-4.2/trunk/gcc/builtins.def llvm-gcc-4.2/trunk/gcc/llvm-convert.cpp Modified: llvm-gcc-4.2/trunk/gcc/builtin-types.def URL: http://llvm.org/viewvc/llvm-project/llvm-gcc-4.2/trunk/gcc/builtin-types.def?rev=46983&r1=46982&r2=46983&view=diff ============================================================================== --- llvm-gcc-4.2/trunk/gcc/builtin-types.def (original) +++ llvm-gcc-4.2/trunk/gcc/builtin-types.def Mon Feb 11 20:50:24 2008 @@ -303,6 +303,10 @@ DEF_FUNCTION_TYPE_2 (BT_FN_I16_VPTR_I16, BT_I16, BT_VOLATILE_PTR, BT_I16) DEF_FUNCTION_TYPE_2 (BT_FN_BOOL_LONGPTR_LONGPTR, BT_BOOL, BT_PTR_LONG, BT_PTR_LONG) +/* APPLE LOCAL begin LLVM */ +DEF_FUNCTION_TYPE_2 (BT_FN_UINT_UINT_CONST_STRING, + BT_UINT, BT_UINT, BT_CONST_STRING) +/* APPLE LOCAL end LLVM */ DEF_FUNCTION_TYPE_3 (BT_FN_STRING_STRING_CONST_STRING_SIZE, BT_STRING, BT_STRING, BT_CONST_STRING, BT_SIZE) Modified: llvm-gcc-4.2/trunk/gcc/builtins.def URL: http://llvm.org/viewvc/llvm-project/llvm-gcc-4.2/trunk/gcc/builtins.def?rev=46983&r1=46982&r2=46983&view=diff ============================================================================== --- llvm-gcc-4.2/trunk/gcc/builtins.def (original) +++ llvm-gcc-4.2/trunk/gcc/builtins.def Mon Feb 11 20:50:24 2008 @@ -691,6 +691,10 @@ DEF_EXT_LIB_BUILTIN (BUILT_IN__EXIT, "_exit", BT_FN_VOID_INT, ATTR_NORETURN_NOTHROW_LIST) DEF_C99_BUILTIN (BUILT_IN__EXIT2, "_Exit", BT_FN_VOID_INT, ATTR_NORETURN_NOTHROW_LIST) +/* APPLE LOCAL begin LLVM */ +DEF_GCC_BUILTIN (BUILT_IN_ANNOTATION, "annotation", BT_FN_UINT_UINT_CONST_STRING, ATTR_NULL) +/* APPLE LOCAL end LLVM */ + /* Implementing nested functions. */ DEF_BUILTIN_STUB (BUILT_IN_INIT_TRAMPOLINE, "__builtin_init_trampoline") /* LLVM local deleted 1 line */ Modified: llvm-gcc-4.2/trunk/gcc/llvm-convert.cpp URL: http://llvm.org/viewvc/llvm-project/llvm-gcc-4.2/trunk/gcc/llvm-convert.cpp?rev=46983&r1=46982&r2=46983&view=diff ============================================================================== --- llvm-gcc-4.2/trunk/gcc/llvm-convert.cpp (original) +++ llvm-gcc-4.2/trunk/gcc/llvm-convert.cpp Mon Feb 11 20:50:24 2008 @@ -4259,7 +4259,38 @@ Builder.CreateUnreachable(); EmitBlock(new BasicBlock("")); return true; - + + // Convert annotation built-in to llvm.annotation intrinsic. + case BUILT_IN_ANNOTATION: { + + // Get file and line number + location_t locus = EXPR_LOCATION (exp); + Constant *lineNo = ConstantInt::get(Type::Int32Ty, locus.line); + Constant *file = ConvertMetadataStringToGV(locus.file); + const Type *SBP= PointerType::getUnqual(Type::Int8Ty); + file = ConstantExpr::getBitCast(file, SBP); + + // Get arguments. + tree arglist = TREE_OPERAND(exp, 1); + Value *ExprVal = Emit(TREE_VALUE(arglist), 0); + const Type *Ty = ExprVal->getType(); + Value *StrVal = Emit(TREE_VALUE(TREE_CHAIN(arglist)), 0); + + SmallVector Args; + Args.push_back(ExprVal); + Args.push_back(StrVal); + Args.push_back(file); + Args.push_back(lineNo); + + assert(Ty && "llvm.annotation arg type may not be null"); + Result = Builder.CreateCall(Intrinsic::getDeclaration(TheModule, + Intrinsic::annotation, + &Ty, + 1), + Args.begin(), Args.end()); + return true; + } + #if 1 // FIXME: Should handle these GCC extensions eventually. case BUILT_IN_APPLY_ARGS: case BUILT_IN_APPLY: From sabre at nondot.org Mon Feb 11 23:07:13 2008 From: sabre at nondot.org (Chris Lattner) Date: Tue, 12 Feb 2008 05:07:13 -0000 Subject: [llvm-commits] [llvm] r46985 - /llvm/trunk/docs/ReleaseNotes.html Message-ID: <200802120507.m1C57EWg029158@zion.cs.uiuc.edu> Author: lattner Date: Mon Feb 11 23:07:12 2008 New Revision: 46985 URL: http://llvm.org/viewvc/llvm-project?rev=46985&view=rev Log: remove unknown details Modified: llvm/trunk/docs/ReleaseNotes.html Modified: llvm/trunk/docs/ReleaseNotes.html URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/ReleaseNotes.html?rev=46985&r1=46984&r2=46985&view=diff ============================================================================== --- llvm/trunk/docs/ReleaseNotes.html (original) +++ llvm/trunk/docs/ReleaseNotes.html Mon Feb 11 23:07:12 2008 @@ -303,10 +303,8 @@ advantage of its predication features.
        • Bruno added PIC support to the MIPS backend, fixed many bugs and improved support for architecture variants.
          • -
        • Arnold Schwaighofer added support for X86 tail calls (limitations? -details?).
          • -
        • Evan contributed several enhancements to Darwin/x86 debug information, -and improvements at -O0 (details?).
          • +
        • Arnold Schwaighofer added initial support for X86 tail calls.
          • +
        • Evan contributed several enhancements to Darwin/x86 debug information.
        • Duncan added x86-64 support for trampolines (pointers to nested functions).
        From tonic at nondot.org Mon Feb 11 23:16:42 2008 From: tonic at nondot.org (Tanya Lattner) Date: Tue, 12 Feb 2008 05:16:42 -0000 Subject: [llvm-commits] [llvm] r46986 - /llvm/branches/release_22/docs/ReleaseNotes.html Message-ID: <200802120516.m1C5Gggp029549@zion.cs.uiuc.edu> Author: tbrethou Date: Mon Feb 11 23:16:42 2008 New Revision: 46986 URL: http://llvm.org/viewvc/llvm-project?rev=46986&view=rev Log: Merge release notes from mainline. Modified: llvm/branches/release_22/docs/ReleaseNotes.html Modified: llvm/branches/release_22/docs/ReleaseNotes.html URL: http://llvm.org/viewvc/llvm-project/llvm/branches/release_22/docs/ReleaseNotes.html?rev=46986&r1=46985&r2=46986&view=diff ============================================================================== --- llvm/branches/release_22/docs/ReleaseNotes.html (original) +++ llvm/branches/release_22/docs/ReleaseNotes.html Mon Feb 11 23:16:42 2008 @@ -4,11 +4,11 @@ - LLVM 2.1 Release Notes + LLVM 2.2 Release Notes -
        LLVM 2.1 Release Notes
        +
        LLVM 2.2 Release Notes
        1. Introduction
          2. @@ -23,6 +23,7 @@

          Written by the LLVM Team

          +

          Introduction @@ -32,7 +33,7 @@

          This document contains the release notes for the LLVM compiler -infrastructure, release 2.1. Here we describe the status of LLVM, including +infrastructure, release 2.2. Here we describe the status of LLVM, including major improvements from the previous release and any known problems. All LLVM releases may be downloaded from the LLVM releases web site.

          @@ -58,122 +59,110 @@
          -

          This is the twelfth public release of the LLVM Compiler Infrastructure. -It includes many features and refinements from LLVM 2.0.

          +

          This is the thirteenth public release of the LLVM Compiler Infrastructure. +It includes many features and refinements from LLVM 2.1.

          + +
          -New Frontends +Deprecated features in LLVM 2.2
          -

          LLVM 2.1 brings two new beta C front-ends. First, a new version of llvm-gcc -based on GCC 4.2, innovatively called "llvm-gcc-4.2". This promises to bring -FORTRAN and Ada support to LLVM as well as features like atomic builtins and -OpenMP. None of these actually work yet, but don't let that stop you checking -it out!

          - -

          Second, LLVM now includes its own native C and Objective-C front-end (C++ is -in progress, but is not very far along) code named "clang". This front-end has a number of great -features, primarily aimed at source-level analysis and speeding up compile-time. -At this point though, the LLVM Code Generator component is still very early in -development, so it's mostly useful for people looking to build source-level -analysis tools or source-to-source translators.

          +

          This is the last LLVM release to support llvm-gcc 4.0, llvm-upgrade, and +llvmc in its current form. llvm-gcc 4.0 has been replaced with llvm-gcc 4.2. +llvm-upgrade is useful for upgrading llvm 1.9 files to llvm 2.x syntax, but you +can always use an old release to do this. llvmc is currently mostly useless in +llvm 2.2, and will be redesigned or removed in llvm 2.3.

          -Optimizer Improvements +llvm-gcc 4.0, llvm-gcc 4.2, and clang
          -

          Some of the most noticable feature improvements this release have been in the -optimizer, speeding it up and making it more aggressive. For example:

          - -
            - -
          • Owen Anderson wrote the new MemoryDependenceAnalysis pass, which provides - a lazy, caching layer on top of AliasAnalysis. He then used it to rewrite - DeadStoreElimination which resulted in significantly better compile time in - common cases,
            • -
          • Owen implemented the new GVN pass, which is also based on - MemoryDependenceAnalysis. This pass replaces GCSE/LoadVN in the standard - set of passes, providing more aggressive optimization at a some-what - improved compile-time cost.
            • -
          • Owen implemented GVN-PRE, a partial redundancy elimination algorithm that - shares some details with the new GVN pass. It is still in need of compile - time tuning, and is not turned on by default.
            • -
          • Devang merged ETForest and DomTree into a single easier to use data - structure. This makes it more obvious which datastructure to choose - (because there is only one) and makes the compiler more memory and time - efficient (less stuff to keep up-to-date).
            • -
          • Nick Lewycky improved loop trip count analysis to handle many more common - cases.
            • - -
          +

          LLVM 2.2 fully supports both the llvm-gcc 4.0 and llvm-gcc 4.2 front-ends (in +LLVM 2.1, llvm-gcc 4.2 was beta). Since LLVM 2.1, the llvm-gcc 4.2 front-end +has made leaps and bounds and is now at least as good as 4.0 in virtually every +area, and is better in several areas (for example, exception handling +correctness, support for Ada and Fortran, better ABI compatibility, etc). We +strongly recommend that you +migrate from llvm-gcc 4.0 to llvm-gcc 4.2 in this release cycle because +LLVM 2.2 is the last release that will support llvm-gcc 4.0: LLVM 2.3 +will only support the llvm-gcc 4.2 front-end.

          + +

          The clang project is an effort to build +a set of new 'llvm native' front-end technologies for the LLVM optimizer +and code generator. Currently, its C and Objective-C support is maturing +nicely, and it has advanced source-to-source analysis and transformation +capabilities. If you are interested in building source-level tools for C and +Objective-C (and eventually C++), you should take a look. However, note that +clang is not an official part of the LLVM 2.2 release. If you are interested in +this project, please see its web site.

          -Code Generator Improvements +Major New Features
          -

          One of the main focuses of this release was performance tuning and bug - fixing. In addition to these, several new major changes occurred:

          +

          LLVM 2.2 includes several major new capabilities:

            +
          • A research team led by Scott Michel in the Computer Systems Research +Department at The Aerospace Corporation contributed the CellSPU backend, which +generates code for the vector coprocessors on the Sony/Toshiba/IBM Cell BE +processor. llvm-gcc 4.2 supports CellSPU as a 'configure' target and progress +is being made so that libgcc.a compiles cleanly. Notable pieces still in +development include full 64-bit integer and full double precision floating +point support.
            • -
          • Dale finished up the Tail Merging optimization in the code generator, and - enabled it by default. This produces smaller code that is also faster in - some cases.
            • - -
          • Christopher Lamb implemented support for virtual register sub-registers, - which can be used to better model many forms of subregisters. As an example - use, he modified the X86 backend to use this to model truncates and - extends more accurately (leading to better code).
            • - -
          • Dan Gohman changed the way we represent vectors before legalization, - significantly simplifying the SelectionDAG representation for these and - making the code generator faster for vector code.
            • +
          • Anton and Duncan significantly improved llvm-gcc 4.2 support for the GCC Ada +(GNAT) and Fortran (gfortran) front-ends. These front-ends should still be considered +experimental however: see the list of known problems. +The release binaries do not contain either front-end: they need to be built from +source (the Ada front-end only builds on x86-32 linux).
            • -
          • Evan contributed a new target independent if-converter. While it is - target independent, so far only the ARM backend uses it.
            • +
          • Dale contributed full support for long double on x86/x86-64 (where it is 80 +bits) and on Darwin PPC/PPC64 (where it is 128 bits). In previous LLVM +releases, llvm-gcc silently mapped long double to double.
            • -
          • Evan rewrote the way the register allocator handles rematerialization, - allowing it to be much more effective on two-address targets like X86, - and taught it to fold loads away when possible (also a big win on X86).
            • +
          • Gordon Henriksen rewrote most of the Accurate Garbage Collection code in the code generator, making the +generated code more efficient and adding support for the OCaml garbage collector +metadata format.
            • -
          • Dan Gohman contributed support for better alignment and volatility handling - in the code generator, and significantly enhanced alignment analysis for SSE - load/store instructions. With his changes, an insufficiently-aligned SSE - load instruction turns into movups, for example.
            • +
          • Christopher Lamb contributed support for multiple address spaces in LLVM +IR. This is useful for supporting targets that have 'near' vs 'far' pointers, +'RAM' vs 'ROM' pointers, or that have non-local memory that can be accessed with +special instructions.
            • -
          • Duraid Madina contributed a new "bigblock" register allocator, and Roman - Levenstein contributed several big improvements. BigBlock is optimized for - code that uses very large basic blocks. It is slightly slower than the - "local" allocator, but produces much better code.
            • - -
          • David Greene refactored the register allocator to split coalescing out from - allocation, making coalescers pluggable.
            • +
          • LLVM now includes a new set of detailed tutorials, which explain how to implement a +language with LLVM and shows how to use several important APIs.
          -
          -Target Specific Improvements +LLVM Core Improvements
          @@ -181,87 +170,142 @@

            -
          • Bruno Cardoso Lopes contributed initial MIPS support. It is sufficient to - run many small programs, but is still incomplete and is not yet - fully performant.
            • - -
          • Bill Wendling added SSSE3 support to the X86 backend.
            • +
          • Gordon contributed support for C and OCaml Bindings for the basic LLVM IR +construction routines as well as several other auxiliary APIs.
            • -
          • Nicholas Geoffray contributed improved linux/ppc ABI and JIT support.
            • +
          • Anton added readnone/readonly attributes for modeling function side effects. +Duncan hooked up GCC's pure/const attributes to them and enhanced mod/ref +analysis to use them.
            • + +
          • Devang added LLVMFoldingBuilder, a version of LLVMBuilder that implicitly +simplifies the code as it is constructed.
            • + +
          • Ted Kremenek added a framework for generic object serialization to bitcode +files. This support is only used by clang right now for ASTs but is extensible +and could be used for serializing arbitrary other data into bitcode files.
            • + +
          • Duncan improved TargetData to distinguish between the size/alignment of a +type in a register, in memory according to the platform ABI, and in memory when +we have a choice.
            • + +
          • Reid moved parameter attributes off of FunctionType and onto functions +and calls. This makes it much easier to add attributes to a function in a +transformation pass.
            • -
          • Dale Johannesen rewrote handling of 32-bit float values in the X86 backend - when using the floating point stack, fixing several nasty bugs.
            • +
          • Dan Gohman added support for vector sin, cos, and pow intrinsics.
            • -
          • Dan contributed rematerialization support for the X86 backend, in addition - to several X86-specific micro optimizations.
          + +
          +Code Generator Improvements +
          + +
          + +

          We put a significant amount of work into the code generator infrastructure, +which allows us to implement more aggressive algorithms and make it run +faster:

          + +
            + +
          • Owen refactored the existing LLVM dominator and loop information code to +allow it work on the machine code representation. He contributed support for +dominator and loop information on machine code and merged the code for forward +and backward dominator computation.
            • + +
          • Dan added support for emitting debug information with .file and .loc +directives on platforms that support it, instead of emitting large tables in the .s +file.
            • + +
          • Evan extended the DAG scheduler to model physical register dependencies +explicitly and have the BURR scheduler pick a correct schedule based on the +dependencies. This reduces our use of the 'flag' operand hack.
            • + +
          • Evan added initial support for register coalescing of subregister +references.
            • + +
          • Rafael Espindola implemented initial support for a new 'byval' attribute, +which allows more efficient by-value argument passing in the LLVM IR. Evan +finished support for it and enabled it in the X86 (32- and 64-bit) and C +backends.
            • + +
          • The LLVM TargetInstrInfo class can now answer queries about the mod/ref and +side-effect behavior of MachineInstr's. This information is inferred +automatically by TableGen from .td files for all instructions with +patterns.
            • + +
          • Evan implemented simple live interval splitting on basic block boundaries. +This allows the register allocator to be more successful at keeping values in +registers in some parts of a value's live range, even if they need to be spilled +in some other block.
            • + +
          • The new MachineRegisterInfo.h class provides support for efficiently +iterating over all defs/uses of a register, and this information is +automatically kept up-to-date. This support is similar to the use_iterator in +the LLVM IR level.
            • + +
          • The MachineInstr, MachineOperand and TargetInstrDesc classes are simpler, +more consistent, and better documented.
            • +
          + +
          -llvm-gcc Improvements +Optimizer Improvements
          -

          New features include: -

          + +

          In addition to a huge array of bug fixes and minor performance tweaks, the +LLVM 2.2 optimizers support a few major enhancements:

            -
          • Duncan and Anton made significant progress chasing down a number of problems - with C++ Zero-Cost exception handling in llvm-gcc 4.0 and 4.2. It is now at - the point where it "just works" on linux/X86-32 and has partial support on - other targets.
            • - -
          • Devang and Duncan fixed a huge number of bugs relating to bitfields, pragma - pack, and variable sized fields in structures.
            • - -
          • Tanya implemented support for __attribute__((noinline)) in - llvm-gcc, and added support for generic variable annotations which are - propagated into the LLVM IR, e.g. - "int X __attribute__((annotate("myproperty")));".
            • - -
          • Sheng Zhou and Christopher Lamb implemented alias analysis support for -"restrict" pointer arguments to functions.
            • - -
          • Duncan contributed support for trampolines (taking the address of a nested - function). Currently this is only supported on the X86-32 target.
            • - -
          • Lauro Ramos Venancio contributed support to encode alignment info in - load and store instructions, the foundation for other alignment-related - work.
            • + +
          • Daniel Berlin and Curtis Dunham rewrote Andersen's alias analysis to be +several orders of magnitude faster, and implemented Offline Variable +Substitution and Lazy Cycle Detection. Note that Andersen's is not enabled in +llvm-gcc by default, but can be accessed through 'opt'.
            • + +
          • Dan Gohman contributed several enhancements to Loop Strength Reduction (LSR) +to make it more aggressive with SSE intrinsics and when induction variables are +used by non-memory instructions.
            • + +
          • Evan added support for simple exit value substitution to LSR.
            • + +
          • Evan enhanced LSR to support induction variable reuse when the induction +variables have different widths.
            • +
          - +
          -LLVM Core Improvements +Target Specific Improvements
          -

          New features include: +

          New target-specific features include:

            -
          • Neil Booth contributed a new "APFloat" class, which ensures that floating - point representation and constant folding is not dependent on the host - architecture that builds the application. This support is the foundation - for "long double" support that will be wrapped up in LLVM 2.2.
            • - -
          • Based on the APFloat class, Dale redesigned the internals of the ConstantFP - class and has been working on extending the core and optimizer components to - support various target-specific 'long double's. We expect this work to be - completed in LLVM 2.2.
            • - -
          • LLVM now provides an LLVMBuilder class, which makes it significantly easier - to create LLVM IR instructions.
            • - -
          • Reid contributed support for intrinsics that take arbitrary integer typed - arguments. Dan Gohman and Chandler extended it to support arbitrary - floating point arguments and vectors.
            • +
          • Evan contributed support to the X86 backend to model the mod/ref behavior +of the EFLAGS register explicitly in all instructions. This gives more freedom +to the scheduler, and is a more explicit way to model the instructions.
            • +
          • Dale contributed support for exception handling on Darwin/PPC and he and +Anton got x86-64 working.
            • +
          • Evan turned on if-conversion by default for ARM, allowing LLVM to take +advantage of its predication features.
            • +
          • Bruno added PIC support to the MIPS backend, fixed many bugs and improved +support for architecture variants.
            • +
          • Arnold Schwaighofer added initial support for X86 tail calls.
            • +
          • Evan contributed several enhancements to Darwin/x86 debug information.
            • +
          • Duncan added x86-64 support for trampolines (pointers to nested functions).
          @@ -276,13 +320,18 @@

            -
          • Sterling Stein contributed a new BrainF frontend, located in llvm/examples. - This shows a some of the more modern APIs for building a front-end, and - demonstrates JIT compiler support.
            • - -
          • David Green contributed a new --enable-expensive-checks configure - option which enables STL checking, and fixed several bugs exposed by - it.
            • +
          • Gordon expanded and updated the LLVM Analysis and +Transformation Passes reference to include descriptions for each pass.
            • + +
          • We rewrote the lexer and parser used by TableGen to make them simpler +and cleaner. This gives tblgen support for 'caret diagnostics'. The .ll file +lexer was also rewritten to support caret diagnostics but doesn't use this +support yet.
            • + +
          • Dale has been grinding through the GCC testsuite, and marked many +LLVM-incompatible tests as not-to-be-run (for example, if they are grepping +through some GCC dump file that LLVM doesn't produce), he also found and fixed +many LLVM bugs exposed by the testsuite.
          @@ -300,9 +349,9 @@
          • Intel and AMD machines running Red Hat Linux, Fedora Core and FreeBSD (and probably other unix-like systems).
            • -
          • PowerPC and X86-based Mac OS X systems, running 10.2 and above in 32-bit and +
          • PowerPC and X86-based Mac OS X systems, running 10.3 and above in 32-bit and 64-bit modes.
            • -
          • Intel and AMD machines running on Win32 using MinGW libraries (native)
            • +
          • Intel and AMD machines running on Win32 using MinGW libraries (native).
          • Intel and AMD machines running on Win32 with the Cygwin libraries (limited support is available for native builds with Visual C++).
          • Sun UltraSPARC workstations running Solaris 8.
            • @@ -348,13 +397,12 @@ components, please contact us on the LLVMdev list.

              -
            • The -cee pass is known to be buggy, and may be removed in a - future release.
              • -
            • The MSIL backend is experimental.
              • -
            • The IA64 code generator is experimental.
              • -
            • The Alpha backend is experimental.
              • -
            • "-filetype=asm" (the default) is the only supported value for the - -filetype llc option.
              • +
            • The -cee pass is known to be buggy and will be removed in + LLVM 2.3.
              • +
            • The MSIL, IA64, Alpha, and MIPS backends are experimental.
              • +
            • The LLC "-filetype=asm" (the default) is the only supported + value for this option.
              • +
            • The llvmc tool is not supported.
          @@ -372,6 +420,8 @@
        2. The X86 backend occasionally has alignment problems on operating systems that don't require 16-byte stack alignment (including most non-darwin OS's like linux).
          3. +
        3. The X86 backend generates inefficient floating point code when configured to + generate code for systems that don't have SSE2.
      @@ -384,8 +434,6 @@
      @@ -405,7 +453,7 @@ results (PR1388).
    • Compilation for ARM Linux OABI (old ABI) is supported, but not fully tested.
      • -
    • There is a bug in QEMU-ARM (<= 0.9.0) which causes it to incorrectly execute +
    • There is a bug in QEMU-ARM (<= 0.9.0) which causes it to incorrectly execute programs compiled with LLVM. Please use more recent versions of QEMU.
    @@ -486,6 +534,7 @@
  • The C backend violates the ABI of common C++ programs, preventing intermixing between C++ compiled by the CBE and C++ code compiled with LLC or native compilers.
    • +
  • The C backend does not support all exception handling constructs.
    • @@ -496,13 +545,59 @@ Known problems with the C front-end + +
    + Known problems with the Ada front-end +
    + +
    +The llvm-gcc 4.2 Ada compiler works fairly well, however this is not a mature +technology and problems should be expected. + +
    + + +
    + Known problems with the Fortran front-end +
    + +
    + + +
    +
    Bugs
    -

    llvm-gcc4 does not currently support Link-Time -Optimization on most platforms "out-of-the-box". Please inquire on the +

    llvm-gcc does not currently support Link-Time +Optimization on most platforms "out-of-the-box". Please inquire on the llvmdev mailing list if you are interested.

    @@ -515,10 +610,6 @@
    @@ -681,7 +751,7 @@ Valid CSS! Valid HTML 4.01! + src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!"> LLVM Compiler Infrastructure
    Last modified: $Date$ From tonic at nondot.org Mon Feb 11 23:19:29 2008 From: tonic at nondot.org (Tanya Lattner) Date: Tue, 12 Feb 2008 05:19:29 -0000 Subject: [llvm-commits] [llvm] r46987 - /llvm/tags/RELEASE_22/ Message-ID: <200802120519.m1C5JTrE029641@zion.cs.uiuc.edu> Author: tbrethou Date: Mon Feb 11 23:19:29 2008 New Revision: 46987 URL: http://llvm.org/viewvc/llvm-project?rev=46987&view=rev Log: Tagging release 2.2. Added: llvm/tags/RELEASE_22/ - copied from r46986, llvm/branches/release_22/ From tonic at nondot.org Mon Feb 11 23:19:58 2008 From: tonic at nondot.org (Tanya Lattner) Date: Tue, 12 Feb 2008 05:19:58 -0000 Subject: [llvm-commits] [llvm-gcc-4.0] r46988 - /llvm-gcc-4.0/tags/RELEASE_22/ Message-ID: <200802120519.m1C5Jw0g029668@zion.cs.uiuc.edu> Author: tbrethou Date: Mon Feb 11 23:19:58 2008 New Revision: 46988 URL: http://llvm.org/viewvc/llvm-project?rev=46988&view=rev Log: Tag release 2.2 Added: llvm-gcc-4.0/tags/RELEASE_22/ - copied from r46987, llvm-gcc-4.0/branches/release_22/ From tonic at nondot.org Mon Feb 11 23:20:15 2008 From: tonic at nondot.org (Tanya Lattner) Date: Tue, 12 Feb 2008 05:20:15 -0000 Subject: [llvm-commits] [llvm-gcc-4.2] r46989 - /llvm-gcc-4.2/tags/RELEASE_22/ Message-ID: <200802120520.m1C5KFuj029701@zion.cs.uiuc.edu> Author: tbrethou Date: Mon Feb 11 23:20:15 2008 New Revision: 46989 URL: http://llvm.org/viewvc/llvm-project?rev=46989&view=rev Log: Tag release 2.2. Added: llvm-gcc-4.2/tags/RELEASE_22/ - copied from r46988, llvm-gcc-4.2/branches/release_22/ From tonic at nondot.org Mon Feb 11 23:20:47 2008 From: tonic at nondot.org (Tanya Lattner) Date: Tue, 12 Feb 2008 05:20:47 -0000 Subject: [llvm-commits] [test-suite] r46990 - /test-suite/tags/RELEASE_22/ Message-ID: <200802120520.m1C5Kl1w029726@zion.cs.uiuc.edu> Author: tbrethou Date: Mon Feb 11 23:20:47 2008 New Revision: 46990 URL: http://llvm.org/viewvc/llvm-project?rev=46990&view=rev Log: Tag release 2.2 Added: test-suite/tags/RELEASE_22/ - copied from r46989, test-suite/branches/release_22/ From tbrethou at cs.uiuc.edu Mon Feb 11 23:59:34 2008 From: tbrethou at cs.uiuc.edu (Tanya Lattner) Date: Mon, 11 Feb 2008 23:59:34 -0600 Subject: [llvm-commits] CVS: llvm-www/releases/2.2/ Message-ID: <200802120559.m1C5xY01008166@zion.cs.uiuc.edu> Changes in directory llvm-www/releases/2.2: --- Log message: Directory /var/cvs/llvm/llvm-www/releases/2.2 added to the repository --- Diffs of the changes: (+0 -0) 0 files changed From tbrethou at cs.uiuc.edu Mon Feb 11 23:59:42 2008 From: tbrethou at cs.uiuc.edu (Tanya Lattner) Date: Mon, 11 Feb 2008 23:59:42 -0600 Subject: [llvm-commits] CVS: llvm-www/releases/2.2/docs/ Message-ID: <200802120559.m1C5xgWX008190@zion.cs.uiuc.edu> Changes in directory llvm-www/releases/2.2/docs: --- Log message: Directory /var/cvs/llvm/llvm-www/releases/2.2/docs added to the repository --- Diffs of the changes: (+0 -0) 0 files changed From tbrethou at cs.uiuc.edu Tue Feb 12 00:01:27 2008 From: tbrethou at cs.uiuc.edu (Tanya Lattner) Date: Tue, 12 Feb 2008 00:01:27 -0600 Subject: [llvm-commits] CVS: llvm-www/releases/2.2/docs/CommandGuide/ Message-ID: <200802120601.m1C61R9b008278@zion.cs.uiuc.edu> Changes in directory llvm-www/releases/2.2/docs/CommandGuide: --- Log message: Directory /var/cvs/llvm/llvm-www/releases/2.2/docs/CommandGuide added to the repository --- Diffs of the changes: (+0 -0) 0 files changed From tbrethou at cs.uiuc.edu Tue Feb 12 00:01:39 2008 From: tbrethou at cs.uiuc.edu (Tanya Lattner) Date: Tue, 12 Feb 2008 00:01:39 -0600 Subject: [llvm-commits] CVS: llvm-www/releases/2.2/docs/CommandGuide/man/ Message-ID: <200802120601.m1C61dY3008342@zion.cs.uiuc.edu> Changes in directory llvm-www/releases/2.2/docs/CommandGuide/man: --- Log message: Directory /var/cvs/llvm/llvm-www/releases/2.2/docs/CommandGuide/man added to the repository --- Diffs of the changes: (+0 -0) 0 files changed From tbrethou at cs.uiuc.edu Tue Feb 12 00:01:39 2008 From: tbrethou at cs.uiuc.edu (Tanya Lattner) Date: Tue, 12 Feb 2008 00:01:39 -0600 Subject: [llvm-commits] CVS: llvm-www/releases/2.2/docs/CommandGuide/ps/ Message-ID: <200802120601.m1C61dOf008345@zion.cs.uiuc.edu> Changes in directory llvm-www/releases/2.2/docs/CommandGuide/ps: --- Log message: Directory /var/cvs/llvm/llvm-www/releases/2.2/docs/CommandGuide/ps added to the repository --- Diffs of the changes: (+0 -0) 0 files changed From tbrethou at cs.uiuc.edu Tue Feb 12 00:01:39 2008 From: tbrethou at cs.uiuc.edu (Tanya Lattner) Date: Tue, 12 Feb 2008 00:01:39 -0600 Subject: [llvm-commits] CVS: llvm-www/releases/2.2/docs/CommandGuide/html/ Message-ID: <200802120601.m1C61dfu008339@zion.cs.uiuc.edu> Changes in directory llvm-www/releases/2.2/docs/CommandGuide/html: --- Log message: Directory /var/cvs/llvm/llvm-www/releases/2.2/docs/CommandGuide/html added to the repository --- Diffs of the changes: (+0 -0) 0 files changed From tbrethou at cs.uiuc.edu Tue Feb 12 00:02:05 2008 From: tbrethou at cs.uiuc.edu (Tanya Lattner) Date: Tue, 12 Feb 2008 00:02:05 -0600 Subject: [llvm-commits] CVS: llvm-www/releases/2.2/docs/CommandGuide/man/man1/ Message-ID: <200802120602.m1C6257Z008382@zion.cs.uiuc.edu> Changes in directory llvm-www/releases/2.2/docs/CommandGuide/man/man1: --- Log message: Directory /var/cvs/llvm/llvm-www/releases/2.2/docs/CommandGuide/man/man1 added to the repository --- Diffs of the changes: (+0 -0) 0 files changed From tbrethou at cs.uiuc.edu Tue Feb 12 00:02:40 2008 From: tbrethou at cs.uiuc.edu (Tanya Lattner) Date: Tue, 12 Feb 2008 00:02:40 -0600 Subject: [llvm-commits] CVS: llvm-www/releases/2.2/docs/img/ Message-ID: <200802120602.m1C62edm008465@zion.cs.uiuc.edu> Changes in directory llvm-www/releases/2.2/docs/img: --- Log message: Directory /var/cvs/llvm/llvm-www/releases/2.2/docs/img added to the repository --- Diffs of the changes: (+0 -0) 0 files changed From tbrethou at cs.uiuc.edu Tue Feb 12 00:02:40 2008 From: tbrethou at cs.uiuc.edu (Tanya Lattner) Date: Tue, 12 Feb 2008 00:02:40 -0600 Subject: [llvm-commits] CVS: llvm-www/releases/2.2/docs/tutorial/ Message-ID: <200802120602.m1C62e8Q008468@zion.cs.uiuc.edu> Changes in directory llvm-www/releases/2.2/docs/tutorial: --- Log message: Directory /var/cvs/llvm/llvm-www/releases/2.2/docs/tutorial added to the repository --- Diffs of the changes: (+0 -0) 0 files changed From tbrethou at cs.uiuc.edu Tue Feb 12 00:02:40 2008 From: tbrethou at cs.uiuc.edu (Tanya Lattner) Date: Tue, 12 Feb 2008 00:02:40 -0600 Subject: [llvm-commits] CVS: llvm-www/releases/2.2/docs/HistoricalNotes/ Message-ID: <200802120602.m1C62eOd008462@zion.cs.uiuc.edu> Changes in directory llvm-www/releases/2.2/docs/HistoricalNotes: --- Log message: Directory /var/cvs/llvm/llvm-www/releases/2.2/docs/HistoricalNotes added to the repository --- Diffs of the changes: (+0 -0) 0 files changed From tonic at nondot.org Tue Feb 12 00:07:05 2008 From: tonic at nondot.org (Tanya Lattner) Date: Tue, 12 Feb 2008 00:07:05 -0600 Subject: [llvm-commits] CVS: llvm-www/releases/2.2/docs/img/Debugging.gif libdeps.gif lines.gif objdeps.gif venusflytrap.jpg Message-ID: <200802120607.m1C674ss008904@zion.cs.uiuc.edu> Changes in directory llvm-www/releases/2.2/docs/img: Debugging.gif added (r1.1) libdeps.gif added (r1.1) lines.gif added (r1.1) objdeps.gif added (r1.1) venusflytrap.jpg added (r1.1) --- Log message: Release 2.2 --- Diffs of the changes: (+0 -0) Debugging.gif | 0 libdeps.gif | 0 lines.gif | 0 objdeps.gif | 0 venusflytrap.jpg | 0 5 files changed Index: llvm-www/releases/2.2/docs/img/Debugging.gif Index: llvm-www/releases/2.2/docs/img/libdeps.gif Index: llvm-www/releases/2.2/docs/img/lines.gif Index: llvm-www/releases/2.2/docs/img/objdeps.gif Index: llvm-www/releases/2.2/docs/img/venusflytrap.jpg From tonic at nondot.org Tue Feb 12 00:07:05 2008 From: tonic at nondot.org (Tanya Lattner) Date: Tue, 12 Feb 2008 00:07:05 -0600 Subject: [llvm-commits] CVS: llvm-www/releases/2.2/docs/HistoricalNotes/2000-11-18-EarlyDesignIdeas.txt 2000-11-18-EarlyDesignIdeasResp.txt 2000-12-06-EncodingIdea.txt 2000-12-06-MeetingSummary.txt 2001-01-31-UniversalIRIdea.txt 2001-02-06-TypeNotationDebate.txt 2001-02-06-TypeNotationDebateResp1.txt 2001-02-06-TypeNotationDebateResp2.txt 2001-02-06-TypeNotationDebateResp4.txt 2001-02-09-AdveComments.txt 2001-02-09-AdveCommentsResponse.txt 2001-02-13-Reference-Memory.txt 2001-02-13-Reference-MemoryResponse.txt 2001-04-16-DynamicCompilation.txt 2001-05-18-ExceptionHandling.txt 2001-05-19-ExceptionResponse.txt 2001-06-01-GCCOptimizations.txt 2001-06-01-GCCOptimizations2.txt 2001-06-20-.NET-Differences.txt 2001-07-06-LoweringIRForCodeGen.txt 2001-07-08-InstructionSelection.txt 2001-07-08-InstructionSelection2.txt 2001-09-18-OptimizeExceptions.txt 2002-05-12-InstListChange.txt 2002-06-25-MegaPatchInfo.txt 2003-01-23-CygwinNotes.txt 2003-06-25-Reoptimizer1.txt 2003-06-26-Reoptimizer2.txt Message-ID: <200802120607.m1C674It009022@zion.cs.uiuc.edu> Changes in directory llvm-www/releases/2.2/docs/HistoricalNotes: 2000-11-18-EarlyDesignIdeas.txt added (r1.1) 2000-11-18-EarlyDesignIdeasResp.txt added (r1.1) 2000-12-06-EncodingIdea.txt added (r1.1) 2000-12-06-MeetingSummary.txt added (r1.1) 2001-01-31-UniversalIRIdea.txt added (r1.1) 2001-02-06-TypeNotationDebate.txt added (r1.1) 2001-02-06-TypeNotationDebateResp1.txt added (r1.1) 2001-02-06-TypeNotationDebateResp2.txt added (r1.1) 2001-02-06-TypeNotationDebateResp4.txt added (r1.1) 2001-02-09-AdveComments.txt added (r1.1) 2001-02-09-AdveCommentsResponse.txt added (r1.1) 2001-02-13-Reference-Memory.txt added (r1.1) 2001-02-13-Reference-MemoryResponse.txt added (r1.1) 2001-04-16-DynamicCompilation.txt added (r1.1) 2001-05-18-ExceptionHandling.txt added (r1.1) 2001-05-19-ExceptionResponse.txt added (r1.1) 2001-06-01-GCCOptimizations.txt added (r1.1) 2001-06-01-GCCOptimizations2.txt added (r1.1) 2001-06-20-.NET-Differences.txt added (r1.1) 2001-07-06-LoweringIRForCodeGen.txt added (r1.1) 2001-07-08-InstructionSelection.txt added (r1.1) 2001-07-08-InstructionSelection2.txt added (r1.1) 2001-09-18-OptimizeExceptions.txt added (r1.1) 2002-05-12-InstListChange.txt added (r1.1) 2002-06-25-MegaPatchInfo.txt added (r1.1) 2003-01-23-CygwinNotes.txt added (r1.1) 2003-06-25-Reoptimizer1.txt added (r1.1) 2003-06-26-Reoptimizer2.txt added (r1.1) --- Log message: Release 2.2 --- Diffs of the changes: (+2185 -0) 2000-11-18-EarlyDesignIdeas.txt | 74 +++++++++ 2000-11-18-EarlyDesignIdeasResp.txt | 199 +++++++++++++++++++++++++ 2000-12-06-EncodingIdea.txt | 30 +++ 2000-12-06-MeetingSummary.txt | 83 ++++++++++ 2001-01-31-UniversalIRIdea.txt | 39 +++++ 2001-02-06-TypeNotationDebate.txt | 67 ++++++++ 2001-02-06-TypeNotationDebateResp1.txt | 75 +++++++++ 2001-02-06-TypeNotationDebateResp2.txt | 53 ++++++ 2001-02-06-TypeNotationDebateResp4.txt | 89 +++++++++++ 2001-02-09-AdveComments.txt | 120 +++++++++++++++ 2001-02-09-AdveCommentsResponse.txt | 245 ++++++++++++++++++++++++++++++++ 2001-02-13-Reference-Memory.txt | 39 +++++ 2001-02-13-Reference-MemoryResponse.txt | 47 ++++++ 2001-04-16-DynamicCompilation.txt | 49 ++++++ 2001-05-18-ExceptionHandling.txt | 202 ++++++++++++++++++++++++++ 2001-05-19-ExceptionResponse.txt | 45 +++++ 2001-06-01-GCCOptimizations.txt | 63 ++++++++ 2001-06-01-GCCOptimizations2.txt | 71 +++++++++ 2001-06-20-.NET-Differences.txt | 30 +++ 2001-07-06-LoweringIRForCodeGen.txt | 31 ++++ 2001-07-08-InstructionSelection.txt | 51 ++++++ 2001-07-08-InstructionSelection2.txt | 25 +++ 2001-09-18-OptimizeExceptions.txt | 56 +++++++ 2002-05-12-InstListChange.txt | 55 +++++++ 2002-06-25-MegaPatchInfo.txt | 72 +++++++++ 2003-01-23-CygwinNotes.txt | 28 +++ 2003-06-25-Reoptimizer1.txt | 137 +++++++++++++++++ 2003-06-26-Reoptimizer2.txt | 110 ++++++++++++++ 28 files changed, 2185 insertions(+) Index: llvm-www/releases/2.2/docs/HistoricalNotes/2000-11-18-EarlyDesignIdeas.txt diff -c /dev/null llvm-www/releases/2.2/docs/HistoricalNotes/2000-11-18-EarlyDesignIdeas.txt:1.1 *** /dev/null Tue Feb 12 00:05:36 2008 --- llvm-www/releases/2.2/docs/HistoricalNotes/2000-11-18-EarlyDesignIdeas.txt Tue Feb 12 00:05:26 2008 *************** *** 0 **** --- 1,74 ---- + Date: Sat, 18 Nov 2000 09:19:35 -0600 (CST) + From: Vikram Adve + To: Chris Lattner + Subject: a few thoughts + + I've been mulling over the virtual machine problem and I had some + thoughts about some things for us to think about discuss: + + 1. We need to be clear on our goals for the VM. Do we want to emphasize + portability and safety like the Java VM? Or shall we focus on the + architecture interface first (i.e., consider the code generation and + processor issues), since the architecture interface question is also + important for portable Java-type VMs? + + This is important because the audiences for these two goals are very + different. Architects and many compiler people care much more about + the second question. The Java compiler and OS community care much more + about the first one. + + Also, while the architecture interface question is important for + Java-type VMs, the design constraints are very different. + + + 2. Design issues to consider (an initial list that we should continue + to modify). Note that I'm not trying to suggest actual solutions here, + but just various directions we can pursue: + + a. A single-assignment VM, which we've both already been thinking about. + + b. A strongly-typed VM. One question is do we need the types to be + explicitly declared or should they be inferred by the dynamic compiler? + + c. How do we get more high-level information into the VM while keeping + to a low-level VM design? + + o Explicit array references as operands? An alternative is + to have just an array type, and let the index computations be + separate 3-operand instructions. + + o Explicit instructions to handle aliasing, e.g.s: + -- an instruction to say "I speculate that these two values are not + aliased, but check at runtime", like speculative execution in + EPIC? + -- or an instruction to check whether two values are aliased and + execute different code depending on the answer, somewhat like + predicated code in EPIC + + o (This one is a difficult but powerful idea.) + A "thread-id" field on every instruction that allows the static + compiler to generate a set of parallel threads, and then have + the runtime compiler and hardware do what they please with it. + This has very powerful uses, but thread-id on every instruction + is expensive in terms of instruction size and code size. + We would need to compactly encode it somehow. + + Also, this will require some reading on at least two other + projects: + -- Multiscalar architecture from Wisconsin + -- Simultaneous multithreading architecture from Washington + + o Or forget all this and stick to a traditional instruction set? + + + BTW, on an unrelated note, after the meeting yesterday, I did remember + that you had suggested doing instruction scheduling on SSA form instead + of a dependence DAG earlier in the semester. When we talked about + it yesterday, I didn't remember where the idea had come from but I + remembered later. Just giving credit where its due... + + Perhaps you can save the above as a file under RCS so you and I can + continue to expand on this. + + --Vikram + Index: llvm-www/releases/2.2/docs/HistoricalNotes/2000-11-18-EarlyDesignIdeasResp.txt diff -c /dev/null llvm-www/releases/2.2/docs/HistoricalNotes/2000-11-18-EarlyDesignIdeasResp.txt:1.1 *** /dev/null Tue Feb 12 00:06:59 2008 --- llvm-www/releases/2.2/docs/HistoricalNotes/2000-11-18-EarlyDesignIdeasResp.txt Tue Feb 12 00:05:26 2008 *************** *** 0 **** --- 1,199 ---- + Date: Sun, 19 Nov 2000 16:23:57 -0600 (CST) + From: Chris Lattner + To: Vikram Adve + Subject: Re: a few thoughts + + Okay... here are a few of my thoughts on this (it's good to know that we + think so alike!): + + > 1. We need to be clear on our goals for the VM. Do we want to emphasize + > portability and safety like the Java VM? Or shall we focus on the + > architecture interface first (i.e., consider the code generation and + > processor issues), since the architecture interface question is also + > important for portable Java-type VMs? + + I forsee the architecture looking kinda like this: (which is completely + subject to change) + + 1. The VM code is NOT guaranteed safe in a java sense. Doing so makes it + basically impossible to support C like languages. Besides that, + certifying a register based language as safe at run time would be a + pretty expensive operation to have to do. Additionally, we would like + to be able to statically eliminate many bounds checks in Java + programs... for example. + + 2. Instead, we can do the following (eventually): + * Java bytecode is used as our "safe" representation (to avoid + reinventing something that we don't add much value to). When the + user chooses to execute Java bytecodes directly (ie, not + precompiled) the runtime compiler can do some very simple + transformations (JIT style) to convert it into valid input for our + VM. Performance is not wonderful, but it works right. + * The file is scheduled to be compiled (rigorously) at a later + time. This could be done by some background process or by a second + processor in the system during idle time or something... + * To keep things "safe" ie to enforce a sandbox on Java/foreign code, + we could sign the generated VM code with a host specific private + key. Then before the code is executed/loaded, we can check to see if + the trusted compiler generated the code. This would be much quicker + than having to validate consistency (especially if bounds checks have + been removed, for example) + + > This is important because the audiences for these two goals are very + > different. Architects and many compiler people care much more about + > the second question. The Java compiler and OS community care much more + > about the first one. + + 3. By focusing on a more low level virtual machine, we have much more room + for value add. The nice safe "sandbox" VM can be provided as a layer + on top of it. It also lets us focus on the more interesting compilers + related projects. + + > 2. Design issues to consider (an initial list that we should continue + > to modify). Note that I'm not trying to suggest actual solutions here, + > but just various directions we can pursue: + + Understood. :) + + > a. A single-assignment VM, which we've both already been thinking + > about. + + Yup, I think that this makes a lot of sense. I am still intrigued, + however, by the prospect of a minimally allocated VM representation... I + think that it could have definate advantages for certain applications + (think very small machines, like PDAs). I don't, however, think that our + initial implementations should focus on this. :) + + Here are some other auxilliary goals that I think we should consider: + + 1. Primary goal: Support a high performance dynamic compilation + system. This means that we have an "ideal" division of labor between + the runtime and static compilers. Of course, the other goals of the + system somewhat reduce the importance of this point (f.e. portability + reduces performance, but hopefully not much) + 2. Portability to different processors. Since we are most familiar with + x86 and solaris, I think that these two are excellent candidates when + we get that far... + 3. Support for all languages & styles of programming (general purpose + VM). This is the point that disallows java style bytecodes, where all + array refs are checked for bounds, etc... + 4. Support linking between different language families. For example, call + C functions directly from Java without using the nasty/slow/gross JNI + layer. This involves several subpoints: + A. Support for languages that require garbage collectors and integration + with languages that don't. As a base point, we could insist on + always using a conservative GC, but implement free as a noop, f.e. + + > b. A strongly-typed VM. One question is do we need the types to be + > explicitly declared or should they be inferred by the dynamic + > compiler? + + B. This is kind of similar to another idea that I have: make OOP + constructs (virtual function tables, class heirarchies, etc) explicit + in the VM representation. I believe that the number of additional + constructs would be fairly low, but would give us lots of important + information... something else that would/could be important is to + have exceptions as first class types so that they would be handled in + a uniform way for the entire VM... so that C functions can call Java + functions for example... + + > c. How do we get more high-level information into the VM while keeping + > to a low-level VM design? + > o Explicit array references as operands? An alternative is + > to have just an array type, and let the index computations be + > separate 3-operand instructions. + + C. In the model I was thinking of (subject to change of course), we + would just have an array type (distinct from the pointer + types). This would allow us to have arbitrarily complex index + expressions, while still distinguishing "load" from "Array load", + for example. Perhaps also, switch jump tables would be first class + types as well? This would allow better reasoning about the program. + + 5. Support dynamic loading of code from various sources. Already + mentioned above was the example of loading java bytecodes, but we want + to support dynamic loading of VM code as well. This makes the job of + the runtime compiler much more interesting: it can do interprocedural + optimizations that the static compiler can't do, because it doesn't + have all of the required information (for example, inlining from + shared libraries, etc...) + + 6. Define a set of generally useful annotations to add to the VM + representation. For example, a function can be analysed to see if it + has any sideeffects when run... also, the MOD/REF sets could be + calculated, etc... we would have to determine what is reasonable. This + would generally be used to make IP optimizations cheaper for the + runtime compiler... + + > o Explicit instructions to handle aliasing, e.g.s: + > -- an instruction to say "I speculate that these two values are not + > aliased, but check at runtime", like speculative execution in + > EPIC? + > -- or an instruction to check whether two values are aliased and + > execute different code depending on the answer, somewhat like + > predicated code in EPIC + + These are also very good points... if this can be determined at compile + time. I think that an epic style of representation (not the instruction + packing, just the information presented) could be a very interesting model + to use... more later... + + > o (This one is a difficult but powerful idea.) + > A "thread-id" field on every instruction that allows the static + > compiler to generate a set of parallel threads, and then have + > the runtime compiler and hardware do what they please with it. + > This has very powerful uses, but thread-id on every instruction + > is expensive in terms of instruction size and code size. + > We would need to compactly encode it somehow. + + Yes yes yes! :) I think it would be *VERY* useful to include this kind + of information (which EPIC architectures *implicitly* encode. The trend + that we are seeing supports this greatly: + + 1. Commodity processors are getting massive SIMD support: + * Intel/Amd MMX/MMX2 + * AMD's 3Dnow! + * Intel's SSE/SSE2 + * Sun's VIS + 2. SMP is becoming much more common, especially in the server space. + 3. Multiple processors on a die are right around the corner. + + If nothing else, not designing this in would severely limit our future + expansion of the project... + + > Also, this will require some reading on at least two other + > projects: + > -- Multiscalar architecture from Wisconsin + > -- Simultaneous multithreading architecture from Washington + > + > o Or forget all this and stick to a traditional instruction set? + + Heh... :) Well, from a pure research point of view, it is almost more + attactive to go with the most extreme/different ISA possible. On one axis + you get safety and conservatism, and on the other you get degree of + influence that the results have. Of course the problem with pure research + is that often times there is no concrete product of the research... :) + + > BTW, on an unrelated note, after the meeting yesterday, I did remember + > that you had suggested doing instruction scheduling on SSA form instead + > of a dependence DAG earlier in the semester. When we talked about + > it yesterday, I didn't remember where the idea had come from but I + > remembered later. Just giving credit where its due... + + :) Thanks. + + > Perhaps you can save the above as a file under RCS so you and I can + > continue to expand on this. + + I think it makes sense to do so when we get our ideas more formalized and + bounce it back and forth a couple of times... then I'll do a more formal + writeup of our goals and ideas. Obviously our first implementation will + not want to do all of the stuff that I pointed out above... be we will + want to design the project so that we do not artificially limit ourselves + at sometime in the future... + + Anyways, let me know what you think about these ideas... and if they sound + reasonable... + + -Chris + Index: llvm-www/releases/2.2/docs/HistoricalNotes/2000-12-06-EncodingIdea.txt diff -c /dev/null llvm-www/releases/2.2/docs/HistoricalNotes/2000-12-06-EncodingIdea.txt:1.1 *** /dev/null Tue Feb 12 00:06:59 2008 --- llvm-www/releases/2.2/docs/HistoricalNotes/2000-12-06-EncodingIdea.txt Tue Feb 12 00:05:26 2008 *************** *** 0 **** --- 1,30 ---- + From: Chris Lattner [mailto:sabre at nondot.org] + Sent: Wednesday, December 06, 2000 6:41 PM + To: Vikram S. Adve + Subject: Additional idea with respect to encoding + + Here's another idea with respect to keeping the common case instruction + size down (less than 32 bits ideally): + + Instead of encoding an instruction to operate on two register numbers, + have it operate on two negative offsets based on the current register + number. Therefore, instead of using: + + r57 = add r55, r56 (r57 is the implicit dest register, of course) + + We could use: + + r57 = add -2, -1 + + My guess is that most SSA references are to recent values (especially if + they correspond to expressions like (x+y*z+p*q/ ...), so the negative + numbers would tend to stay small, even at the end of the procedure (where + the implicit register destination number could be quite large). Of course + the negative sign is reduntant, so you would be storing small integers + almost all of the time, and 5-6 bits worth of register number would be + plenty for most cases... + + What do you think? + + -Chris + Index: llvm-www/releases/2.2/docs/HistoricalNotes/2000-12-06-MeetingSummary.txt diff -c /dev/null llvm-www/releases/2.2/docs/HistoricalNotes/2000-12-06-MeetingSummary.txt:1.1 *** /dev/null Tue Feb 12 00:06:59 2008 --- llvm-www/releases/2.2/docs/HistoricalNotes/2000-12-06-MeetingSummary.txt Tue Feb 12 00:05:26 2008 *************** *** 0 **** --- 1,83 ---- + SUMMARY + ------- + + We met to discuss the LLVM instruction format and bytecode representation: + + ISSUES RESOLVED + --------------- + + 1. We decided that we shall use a flat namespace to represent our + variables in SSA form, as opposed to having a two dimensional namespace + of the original variable and the SSA instance subscript. + + ARGUMENT AGAINST: + * A two dimensional namespace would be valuable when doing alias + analysis because the extra information can help limit the scope of + analysis. + + ARGUMENT FOR: + * Including this information would require that all users of the LLVM + bytecode would have to parse and handle it. This would slow down the + common case and inflate the instruction representation with another + infinite variable space. + + REASONING: + * It was decided that because original variable sources could be + reconstructed from SSA form in linear time, that it would be an + unjustified expense for the common case to include the extra + information for one optimization. Alias analysis itself is typically + greater than linear in asymptotic complexity, so this extra analaysis + would not affect the runtime of the optimization in a significant + way. Additionally, this would be an unlikely optimization to do at + runtime. + + + IDEAS TO CONSIDER + ----------------- + + 1. Including dominator information in the LLVM bytecode + representation. This is one example of an analysis result that may be + packaged with the bytecodes themselves. As a conceptual implementation + idea, we could include an immediate dominator number for each basic block + in the LLVM bytecode program. Basic blocks could be numbered according + to the order of occurance in the bytecode representation. + + 2. Including loop header and body information. This would facilitate + detection of intervals and natural loops. + + UNRESOLVED ISSUES + ----------------- + + 1. Will oSUIF provide enough of an infrastructure to support the research + that we will be doing? We know that it has less than stellar + performance, but hope that this will be of little importance for our + static compiler. This could affect us if we decided to do some IP + research. Also we do not yet understand the level of exception support + currently implemented. + + 2. Should we consider the requirements of a direct hardware implementation + of the LLVM when we design it? If so, several design issues should + have their priorities shifted. The other option is to focus on a + software layer interpreting the LLVM in all cases. + + 3. Should we use some form of packetized format to improve forward + compatibility? For example, we could design the system to encode a + packet type and length field before analysis information, to allow a + runtime to skip information that it didn't understand in a bytecode + stream. The obvious benefit would be for compatibility, the drawback + is that it would tend to splinter that 'standard' LLVM definition. + + 4. Should we use fixed length instructions or variable length + instructions? Fetching variable length instructions is expensive (for + either hardware or software based LLVM runtimes), but we have several + 'infinite' spaces that instructions operate in (SSA register numbers, + type spaces, or packet length [if packets were implemented]). Several + options were mentioned including: + A. Using 16 or 32 bit numbers, which would be 'big enough' + B. A scheme similar to how UTF-8 works, to encode infinite numbers + while keeping small number small. + C. Use something similar to Huffman encoding, so that the most common + numbers are the smallest. + + -Chris + Index: llvm-www/releases/2.2/docs/HistoricalNotes/2001-01-31-UniversalIRIdea.txt diff -c /dev/null llvm-www/releases/2.2/docs/HistoricalNotes/2001-01-31-UniversalIRIdea.txt:1.1 *** /dev/null Tue Feb 12 00:06:59 2008 --- llvm-www/releases/2.2/docs/HistoricalNotes/2001-01-31-UniversalIRIdea.txt Tue Feb 12 00:05:26 2008 *************** *** 0 **** --- 1,39 ---- + Date: Wed, 31 Jan 2001 12:04:33 -0600 + From: Vikram S. Adve + To: Chris Lattner + Subject: another thought + + I have a budding idea about making LLVM a little more ambitious: a + customizable runtime system that can be used to implement language-specific + virtual machines for many different languages. E.g., a C vm, a C++ vm, a + Java vm, a Lisp vm, .. + + The idea would be that LLVM would provide a standard set of runtime features + (some low-level like standard assembly instructions with code generation and + static and runtime optimization; some higher-level like type-safety and + perhaps a garbage collection library). Each language vm would select the + runtime features needed for that language, extending or customizing them as + needed. Most of the machine-dependent code-generation and optimization + features as well as low-level machine-independent optimizations (like PRE) + could be provided by LLVM and should be sufficient for any language, + simplifying the language compiler. (This would also help interoperability + between languages.) Also, some or most of the higher-level + machine-independent features like type-safety and access safety should be + reusable by different languages, with minor extensions. The language + compiler could then focus on language-specific analyses and optimizations. + + The risk is that this sounds like a universal IR -- something that the + compiler community has tried and failed to develop for decades, and is + universally skeptical about. No matter what we say, we won't be able to + convince anyone that we have a universal IR that will work. We need to + think about whether LLVM is different or if has something novel that might + convince people. E.g., the idea of providing a package of separable + features that different languages select from. Also, using SSA with or + without type-safety as the intermediate representation. + + One interesting starting point would be to discuss how a JVM would be + implemented on top of LLVM a bit more. That might give us clues on how to + structure LLVM to support one or more language VMs. + + --Vikram + Index: llvm-www/releases/2.2/docs/HistoricalNotes/2001-02-06-TypeNotationDebate.txt diff -c /dev/null llvm-www/releases/2.2/docs/HistoricalNotes/2001-02-06-TypeNotationDebate.txt:1.1 *** /dev/null Tue Feb 12 00:06:59 2008 --- llvm-www/releases/2.2/docs/HistoricalNotes/2001-02-06-TypeNotationDebate.txt Tue Feb 12 00:05:26 2008 *************** *** 0 **** --- 1,67 ---- + Date: Tue, 6 Feb 2001 20:27:37 -0600 (CST) + From: Chris Lattner + To: Vikram S. Adve + Subject: Type notation debate... + + This is the way that I am currently planning on implementing types: + + Primitive Types: + type ::= void|bool|sbyte|ubyte|short|ushort|int|uint|long|ulong + + Method: + typelist ::= typelisth | /*empty*/ + typelisth ::= type | typelisth ',' type + type ::= type (typelist) + + Arrays (without and with size): + type ::= '[' type ']' | '[' INT ',' type ']' + + Pointer: + type ::= type '*' + + Structure: + type ::= '{' typelist '}' + + Packed: + type ::= '<' INT ',' type '>' + + Simple examples: + + [[ %4, int ]] - array of (array of 4 (int)) + [ { int, int } ] - Array of structure + [ < %4, int > ] - Array of 128 bit SIMD packets + int (int, [[int, %4]]) - Method taking a 2d array and int, returning int + + + Okay before you comment, please look at: + + http://www.research.att.com/~bs/devXinterview.html + + Search for "In another interview, you defined the C declarator syntax as + an experiment that failed. However, this syntactic construct has been + around for 27 years and perhaps more; why do you consider it problematic + (except for its cumbersome syntax)?" and read that response for me. :) + + Now with this syntax, his example would be represented as: + + [ %10, bool (int, int) * ] * + + vs + + bool (*(*)[10])(int, int) + + in C. + + Basically, my argument for this type construction system is that it is + VERY simple to use and understand (although it IS different than C, it is + very simple and straightforward, which C is NOT). In fact, I would assert + that most programmers TODAY do not understand pointers to member + functions, and have to look up an example when they have to write them. + + In my opinion, it is critically important to have clear and concise type + specifications, because types are going to be all over the programs. + + Let me know your thoughts on this. :) + + -Chris + Index: llvm-www/releases/2.2/docs/HistoricalNotes/2001-02-06-TypeNotationDebateResp1.txt diff -c /dev/null llvm-www/releases/2.2/docs/HistoricalNotes/2001-02-06-TypeNotationDebateResp1.txt:1.1 *** /dev/null Tue Feb 12 00:06:59 2008 --- llvm-www/releases/2.2/docs/HistoricalNotes/2001-02-06-TypeNotationDebateResp1.txt Tue Feb 12 00:05:26 2008 *************** *** 0 **** --- 1,75 ---- + Date: Thu, 8 Feb 2001 08:42:04 -0600 + From: Vikram S. Adve + To: Chris Lattner + Subject: RE: Type notation debate... + + Chris, + + > Okay before you comment, please look at: + > + > http://www.research.att.com/~bs/devXinterview.html + + I read this argument. Even before that, I was already in agreement with you + and him that the C declarator syntax is difficult and confusing. + + But in fact, if you read the entire answer carefully, he came to the same + conclusion I do: that you have to go with familiar syntax over logical + syntax because familiarity is such a strong force: + + "However, familiarity is a strong force. To compare, in English, we + live + more or less happily with the absurd rules for "to be" (am, are, is, been, + was, were, ...) and all attempts to simplify are treated with contempt or + (preferably) humor. It be a curious world and it always beed." + + > Basically, my argument for this type construction system is that it is + > VERY simple to use and understand (although it IS different than C, it is + > very simple and straightforward, which C is NOT). In fact, I would assert + > that most programmers TODAY do not understand pointers to member + > functions, and have to look up an example when they have to write them. + + Again, I don't disagree with this at all. But to some extent this + particular problem is inherently difficult. Your syntax for the above + example may be easier for you to read because this is the way you have been + thinking about it. Honestly, I don't find it much easier than the C syntax. + In either case, I would have to look up an example to write pointers to + member functions. + + But pointers to member functions are nowhere near as common as arrays. And + the old array syntax: + type [ int, int, ...] + is just much more familiar and clear to people than anything new you + introduce, no matter how logical it is. Introducing a new syntax that may + make function pointers easier but makes arrays much more difficult seems + very risky to me. + + > In my opinion, it is critically important to have clear and concise type + > specifications, because types are going to be all over the programs. + + I absolutely agree. But the question is, what is more clear and concise? + The syntax programmers are used to out of years of experience or a new + syntax that they have never seen that has a more logical structure. I think + the answer is the former. Sometimes, you have to give up a better idea + because you can't overcome sociological barriers to it. Qwerty keyboards + and Windows are two classic examples of bad technology that are difficult to + root out. + + P.S. Also, while I agree that most your syntax is more logical, there is + one part that isn't: + + Arrays (without and with size): + type ::= '[' type ']' | '[' INT ',' type ']'. + + The arrays with size lists the dimensions and the type in a single list. + That is just too confusing: + [10, 40, int] + This seems to be a 3-D array where the third dimension is something strange. + It is too confusing to have a list of 3 things, some of which are dimensions + and one is a type. Either of the following would be better: + + array [10, 40] of int + or + int [10, 40] + + --Vikram + Index: llvm-www/releases/2.2/docs/HistoricalNotes/2001-02-06-TypeNotationDebateResp2.txt diff -c /dev/null llvm-www/releases/2.2/docs/HistoricalNotes/2001-02-06-TypeNotationDebateResp2.txt:1.1 *** /dev/null Tue Feb 12 00:07:00 2008 --- llvm-www/releases/2.2/docs/HistoricalNotes/2001-02-06-TypeNotationDebateResp2.txt Tue Feb 12 00:05:26 2008 *************** *** 0 **** --- 1,53 ---- + Date: Thu, 8 Feb 2001 14:31:05 -0600 (CST) + From: Chris Lattner + To: Vikram S. Adve + Subject: RE: Type notation debate... + + > Arrays (without and with size): + > type ::= '[' type ']' | '[' INT ',' type ']'. + > + > The arrays with size lists the dimensions and the type in a single list. + > That is just too confusing: + + > [10, 40, int] + > This seems to be a 3-D array where the third dimension is something strange. + > It is too confusing to have a list of 3 things, some of which are dimensions + > and one is a type. + + The above grammar indicates that there is only one integer parameter, ie + the upper bound. The lower bound is always implied to be zero, for + several reasons: + + * As a low level VM, we want to expose addressing computations + explicitly. Since the lower bound must always be known in a high level + language statically, the language front end can do the translation + automatically. + * This fits more closely with what Java needs, ie what we need in the + short term. Java arrays are always zero based. + + If a two element list is too confusing, I would recommend an alternate + syntax of: + + type ::= '[' type ']' | '[' INT 'x' type ']'. + + For example: + [12 x int] + [12x int] + [ 12 x [ 4x int ]] + + Which is syntactically nicer, and more explicit. + + > Either of the following would be better: + > array [10, 40] of int + + I considered this approach for arrays in general (ie array of int/ array + of 12 int), but found that it made declarations WAY too long. Remember + that because of the nature of llvm, you get a lot of types strewn all over + the program, and using the 'typedef' like facility is not a wonderful + option, because then types aren't explicit anymore. + + I find this email interesting, because you contradict the previous email + you sent, where you recommend that we stick to C syntax.... + + -Chris + Index: llvm-www/releases/2.2/docs/HistoricalNotes/2001-02-06-TypeNotationDebateResp4.txt diff -c /dev/null llvm-www/releases/2.2/docs/HistoricalNotes/2001-02-06-TypeNotationDebateResp4.txt:1.1 *** /dev/null Tue Feb 12 00:07:00 2008 --- llvm-www/releases/2.2/docs/HistoricalNotes/2001-02-06-TypeNotationDebateResp4.txt Tue Feb 12 00:05:26 2008 *************** *** 0 **** --- 1,89 ---- + > But in fact, if you read the entire answer carefully, he came to the same + > conclusion I do: that you have to go with familiar syntax over logical + > syntax because familiarity is such a strong force: + > "However, familiarity is a strong force. To compare, in English, we + live + > more or less happily with the absurd rules for "to be" (am, are, is, been, + > was, were, ...) and all attempts to simplify are treated with contempt or + > (preferably) humor. It be a curious world and it always beed." + + Although you have to remember that his situation was considerably + different than ours. He was in a position where he was designing a high + level language that had to be COMPATIBLE with C. Our language is such + that a new person would have to learn the new, different, syntax + anyways. Making them learn about the type system does not seem like much + of a stretch from learning the opcodes and how SSA form works, and how + everything ties together... + + > > Basically, my argument for this type construction system is that it is + > > VERY simple to use and understand (although it IS different than C, it is + > > very simple and straightforward, which C is NOT). In fact, I would assert + > > that most programmers TODAY do not understand pointers to member + > > functions, and have to look up an example when they have to write them. + + > Again, I don't disagree with this at all. But to some extent this + > particular problem is inherently difficult. Your syntax for the above + > example may be easier for you to read because this is the way you have been + > thinking about it. Honestly, I don't find it much easier than the C syntax. + > In either case, I would have to look up an example to write pointers to + > member functions. + + I would argue that because the lexical structure of the language is self + consistent, any person who spent a significant amount of time programming + in LLVM directly would understand how to do it without looking it up in a + manual. The reason this does not work for C is because you rarely have to + declare these pointers, and the syntax is inconsistent with the method + declaration and calling syntax. + + > But pointers to member functions are nowhere near as common as arrays. + + Very true. If you're implementing an object oriented language, however, + remember that you have to do all the pointer to member function stuff + yourself.... so everytime you invoke a virtual method one is involved + (instead of having C++ hide it for you behind "syntactic sugar"). + + > And the old array syntax: + > type [ int, int, ...] + > is just much more familiar and clear to people than anything new you + > introduce, no matter how logical it is. + + Erm... excuse me but how is this the "old array syntax"? If you are + arguing for consistency with C, you should be asking for 'type int []', + which is significantly different than the above (beside the above + introduces a new operator and duplicates information + needlessly). Basically what I am suggesting is exactly the above without + the fluff. So instead of: + + type [ int, int, ...] + + you use: + + type [ int ] + + > Introducing a new syntax that may + > make function pointers easier but makes arrays much more difficult seems + > very risky to me. + + This is not about function pointers. This is about consistency in the + type system, and consistency with the rest of the language. The point + above does not make arrays any more difficult to use, and makes the + structure of types much more obvious than the "c way". + + > > In my opinion, it is critically important to have clear and concise type + > > specifications, because types are going to be all over the programs. + > + > I absolutely agree. But the question is, what is more clear and concise? + > The syntax programmers are used to out of years of experience or a new + > syntax that they have never seen that has a more logical structure. I think + > the answer is the former. Sometimes, you have to give up a better idea + > because you can't overcome sociological barriers to it. Qwerty keyboards + > and Windows are two classic examples of bad technology that are difficult to + > root out. + + Very true, but you seem to be advocating a completely different Type + system than C has, in addition to it not offering the advantages of clear + structure that the system I recommended does... so you seem to not have a + problem with changing this, just with what I change it to. :) + + -Chris + Index: llvm-www/releases/2.2/docs/HistoricalNotes/2001-02-09-AdveComments.txt diff -c /dev/null llvm-www/releases/2.2/docs/HistoricalNotes/2001-02-09-AdveComments.txt:1.1 *** /dev/null Tue Feb 12 00:07:00 2008 --- llvm-www/releases/2.2/docs/HistoricalNotes/2001-02-09-AdveComments.txt Tue Feb 12 00:05:26 2008 *************** *** 0 **** --- 1,120 ---- + Ok, here are my comments and suggestions about the LLVM instruction set. + We should discuss some now, but can discuss many of them later, when we + revisit synchronization, type inference, and other issues. + (We have discussed some of the comments already.) + + + o We should consider eliminating the type annotation in cases where it is + essentially obvious from the instruction type, e.g., in br, it is obvious + that the first arg. should be a bool and the other args should be labels: + + br bool , label , label + + I think your point was that making all types explicit improves clarity + and readability. I agree to some extent, but it also comes at the cost + of verbosity. And when the types are obvious from people's experience + (e.g., in the br instruction), it doesn't seem to help as much. + + + o On reflection, I really like your idea of having the two different switch + types (even though they encode implementation techniques rather than + semantics). It should simplify building the CFG and my guess is it could + enable some significant optimizations, though we should think about which. + + + o In the lookup-indirect form of the switch, is there a reason not to make + the val-type uint? Most HLL switch statements (including Java and C++) + require that anyway. And it would also make the val-type uniform + in the two forms of the switch. + + I did see the switch-on-bool examples and, while cute, we can just use + the branch instructions in that particular case. + + + o I agree with your comment that we don't need 'neg'. + + + o There's a trade-off with the cast instruction: + + it avoids having to define all the upcasts and downcasts that are + valid for the operands of each instruction (you probably have thought + of other benefits also) + - it could make the bytecode significantly larger because there could + be a lot of cast operations + + + o Making the second arg. to 'shl' a ubyte seems good enough to me. + 255 positions seems adequate for several generations of machines + and is more compact than uint. + + + o I still have some major concerns about including malloc and free in the + language (either as builtin functions or instructions). LLVM must be + able to represent code from many different languages. Languages such as + C, C++ Java and Fortran 90 would not be able to use our malloc anyway + because each of them will want to provide a library implementation of it. + + This gets even worse when code from different languages is linked + into a single executable (which is fairly common in large apps). + Having a single malloc would just not suffice, and instead would simply + complicate the picture further because it adds an extra variant in + addition to the one each language provides. + + Instead, providing a default library version of malloc and free + (and perhaps a malloc_gc with garbage collection instead of free) + would make a good implementation available to anyone who wants it. + + I don't recall all your arguments in favor so let's discuss this again, + and soon. + + + o 'alloca' on the other hand sounds like a good idea, and the + implementation seems fairly language-independent so it doesn't have the + problems with malloc listed above. + + + o About indirect call: + Your option #2 sounded good to me. I'm not sure I understand your + concern about an explicit 'icall' instruction? + + + o A pair of important synchronization instr'ns to think about: + load-linked + store-conditional + + + o Other classes of instructions that are valuable for pipeline performance: + conditional-move + predicated instructions + + + o I believe tail calls are relatively easy to identify; do you know why + .NET has a tailcall instruction? + + + o I agree that we need a static data space. Otherwise, emulating global + data gets unnecessarily complex. + + + o About explicit parallelism: + + We once talked about adding a symbolic thread-id field to each + instruction. (It could be optional so single-threaded codes are + not penalized.) This could map well to multi-threaded architectures + while providing easy ILP for single-threaded onces. But it is probably + too radical an idea to include in a base version of LLVM. Instead, it + could a great topic for a separate study. + + What is the semantics of the IA64 stop bit? + + + + + o And finally, another thought about the syntax for arrays :-) + + Although this syntax: + array of + is verbose, it will be used only in the human-readable assembly code so + size should not matter. I think we should consider it because I find it + to be the clearest syntax. It could even make arrays of function + pointers somewhat readable. + Index: llvm-www/releases/2.2/docs/HistoricalNotes/2001-02-09-AdveCommentsResponse.txt diff -c /dev/null llvm-www/releases/2.2/docs/HistoricalNotes/2001-02-09-AdveCommentsResponse.txt:1.1 *** /dev/null Tue Feb 12 00:07:01 2008 --- llvm-www/releases/2.2/docs/HistoricalNotes/2001-02-09-AdveCommentsResponse.txt Tue Feb 12 00:05:26 2008 *************** *** 0 **** --- 1,245 ---- + From: Chris Lattner + To: "Vikram S. Adve" + Subject: Re: LLVM Feedback + + I've included your feedback in the /home/vadve/lattner/llvm/docs directory + so that it will live in CVS eventually with the rest of LLVM. I've + significantly updated the documentation to reflect the changes you + suggested, as specified below: + + > We should consider eliminating the type annotation in cases where it is + > essentially obvious from the instruction type: + > br bool , label , label + > I think your point was that making all types explicit improves clarity + > and readability. I agree to some extent, but it also comes at the + > cost of verbosity. And when the types are obvious from people's + > experience (e.g., in the br instruction), it doesn't seem to help as + > much. + + Very true. We should discuss this more, but my reasoning is more of a + consistency argument. There are VERY few instructions that can have all + of the types eliminated, and doing so when available unnecesarily makes + the language more difficult to handle. Especially when you see 'int + %this' and 'bool %that' all over the place, I think it would be + disorienting to see: + + br %predicate, %iftrue, %iffalse + + for branches. Even just typing that once gives me the creeps. ;) Like I + said, we should probably discuss this further in person... + + > On reflection, I really like your idea of having the two different + > switch types (even though they encode implementation techniques rather + > than semantics). It should simplify building the CFG and my guess is it + > could enable some significant optimizations, though we should think + > about which. + + Great. I added a note to the switch section commenting on how the VM + should just use the instruction type as a hint, and that the + implementation may choose altermate representations (such as predicated + branches). + + > In the lookup-indirect form of the switch, is there a reason not to + > make the val-type uint? + + No. This was something I was debating for a while, and didn't really feel + strongly about either way. It is common to switch on other types in HLL's + (for example signed int's are particually common), but in this case, all + that will be added is an additional 'cast' instruction. I removed that + from the spec. + + > I agree with your comment that we don't need 'neg' + + Removed. + + > There's a trade-off with the cast instruction: + > + it avoids having to define all the upcasts and downcasts that are + > valid for the operands of each instruction (you probably have + > thought of other benefits also) + > - it could make the bytecode significantly larger because there could + > be a lot of cast operations + + + You NEED casts to represent things like: + void foo(float); + ... + int x; + ... + foo(x); + in a language like C. Even in a Java like language, you need upcasts + and some way to implement dynamic downcasts. + + Not all forms of instructions take every type (for example you can't + shift by a floating point number of bits), thus SOME programs will need + implicit casts. + + To be efficient and to avoid your '-' point above, we just have to be + careful to specify that the instructions shall operate on all common + types, therefore casting should be relatively uncommon. For example all + of the arithmetic operations work on almost all data types. + + > Making the second arg. to 'shl' a ubyte seems good enough to me. + > 255 positions seems adequate for several generations of machines + + Okay, that comment is removed. + + > and is more compact than uint. + + No, it isn't. Remember that the bytecode encoding saves value slots into + the bytecode instructions themselves, not constant values. This is + another case where we may introduce more cast instructions (but we will + also reduce the number of opcode variants that must be supported by a + virtual machine). Because most shifts are by constant values, I don't + think that we'll have to cast many shifts. :) + + > I still have some major concerns about including malloc and free in the + > language (either as builtin functions or instructions). + + Agreed. How about this proposal: + + malloc/free are either built in functions or actual opcodes. They provide + all of the type safety that the document would indicate, blah blah + blah. :) + + Now, because of all of the excellent points that you raised, an + implementation may want to override the default malloc/free behavior of + the program. To do this, they simply implement a "malloc" and + "free" function. The virtual machine will then be defined to use the user + defined malloc/free function (which return/take void*'s, not type'd + pointers like the builtin function would) if one is available, otherwise + fall back on a system malloc/free. + + Does this sound like a good compromise? It would give us all of the + typesafety/elegance in the language while still allowing the user to do + all the cool stuff they want to... + + > 'alloca' on the other hand sounds like a good idea, and the + > implementation seems fairly language-independent so it doesn't have the + > problems with malloc listed above. + + Okay, once we get the above stuff figured out, I'll put it all in the + spec. + + > About indirect call: + > Your option #2 sounded good to me. I'm not sure I understand your + > concern about an explicit 'icall' instruction? + + I worry too much. :) The other alternative has been removed. 'icall' is + now up in the instruction list next to 'call'. + + > I believe tail calls are relatively easy to identify; do you know why + > .NET has a tailcall instruction? + + Although I am just guessing, I believe it probably has to do with the fact + that they want languages like Haskell and lisp to be efficiently runnable + on their VM. Of course this means that the VM MUST implement tail calls + 'correctly', or else life will suck. :) I would put this into a future + feature bin, because it could be pretty handy... + + > A pair of important synchronization instr'ns to think about: + > load-linked + > store-conditional + + What is 'load-linked'? I think that (at least for now) I should add these + to the 'possible extensions' section, because they are not immediately + needed... + + > Other classes of instructions that are valuable for pipeline + > performance: + > conditional-move + > predicated instructions + + Conditional move is effectly a special case of a predicated + instruction... and I think that all predicated instructions can possibly + be implemented later in LLVM. It would significantly change things, and + it doesn't seem to be very necessary right now. It would seem to + complicate flow control analysis a LOT in the virtual machine. I would + tend to prefer that a predicated architecture like IA64 convert from a + "basic block" representation to a predicated rep as part of it's dynamic + complication phase. Also, if a basic block contains ONLY a move, then + that can be trivally translated into a conditional move... + + > I agree that we need a static data space. Otherwise, emulating global + > data gets unnecessarily complex. + + Definately. Also a later item though. :) + + > We once talked about adding a symbolic thread-id field to each + > .. + > Instead, it could a great topic for a separate study. + + Agreed. :) + + > What is the semantics of the IA64 stop bit? + + Basically, the IA64 writes instructions like this: + mov ... + add ... + sub ... + op xxx + op xxx + ;; + mov ... + add ... + sub ... + op xxx + op xxx + ;; + + Where the ;; delimits a group of instruction with no dependencies between + them, which can all be executed concurrently (to the limits of the + available functional units). The ;; gets translated into a bit set in one + of the opcodes. + + The advantages of this representation is that you don't have to do some + kind of 'thread id scheduling' pass by having to specify ahead of time how + many threads to use, and the representation doesn't have a per instruction + overhead... + + > And finally, another thought about the syntax for arrays :-) + > Although this syntax: + > array of + > is verbose, it will be used only in the human-readable assembly code so + > size should not matter. I think we should consider it because I find it + > to be the clearest syntax. It could even make arrays of function + > pointers somewhat readable. + + My only comment will be to give you an example of why this is a bad + idea. :) + + Here is an example of using the switch statement (with my recommended + syntax): + + switch uint %val, label %otherwise, + [%3 x {uint, label}] [ { uint %57, label %l1 }, + { uint %20, label %l2 }, + { uint %14, label %l3 } ] + + Here it is with the syntax you are proposing: + + switch uint %val, label %otherwise, + array %3 of {uint, label} + array of {uint, label} + { uint %57, label %l1 }, + { uint %20, label %l2 }, + { uint %14, label %l3 } + + Which is ambiguous and very verbose. It would be possible to specify + constants with [] brackets as in my syntax, which would look like this: + + switch uint %val, label %otherwise, + array %3 of {uint, label} [ { uint %57, label %l1 }, + { uint %20, label %l2 }, + { uint %14, label %l3 } ] + + But then the syntax is inconsistent between type definition and constant + definition (why do []'s enclose the constants but not the types??). + + Anyways, I'm sure that there is much debate still to be had over + this... :) + + -Chris + + http://www.nondot.org/~sabre/os/ + http://www.nondot.org/MagicStats/ + http://korbit.sourceforge.net/ + + Index: llvm-www/releases/2.2/docs/HistoricalNotes/2001-02-13-Reference-Memory.txt diff -c /dev/null llvm-www/releases/2.2/docs/HistoricalNotes/2001-02-13-Reference-Memory.txt:1.1 *** /dev/null Tue Feb 12 00:07:02 2008 --- llvm-www/releases/2.2/docs/HistoricalNotes/2001-02-13-Reference-Memory.txt Tue Feb 12 00:05:26 2008 *************** *** 0 **** --- 1,39 ---- + Date: Tue, 13 Feb 2001 13:29:52 -0600 (CST) + From: Chris Lattner + To: Vikram S. Adve + Subject: LLVM Concerns... + + + I've updated the documentation to include load store and allocation + instructions (please take a look and let me know if I'm on the right + track): + + file:/home/vadve/lattner/llvm/docs/LangRef.html#memoryops + + I have a couple of concerns I would like to bring up: + + 1. Reference types + Right now, I've spec'd out the language to have a pointer type, which + works fine for lots of stuff... except that Java really has + references: constrained pointers that cannot be manipulated: added and + subtracted, moved, etc... Do we want to have a type like this? It + could be very nice for analysis (pointer always points to the start of + an object, etc...) and more closely matches Java semantics. The + pointer type would be kept for C++ like semantics. Through analysis, + C++ pointers could be promoted to references in the LLVM + representation. + + 2. Our "implicit" memory references in assembly language: + After thinking about it, this model has two problems: + A. If you do pointer analysis and realize that two stores are + independent and can share the same memory source object, there is + no way to represent this in either the bytecode or assembly. + B. When parsing assembly/bytecode, we effectively have to do a full + SSA generation/PHI node insertion pass to build the dependencies + when we don't want the "pinned" representation. This is not + cool. + I'm tempted to make memory references explicit in both the assembly and + bytecode to get around this... what do you think? + + -Chris + Index: llvm-www/releases/2.2/docs/HistoricalNotes/2001-02-13-Reference-MemoryResponse.txt diff -c /dev/null llvm-www/releases/2.2/docs/HistoricalNotes/2001-02-13-Reference-MemoryResponse.txt:1.1 *** /dev/null Tue Feb 12 00:07:02 2008 --- llvm-www/releases/2.2/docs/HistoricalNotes/2001-02-13-Reference-MemoryResponse.txt Tue Feb 12 00:05:26 2008 *************** *** 0 **** --- 1,47 ---- + Date: Tue, 13 Feb 2001 18:25:42 -0600 + From: Vikram S. Adve + To: Chris Lattner + Subject: RE: LLVM Concerns... + + > 1. Reference types + > Right now, I've spec'd out the language to have a pointer type, which + > works fine for lots of stuff... except that Java really has + > references: constrained pointers that cannot be manipulated: added and + > subtracted, moved, etc... Do we want to have a type like this? It + > could be very nice for analysis (pointer always points to the start of + > an object, etc...) and more closely matches Java semantics. The + > pointer type would be kept for C++ like semantics. Through analysis, + > C++ pointers could be promoted to references in the LLVM + > representation. + + + You're right, having references would be useful. Even for C++ the *static* + compiler could generate references instead of pointers with fairly + straightforward analysis. Let's include a reference type for now. But I'm + also really concerned that LLVM is becoming big and complex and (perhaps) + too high-level. After we get some initial performance results, we may have + a clearer idea of what our goals should be and we should revisit this + question then. + + > 2. Our "implicit" memory references in assembly language: + > After thinking about it, this model has two problems: + > A. If you do pointer analysis and realize that two stores are + > independent and can share the same memory source object, + + not sure what you meant by "share the same memory source object" + + > there is + > no way to represent this in either the bytecode or assembly. + > B. When parsing assembly/bytecode, we effectively have to do a full + > SSA generation/PHI node insertion pass to build the dependencies + > when we don't want the "pinned" representation. This is not + > cool. + + I understand the concern. But again, let's focus on the performance first + and then look at the language design issues. E.g., it would be good to know + how big the bytecode files are before expanding them further. I am pretty + keen to explore the implications of LLVM for mobile devices. Both bytecode + size and power consumption are important to consider there. + + --Vikram + Index: llvm-www/releases/2.2/docs/HistoricalNotes/2001-04-16-DynamicCompilation.txt diff -c /dev/null llvm-www/releases/2.2/docs/HistoricalNotes/2001-04-16-DynamicCompilation.txt:1.1 *** /dev/null Tue Feb 12 00:07:02 2008 --- llvm-www/releases/2.2/docs/HistoricalNotes/2001-04-16-DynamicCompilation.txt Tue Feb 12 00:05:26 2008 *************** *** 0 **** --- 1,49 ---- + By Chris: + + LLVM has been designed with two primary goals in mind. First we strive to + enable the best possible division of labor between static and dynamic + compilers, and second, we need a flexible and powerful interface + between these two complementary stages of compilation. We feel that + providing a solution to these two goals will yield an excellent solution + to the performance problem faced by modern architectures and programming + languages. + + A key insight into current compiler and runtime systems is that a + compiler may fall in anywhere in a "continuum of compilation" to do its + job. On one side, scripting languages statically compile nothing and + dynamically compile (or equivalently, interpret) everything. On the far + other side, traditional static compilers process everything statically and + nothing dynamically. These approaches have typically been seen as a + tradeoff between performance and portability. On a deeper level, however, + there are two reasons that optimal system performance may be obtained by a + system somewhere in between these two extremes: Dynamic application + behavior and social constraints. + + From a technical perspective, pure static compilation cannot ever give + optimal performance in all cases, because applications have varying dynamic + behavior that the static compiler cannot take into consideration. Even + compilers that support profile guided optimization generate poor code in + the real world, because using such optimization tunes that application + to one particular usage pattern, whereas real programs (as opposed to + benchmarks) often have several different usage patterns. + + On a social level, static compilation is a very shortsighted solution to + the performance problem. Instruction set architectures (ISAs) continuously + evolve, and each implementation of an ISA (a processor) must choose a set + of tradeoffs that make sense in the market context that it is designed for. + With every new processor introduced, the vendor faces two fundamental + problems: First, there is a lag time between when a processor is introduced + to when compilers generate quality code for the architecture. Secondly, + even when compilers catch up to the new architecture there is often a large + body of legacy code that was compiled for previous generations and will + not or can not be upgraded. Thus a large percentage of code running on a + processor may be compiled quite sub-optimally for the current + characteristics of the dynamic execution environment. + + For these reasons, LLVM has been designed from the beginning as a long-term + solution to these problems. Its design allows the large body of platform + independent, static, program optimizations currently in compilers to be + reused unchanged in their current form. It also provides important static + type information to enable powerful dynamic and link time optimizations + to be performed quickly and efficiently. This combination enables an + increase in effective system performance for real world environments. Index: llvm-www/releases/2.2/docs/HistoricalNotes/2001-05-18-ExceptionHandling.txt diff -c /dev/null llvm-www/releases/2.2/docs/HistoricalNotes/2001-05-18-ExceptionHandling.txt:1.1 *** /dev/null Tue Feb 12 00:07:03 2008 --- llvm-www/releases/2.2/docs/HistoricalNotes/2001-05-18-ExceptionHandling.txt Tue Feb 12 00:05:26 2008 *************** *** 0 **** --- 1,202 ---- + Meeting notes: Implementation idea: Exception Handling in C++/Java + + The 5/18/01 meeting discussed ideas for implementing exceptions in LLVM. + We decided that the best solution requires a set of library calls provided by + the VM, as well as an extension to the LLVM function invocation syntax. + + The LLVM function invocation instruction previously looks like this (ignoring + types): + + call func(arg1, arg2, arg3) + + The extension discussed today adds an optional "with" clause that + associates a label with the call site. The new syntax looks like this: + + call func(arg1, arg2, arg3) with funcCleanup + + This funcHandler always stays tightly associated with the call site (being + encoded directly into the call opcode itself), and should be used whenever + there is cleanup work that needs to be done for the current function if + an exception is thrown by func (or if we are in a try block). + + To support this, the VM/Runtime provide the following simple library + functions (all syntax in this document is very abstract): + + typedef struct { something } %frame; + The VM must export a "frame type", that is an opaque structure used to + implement different types of stack walking that may be used by various + language runtime libraries. We imagine that it would be typical to + represent a frame with a PC and frame pointer pair, although that is not + required. + + %frame getStackCurrentFrame(); + Get a frame object for the current function. Note that if the current + function was inlined into its caller, the "current" frame will belong to + the "caller". + + bool isFirstFrame(%frame f); + Returns true if the specified frame is the top level (first activated) frame + for this thread. For the main thread, this corresponds to the main() + function, for a spawned thread, it corresponds to the thread function. + + %frame getNextFrame(%frame f); + Return the previous frame on the stack. This function is undefined if f + satisfies the predicate isFirstFrame(f). + + Label *getFrameLabel(%frame f); + If a label was associated with f (as discussed below), this function returns + it. Otherwise, it returns a null pointer. + + doNonLocalBranch(Label *L); + At this point, it is not clear whether this should be a function or + intrinsic. It should probably be an intrinsic in LLVM, but we'll deal with + this issue later. + + + Here is a motivating example that illustrates how these facilities could be + used to implement the C++ exception model: + + void TestFunction(...) { + A a; B b; + foo(); // Any function call may throw + bar(); + C c; + + try { + D d; + baz(); + } catch (int) { + ...int Stuff... + // execution continues after the try block: the exception is consumed + } catch (double) { + ...double stuff... + throw; // Exception is propogated + } + } + + This function would compile to approximately the following code (heavy + pseudo code follows): + + Func: + %a = alloca A + A::A(%a) // These ctors & dtors could throw, but we ignore this + %b = alloca B // minor detail for this example + B::B(%b) + + call foo() with fooCleanup // An exception in foo is propogated to fooCleanup + call bar() with barCleanup // An exception in bar is propogated to barCleanup + + %c = alloca C + C::C(c) + %d = alloca D + D::D(d) + call baz() with bazCleanup // An exception in baz is propogated to bazCleanup + d->~D(); + EndTry: // This label corresponds to the end of the try block + c->~C() // These could also throw, these are also ignored + b->~B() + a->~A() + return + + Note that this is a very straight forward and literal translation: exactly + what we want for zero cost (when unused) exception handling. Especially on + platforms with many registers (ie, the IA64) setjmp/longjmp style exception + handling is *very* impractical. Also, the "with" clauses describe the + control flow paths explicitly so that analysis is not adversly effected. + + The foo/barCleanup labels are implemented as: + + TryCleanup: // Executed if an exception escapes the try block + c->~C() + barCleanup: // Executed if an exception escapes from bar() + // fall through + fooCleanup: // Executed if an exception escapes from foo() + b->~B() + a->~A() + Exception *E = getThreadLocalException() + call throw(E) // Implemented by the C++ runtime, described below + + Which does the work one would expect. getThreadLocalException is a function + implemented by the C++ support library. It returns the current exception + object for the current thread. Note that we do not attempt to recycle the + shutdown code from before, because performance of the mainline code is + critically important. Also, obviously fooCleanup and barCleanup may be + merged and one of them eliminated. This just shows how the code generator + would most likely emit code. + + The bazCleanup label is more interesting. Because the exception may be caught + by the try block, we must dispatch to its handler... but it does not exist + on the call stack (it does not have a VM Call->Label mapping installed), so + we must dispatch statically with a goto. The bazHandler thus appears as: + + bazHandler: + d->~D(); // destruct D as it goes out of scope when entering catch clauses + goto TryHandler + + In general, TryHandler is not the same as bazHandler, because multiple + function calls could be made from the try block. In this case, trivial + optimization could merge the two basic blocks. TryHandler is the code + that actually determines the type of exception, based on the Exception object + itself. For this discussion, assume that the exception object contains *at + least*: + + 1. A pointer to the RTTI info for the contained object + 2. A pointer to the dtor for the contained object + 3. The contained object itself + + Note that it is necessary to maintain #1 & #2 in the exception object itself + because objects without virtual function tables may be thrown (as in this + example). Assuming this, TryHandler would look something like this: + + TryHandler: + Exception *E = getThreadLocalException(); + switch (E->RTTIType) { + case IntRTTIInfo: + ...int Stuff... // The action to perform from the catch block + break; + case DoubleRTTIInfo: + ...double Stuff... // The action to perform from the catch block + goto TryCleanup // This catch block rethrows the exception + break; // Redundant, eliminated by the optimizer + default: + goto TryCleanup // Exception not caught, rethrow + } + + // Exception was consumed + if (E->dtor) + E->dtor(E->object) // Invoke the dtor on the object if it exists + goto EndTry // Continue mainline code... + + And that is all there is to it. + + The throw(E) function would then be implemented like this (which may be + inlined into the caller through standard optimization): + + function throw(Exception *E) { + // Get the start of the stack trace... + %frame %f = call getStackCurrentFrame() + + // Get the label information that corresponds to it + label * %L = call getFrameLabel(%f) + while (%L == 0 && !isFirstFrame(%f)) { + // Loop until a cleanup handler is found + %f = call getNextFrame(%f) + %L = call getFrameLabel(%f) + } + + if (%L != 0) { + call setThreadLocalException(E) // Allow handlers access to this... + call doNonLocalBranch(%L) + } + // No handler found! + call BlowUp() // Ends up calling the terminate() method in use + } + + That's a brief rundown of how C++ exception handling could be implemented in + llvm. Java would be very similar, except it only uses destructors to unlock + synchronized blocks, not to destroy data. Also, it uses two stack walks: a + nondestructive walk that builds a stack trace, then a destructive walk that + unwinds the stack as shown here. + + It would be trivial to get exception interoperability between C++ and Java. + Index: llvm-www/releases/2.2/docs/HistoricalNotes/2001-05-19-ExceptionResponse.txt diff -c /dev/null llvm-www/releases/2.2/docs/HistoricalNotes/2001-05-19-ExceptionResponse.txt:1.1 *** /dev/null Tue Feb 12 00:07:03 2008 --- llvm-www/releases/2.2/docs/HistoricalNotes/2001-05-19-ExceptionResponse.txt Tue Feb 12 00:05:26 2008 *************** *** 0 **** --- 1,45 ---- + Date: Sat, 19 May 2001 19:09:13 -0500 (CDT) + From: Chris Lattner + To: Vikram S. Adve + Subject: RE: Meeting writeup + + > I read it through and it looks great! + + Thanks! + + > The finally clause in Java may need more thought. The code for this clause + > is like a subroutine because it needs to be entered from many points (end of + > try block and beginning of each catch block), and then needs to *return to + > the place from where the code was entered*. That's why JVM has the + > jsr/jsr_w instruction. + + Hrm... I guess that is an implementation decision. It can either be + modelled as a subroutine (as java bytecodes do), which is really + gross... or it can be modelled as code duplication (emitted once inline, + then once in the exception path). Because this could, at worst, + slightly less than double the amount of code in a function (it is + bounded) I don't think this is a big deal. One of the really nice things + about the LLVM representation is that it still allows for runtime code + generation for exception paths (exceptions paths are not compiled until + needed). Obviously a static compiler couldn't do this though. :) + + In this case, only one copy of the code would be compiled... until the + other one is needed on demand. Also this strategy fits with the "zero + cost" exception model... the standard case is not burdened with extra + branches or "call"s. + + > I suppose you could save the return address in a particular register + > (specific to this finally block), jump to the finally block, and then at the + > end of the finally block, jump back indirectly through this register. It + > will complicate building the CFG but I suppose that can be handled. It is + > also unsafe in terms of checking where control returns (which is I suppose + > why the JVM doesn't use this). + + I think that a code duplication method would be cleaner, and would avoid + the caveats that you mention. Also, it does not slow down the normal case + with an indirect branch... + + Like everything, we can probably defer a final decision until later. :) + + -Chris + Index: llvm-www/releases/2.2/docs/HistoricalNotes/2001-06-01-GCCOptimizations.txt diff -c /dev/null llvm-www/releases/2.2/docs/HistoricalNotes/2001-06-01-GCCOptimizations.txt:1.1 *** /dev/null Tue Feb 12 00:07:03 2008 --- llvm-www/releases/2.2/docs/HistoricalNotes/2001-06-01-GCCOptimizations.txt Tue Feb 12 00:05:26 2008 *************** *** 0 **** --- 1,63 ---- + Date: Fri, 1 Jun 2001 16:38:17 -0500 (CDT) + From: Chris Lattner + To: Vikram S. Adve + Subject: Interesting: GCC passes + + + Take a look at this document (which describes the order of optimizations + that GCC performs): + + http://gcc.gnu.org/onlinedocs/gcc_17.html + + The rundown is that after RTL generation, the following happens: + + 1 . [t] jump optimization (jumps to jumps, etc) + 2 . [t] Delete unreachable code + 3 . Compute live ranges for CSE + 4 . [t] Jump threading (jumps to jumps with identical or inverse conditions) + 5 . [t] CSE + 6 . *** Conversion to SSA + 7 . [t] SSA Based DCE + 8 . *** Conversion to LLVM + 9 . UnSSA + 10. GCSE + 11. LICM + 12. Strength Reduction + 13. Loop unrolling + 14. [t] CSE + 15. [t] DCE + 16. Instruction combination, register movement, scheduling... etc. + + I've marked optimizations with a [t] to indicate things that I believe to + be relatively trivial to implement in LLVM itself. The time consuming + things to reimplement would be SSA based PRE, Strength reduction & loop + unrolling... these would be the major things we would miss out on if we + did LLVM creation from tree code [inlining and other high level + optimizations are done on the tree representation]. + + Given the lack of "strong" optimizations that would take a long time to + reimplement, I am leaning a bit more towards creating LLVM from the tree + code. Especially given that SGI has GPL'd their compiler, including many + SSA based optimizations that could be adapted (besides the fact that their + code looks MUCH nicer than GCC :) + + Even if we choose to do LLVM code emission from RTL, we will almost + certainly want to move LLVM emission from step 8 down until at least CSE + has been rerun... which causes me to wonder if the SSA generation code + will still work (due to global variable dependencies and stuff). I assume + that it can be made to work, but might be a little more involved than we + would like. + + I'm continuing to look at the Tree -> RTL code. It is pretty gross + because they do some of the translation a statement at a time, and some + of it a function at a time... I'm not quite clear why and how the + distinction is drawn, but it does not appear that there is a wonderful + place to attach extra info. + + Anyways, I'm proceeding with the RTL -> LLVM conversion phase for now. We + can talk about this more on Monday. + + Wouldn't it be nice if there were a obvious decision to be made? :) + + -Chris + Index: llvm-www/releases/2.2/docs/HistoricalNotes/2001-06-01-GCCOptimizations2.txt diff -c /dev/null llvm-www/releases/2.2/docs/HistoricalNotes/2001-06-01-GCCOptimizations2.txt:1.1 *** /dev/null Tue Feb 12 00:07:03 2008 --- llvm-www/releases/2.2/docs/HistoricalNotes/2001-06-01-GCCOptimizations2.txt Tue Feb 12 00:05:26 2008 *************** *** 0 **** --- 1,71 ---- + Date: Fri, 1 Jun 2001 17:08:44 -0500 (CDT) + From: Chris Lattner + To: Vikram S. Adve + Subject: RE: Interesting: GCC passes + + > That is very interesting. I agree that some of these could be done on LLVM + > at link-time, but it is the extra time required that concerns me. Link-time + > optimization is severely time-constrained. + + If we were to reimplement any of these optimizations, I assume that we + could do them a translation unit at a time, just as GCC does now. This + would lead to a pipeline like this: + + Static optimizations, xlation unit at a time: + .c --GCC--> .llvm --llvmopt--> .llvm + + Link time optimizations: + .llvm --llvm-ld--> .llvm --llvm-link-opt--> .llvm + + Of course, many optimizations could be shared between llvmopt and + llvm-link-opt, but the wouldn't need to be shared... Thus compile time + could be faster, because we are using a "smarter" IR (SSA based). + + > BTW, about SGI, "borrowing" SSA-based optimizations from one compiler and + > putting it into another is not necessarily easier than re-doing it. + > Optimization code is usually heavily tied in to the specific IR they use. + + Understood. The only reason that I brought this up is because SGI's IR is + more similar to LLVM than it is different in many respects (SSA based, + relatively low level, etc), and could be easily adapted. Also their + optimizations are written in C++ and are actually somewhat + structured... of course it would be no walk in the park, but it would be + much less time consuming to adapt, say, SSA-PRE than to rewrite it. + + > But your larger point is valid that adding SSA based optimizations is + > feasible and should be fun. (Again, link time cost is the issue.) + + Assuming linktime cost wasn't an issue, the question is: + Does using GCC's backend buy us anything? + + > It also occurs to me that GCC is probably doing quite a bit of back-end + > optimization (step 16 in your list). Do you have a breakdown of that? + + Not really. The irritating part of GCC is that it mixes it all up and + doesn't have a clean seperation of concerns. A lot of the "back end + optimization" happens right along with other data optimizations (ie, CSE + of machine specific things). + + As far as REAL back end optimizations go, it looks something like this: + + 1. Instruction combination: try to make CISCy instructions, if available + 2. Register movement: try to get registers in the right places for the + architecture to avoid register to register moves. For example, try to get + the first argument of a function to naturally land in %o0 for sparc. + 3. Instruction scheduling: 'nuff said :) + 4. Register class preferencing: ?? + 5. Local register allocation + 6. global register allocation + 7. Spilling + 8. Local regalloc + 9. Jump optimization + 10. Delay slot scheduling + 11. Branch shorting for CISC machines + 12. Instruction selection & peephole optimization + 13. Debug info output + + But none of this would be usable for LLVM anyways, unless we were using + GCC as a static compiler. + + -Chris + Index: llvm-www/releases/2.2/docs/HistoricalNotes/2001-06-20-.NET-Differences.txt diff -c /dev/null llvm-www/releases/2.2/docs/HistoricalNotes/2001-06-20-.NET-Differences.txt:1.1 *** /dev/null Tue Feb 12 00:07:03 2008 --- llvm-www/releases/2.2/docs/HistoricalNotes/2001-06-20-.NET-Differences.txt Tue Feb 12 00:05:26 2008 *************** *** 0 **** --- 1,30 ---- + Date: Wed, 20 Jun 2001 12:32:22 -0500 + From: Vikram Adve + To: Chris Lattner + Subject: .NET vs. our VM + + One significant difference between .NET CLR and our VM is that the CLR + includes full information about classes and inheritance. In fact, I just + sat through the paper on adding templates to .NET CLR, and the speaker + indicated that the goal seems to be to do simple static compilation (very + little lowering or optimization). Also, the templates implementation in CLR + "relies on dynamic class loading and JIT compilation". + + This is an important difference because I think there are some significant + advantages to have a much lower level VM layer, and do significant static + analysis and optimization. + + I also talked to the lead guy for KAI's C++ compiler (Arch Robison) and he + said that SGI and other commercial compilers have included options to export + their *IR* next to the object code (i.e., .il files) and use them for + link-time code generation. In fact, he said that the .o file was nearly + empty and was entirely generated from the .il at link-time. But he agreed + that this limited the link-time interprocedural optimization to modules + compiled by the same compiler, whereas our approach allows us to link and + optimize modules from multiple different compilers. (Also, of course, they + don't do anything for runtime optimization). + + All issues to bring up in Related Work. + + --Vikram + Index: llvm-www/releases/2.2/docs/HistoricalNotes/2001-07-06-LoweringIRForCodeGen.txt diff -c /dev/null llvm-www/releases/2.2/docs/HistoricalNotes/2001-07-06-LoweringIRForCodeGen.txt:1.1 *** /dev/null Tue Feb 12 00:07:03 2008 --- llvm-www/releases/2.2/docs/HistoricalNotes/2001-07-06-LoweringIRForCodeGen.txt Tue Feb 12 00:05:26 2008 *************** *** 0 **** --- 1,31 ---- + Date: Fri, 6 Jul 2001 16:56:56 -0500 + From: Vikram S. Adve + To: Chris Lattner + Subject: lowering the IR + + BTW, I do think that we should consider lowering the IR as you said. I + didn't get time to raise it today, but it comes up with the SPARC + move-conditional instruction. I don't think we want to put that in the core + VM -- it is a little too specialized. But without a corresponding + conditional move instruction in the VM, it is pretty difficult to maintain a + close mapping between VM and machine code. Other architectures may have + other such instructions. + + What I was going to suggest was that for a particular processor, we define + additional VM instructions that match some of the unusual opcodes on the + processor but have VM semantics otherwise, i.e., all operands are in SSA + form and typed. This means that we can re-generate core VM code from the + more specialized code any time we want (so that portability is not lost). + + Typically, a static compiler like gcc would generate just the core VM, which + is relatively portable. Anyone (an offline tool, the linker, etc., or even + the static compiler itself if it chooses) can transform that into more + specialized target-specific VM code for a particular architecture. If the + linker does it, it can do it after all machine-independent optimizations. + This would be the most convenient, but not necessary. + + The main benefit of lowering will be that we will be able to retain a close + mapping between VM and machine code. + + --Vikram + Index: llvm-www/releases/2.2/docs/HistoricalNotes/2001-07-08-InstructionSelection.txt diff -c /dev/null llvm-www/releases/2.2/docs/HistoricalNotes/2001-07-08-InstructionSelection.txt:1.1 *** /dev/null Tue Feb 12 00:07:03 2008 --- llvm-www/releases/2.2/docs/HistoricalNotes/2001-07-08-InstructionSelection.txt Tue Feb 12 00:05:26 2008 *************** *** 0 **** --- 1,51 ---- + Date: Sun, 8 Jul 2001 09:37:22 -0500 + From: Vikram S. Adve + To: Ruchira Sasanka + Cc: Chris Lattner + Subject: machine instruction operands + + Ruchira, + + When generating machine instructions, I have to make several choices about + operands. For cases were a register is required, there are 3 cases: + + 1. The register is for a Value* that is already in the VM code. + + 2. The register is for a value that is not in the VM code, usually because 2 + machine instructions get generated for a single VM instruction (and the + register holds the result of the first m/c instruction and is used by the + second m/c instruction). + + 3. The register is a pre-determined machine register. + + E.g, for this VM instruction: + ptr = alloca type, numElements + I have to generate 2 machine instructions: + reg = mul constant, numElements + ptr = add %sp, reg + + Each machine instruction is of class MachineInstr. + It has a vector of operands. All register operands have type MO_REGISTER. + The 3 types of register operands are marked using this enum: + + enum VirtualRegisterType { + MO_VMVirtualReg, // virtual register for *value + MO_MInstrVirtualReg, // virtual register for result of *minstr + MO_MachineReg // pre-assigned machine register `regNum' + } vregType; + + Here's how this affects register allocation: + + 1. MO_VMVirtualReg is the standard case: you just do the register + allocation. + + 2. MO_MInstrVirtualReg is the case where there is a hidden register being + used. You should decide how you want to handle it, e.g., do you want do + create a Value object during the preprocessing phase to make the value + explicit (like for address register for the RETURN instruction). + + 3. For case MO_MachineReg, you don't need to do anything, at least for + SPARC. The only machine regs I am using so far are %g0 and %sp. + + --Vikram + Index: llvm-www/releases/2.2/docs/HistoricalNotes/2001-07-08-InstructionSelection2.txt diff -c /dev/null llvm-www/releases/2.2/docs/HistoricalNotes/2001-07-08-InstructionSelection2.txt:1.1 *** /dev/null Tue Feb 12 00:07:04 2008 --- llvm-www/releases/2.2/docs/HistoricalNotes/2001-07-08-InstructionSelection2.txt Tue Feb 12 00:05:26 2008 *************** *** 0 **** --- 1,25 ---- + Date: Sun, 8 Jul 2001 10:02:20 -0500 + From: Vikram S. Adve + To: vadve at cs.uiuc.edu, Ruchira Sasanka + Cc: Chris Lattner + Subject: RE: machine instruction operands + + I got interrupted and forgot to explain the example. In that case: + + reg will be the 3rd operand of MUL and it will be of type + MO_MInstrVirtualReg. The field MachineInstr* minstr will point to the + instruction that computes reg. + + numElements will be an immediate constant, not a register. + + %sp will be operand 1 of ADD and it will be of type MO_MachineReg. The + field regNum identifies the register. + + numElements will be operand 2 of ADD and it will be of type + MO_VMVirtualReg. The field Value* value identifies the value. + + ptr will be operand 3 of ADD will also be %sp, i.e., of + type MO_MachineReg. regNum identifies the register. + + --Vikram + Index: llvm-www/releases/2.2/docs/HistoricalNotes/2001-09-18-OptimizeExceptions.txt diff -c /dev/null llvm-www/releases/2.2/docs/HistoricalNotes/2001-09-18-OptimizeExceptions.txt:1.1 *** /dev/null Tue Feb 12 00:07:04 2008 --- llvm-www/releases/2.2/docs/HistoricalNotes/2001-09-18-OptimizeExceptions.txt Tue Feb 12 00:05:26 2008 *************** *** 0 **** --- 1,56 ---- + Date: Tue, 18 Sep 2001 00:38:37 -0500 (CDT) + From: Chris Lattner + To: Vikram S. Adve + Subject: Idea for a simple, useful link time optimization + + + In C++ programs, exceptions suck, and here's why: + + 1. In virtually all function calls, you must assume that the function + throws an exception, unless it is defined as 'nothrow'. This means + that every function call has to have code to invoke dtors on objects + locally if one is thrown by the function. Most functions don't throw + exceptions, so this code is dead [with all the bad effects of dead + code, including icache pollution]. + 2. Declaring a function nothrow causes catch blocks to be added to every + call that isnot provably nothrow. This makes them very slow. + 3. Extra extraneous exception edges reduce the opportunity for code + motion. + 4. EH is typically implemented with large lookup tables. Ours is going to + be much smaller (than the "standard" way of doing it) to start with, + but eliminating it entirely would be nice. :) + 5. It is physically impossible to correctly put (accurate, correct) + exception specifications on generic, templated code. But it is trivial + to analyze instantiations of said code. + 6. Most large C++ programs throw few exceptions. Most well designed + programs only throw exceptions in specific planned portions of the + code. + + Given our _planned_ model of handling exceptions, all of this would be + pretty trivial to eliminate through some pretty simplistic interprocedural + analysis. The DCE factor alone could probably be pretty significant. The + extra code motion opportunities could also be exploited though... + + Additionally, this optimization can be implemented in a straight forward + conservative manner, allowing libraries to be optimized or individual + files even (if there are leaf functions visible in the translation unit + that are called). + + I think it's a reasonable optimization that hasn't really been addressed + (because assembly is way too low level for this), and could have decent + payoffs... without being a overly complex optimization. + + After I wrote all of that, I found this page that is talking about + basically the same thing I just wrote, except that it is translation unit + at a time, tree based approach: + http://www.ocston.org/~jls/ehopt.html + + but is very useful from "expected gain" and references perspective. Note + that their compiler is apparently unable to inline functions that use + exceptions, so there numbers are pretty worthless... also our results + would (hopefully) be better because it's interprocedural... + + What do you think? + + -Chris + Index: llvm-www/releases/2.2/docs/HistoricalNotes/2002-05-12-InstListChange.txt diff -c /dev/null llvm-www/releases/2.2/docs/HistoricalNotes/2002-05-12-InstListChange.txt:1.1 *** /dev/null Tue Feb 12 00:07:04 2008 --- llvm-www/releases/2.2/docs/HistoricalNotes/2002-05-12-InstListChange.txt Tue Feb 12 00:05:26 2008 *************** *** 0 **** --- 1,55 ---- + Date: Sun, 12 May 2002 17:12:53 -0500 (CDT) + From: Chris Lattner + To: "Vikram S. Adve" + Subject: LLVM change + + There is a fairly fundemental change that I would like to make to the LLVM + infrastructure, but I'd like to know if you see any drawbacks that I + don't... + + Basically right now at the basic block level, each basic block contains an + instruction list (returned by getInstList()) that is a ValueHolder of + instructions. To iterate over instructions, we must actually iterate over + the instlist, and access the instructions through the instlist. + + To add or remove an instruction from a basic block, we need to get an + iterator to an instruction, which, given just an Instruction*, requires a + linear search of the basic block the instruction is contained in... just + to insert an instruction before another instruction, or to delete an + instruction! This complicates algorithms that should be very simple (like + simple constant propogation), because they aren't actually sparse anymore, + they have to traverse basic blocks to remove constant propogated + instructions. + + Additionally, adding or removing instructions to a basic block + _invalidates all iterators_ pointing into that block, which is really + irritating. + + To fix these problems (and others), I would like to make the ordering of + the instructions be represented with a doubly linked list in the + instructions themselves, instead of an external data structure. This is + how many other representations do it, and frankly I can't remember why I + originally implemented it the way I did. + + Long term, all of the code that depends on the nasty features in the + instruction list (which can be found by grep'ing for getInstList()) will + be changed to do nice local transformations. In the short term, I'll + change the representation, but preserve the interface (including + getInstList()) so that all of the code doesn't have to change. + + Iteration over the instructions in a basic block remains the simple: + for (BasicBlock::iterator I = BB->begin(), E = BB->end(); I != E; ++I) ... + + But we will also support: + for (Instruction *I = BB->front(); I; I = I->getNext()) ... + + After converting instructions over, I'll convert basic blocks and + functions to have a similar interface. + + The only negative aspect of this change that I see is that it increases + the amount of memory consumed by one pointer per instruction. Given the + benefits, I think this is a very reasonable tradeoff. + + What do you think? + + -Chris Index: llvm-www/releases/2.2/docs/HistoricalNotes/2002-06-25-MegaPatchInfo.txt diff -c /dev/null llvm-www/releases/2.2/docs/HistoricalNotes/2002-06-25-MegaPatchInfo.txt:1.1 *** /dev/null Tue Feb 12 00:07:04 2008 --- llvm-www/releases/2.2/docs/HistoricalNotes/2002-06-25-MegaPatchInfo.txt Tue Feb 12 00:05:26 2008 *************** *** 0 **** --- 1,72 ---- + Changes: + * Change the casting code to be const correct. Now, doing this is invalid: + const Value *V = ...; + Instruction *I = dyn_cast(V); + instead, the second line should be: + const Instruction *I = dyn_cast(V); + + * Change the casting code to allow casting a reference value thus: + const Value &V = ...; + Instruction &I = cast(V); + + dyn_cast does not work with references, because it must return a null pointer + on failure. + + * Fundamentally change how instructions and other values are represented. + Before, every llvm container was an instance of the ValueHolder template, + instantiated for each container type. This ValueHolder was effectively a + wrapper around a vector of pointers to the sub-objects. + + Now, instead of having a vector to pointers of objects, the objects are + maintained in a doubly linked list of values (ie each Instruction now has + Next & Previous fields). The containers are now instances of ilist (intrusive + linked list class), which use the next and previous fields to chain them + together. The advantage of this implementation is that iterators can be + formed directly from pointers to the LLVM value, and invalidation is much + easier to handle. + + * As part of the above change, dereferencing an iterator (for example: + BasicBlock::iterator) now produces a reference to the underlying type (same + example: Instruction&) instead of a pointer to the underlying object. This + makes it much easier to write nested loops that iterator over things, changing + this: + + for (Function::iterator BI = Func->begin(); BI != Func->end(); ++BI) + for (BasicBlock::iterator II = (*BI)->begin(); II != (*BI)->end(); ++II) + (*II)->dump(); + + into: + + for (Function::iterator BI = Func->begin(); BI != Func->end(); ++BI) + for (BasicBlock::iterator II = BI->begin(); II != BI->end(); ++II) + II->dump(); + + which is much more natural and what users expect. + + * Simplification of #include's: Before, it was necessary for a .cpp file to + include every .h file that it used. Now things are batched a little bit more + to make it easier to use. Specifically, the include graph now includes these + edges: + Module.h -> Function.h, GlobalVariable.h + Function.h -> BasicBlock.h, Argument.h + BasicBlock.h -> Instruction.h + + Which means that #including Function.h is usually sufficient for getting the + lower level #includes. + + * Printing out a Value* has now changed: Printing a Value* will soon print out + the address of the value instead of the contents of the Value. To print out + the contents, you must convert it to a reference with (for example) + 'cout << *I' instead of 'cout << I;'. This conversion is not yet complete, + but will be eventually. In the mean time, both forms print out the contents. + + * References are used much more throughout the code base. In general, if a + pointer is known to never be null, it is passed in as a reference instead of a + pointer. For example, the instruction visitor class uses references instead + of pointers, and that Pass subclasses now all receive references to Values + instead of pointers, because they may never be null. + + * The Function class now has helper functions for accessing the Arguments list. + Instead of having to go through getArgumentList for simple things like + iterator over the arguments, now the a*() methods can be used to access them. + Index: llvm-www/releases/2.2/docs/HistoricalNotes/2003-01-23-CygwinNotes.txt diff -c /dev/null llvm-www/releases/2.2/docs/HistoricalNotes/2003-01-23-CygwinNotes.txt:1.1 *** /dev/null Tue Feb 12 00:07:04 2008 --- llvm-www/releases/2.2/docs/HistoricalNotes/2003-01-23-CygwinNotes.txt Tue Feb 12 00:05:26 2008 *************** *** 0 **** --- 1,28 ---- + Date: Mon, 20 Jan 2003 00:00:28 -0600 + From: Brian R. Gaeke + Subject: windows vs. llvm + + If you're interested, here are some of the major problems compiling LLVM + under Cygwin and/or Mingw. + + 1. Cygwin doesn't have or , so all the INT*_MAX + symbols and standard int*_t types are off in limbo somewhere. Mingw has + , but Cygwin doesn't like it. + + 2. Mingw doesn't have (because Windows doesn't have it.) + + 3. SA_SIGINFO and friends are not around; only signal() seems to work. + + 4. Relink, aka ld -r, doesn't work (probably an ld bug); you need + DONT_BUILD_RELINKED. This breaks all the tools makefiles; you just need to + change them to have .a's. + + 5. There isn't a . + + 6. There isn't a mallinfo() (or, at least, it's documented, but it doesn't seem + to link). + + 7. The version of Bison that cygwin (and newer Linux versions) comes with + does not like = signs in rules. Burg's gram.yc source file uses them. I think + you can just take them out. + Index: llvm-www/releases/2.2/docs/HistoricalNotes/2003-06-25-Reoptimizer1.txt diff -c /dev/null llvm-www/releases/2.2/docs/HistoricalNotes/2003-06-25-Reoptimizer1.txt:1.1 *** /dev/null Tue Feb 12 00:07:04 2008 --- llvm-www/releases/2.2/docs/HistoricalNotes/2003-06-25-Reoptimizer1.txt Tue Feb 12 00:05:26 2008 *************** *** 0 **** --- 1,137 ---- + Wed Jun 25 15:13:51 CDT 2003 + + First-level instrumentation + --------------------------- + + We use opt to do Bytecode-to-bytecode instrumentation. Look at + back-edges and insert llvm_first_trigger() function call which takes + no arguments and no return value. This instrumentation is designed to + be easy to remove, for instance by writing a NOP over the function + call instruction. + + Keep count of every call to llvm_first_trigger(), and maintain + counters in a map indexed by return address. If the trigger count + exceeds a threshold, we identify a hot loop and perform second-level + instrumentation on the hot loop region (the instructions between the + target of the back-edge and the branch that causes the back-edge). We + do not move code across basic-block boundaries. + + + Second-level instrumentation + --------------------------- + + We remove the first-level instrumentation by overwriting the CALL to + llvm_first_trigger() with a NOP. + + The reoptimizer maintains a map between machine-code basic blocks and + LLVM BasicBlock*s. We only keep track of paths that start at the + first machine-code basic block of the hot loop region. + + How do we keep track of which edges to instrument, and which edges are + exits from the hot region? 3 step process. + + 1) Do a DFS from the first machine-code basic block of the hot loop + region and mark reachable edges. + + 2) Do a DFS from the last machine-code basic block of the hot loop + region IGNORING back edges, and mark the edges which are reachable in + 1) and also in 2) (i.e., must be reachable from both the start BB and + the end BB of the hot region). + + 3) Mark BBs which end in edges that exit the hot region; we need to + instrument these differently. + + Assume that there is 1 free register. On SPARC we use %g1, which LLC + has agreed not to use. Shift a 1 into it at the beginning. At every + edge which corresponds to a conditional branch, we shift 0 for not + taken and 1 for taken into a register. This uniquely numbers the paths + through the hot region. Silently fail if we need more than 64 bits. + + At the end BB we call countPath and increment the counter based on %g1 + and the return address of the countPath call. We keep track of the + number of iterations and the number of paths. We only run this + version 30 or 40 times. + + Find the BBs that total 90% or more of execution, and aggregate them + together to form our trace. But we do not allow more than 5 paths; if + we have more than 5 we take the ones that are executed the most. We + verify our assumption that we picked a hot back-edge in first-level + instrumentation, by making sure that the number of times we took an + exit edge from the hot trace is less than 10% of the number of + iterations. + + LLC has been taught to recognize llvm_first_trigger() calls and NOT + generate saves and restores of caller-saved registers around these + calls. + + + Phase behavior + -------------- + + We turn off llvm_first_trigger() calls with NOPs, but this would hide + phase behavior from us (when some funcs/traces stop being hot and + others become hot.) + + We have a SIGALRM timer that counts time for us. Every time we get a + SIGALRM we look at our priority queue of locations where we have + removed llvm_first_trigger() calls. Each location is inserted along + with a time when we will next turn instrumentation back on for that + call site. If the time has arrived for a particular call site, we pop + that off the prio. queue and turn instrumentation back on for that + call site. + + + Generating traces + ----------------- + + When we finally generate an optimized trace we first copy the code + into the trace cache. This leaves us with 3 copies of the code: the + original code, the instrumented code, and the optimized trace. The + optimized trace does not have instrumentation. The original code and + the instrumented code are modified to have a branch to the trace + cache, where the optimized traces are kept. + + We copy the code from the original to the instrumentation version + by tracing the LLVM-to-Machine code basic block map and then copying + each machine code basic block we think is in the hot region into the + trace cache. Then we instrument that code. The process is similar for + generating the final optimized trace; we copy the same basic blocks + because we might need to put in fixup code for exit BBs. + + LLVM basic blocks are not typically used in the Reoptimizer except + for the mapping information. + + We are restricted to using single instructions to branch between the + original code, trace, and instrumented code. So we have to keep the + code copies in memory near the original code (they can't be far enough + away that a single pc-relative branch would not work.) Malloc() or + data region space is too far away. this impacts the design of the + trace cache. + + We use a dummy function that is full of a bunch of for loops which we + overwrite with trace-cache code. The trace manager keeps track of + whether or not we have enough space in the trace cache, etc. + + The trace insertion routine takes an original start address, a vector + of machine instructions representing the trace, index of branches and + their corresponding absolute targets, and index of calls and their + corresponding absolute targets. + + The trace insertion routine is responsible for inserting branches from + the beginning of the original code to the beginning of the optimized + trace. This is because at some point the trace cache may run out of + space and it may have to evict a trace, at which point the branch to + the trace would also have to be removed. It uses a round-robin + replacement policy; we have found that this is almost as good as LRU + and better than random (especially because of problems fitting the new + trace in.) + + We cannot deal with discontiguous trace cache areas. The trace cache + is supposed to be cache-line-aligned, but it is not page-aligned. + + We generate instrumentation traces and optimized traces into separate + trace caches. We keep the instrumented code around because you don't + want to delete a trace when you still might have to return to it + (i.e., return from a llvm_first_trigger() or countPath() call.) + + Index: llvm-www/releases/2.2/docs/HistoricalNotes/2003-06-26-Reoptimizer2.txt diff -c /dev/null llvm-www/releases/2.2/docs/HistoricalNotes/2003-06-26-Reoptimizer2.txt:1.1 *** /dev/null Tue Feb 12 00:07:04 2008 --- llvm-www/releases/2.2/docs/HistoricalNotes/2003-06-26-Reoptimizer2.txt Tue Feb 12 00:05:26 2008 *************** *** 0 **** --- 1,110 ---- + Thu Jun 26 14:43:04 CDT 2003 + + Information about BinInterface + ------------------------------ + + Take in a set of instructions with some particular register + allocation. It allows you to add, modify, or delete some instructions, + in SSA form (kind of like LLVM's MachineInstrs.) Then re-allocate + registers. It assumes that the transformations you are doing are safe. + It does not update the mapping information or the LLVM representation + for the modified trace (so it would not, for instance, support + multiple optimization passes; passes have to be aware of and update + manually the mapping information.) + + The way you use it is you take the original code and provide it to + BinInterface; then you do optimizations to it, then you put it in the + trace cache. + + The BinInterface tries to find live-outs for traces so that it can do + register allocation on just the trace, and stitch the trace back into + the original code. It has to preserve the live-ins and live-outs when + it does its register allocation. (On exits from the trace we have + epilogues that copy live-outs back into the right registers, but + live-ins have to be in the right registers.) + + + Limitations of BinInterface + --------------------------- + + It does copy insertions for PHIs, which it infers from the machine + code. The mapping info inserted by LLC is not sufficient to determine + the PHIs. + + It does not handle integer or floating-point condition codes and it + does not handle floating-point register allocation. + + It is not aggressively able to use lots of registers. + + There is a problem with alloca: we cannot find our spill space for + spilling registers, normally allocated on the stack, if the trace + follows an alloca(). What might be an acceptable solution would be to + disable trace generation on functions that have variable-sized + alloca()s. Variable-sized allocas in the trace would also probably + screw things up. + + Because of the FP and alloca limitations, the BinInterface is + completely disabled right now. + + + Demo + ---- + + This is a demo of the Ball & Larus version that does NOT use 2-level + profiling. + + 1. Compile program with llvm-gcc. + 2. Run opt -lowerswitch -paths -emitfuncs on the bytecode. + -lowerswitch change switch statements to branches + -paths Ball & Larus path-profiling algorithm + -emitfuncs emit the table of functions + 3. Run llc to generate SPARC assembly code for the result of step 2. + 4. Use g++ to link the (instrumented) assembly code. + + We use a script to do all this: + ------------------------------------------------------------------------------ + #!/bin/sh + llvm-gcc $1.c -o $1 + opt -lowerswitch -paths -emitfuncs $1.bc > $1.run.bc + llc -f $1.run.bc + LIBS=$HOME/llvm_sparc/lib/Debug + GXX=/usr/dcs/software/evaluation/bin/g++ + $GXX -g -L $LIBS $1.run.s -o $1.run.llc \ + $LIBS/tracecache.o \ + $LIBS/mapinfo.o \ + $LIBS/trigger.o \ + $LIBS/profpaths.o \ + $LIBS/bininterface.o \ + $LIBS/support.o \ + $LIBS/vmcore.o \ + $LIBS/transformutils.o \ + $LIBS/bcreader.o \ + -lscalaropts -lscalaropts -lanalysis \ + -lmalloc -lcpc -lm -ldl + ------------------------------------------------------------------------------ + + 5. Run the resulting binary. You will see output from BinInterface + (described below) intermixed with the output from the program. + + + Output from BinInterface + ------------------------ + + BinInterface's debugging code prints out the following stuff in order: + + 1. Initial code provided to BinInterface with original register + allocation. + + 2. Section 0 is the trace prolog, consisting mainly of live-ins and + register saves which will be restored in epilogs. + + 3. Section 1 is the trace itself, in SSA form used by BinInterface, + along with the PHIs that are inserted. + PHIs are followed by the copies that implement them. + Each branch (i.e., out of the trace) is annotated with the + section number that represents the epilog it branches to. + + 4. All the other sections starting with Section 2 are trace epilogs. + Every branch from the trace has to go to some epilog. + + 5. After the last section is the register allocation output. From tonic at nondot.org Tue Feb 12 00:07:07 2008 From: tonic at nondot.org (Tanya Lattner) Date: Tue, 12 Feb 2008 00:07:07 -0600 Subject: [llvm-commits] CVS: llvm-www/releases/2.2/docs/AliasAnalysis.html BOOST_LICENSE_1_0.txt BitCodeFormat.html Bugpoint.html CFEBuildInstrs.html CodeGenerator.html CodingStandards.html CommandLine.html CompilerDriver.html CompilerWriterInfo.html DeveloperPolicy.html ExceptionHandling.html ExtendingLLVM.html FAQ.html GarbageCollection.html GetElementPtr.html GettingStarted.html GettingStartedVS.html HowToReleaseLLVM.html HowToSubmitABug.html LangRef.html Lexicon.html LinkTimeOptimization.html Makefile MakefileGuide.html Passes.html ProgrammersManual.html Projects.html ReleaseNotes.html SourceLevelDebugging.html Stacker.html SystemLibrary.html TableGenFundamentals.html TestingGuide.html UsingLibraries.html WritingAnLLVMBackend.html WritingAnLLVMPass.html doxygen.cfg doxygen.cfg.in doxygen.css doxygen.footer doxygen.header doxygen.intro html.tar.gz index.html llvm.css Message-ID: <200802120607.m1C677VD009101@zion.cs.uiuc.edu> Changes in directory llvm-www/releases/2.2/docs: AliasAnalysis.html added (r1.1) BOOST_LICENSE_1_0.txt added (r1.1) BitCodeFormat.html added (r1.1) Bugpoint.html added (r1.1) CFEBuildInstrs.html added (r1.1) CodeGenerator.html added (r1.1) CodingStandards.html added (r1.1) CommandLine.html added (r1.1) CompilerDriver.html added (r1.1) CompilerWriterInfo.html added (r1.1) DeveloperPolicy.html added (r1.1) ExceptionHandling.html added (r1.1) ExtendingLLVM.html added (r1.1) FAQ.html added (r1.1) GarbageCollection.html added (r1.1) GetElementPtr.html added (r1.1) GettingStarted.html added (r1.1) GettingStartedVS.html added (r1.1) HowToReleaseLLVM.html added (r1.1) HowToSubmitABug.html added (r1.1) LangRef.html added (r1.1) Lexicon.html added (r1.1) LinkTimeOptimization.html added (r1.1) Makefile added (r1.1) MakefileGuide.html added (r1.1) Passes.html added (r1.1) ProgrammersManual.html added (r1.1) Projects.html added (r1.1) ReleaseNotes.html added (r1.1) SourceLevelDebugging.html added (r1.1) Stacker.html added (r1.1) SystemLibrary.html added (r1.1) TableGenFundamentals.html added (r1.1) TestingGuide.html added (r1.1) UsingLibraries.html added (r1.1) WritingAnLLVMBackend.html added (r1.1) WritingAnLLVMPass.html added (r1.1) doxygen.cfg added (r1.1) doxygen.cfg.in added (r1.1) doxygen.css added (r1.1) doxygen.footer added (r1.1) doxygen.header added (r1.1) doxygen.intro added (r1.1) html.tar.gz added (r1.1) index.html added (r1.1) llvm.css added (r1.1) --- Log message: Release 2.2 --- Diffs of the changes: (+38953 -0) AliasAnalysis.html | 984 ++++++++ BOOST_LICENSE_1_0.txt | 23 BitCodeFormat.html | 653 +++++ Bugpoint.html | 244 ++ CFEBuildInstrs.html | 97 CodeGenerator.html | 1962 ++++++++++++++++ CodingStandards.html | 767 ++++++ CommandLine.html | 1935 ++++++++++++++++ CompilerDriver.html | 823 +++++++ CompilerWriterInfo.html | 261 ++ DeveloperPolicy.html | 555 ++++ ExceptionHandling.html | 478 ++++ ExtendingLLVM.html | 391 +++ FAQ.html | 682 +++++ GarbageCollection.html | 1419 ++++++++++++ GetElementPtr.html | 370 +++ GettingStarted.html | 1642 ++++++++++++++ GettingStartedVS.html | 380 +++ HowToReleaseLLVM.html | 608 +++++ HowToSubmitABug.html | 355 +++ LangRef.html | 5338 ++++++++++++++++++++++++++++++++++++++++++++++ Lexicon.html | 254 ++ LinkTimeOptimization.html | 392 +++ Makefile | 91 MakefileGuide.html | 1041 ++++++++ Passes.html | 1930 ++++++++++++++++ ProgrammersManual.html | 3197 +++++++++++++++++++++++++++ Projects.html | 460 +++ ReleaseNotes.html | 761 ++++++ SourceLevelDebugging.html | 1782 +++++++++++++++ Stacker.html | 1428 ++++++++++++ SystemLibrary.html | 344 ++ TableGenFundamentals.html | 646 +++++ TestingGuide.html | 894 +++++++ UsingLibraries.html | 449 +++ WritingAnLLVMBackend.html | 260 ++ WritingAnLLVMPass.html | 1819 +++++++++++++++ doxygen.cfg | 1230 ++++++++++ doxygen.cfg.in | 1230 ++++++++++ doxygen.css | 378 +++ doxygen.footer | 13 doxygen.header | 9 doxygen.intro | 18 html.tar.gz | 0 index.html | 276 ++ llvm.css | 84 46 files changed, 38953 insertions(+) Index: llvm-www/releases/2.2/docs/AliasAnalysis.html diff -c /dev/null llvm-www/releases/2.2/docs/AliasAnalysis.html:1.1 *** /dev/null Tue Feb 12 00:05:44 2008 --- llvm-www/releases/2.2/docs/AliasAnalysis.html Tue Feb 12 00:05:03 2008 *************** *** 0 **** --- 1,984 ---- + + + + LLVM Alias Analysis Infrastructure + + + + +
    + LLVM Alias Analysis Infrastructure +
    + +
      +
    1. Introduction
      2. + +
    2. AliasAnalysis Class Overview + +
      3. + +
    3. Writing a new AliasAnalysis Implementation + +
      4. + +
    4. Using alias analysis results + +
      5. + +
    5. Existing alias analysis implementations and clients + +
      6. +
    6. Memory Dependence Analysis
      7. +
    + +
    +

    Written by Chris Lattner

    +
    + + +
    + Introduction +
    + + +
    + +

    Alias Analysis (aka Pointer Analysis) is a class of techniques which attempt + to determine whether or not two pointers ever can point to the same object in + memory. There are many different algorithms for alias analysis and many + different ways of classifying them: flow-sensitive vs flow-insensitive, + context-sensitive vs context-insensitive, field-sensitive vs field-insensitive, + unification-based vs subset-based, etc. Traditionally, alias analyses respond + to a query with a Must, May, or No alias response, + indicating that two pointers always point to the same object, might point to the + same object, or are known to never point to the same object.

    + +

    The LLVM AliasAnalysis + class is the primary interface used by clients and implementations of alias + analyses in the LLVM system. This class is the common interface between clients + of alias analysis information and the implementations providing it, and is + designed to support a wide range of implementations and clients (but currently + all clients are assumed to be flow-insensitive). In addition to simple alias + analysis information, this class exposes Mod/Ref information from those + implementations which can provide it, allowing for powerful analyses and + transformations to work well together.

    + +

    This document contains information necessary to successfully implement this + interface, use it, and to test both sides. It also explains some of the finer + points about what exactly results mean. If you feel that something is unclear + or should be added, please let me + know.

    + +
    + + +
    + AliasAnalysis Class Overview +
    + + +
    + +

    The AliasAnalysis + class defines the interface that the various alias analysis implementations + should support. This class exports two important enums: AliasResult + and ModRefResult which represent the result of an alias query or a + mod/ref query, respectively.

    + +

    The AliasAnalysis interface exposes information about memory, + represented in several different ways. In particular, memory objects are + represented as a starting address and size, and function calls are represented + as the actual call or invoke instructions that performs the + call. The AliasAnalysis interface also exposes some helper methods + which allow you to get mod/ref information for arbitrary instructions.

    + +
    + + +
    + Representation of Pointers +
    + +
    + +

    Most importantly, the AliasAnalysis class provides several methods + which are used to query whether or not two memory objects alias, whether + function calls can modify or read a memory object, etc. For all of these + queries, memory objects are represented as a pair of their starting address (a + symbolic LLVM Value*) and a static size.

    + +

    Representing memory objects as a starting address and a size is critically + important for correct Alias Analyses. For example, consider this (silly, but + possible) C code:

    + +
    + 
    + int i;
+ char C[2];
+ char A[10]; 
+ /* ... */
+ for (i = 0; i != 10; ++i) {
+   C[0] = A[i];          /* One byte store */
+   C[1] = A[9-i];        /* One byte store */
+ }
+
    +
    + +

    In this case, the basicaa pass will disambiguate the stores to + C[0] and C[1] because they are accesses to two distinct + locations one byte apart, and the accesses are each one byte. In this case, the + LICM pass can use store motion to remove the stores from the loop. In + constrast, the following code:

    + +
    + 
    + int i;
+ char C[2];
+ char A[10]; 
+ /* ... */
+ for (i = 0; i != 10; ++i) {
+   ((short*)C)[0] = A[i];  /* Two byte store! */
+   C[1] = A[9-i];          /* One byte store */
+ }
+
    +
    + +

    In this case, the two stores to C do alias each other, because the access to + the &C[0] element is a two byte access. If size information wasn't + available in the query, even the first case would have to conservatively assume + that the accesses alias.

    + +
    + + +
    + The alias method +
    + +
    + The alias method is the primary interface used to determine whether or + not two memory objects alias each other. It takes two memory objects as input + and returns MustAlias, MayAlias, or NoAlias as appropriate. +
    + + +
    + Must, May, and No Alias Responses +
    + +
    + +

    An Alias Analysis implementation can return one of three responses: + MustAlias, MayAlias, and NoAlias. The No and May alias results are obvious: if + the two pointers can never equal each other, return NoAlias, if they might, + return MayAlias.

    + +

    The MustAlias response is trickier though. In LLVM, the Must Alias response + may only be returned if the two memory objects are guaranteed to always start at + exactly the same location. If two memory objects overlap, but do not start at + the same location, return MayAlias.

    + +
    + + +
    + The getModRefInfo methods +
    + +
    + +

    The getModRefInfo methods return information about whether the + execution of an instruction can read or modify a memory location. Mod/Ref + information is always conservative: if an instruction might read or write + a location, ModRef is returned.

    + +

    The AliasAnalysis class also provides a getModRefInfo + method for testing dependencies between function calls. This method takes two + call sites (CS1 & CS2), returns NoModRef if the two calls refer to disjoint + memory locations, Ref if CS1 reads memory written by CS2, Mod if CS1 writes to + memory read or written by CS2, or ModRef if CS1 might read or write memory + accessed by CS2. Note that this relation is not commutative. Clients that use + this method should be predicated on the hasNoModRefInfoForCalls() + method, which indicates whether or not an analysis can provide mod/ref + information for function call pairs (most can not). If this predicate is false, + the client shouldn't waste analysis time querying the getModRefInfo + method many times.

    + +
    + + + +
    + Other useful AliasAnalysis methods +
    + +
    + +

    + Several other tidbits of information are often collected by various alias + analysis implementations and can be put to good use by various clients. +

    + +
    + + +
    + The getMustAliases method +
    + +
    + +

    The getMustAliases method returns all values that are known to + always must alias a pointer. This information can be provided in some cases for + important objects like the null pointer and global values. Knowing that a + pointer always points to a particular function allows indirect calls to be + turned into direct calls, for example.

    + +
    + + +
    + The pointsToConstantMemory method +
    + +
    + +

    The pointsToConstantMemory method returns true if and only if the + analysis can prove that the pointer only points to unchanging memory locations + (functions, constant global variables, and the null pointer). This information + can be used to refine mod/ref information: it is impossible for an unchanging + memory location to be modified.

    + +
    + + +
    + The doesNotAccessMemory and + onlyReadsMemory methods +
    + +
    + +

    These methods are used to provide very simple mod/ref information for + function calls. The doesNotAccessMemory method returns true for a + function if the analysis can prove that the function never reads or writes to + memory, or if the function only reads from constant memory. Functions with this + property are side-effect free and only depend on their input arguments, allowing + them to be eliminated if they form common subexpressions or be hoisted out of + loops. Many common functions behave this way (e.g., sin and + cos) but many others do not (e.g., acos, which modifies the + errno variable).

    + +

    The onlyReadsMemory method returns true for a function if analysis + can prove that (at most) the function only reads from non-volatile memory. + Functions with this property are side-effect free, only depending on their input + arguments and the state of memory when they are called. This property allows + calls to these functions to be eliminated and moved around, as long as there is + no store instruction that changes the contents of memory. Note that all + functions that satisfy the doesNotAccessMemory method also satisfies + onlyReadsMemory.

    + +
    + + +
    + Writing a new AliasAnalysis Implementation +
    + + +
    + +

    Writing a new alias analysis implementation for LLVM is quite + straight-forward. There are already several implementations that you can use + for examples, and the following information should help fill in any details. + For a examples, take a look at the various alias analysis + implementations included with LLVM.

    + +
    + + +
    + Different Pass styles +
    + +
    + +

    The first step to determining what type of LLVM pass you need to use for your Alias + Analysis. As is the case with most other analyses and transformations, the + answer should be fairly obvious from what type of problem you are trying to + solve:

    + +
      +
    1. If you require interprocedural analysis, it should be a + Pass.
      2. +
    2. If you are a function-local analysis, subclass FunctionPass.
      3. +
    3. If you don't need to look at the program at all, subclass + ImmutablePass.
      4. +
    + +

    In addition to the pass that you subclass, you should also inherit from the + AliasAnalysis interface, of course, and use the + RegisterAnalysisGroup template to register as an implementation of + AliasAnalysis.

    + +
    + + +
    + Required initialization calls +
    + +
    + +

    Your subclass of AliasAnalysis is required to invoke two methods on + the AliasAnalysis base class: getAnalysisUsage and + InitializeAliasAnalysis. In particular, your implementation of + getAnalysisUsage should explicitly call into the + AliasAnalysis::getAnalysisUsage method in addition to doing any + declaring any pass dependencies your pass has. Thus you should have something + like this:

    + +
    + 
    + void getAnalysisUsage(AnalysisUsage &AU) const {
+   AliasAnalysis::getAnalysisUsage(AU);
+   // declare your dependencies here.
+ }
+
    +
    + +

    Additionally, your must invoke the InitializeAliasAnalysis method + from your analysis run method (run for a Pass, + runOnFunction for a FunctionPass, or InitializePass + for an ImmutablePass). For example (as part of a Pass):

    + +
    + 
    + bool run(Module &M) {
+   InitializeAliasAnalysis(this);
+   // Perform analysis here...
+   return false;
+ }
+
    +
    + +
    + + +
    + Interfaces which may be specified +
    + +
    + +

    All of the AliasAnalysis + virtual methods default to providing chaining to another + alias analysis implementation, which ends up returning conservatively correct + information (returning "May" Alias and "Mod/Ref" for alias and mod/ref queries + respectively). Depending on the capabilities of the analysis you are + implementing, you just override the interfaces you can improve.

    + +
    + + + + +
    + AliasAnalysis chaining behavior +
    + +
    + +

    With only two special exceptions (the basicaa and no-aa + passes) every alias analysis pass chains to another alias analysis + implementation (for example, the user can specify "-basicaa -ds-aa + -anders-aa -licm" to get the maximum benefit from the three alias + analyses). The alias analysis class automatically takes care of most of this + for methods that you don't override. For methods that you do override, in code + paths that return a conservative MayAlias or Mod/Ref result, simply return + whatever the superclass computes. For example:

    + +
    + 
    + AliasAnalysis::AliasResult alias(const Value *V1, unsigned V1Size,
+                                  const Value *V2, unsigned V2Size) {
+   if (...)
+     return NoAlias;
+   ...
+ 
+   // Couldn't determine a must or no-alias result.
+   return AliasAnalysis::alias(V1, V1Size, V2, V2Size);
+ }
+
    +
    + +

    In addition to analysis queries, you must make sure to unconditionally pass + LLVM update notification methods to the superclass as + well if you override them, which allows all alias analyses in a change to be + updated.

    + +
    + + + +
    + Updating analysis results for transformations +
    + +
    +

    + Alias analysis information is initially computed for a static snapshot of the + program, but clients will use this information to make transformations to the + code. All but the most trivial forms of alias analysis will need to have their + analysis results updated to reflect the changes made by these transformations. +

    + +

    + The AliasAnalysis interface exposes two methods which are used to + communicate program changes from the clients to the analysis implementations. + Various alias analysis implementations should use these methods to ensure that + their internal data structures are kept up-to-date as the program changes (for + example, when an instruction is deleted), and clients of alias analysis must be + sure to call these interfaces appropriately. +

    +
    + + +
    The deleteValue method
    + +
    + The deleteValue method is called by transformations when they remove an + instruction or any other value from the program (including values that do not + use pointers). Typically alias analyses keep data structures that have entries + for each value in the program. When this method is called, they should remove + any entries for the specified value, if they exist. +
    + + +
    The copyValue method
    + +
    + The copyValue method is used when a new value is introduced into the + program. There is no way to introduce a value into the program that did not + exist before (this doesn't make sense for a safe compiler transformation), so + this is the only way to introduce a new value. This method indicates that the + new value has exactly the same properties as the value being copied. +
    + + +
    The replaceWithNewValue method
    + +
    + This method is a simple helper method that is provided to make clients easier to + use. It is implemented by copying the old analysis information to the new + value, then deleting the old value. This method cannot be overridden by alias + analysis implementations. +
    + + +
    + Efficiency Issues +
    + +
    + +

    From the LLVM perspective, the only thing you need to do to provide an + efficient alias analysis is to make sure that alias analysis queries are + serviced quickly. The actual calculation of the alias analysis results (the + "run" method) is only performed once, but many (perhaps duplicate) queries may + be performed. Because of this, try to move as much computation to the run + method as possible (within reason).

    + +
    + + +
    + Using alias analysis results +
    + + +
    + +

    There are several different ways to use alias analysis results. In order of + preference, these are...

    + +
    + + +
    + Using the -load-vn Pass +
    + +
    + +

    The load-vn pass uses alias analysis to provide value numbering + information for load instructions and pointer values. If your analysis + or transformation can be modeled in a form that uses value numbering + information, you don't have to do anything special to handle load instructions: + just use the load-vn pass, which uses alias analysis.

    + +
    + + +
    + Using the AliasSetTracker class +
    + +
    + +

    Many transformations need information about alias sets that are active + in some scope, rather than information about pairwise aliasing. The AliasSetTracker class + is used to efficiently build these Alias Sets from the pairwise alias analysis + information provided by the AliasAnalysis interface.

    + +

    First you initialize the AliasSetTracker by using the "add" methods + to add information about various potentially aliasing instructions in the scope + you are interested in. Once all of the alias sets are completed, your pass + should simply iterate through the constructed alias sets, using the + AliasSetTracker begin()/end() methods.

    + +

    The AliasSets formed by the AliasSetTracker are guaranteed + to be disjoint, calculate mod/ref information and volatility for the set, and + keep track of whether or not all of the pointers in the set are Must aliases. + The AliasSetTracker also makes sure that sets are properly folded due to call + instructions, and can provide a list of pointers in each set.

    + +

    As an example user of this, the Loop + Invariant Code Motion pass uses AliasSetTrackers to calculate alias + sets for each loop nest. If an AliasSet in a loop is not modified, + then all load instructions from that set may be hoisted out of the loop. If any + alias sets are stored to and are must alias sets, then the stores may be + sunk to outside of the loop, promoting the memory location to a register for the + duration of the loop nest. Both of these transformations only apply if the + pointer argument is loop-invariant.

    + +
    + + +
    + The AliasSetTracker implementation +
    + +
    + +

    The AliasSetTracker class is implemented to be as efficient as possible. It + uses the union-find algorithm to efficiently merge AliasSets when a pointer is + inserted into the AliasSetTracker that aliases multiple sets. The primary data + structure is a hash table mapping pointers to the AliasSet they are in.

    + +

    The AliasSetTracker class must maintain a list of all of the LLVM Value*'s + that are in each AliasSet. Since the hash table already has entries for each + LLVM Value* of interest, the AliasesSets thread the linked list through these + hash-table nodes to avoid having to allocate memory unnecessarily, and to make + merging alias sets extremely efficient (the linked list merge is constant time). +

    + +

    You shouldn't need to understand these details if you are just a client of + the AliasSetTracker, but if you look at the code, hopefully this brief + description will help make sense of why things are designed the way they + are.

    + +
    + + +
    + Using the AliasAnalysis interface directly +
    + +
    + +

    If neither of these utility class are what your pass needs, you should use + the interfaces exposed by the AliasAnalysis class directly. Try to use + the higher-level methods when possible (e.g., use mod/ref information instead of + the alias method directly if possible) to get the + best precision and efficiency.

    + +
    + + +
    + Existing alias analysis implementations and clients +
    + + +
    + +

    If you're going to be working with the LLVM alias analysis infrastructure, + you should know what clients and implementations of alias analysis are + available. In particular, if you are implementing an alias analysis, you should + be aware of the the clients that are useful + for monitoring and evaluating different implementations.

    + +
    + + +
    + Available AliasAnalysis implementations +
    + +
    + +

    This section lists the various implementations of the AliasAnalysis + interface. With the exception of the -no-aa and + -basicaa implementations, all of these chain to other alias analysis implementations.

    + +
    + + +
    + The -no-aa pass +
    + +
    + +

    The -no-aa pass is just like what it sounds: an alias analysis that + never returns any useful information. This pass can be useful if you think that + alias analysis is doing something wrong and are trying to narrow down a + problem.

    + +
    + + +
    + The -basicaa pass +
    + +
    + +

    The -basicaa pass is the default LLVM alias analysis. It is an + aggressive local analysis that "knows" many important facts:

    + +
      +
    • Distinct globals, stack allocations, and heap allocations can never + alias.
      • +
    • Globals, stack allocations, and heap allocations never alias the null + pointer.
      • +
    • Different fields of a structure do not alias.
      • +
    • Indexes into arrays with statically differing subscripts cannot alias.
      • +
    • Many common standard C library functions never access memory or only read memory.
      • +
    • Pointers that obviously point to constant globals + "pointToConstantMemory".
      • +
    • Function calls can not modify or references stack allocations if they never + escape from the function that allocates them (a common case for automatic + arrays).
      • +
    + +
    + + +
    + The -globalsmodref-aa pass +
    + +
    + +

    This pass implements a simple context-sensitive mod/ref and alias analysis + for internal global variables that don't "have their address taken". If a + global does not have its address taken, the pass knows that no pointers alias + the global. This pass also keeps track of functions that it knows never access + memory or never read memory. This allows certain optimizations (e.g. GCSE) to + eliminate call instructions entirely. +

    + +

    The real power of this pass is that it provides context-sensitive mod/ref + information for call instructions. This allows the optimizer to know that + calls to a function do not clobber or read the value of the global, allowing + loads and stores to be eliminated.

    + +

    Note that this pass is somewhat limited in its scope (only support + non-address taken globals), but is very quick analysis.

    +
    + + +
    + The -anders-aa pass +
    + +
    + +

    The -anders-aa pass implements the well-known "Andersen's algorithm" + for interprocedural alias analysis. This algorithm is a subset-based, + flow-insensitive, context-insensitive, and field-insensitive alias analysis that + is widely believed to be fairly precise. Unfortunately, this algorithm is also + O(N3). The LLVM implementation currently does not implement any of + the refinements (such as "online cycle elimination" or "offline variable + substitution") to improve its efficiency, so it can be quite slow in common + cases. +

    + +
    + + +
    + The -steens-aa pass +
    + +
    + +

    The -steens-aa pass implements a variation on the well-known + "Steensgaard's algorithm" for interprocedural alias analysis. Steensgaard's + algorithm is a unification-based, flow-insensitive, context-insensitive, and + field-insensitive alias analysis that is also very scalable (effectively linear + time).

    + +

    The LLVM -steens-aa pass implements a "speculatively + field-sensitive" version of Steensgaard's algorithm using the Data + Structure Analysis framework. This gives it substantially more precision than + the standard algorithm while maintaining excellent analysis scalability.

    + +

    Note that -steens-aa is available in the optional "poolalloc" + module, it is not part of the LLVM core.

    + +
    + + +
    + The -ds-aa pass +
    + +
    + +

    The -ds-aa pass implements the full Data Structure Analysis + algorithm. Data Structure Analysis is a modular unification-based, + flow-insensitive, context-sensitive, and speculatively + field-sensitive alias analysis that is also quite scalable, usually at + O(n*log(n)).

    + +

    This algorithm is capable of responding to a full variety of alias analysis + queries, and can provide context-sensitive mod/ref information as well. The + only major facility not implemented so far is support for must-alias + information.

    + +

    Note that -ds-aa is available in the optional "poolalloc" + module, it is not part of the LLVM core.

    + +
    + + + +
    + Alias analysis driven transformations +
    + +
    + LLVM includes several alias-analysis driven transformations which can be used + with any of the implementations above. +
    + + +
    + The -adce pass +
    + +
    + +

    The -adce pass, which implements Aggressive Dead Code Elimination + uses the AliasAnalysis interface to delete calls to functions that do + not have side-effects and are not used.

    + +
    + + + +
    + The -licm pass +
    + +
    + +

    The -licm pass implements various Loop Invariant Code Motion related + transformations. It uses the AliasAnalysis interface for several + different transformations:

    + +
      +
    • It uses mod/ref information to hoist or sink load instructions out of loops + if there are no instructions in the loop that modifies the memory loaded.
      • + +
    • It uses mod/ref information to hoist function calls out of loops that do not + write to memory and are loop-invariant.
      • + +
    • If uses alias information to promote memory objects that are loaded and + stored to in loops to live in a register instead. It can do this if there are + no may aliases to the loaded/stored memory location.
      • +
    + +
    + + +
    + The -argpromotion pass +
    + +
    +

    + The -argpromotion pass promotes by-reference arguments to be passed in + by-value instead. In particular, if pointer arguments are only loaded from it + passes in the value loaded instead of the address to the function. This pass + uses alias information to make sure that the value loaded from the argument + pointer is not modified between the entry of the function and any load of the + pointer.

    +
    + + +
    + The -load-vn & -gcse passes +
    + +
    + +

    The -load-vn pass uses alias analysis to "value + number" loads and pointers values, which is used by the GCSE pass to + eliminate instructions. The -load-vn pass relies on alias information + and must-alias information. This combination of passes can make the following + transformations:

    + +
      +
    • Redundant load instructions are eliminated.
      • +
    • Load instructions that follow a store to the same location are replaced with + the stored value ("store forwarding").
      • +
    • Pointers values (e.g. formal arguments) that must-alias simpler expressions + (e.g. global variables or the null pointer) are replaced. Note that this + implements transformations like "virtual method resolution", turning indirect + calls into direct calls.
      • +
    + +
    + + +
    + Clients for debugging and evaluation of + implementations +
    + +
    + +

    These passes are useful for evaluating the various alias analysis + implementations. You can use them with commands like 'opt -anders-aa -ds-aa + -aa-eval foo.bc -disable-output -stats'.

    + +
    + + +
    + The -print-alias-sets pass +
    + +
    + +

    The -print-alias-sets pass is exposed as part of the + opt tool to print out the Alias Sets formed by the AliasSetTracker class. This is useful if you're using + the AliasSetTracker class. To use it, use something like:

    + +
    + 
    + % opt -ds-aa -print-alias-sets -disable-output
+
    +
    + +
    + + + +
    + The -count-aa pass +
    + +
    + +

    The -count-aa pass is useful to see how many queries a particular + pass is making and what responses are returned by the alias analysis. As an + example,

    + +
    + 
    + % opt -basicaa -count-aa -ds-aa -count-aa -licm
+
    +
    + +

    will print out how many queries (and what responses are returned) by the + -licm pass (of the -ds-aa pass) and how many queries are made + of the -basicaa pass by the -ds-aa pass. This can be useful + when debugging a transformation or an alias analysis implementation.

    + +
    + + +
    + The -aa-eval pass +
    + +
    + +

    The -aa-eval pass simply iterates through all pairs of pointers in a + function and asks an alias analysis whether or not the pointers alias. This + gives an indication of the precision of the alias analysis. Statistics are + printed indicating the percent of no/may/must aliases found (a more precise + algorithm will have a lower number of may aliases).

    + +
    + + +
    + Memory Dependence Analysis +
    + + +
    + +

    If you're just looking to be a client of alias analysis information, consider + using the Memory Dependence Analysis interface instead. MemDep is a lazy, + caching layer on top of alias analysis that is able to answer the question of + what preceding memory operations a given instruction depends on, either at an + intra- or inter-block level. Because of its laziness and caching + policy, using MemDep can be a significant performance win over accessing alias + analysis directly.

    + +
    + + + +
    +
    + Valid CSS! + Valid HTML 4.01! + + Chris Lattner
    + LLVM Compiler Infrastructure
    + Last modified: $Date: 2008/02/12 06:05:03 $ +
    + + + Index: llvm-www/releases/2.2/docs/BOOST_LICENSE_1_0.txt diff -c /dev/null llvm-www/releases/2.2/docs/BOOST_LICENSE_1_0.txt:1.1 *** /dev/null Tue Feb 12 00:06:59 2008 --- llvm-www/releases/2.2/docs/BOOST_LICENSE_1_0.txt Tue Feb 12 00:05:03 2008 *************** *** 0 **** --- 1,23 ---- + Boost Software License - Version 1.0 - August 17th, 2003 + + Permission is hereby granted, free of charge, to any person or organization + obtaining a copy of the software and accompanying documentation covered by + this license (the "Software") to use, reproduce, display, distribute, + execute, and transmit the Software, and to prepare derivative works of the + Software, and to permit third-parties to whom the Software is furnished to + do so, all subject to the following: + + The copyright notices in the Software and this entire statement, including + the above license grant, this restriction and the following disclaimer, + must be included in all copies of the Software, in whole or in part, and + all derivative works of the Software, unless such copies or derivative + works are solely in the form of machine-executable object code generated by + a source language processor. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT + SHALL THE COPYRIGHT HOLDERS OR ANYONE DISTRIBUTING THE SOFTWARE BE LIABLE + FOR ANY DAMAGES OR OTHER LIABILITY, WHETHER IN CONTRACT, TORT OR OTHERWISE, + ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER + DEALINGS IN THE SOFTWARE. Index: llvm-www/releases/2.2/docs/BitCodeFormat.html diff -c /dev/null llvm-www/releases/2.2/docs/BitCodeFormat.html:1.1 *** /dev/null Tue Feb 12 00:06:59 2008 --- llvm-www/releases/2.2/docs/BitCodeFormat.html Tue Feb 12 00:05:03 2008 *************** *** 0 **** --- 1,653 ---- + + + + + LLVM Bitcode File Format + + + +
    LLVM Bitcode File Format
    +
      +
    1. Abstract
      2. +
    2. Overview
      3. +
    3. Bitstream Format +
        +
      1. Magic Numbers
        2. +
      2. Primitives
        3. +
      3. Abbreviation IDs
        4. +
      4. Blocks
        5. +
      5. Data Records
        6. +
      6. Abbreviations
        7. +
      7. Standard Blocks
        8. +
      +
      4. +
    4. LLVM IR Encoding +
        +
      1. Basics
        2. +
      +
      5. +
    +
    +

    Written by Chris Lattner + and Joshua Haberman. +

    +
    + + +
    Abstract
    + + +
    + +

    This document describes the LLVM bitstream file format and the encoding of + the LLVM IR into it.

    + +
    + + +
    Overview
    + + +
    + +

    + What is commonly known as the LLVM bitcode file format (also, sometimes + anachronistically known as bytecode) is actually two things: a bitstream container format + and an encoding of LLVM IR into the container format.

    + +

    + The bitstream format is an abstract encoding of structured data, very + similar to XML in some ways. Like XML, bitstream files contain tags, and nested + structures, and you can parse the file without having to understand the tags. + Unlike XML, the bitstream format is a binary encoding, and unlike XML it + provides a mechanism for the file to self-describe "abbreviations", which are + effectively size optimizations for the content.

    + +

    This document first describes the LLVM bitstream format, then describes the + record structure used by LLVM IR files. +

    + +
    + + +
    Bitstream Format
    + + +
    + +

    + The bitstream format is literally a stream of bits, with a very simple + structure. This structure consists of the following concepts: +

    + +
      +
    • A "magic number" that identifies the contents of + the stream.
      • +
    • Encoding primitives like variable bit-rate + integers.
      • +
    • Blocks, which define nested content.
      • +
    • Data Records, which describe entities within the + file.
      • +
    • Abbreviations, which specify compression optimizations for the file.
      • +
    + +

    Note that the llvm-bcanalyzer tool can be + used to dump and inspect arbitrary bitstreams, which is very useful for + understanding the encoding.

    + +
    + + +
    Magic Numbers +
    + +
    + +

    The first two bytes of a bitcode file are 'BC' (0x42, 0x43). + The second two bytes are an application-specific magic number. Generic + bitcode tools can look at only the first two bytes to verify the file is + bitcode, while application-specific programs will want to look at all four.

    + +
    + + +
    Primitives +
    + +
    + +

    + A bitstream literally consists of a stream of bits, which are read in order + starting with the least significant bit of each byte. The stream is made up of a + number of primitive values that encode a stream of unsigned integer values. + These + integers are are encoded in two ways: either as Fixed + Width Integers or as Variable Width + Integers. +

    + +
    + + +
    Fixed Width Integers +
    + +
    + +

    Fixed-width integer values have their low bits emitted directly to the file. + For example, a 3-bit integer value encodes 1 as 001. Fixed width integers + are used when there are a well-known number of options for a field. For + example, boolean values are usually encoded with a 1-bit wide integer. +

    + +
    + + +
    Variable Width + Integers
    + +
    + +

    Variable-width integer (VBR) values encode values of arbitrary size, + optimizing for the case where the values are small. Given a 4-bit VBR field, + any 3-bit value (0 through 7) is encoded directly, with the high bit set to + zero. Values larger than N-1 bits emit their bits in a series of N-1 bit + chunks, where all but the last set the high bit.

    + +

    For example, the value 27 (0x1B) is encoded as 1011 0011 when emitted as a + vbr4 value. The first set of four bits indicates the value 3 (011) with a + continuation piece (indicated by a high bit of 1). The next word indicates a + value of 24 (011 << 3) with no continuation. The sum (3+24) yields the value + 27. +

    + +
    + + +
    6-bit characters
    + +
    + +

    6-bit characters encode common characters into a fixed 6-bit field. They + represent the following characters with the following 6-bit values:

    + +
      +
    • 'a' .. 'z' - 0 .. 25
      • +
    • 'A' .. 'Z' - 26 .. 51
      • +
    • '0' .. '9' - 52 .. 61
      • +
    • '.' - 62
      • +
    • '_' - 63
      • +
    + +

    This encoding is only suitable for encoding characters and strings that + consist only of the above characters. It is completely incapable of encoding + characters not in the set.

    + +
    + + +
    Word Alignment
    + +
    + +

    Occasionally, it is useful to emit zero bits until the bitstream is a + multiple of 32 bits. This ensures that the bit position in the stream can be + represented as a multiple of 32-bit words.

    + +
    + + + +
    Abbreviation IDs +
    + +
    + +

    + A bitstream is a sequential series of Blocks and + Data Records. Both of these start with an + abbreviation ID encoded as a fixed-bitwidth field. The width is specified by + the current block, as described below. The value of the abbreviation ID + specifies either a builtin ID (which have special meanings, defined below) or + one of the abbreviation IDs defined by the stream itself. +

    + +

    + The set of builtin abbrev IDs is: +

    + +
      +
    • 0 - END_BLOCK - This abbrev ID marks the end of the + current block.
      • +
    • 1 - ENTER_SUBBLOCK - This abbrev ID marks the + beginning of a new block.
      • +
    • 2 - DEFINE_ABBREV - This defines a new + abbreviation.
      • +
    • 3 - UNABBREV_RECORD - This ID specifies the + definition of an unabbreviated record.
      • +
    + +

    Abbreviation IDs 4 and above are defined by the stream itself, and specify + an abbreviated record encoding.

    + +
    + + +
    Blocks +
    + +
    + +

    + Blocks in a bitstream denote nested regions of the stream, and are identified by + a content-specific id number (for example, LLVM IR uses an ID of 12 to represent + function bodies). Block IDs 0-7 are reserved for standard blocks + whose meaning is defined by Bitcode; block IDs 8 and greater are + application specific. Nested blocks capture the hierachical structure of the data + encoded in it, and various properties are associated with blocks as the file is + parsed. Block definitions allow the reader to efficiently skip blocks + in constant time if the reader wants a summary of blocks, or if it wants to + efficiently skip data they do not understand. The LLVM IR reader uses this + mechanism to skip function bodies, lazily reading them on demand. +

    + +

    + When reading and encoding the stream, several properties are maintained for the + block. In particular, each block maintains: +

    + +
      +
    1. A current abbrev id width. This value starts at 2, and is set every time a + block record is entered. The block entry specifies the abbrev id width for + the body of the block.
      2. + +
    2. A set of abbreviations. Abbreviations may be defined within a block, in + which case they are only defined in that block (neither subblocks nor + enclosing blocks see the abbreviation). Abbreviations can also be defined + inside a BLOCKINFO block, in which case they are + defined in all blocks that match the ID that the BLOCKINFO block is describing. +
      3. +
    + +

    As sub blocks are entered, these properties are saved and the new sub-block + has its own set of abbreviations, and its own abbrev id width. When a sub-block + is popped, the saved values are restored.

    + +
    + + +
    ENTER_SUBBLOCK + Encoding
    + +
    + +

    [ENTER_SUBBLOCK, blockidvbr8, newabbrevlenvbr4, + <align32bits>, blocklen32]

    + +

    + The ENTER_SUBBLOCK abbreviation ID specifies the start of a new block record. + The blockid value is encoded as a 8-bit VBR identifier, and indicates + the type of block being entered (which can be a standard + block or an application-specific block). The + newabbrevlen value is a 4-bit VBR which specifies the + abbrev id width for the sub-block. The blocklen is a 32-bit aligned + value that specifies the size of the subblock, in 32-bit words. This value + allows the reader to skip over the entire block in one jump. +

    + +
    + + +
    END_BLOCK + Encoding
    + +
    + +

    [END_BLOCK, <align32bits>]

    + +

    + The END_BLOCK abbreviation ID specifies the end of the current block record. + Its end is aligned to 32-bits to ensure that the size of the block is an even + multiple of 32-bits.

    + +
    + + + + +
    Data Records +
    + +
    +

    + Data records consist of a record code and a number of (up to) 64-bit integer + values. The interpretation of the code and values is application specific and + there are multiple different ways to encode a record (with an unabbrev record + or with an abbreviation). In the LLVM IR format, for example, there is a record + which encodes the target triple of a module. The code is MODULE_CODE_TRIPLE, + and the values of the record are the ascii codes for the characters in the + string.

    + +
    + + +
    UNABBREV_RECORD + Encoding
    + +
    + +

    [UNABBREV_RECORD, codevbr6, numopsvbr6, + op0vbr6, op1vbr6, ...]

    + +

    An UNABBREV_RECORD provides a default fallback encoding, which is both + completely general and also extremely inefficient. It can describe an arbitrary + record, by emitting the code and operands as vbrs.

    + +

    For example, emitting an LLVM IR target triple as an unabbreviated record + requires emitting the UNABBREV_RECORD abbrevid, a vbr6 for the + MODULE_CODE_TRIPLE code, a vbr6 for the length of the string (which is equal to + the number of operands), and a vbr6 for each character. Since there are no + letters with value less than 32, each letter would need to be emitted as at + least a two-part VBR, which means that each letter would require at least 12 + bits. This is not an efficient encoding, but it is fully general.

    + +
    + + +
    Abbreviated Record + Encoding
    + +
    + +

    [<abbrevid>, fields...]

    + +

    An abbreviated record is a abbreviation id followed by a set of fields that + are encoded according to the abbreviation + definition. This allows records to be encoded significantly more densely + than records encoded with the UNABBREV_RECORD + type, and allows the abbreviation types to be specified in the stream itself, + which allows the files to be completely self describing. The actual encoding + of abbreviations is defined below. +

    + +
    + + +
    Abbreviations +
    + +
    +

    + Abbreviations are an important form of compression for bitstreams. The idea is + to specify a dense encoding for a class of records once, then use that encoding + to emit many records. It takes space to emit the encoding into the file, but + the space is recouped (hopefully plus some) when the records that use it are + emitted. +

    + +

    + Abbreviations can be determined dynamically per client, per file. Since the + abbreviations are stored in the bitstream itself, different streams of the same + format can contain different sets of abbreviations if the specific stream does + not need it. As a concrete example, LLVM IR files usually emit an abbreviation + for binary operators. If a specific LLVM module contained no or few binary + operators, the abbreviation does not need to be emitted. +

    +
    + + +
    DEFINE_ABBREV + Encoding
    + +
    + +

    [DEFINE_ABBREV, numabbrevopsvbr5, abbrevop0, abbrevop1, + ...]

    + +

    A DEFINE_ABBREV record adds an abbreviation to the list of currently + defined abbreviations in the scope of this block. This definition only + exists inside this immediate block -- it is not visible in subblocks or + enclosing blocks. + Abbreviations are implicitly assigned IDs + sequentially starting from 4 (the first application-defined abbreviation ID). + Any abbreviations defined in a BLOCKINFO record receive IDs first, in order, + followed by any abbreviations defined within the block itself. + Abbreviated data records reference this ID to indicate what abbreviation + they are invoking.

    + +

    An abbreviation definition consists of the DEFINE_ABBREV abbrevid followed + by a VBR that specifies the number of abbrev operands, then the abbrev + operands themselves. Abbreviation operands come in three forms. They all start + with a single bit that indicates whether the abbrev operand is a literal operand + (when the bit is 1) or an encoding operand (when the bit is 0).

    + +
      +
    1. Literal operands - [11, litvaluevbr8] - + Literal operands specify that the value in the result + is always a single specific value. This specific value is emitted as a vbr8 + after the bit indicating that it is a literal operand.
      2. +
    2. Encoding info without data - [01, encoding3] + - Operand encodings that do not have extra data are just emitted as their code. +
      3. +
    3. Encoding info with data - [01, encoding3, + valuevbr5] - Operand encodings that do have extra data are + emitted as their code, followed by the extra data. +
      4. +
    + +

    The possible operand encodings are:

    + +
      +
    • 1 - Fixed - The field should be emitted as a fixed-width value, whose width + is specified by the operand's extra data.
      • +
    • 2 - VBR - The field should be emitted as a variable-width value, whose width + is specified by the operand's extra data.
      • +
    • 3 - Array - This field is an array of values. The array operand has no + extra data, but expects another operand to follow it which indicates the + element type of the array. When reading an array in an abbreviated record, + the first integer is a vbr6 that indicates the array length, followed by + the encoded elements of the array. An array may only occur as the last + operand of an abbreviation (except for the one final operand that gives + the array's type).
      • +
    • 4 - Char6 - This field should be emitted as a char6-encoded + value. This operand type takes no extra data.
      • +
    + +

    For example, target triples in LLVM modules are encoded as a record of the + form [TRIPLE, 'a', 'b', 'c', 'd']. Consider if the bitstream emitted + the following abbrev entry:

    + +
      +
    • [0, Fixed, 4]
      • +
    • [0, Array]
      • +
    • [0, Char6]
      • +
    + +

    When emitting a record with this abbreviation, the above entry would be + emitted as:

    + +

    [4abbrevwidth, 24, 4vbr6, + 06, 16, 26, 36]

    + +

    These values are:

    + +
      +
    1. The first value, 4, is the abbreviation ID for this abbreviation.
      2. +
    2. The second value, 2, is the code for TRIPLE in LLVM IR files.
      3. +
    3. The third value, 4, is the length of the array.
      4. +
    4. The rest of the values are the char6 encoded values for "abcd".
      5. +
    + +

    With this abbreviation, the triple is emitted with only 37 bits (assuming a + abbrev id width of 3). Without the abbreviation, significantly more space would + be required to emit the target triple. Also, since the TRIPLE value is not + emitted as a literal in the abbreviation, the abbreviation can also be used for + any other string value. +

    + +
    + + +
    Standard Blocks +
    + +
    + +

    + In addition to the basic block structure and record encodings, the bitstream + also defines specific builtin block types. These block types specify how the + stream is to be decoded or other metadata. In the future, new standard blocks + may be added. Block IDs 0-7 are reserved for standard blocks. +

    + +
    + + +
    #0 - BLOCKINFO + Block
    + +
    + +

    The BLOCKINFO block allows the description of metadata for other blocks. The + currently specified records are:

    + +
      +
    • [SETBID (#1), blockid]
      • +
    • [DEFINE_ABBREV, ...]
      • +
    + +

    + The SETBID record indicates which block ID is being described. SETBID + records can occur multiple times throughout the block to change which + block ID is being described. There must be a SETBID record prior to + any other records. +

    + +

    + Standard DEFINE_ABBREV records can occur inside BLOCKINFO blocks, but unlike + their occurrence in normal blocks, the abbreviation is defined for blocks + matching the block ID we are describing, not the BLOCKINFO block itself. + The abbreviations defined in BLOCKINFO blocks receive abbreviation ids + as described in DEFINE_ABBREV. +

    + +

    + Note that although the data in BLOCKINFO blocks is described as "metadata," the + abbreviations they contain are essential for parsing records from the + corresponding blocks. It is not safe to skip them. +

    + +
    + + +
    LLVM IR Encoding
    + + +
    + +

    LLVM IR is encoded into a bitstream by defining blocks and records. It uses + blocks for things like constant pools, functions, symbol tables, etc. It uses + records for things like instructions, global variable descriptors, type + descriptions, etc. This document does not describe the set of abbreviations + that the writer uses, as these are fully self-described in the file, and the + reader is not allowed to build in any knowledge of this.

    + +
    + + +
    Basics +
    + + +
    LLVM IR Magic Number
    + +
    + +

    + The magic number for LLVM IR files is: +

    + +

    [0x04, 0xC4, 0xE4, 0xD4]

    + +

    When combined with the bitcode magic number and viewed as bytes, this is "BC 0xC0DE".

    + +
    + + +
    Signed VBRs
    + +
    + +

    + Variable Width Integers are an efficient way to + encode arbitrary sized unsigned values, but is an extremely inefficient way to + encode signed values (as signed values are otherwise treated as maximally large + unsigned values).

    + +

    As such, signed vbr values of a specific width are emitted as follows:

    + +
      +
    • Positive values are emitted as vbrs of the specified width, but with their + value shifted left by one.
      • +
    • Negative values are emitted as vbrs of the specified width, but the negated + value is shifted left by one, and the low bit is set.
      • +
    + +

    With this encoding, small positive and small negative values can both be + emitted efficiently.

    + +
    + + + +
    LLVM IR Blocks
    + +
    + +

    + LLVM IR is defined with the following blocks: +

    + +
      +
    • 8 - MODULE_BLOCK - This is the top-level block that contains the + entire module, and describes a variety of per-module information.
      • +
    • 9 - PARAMATTR_BLOCK - This enumerates the parameter attributes.
      • +
    • 10 - TYPE_BLOCK - This describes all of the types in the module.
      • +
    • 11 - CONSTANTS_BLOCK - This describes constants for a module or + function.
      • +
    • 12 - FUNCTION_BLOCK - This describes a function body.
      • +
    • 13 - TYPE_SYMTAB_BLOCK - This describes the type symbol table.
      • +
    • 14 - VALUE_SYMTAB_BLOCK - This describes a value symbol table.
      • +
    + +
    + + +
    MODULE_BLOCK Contents +
    + +
    + +

    +

    + +
    + + + +
    +
    Valid CSS! + Valid HTML 4.01! + Chris Lattner
    + The LLVM Compiler Infrastructure
    + Last modified: $Date: 2008/02/12 06:05:03 $ +
    + + Index: llvm-www/releases/2.2/docs/Bugpoint.html diff -c /dev/null llvm-www/releases/2.2/docs/Bugpoint.html:1.1 *** /dev/null Tue Feb 12 00:06:59 2008 --- llvm-www/releases/2.2/docs/Bugpoint.html Tue Feb 12 00:05:03 2008 *************** *** 0 **** --- 1,244 ---- + + + + LLVM bugpoint tool: design and usage + + + +
    + LLVM bugpoint tool: design and usage +
    + + + +
    +

    Written by Chris Lattner

    +
    + + +
    + Description +
    + + +
    + +

    bugpoint narrows down the source of problems in LLVM tools and + passes. It can be used to debug three types of failures: optimizer crashes, + miscompilations by optimizers, or bad native code generation (including problems + in the static and JIT compilers). It aims to reduce large test cases to small, + useful ones. For example, if opt crashes while optimizing a + file, it will identify the optimization (or combination of optimizations) that + causes the crash, and reduce the file down to a small example which triggers the + crash.

    + +

    For detailed case scenarios, such as debugging opt, + llvm-ld, or one of the LLVM code generators, see How To Submit a Bug Report document.

    + +
    + + +
    + Design Philosophy +
    + + +
    + +

    bugpoint is designed to be a useful tool without requiring any + hooks into the LLVM infrastructure at all. It works with any and all LLVM + passes and code generators, and does not need to "know" how they work. Because + of this, it may appear to do stupid things or miss obvious + simplifications. bugpoint is also designed to trade off programmer + time for computer time in the compiler-debugging process; consequently, it may + take a long period of (unattended) time to reduce a test case, but we feel it + is still worth it. Note that bugpoint is generally very quick unless + debugging a miscompilation where each test of the program (which requires + executing it) takes a long time.

    + +
    + + +
    + Automatic Debugger Selection +
    + +
    + +

    bugpoint reads each .bc or .ll file specified on + the command line and links them together into a single module, called the test + program. If any LLVM passes are specified on the command line, it runs these + passes on the test program. If any of the passes crash, or if they produce + malformed output (which causes the verifier to abort), bugpoint starts + the crash debugger.

    + +

    Otherwise, if the -output option was not specified, + bugpoint runs the test program with the C backend (which is assumed to + generate good code) to generate a reference output. Once bugpoint has + a reference output for the test program, it tries executing it with the + selected code generator. If the selected code generator crashes, + bugpoint starts the crash debugger on the + code generator. Otherwise, if the resulting output differs from the reference + output, it assumes the difference resulted from a code generator failure, and + starts the code generator debugger.

    + +

    Finally, if the output of the selected code generator matches the reference + output, bugpoint runs the test program after all of the LLVM passes + have been applied to it. If its output differs from the reference output, it + assumes the difference resulted from a failure in one of the LLVM passes, and + enters the miscompilation debugger. + Otherwise, there is no problem bugpoint can debug.

    + +
    + + +
    + Crash debugger +
    + +
    + +

    If an optimizer or code generator crashes, bugpoint will try as hard + as it can to reduce the list of passes (for optimizer crashes) and the size of + the test program. First, bugpoint figures out which combination of + optimizer passes triggers the bug. This is useful when debugging a problem + exposed by opt, for example, because it runs over 38 passes.

    + +

    Next, bugpoint tries removing functions from the test program, to + reduce its size. Usually it is able to reduce a test program to a single + function, when debugging intraprocedural optimizations. Once the number of + functions has been reduced, it attempts to delete various edges in the control + flow graph, to reduce the size of the function as much as possible. Finally, + bugpoint deletes any individual LLVM instructions whose absence does + not eliminate the failure. At the end, bugpoint should tell you what + passes crash, give you a bitcode file, and give you instructions on how to + reproduce the failure with opt or llc.

    + +
    + + +
    + Code generator debugger +
    + +
    + +

    The code generator debugger attempts to narrow down the amount of code that + is being miscompiled by the selected code generator. To do this, it takes the + test program and partitions it into two pieces: one piece which it compiles + with the C backend (into a shared object), and one piece which it runs with + either the JIT or the static LLC compiler. It uses several techniques to + reduce the amount of code pushed through the LLVM code generator, to reduce the + potential scope of the problem. After it is finished, it emits two bitcode + files (called "test" [to be compiled with the code generator] and "safe" [to be + compiled with the C backend], respectively), and instructions for reproducing + the problem. The code generator debugger assumes that the C backend produces + good code.

    + +
    + + +
    + Miscompilation debugger +
    + +
    + +

    The miscompilation debugger works similarly to the code generator debugger. + It works by splitting the test program into two pieces, running the + optimizations specified on one piece, linking the two pieces back together, and + then executing the result. It attempts to narrow down the list of passes to + the one (or few) which are causing the miscompilation, then reduce the portion + of the test program which is being miscompiled. The miscompilation debugger + assumes that the selected code generator is working properly.

    + +
    + + +
    + Advice for using bugpoint +
    + + +
    + + bugpoint can be a remarkably useful tool, but it sometimes works in + non-obvious ways. Here are some hints and tips:

    + +

      +
    1. In the code generator and miscompilation debuggers, bugpoint only + works with programs that have deterministic output. Thus, if the program + outputs argv[0], the date, time, or any other "random" data, + bugpoint may misinterpret differences in these data, when output, + as the result of a miscompilation. Programs should be temporarily modified + to disable outputs that are likely to vary from run to run. + +
    2. In the code generator and miscompilation debuggers, debugging will go + faster if you manually modify the program or its inputs to reduce the + runtime, but still exhibit the problem. + +
    3. bugpoint is extremely useful when working on a new optimization: + it helps track down regressions quickly. To avoid having to relink + bugpoint every time you change your optimization however, have + bugpoint dynamically load your optimization with the + -load option. + +

    4. bugpoint can generate a lot of output and run for a long period + of time. It is often useful to capture the output of the program to file. + For example, in the C shell, you can run:

      + +
      +

      bugpoint ... |& tee bugpoint.log

      +
      + +

      to get a copy of bugpoint's output in the file + bugpoint.log, as well as on your terminal.

      + +
    5. bugpoint cannot debug problems with the LLVM linker. If + bugpoint crashes before you see its "All input ok" message, + you might try llvm-link -v on the same set of input files. If + that also crashes, you may be experiencing a linker bug. + +
    6. If your program is supposed to crash, bugpoint will be + confused. One way to deal with this is to cause bugpoint to ignore the exit + code from your program, by giving it the -check-exit-code=false + option. + +
    7. bugpoint is useful for proactively finding bugs in LLVM. + Invoking bugpoint with the -find-bugs option will cause + the list of specified optimizations to be randomized and applied to the + program. This process will repeat until a bug is found or the user + kills bugpoint. + +
    + +
    + + + +
    +
    + Valid CSS! + Valid HTML 4.01! + + Chris Lattner
    + LLVM Compiler Infrastructure
    + Last modified: $Date: 2008/02/12 06:05:03 $ +
    + + + Index: llvm-www/releases/2.2/docs/CFEBuildInstrs.html diff -c /dev/null llvm-www/releases/2.2/docs/CFEBuildInstrs.html:1.1 *** /dev/null Tue Feb 12 00:06:59 2008 --- llvm-www/releases/2.2/docs/CFEBuildInstrs.html Tue Feb 12 00:05:03 2008 *************** *** 0 **** --- 1,97 ---- + + + + + + Building the LLVM C/C++ Front-End + + + +
    + Building the LLVM C/C++ Front-End +
    + +
      +
    1. Building llvm-gcc 4 from Source
      2. +
    2. License Information
      3. +
    + +
    +

    Written by the LLVM Team

    +
    + + +
    + Building llvm-gcc 4 from Source +
    + + +
    + +

    This section describes how to aquire and build llvm-gcc4, which is based on + the GCC 4.0.1 front-end. This front-end supports C, C++, Objective-C, and + Objective-C++. Note that the instructions for building this front-end are + completely different (and much easier!) than those for building llvm-gcc3 in + the past.

    + +
      +

    1. Retrieve the appropriate llvm-gcc4-x.y.source.tar.gz archive from the + llvm web site.

      + +

      It is also possible to download the sources of the llvm-gcc4 front end + from a read-only mirror using subversion. To check out the code the + first time use:

      + +
      + 
      + svn co http://llvm.org/svn/llvm-project/llvm-gcc-4.0/trunk dst-directory
+
      +
      + +

      After that, the code can be be updated in the destination directory + using:

      + +
      + 
      svn update
      +
      + +

      The mirror is brought up to date every evening.

      2. + +
    2. Follow the directions in the top-level README.LLVM file for + up-to-date instructions on how to build llvm-gcc4.
      3. +
    + +
    + +
    + License Information +
    + +
    +

    + The LLVM GCC frontend is licensed to you under the GNU General Public License + and the GNU Lesser General Public License. Please see the files COPYING and + COPYING.LIB for more details. +

    + +

    + More information is available in the FAQ. +

    +
    + + + +
    +
    + Valid CSS! + Valid HTML 4.01! + + LLVM Compiler Infrastructure
    + Last modified: $Date: 2008/02/12 06:05:03 $ +
    + + + Index: llvm-www/releases/2.2/docs/CodeGenerator.html diff -c /dev/null llvm-www/releases/2.2/docs/CodeGenerator.html:1.1 *** /dev/null Tue Feb 12 00:06:59 2008 --- llvm-www/releases/2.2/docs/CodeGenerator.html Tue Feb 12 00:05:03 2008 *************** *** 0 **** --- 1,1962 ---- + + + + + The LLVM Target-Independent Code Generator + + + + +
    + The LLVM Target-Independent Code Generator +
    + +
      +
    1. Introduction + +
      2. +
    2. Target description classes + +
      3. +
    3. Machine code description classes + +
      4. +
    4. Target-independent code generation algorithms + +
      5. +
    5. Target-specific Implementation Notes +
      6. + +
    + +
    +

    Written by Chris Lattner, + Bill Wendling, + Fernando Magno Quintao + Pereira and + Jim Laskey

    +
    + +
    +

    Warning: This is a work in progress.

    +
    + + +
    + Introduction +
    + + +
    + +

    The LLVM target-independent code generator is a framework that provides a + suite of reusable components for translating the LLVM internal representation to + the machine code for a specified target—either in assembly form (suitable + for a static compiler) or in binary machine code format (usable for a JIT + compiler). The LLVM target-independent code generator consists of five main + components:

    + +
      +
    1. Abstract target description interfaces which + capture important properties about various aspects of the machine, independently + of how they will be used. These interfaces are defined in + include/llvm/Target/.
      2. + +
    2. Classes used to represent the machine code being + generated for a target. These classes are intended to be abstract enough to + represent the machine code for any target machine. These classes are + defined in include/llvm/CodeGen/.
      3. + +
    3. Target-independent algorithms used to implement + various phases of native code generation (register allocation, scheduling, stack + frame representation, etc). This code lives in lib/CodeGen/.
      4. + +
    4. Implementations of the abstract target description + interfaces for particular targets. These machine descriptions make use of + the components provided by LLVM, and can optionally provide custom + target-specific passes, to build complete code generators for a specific target. + Target descriptions live in lib/Target/.
      5. + +
    5. The target-independent JIT components. The LLVM JIT is + completely target independent (it uses the TargetJITInfo structure to + interface for target-specific issues. The code for the target-independent + JIT lives in lib/ExecutionEngine/JIT.
      6. + +
    + +

    + Depending on which part of the code generator you are interested in working on, + different pieces of this will be useful to you. In any case, you should be + familiar with the target description and machine code representation classes. If you want to add + a backend for a new target, you will need to implement the + target description classes for your new target and understand the LLVM code representation. If you are interested in + implementing a new code generation algorithm, it + should only depend on the target-description and machine code representation + classes, ensuring that it is portable. +

    + +
    + + +
    + Required components in the code generator +
    + +
    + +

    The two pieces of the LLVM code generator are the high-level interface to the + code generator and the set of reusable components that can be used to build + target-specific backends. The two most important interfaces (TargetMachine and TargetData) are the only ones that are + required to be defined for a backend to fit into the LLVM system, but the others + must be defined if the reusable code generator components are going to be + used.

    + +

    This design has two important implications. The first is that LLVM can + support completely non-traditional code generation targets. For example, the C + backend does not require register allocation, instruction selection, or any of + the other standard components provided by the system. As such, it only + implements these two interfaces, and does its own thing. Another example of a + code generator like this is a (purely hypothetical) backend that converts LLVM + to the GCC RTL form and uses GCC to emit machine code for a target.

    + +

    This design also implies that it is possible to design and + implement radically different code generators in the LLVM system that do not + make use of any of the built-in components. Doing so is not recommended at all, + but could be required for radically different targets that do not fit into the + LLVM machine description model: FPGAs for example.

    + +
    + + +
    + The high-level design of the code generator +
    + +
    + +

    The LLVM target-independent code generator is designed to support efficient and + quality code generation for standard register-based microprocessors. Code + generation in this model is divided into the following stages:

    + +
      +
    1. Instruction Selection - This phase + determines an efficient way to express the input LLVM code in the target + instruction set. + This stage produces the initial code for the program in the target instruction + set, then makes use of virtual registers in SSA form and physical registers that + represent any required register assignments due to target constraints or calling + conventions. This step turns the LLVM code into a DAG of target + instructions.
      2. + +
    2. Scheduling and Formation - This + phase takes the DAG of target instructions produced by the instruction selection + phase, determines an ordering of the instructions, then emits the instructions + as MachineInstrs with that ordering. Note + that we describe this in the instruction selection + section because it operates on a SelectionDAG. +
      3. + +
    3. SSA-based Machine Code Optimizations - This + optional stage consists of a series of machine-code optimizations that + operate on the SSA-form produced by the instruction selector. Optimizations + like modulo-scheduling or peephole optimization work here. +
      4. + +
    4. Register Allocation - The + target code is transformed from an infinite virtual register file in SSA form + to the concrete register file used by the target. This phase introduces spill + code and eliminates all virtual register references from the program.
      5. + +
    5. Prolog/Epilog Code Insertion - Once the + machine code has been generated for the function and the amount of stack space + required is known (used for LLVM alloca's and spill slots), the prolog and + epilog code for the function can be inserted and "abstract stack location + references" can be eliminated. This stage is responsible for implementing + optimizations like frame-pointer elimination and stack packing.
      6. + +
    6. Late Machine Code Optimizations - Optimizations + that operate on "final" machine code can go here, such as spill code scheduling + and peephole optimizations.
      7. + +
    7. Code Emission - The final stage actually + puts out the code for the current function, either in the target assembler + format or in machine code.
      8. + +
    + +

    The code generator is based on the assumption that the instruction selector + will use an optimal pattern matching selector to create high-quality sequences of + native instructions. Alternative code generator designs based on pattern + expansion and aggressive iterative peephole optimization are much slower. This + design permits efficient compilation (important for JIT environments) and + aggressive optimization (used when generating code offline) by allowing + components of varying levels of sophistication to be used for any step of + compilation.

    + +

    In addition to these stages, target implementations can insert arbitrary + target-specific passes into the flow. For example, the X86 target uses a + special pass to handle the 80x87 floating point stack architecture. Other + targets with unusual requirements can be supported with custom passes as + needed.

    + +
    + + + +
    + Using TableGen for target description +
    + +
    + +

    The target description classes require a detailed description of the target + architecture. These target descriptions often have a large amount of common + information (e.g., an add instruction is almost identical to a + sub instruction). + In order to allow the maximum amount of commonality to be factored out, the LLVM + code generator uses the TableGen tool to + describe big chunks of the target machine, which allows the use of + domain-specific and target-specific abstractions to reduce the amount of + repetition.

    + +

    As LLVM continues to be developed and refined, we plan to move more and more + of the target description to the .td form. Doing so gives us a + number of advantages. The most important is that it makes it easier to port + LLVM because it reduces the amount of C++ code that has to be written, and the + surface area of the code generator that needs to be understood before someone + can get something working. Second, it makes it easier to change things. In + particular, if tables and other things are all emitted by tblgen, we + only need a change in one place (tblgen) to update all of the targets + to a new interface.

    + +
    + + +
    + Target description classes +
    + + +
    + +

    The LLVM target description classes (located in the + include/llvm/Target directory) provide an abstract description of the + target machine independent of any particular client. These classes are + designed to capture the abstract properties of the target (such as the + instructions and registers it has), and do not incorporate any particular pieces + of code generation algorithms.

    + +

    All of the target description classes (except the TargetData class) are designed to be subclassed by + the concrete target implementation, and have virtual methods implemented. To + get to these implementations, the TargetMachine class provides accessors that + should be implemented by the target.

    + +
    + + +
    + The TargetMachine class +
    + +
    + +

    The TargetMachine class provides virtual methods that are used to + access the target-specific implementations of the various target description + classes via the get*Info methods (getInstrInfo, + getRegisterInfo, getFrameInfo, etc.). This class is + designed to be specialized by + a concrete target implementation (e.g., X86TargetMachine) which + implements the various virtual methods. The only required target description + class is the TargetData class, but if the + code generator components are to be used, the other interfaces should be + implemented as well.

    + +
    + + + +
    + The TargetData class +
    + +
    + +

    The TargetData class is the only required target description class, + and it is the only class that is not extensible (you cannot derived a new + class from it). TargetData specifies information about how the target + lays out memory for structures, the alignment requirements for various data + types, the size of pointers in the target, and whether the target is + little-endian or big-endian.

    + +
    + + +
    + The TargetLowering class +
    + +
    + +

    The TargetLowering class is used by SelectionDAG based instruction + selectors primarily to describe how LLVM code should be lowered to SelectionDAG + operations. Among other things, this class indicates:

    + +
      +
    • an initial register class to use for various ValueTypes
      • +
    • which operations are natively supported by the target machine
      • +
    • the return type of setcc operations
      • +
    • the type to use for shift amounts
      • +
    • various high-level characteristics, like whether it is profitable to turn + division by a constant into a multiplication sequence
      • +
    + +
    + + +
    + The MRegisterInfo class +
    + +
    + +

    The MRegisterInfo class (which will eventually be renamed to + TargetRegisterInfo) is used to describe the register file of the + target and any interactions between the registers.

    + +

    Registers in the code generator are represented in the code generator by + unsigned integers. Physical registers (those that actually exist in the target + description) are unique small numbers, and virtual registers are generally + large. Note that register #0 is reserved as a flag value.

    + +

    Each register in the processor description has an associated + TargetRegisterDesc entry, which provides a textual name for the + register (used for assembly output and debugging dumps) and a set of aliases + (used to indicate whether one register overlaps with another). +

    + +

    In addition to the per-register description, the MRegisterInfo class + exposes a set of processor specific register classes (instances of the + TargetRegisterClass class). Each register class contains sets of + registers that have the same properties (for example, they are all 32-bit + integer registers). Each SSA virtual register created by the instruction + selector has an associated register class. When the register allocator runs, it + replaces virtual registers with a physical register in the set.

    + +

    + The target-specific implementations of these classes is auto-generated from a TableGen description of the register file. +

    + +
    + + +
    + The TargetInstrInfo class +
    + +
    +

    The TargetInstrInfo class is used to describe the machine + instructions supported by the target. It is essentially an array of + TargetInstrDescriptor objects, each of which describes one + instruction the target supports. Descriptors define things like the mnemonic + for the opcode, the number of operands, the list of implicit register uses + and defs, whether the instruction has certain target-independent properties + (accesses memory, is commutable, etc), and holds any target-specific + flags.

    +
    + + +
    + The TargetFrameInfo class +
    + +
    +

    The TargetFrameInfo class is used to provide information about the + stack frame layout of the target. It holds the direction of stack growth, + the known stack alignment on entry to each function, and the offset to the + local area. The offset to the local area is the offset from the stack + pointer on function entry to the first location where function data (local + variables, spill locations) can be stored.

    +
    + + +
    + The TargetSubtarget class +
    + +
    +

    The TargetSubtarget class is used to provide information about the + specific chip set being targeted. A sub-target informs code generation of + which instructions are supported, instruction latencies and instruction + execution itinerary; i.e., which processing units are used, in what order, and + for how long.

    +
    + + + +
    + The TargetJITInfo class +
    + +
    +

    The TargetJITInfo class exposes an abstract interface used by the + Just-In-Time code generator to perform target-specific activities, such as + emitting stubs. If a TargetMachine supports JIT code generation, it + should provide one of these objects through the getJITInfo + method.

    +
    + + +
    + Machine code description classes +
    + + +
    + +

    At the high-level, LLVM code is translated to a machine specific + representation formed out of + MachineFunction, + MachineBasicBlock, and MachineInstr instances + (defined in include/llvm/CodeGen). This representation is completely + target agnostic, representing instructions in their most abstract form: an + opcode and a series of operands. This representation is designed to support + both an SSA representation for machine code, as well as a register allocated, + non-SSA form.

    + +
    + + +
    + The MachineInstr class +
    + +
    + +

    Target machine instructions are represented as instances of the + MachineInstr class. This class is an extremely abstract way of + representing machine instructions. In particular, it only keeps track of + an opcode number and a set of operands.

    + +

    The opcode number is a simple unsigned integer that only has meaning to a + specific backend. All of the instructions for a target should be defined in + the *InstrInfo.td file for the target. The opcode enum values + are auto-generated from this description. The MachineInstr class does + not have any information about how to interpret the instruction (i.e., what the + semantics of the instruction are); for that you must refer to the + TargetInstrInfo class.

    + +

    The operands of a machine instruction can be of several different types: + a register reference, a constant integer, a basic block reference, etc. In + addition, a machine operand should be marked as a def or a use of the value + (though only registers are allowed to be defs).

    + +

    By convention, the LLVM code generator orders instruction operands so that + all register definitions come before the register uses, even on architectures + that are normally printed in other orders. For example, the SPARC add + instruction: "add %i1, %i2, %i3" adds the "%i1", and "%i2" registers + and stores the result into the "%i3" register. In the LLVM code generator, + the operands should be stored as "%i3, %i1, %i2": with the destination + first.

    + +

    Keeping destination (definition) operands at the beginning of the operand + list has several advantages. In particular, the debugging printer will print + the instruction like this:

    + +
    + 
    + %r3 = add %i1, %i2
+
    +
    + +

    Also if the first operand is a def, it is easier to create instructions whose only def is the first + operand.

    + +
    + + +
    + Using the MachineInstrBuilder.h functions +
    + +
    + +

    Machine instructions are created by using the BuildMI functions, + located in the include/llvm/CodeGen/MachineInstrBuilder.h file. The + BuildMI functions make it easy to build arbitrary machine + instructions. Usage of the BuildMI functions look like this:

    + +
    + 
    + // Create a 'DestReg = mov 42' (rendered in X86 assembly as 'mov DestReg, 42')
+ // instruction.  The '1' specifies how many operands will be added.
+ MachineInstr *MI = BuildMI(X86::MOV32ri, 1, DestReg).addImm(42);
+ 
+ // Create the same instr, but insert it at the end of a basic block.
+ MachineBasicBlock &MBB = ...
+ BuildMI(MBB, X86::MOV32ri, 1, DestReg).addImm(42);
+ 
+ // Create the same instr, but insert it before a specified iterator point.
+ MachineBasicBlock::iterator MBBI = ...
+ BuildMI(MBB, MBBI, X86::MOV32ri, 1, DestReg).addImm(42);
+ 
+ // Create a 'cmp Reg, 0' instruction, no destination reg.
+ MI = BuildMI(X86::CMP32ri, 2).addReg(Reg).addImm(0);
+ // Create an 'sahf' instruction which takes no operands and stores nothing.
+ MI = BuildMI(X86::SAHF, 0);
+ 
+ // Create a self looping branch instruction.
+ BuildMI(MBB, X86::JNE, 1).addMBB(&MBB);
+
    +
    + +

    The key thing to remember with the BuildMI functions is that you + have to specify the number of operands that the machine instruction will take. + This allows for efficient memory allocation. You also need to specify if + operands default to be uses of values, not definitions. If you need to add a + definition operand (other than the optional destination register), you must + explicitly mark it as such:

    + +
    + 
    + MI.addReg(Reg, MachineOperand::Def);
+
    +
    + +
    + + +
    + Fixed (preassigned) registers +
    + +
    + +

    One important issue that the code generator needs to be aware of is the + presence of fixed registers. In particular, there are often places in the + instruction stream where the register allocator must arrange for a + particular value to be in a particular register. This can occur due to + limitations of the instruction set (e.g., the X86 can only do a 32-bit divide + with the EAX/EDX registers), or external factors like calling + conventions. In any case, the instruction selector should emit code that + copies a virtual register into or out of a physical register when needed.

    + +

    For example, consider this simple LLVM example:

    + +
    + 
    + int %test(int %X, int %Y) {
+   %Z = div int %X, %Y
+   ret int %Z
+ }
+
    +
    + +

    The X86 instruction selector produces this machine code for the div + and ret (use + "llc X.bc -march=x86 -print-machineinstrs" to get this):

    + +
    + 
    + ;; Start of div
+ %EAX = mov %reg1024           ;; Copy X (in reg1024) into EAX
+ %reg1027 = sar %reg1024, 31
+ %EDX = mov %reg1027           ;; Sign extend X into EDX
+ idiv %reg1025                 ;; Divide by Y (in reg1025)
+ %reg1026 = mov %EAX           ;; Read the result (Z) out of EAX
+ 
+ ;; Start of ret
+ %EAX = mov %reg1026           ;; 32-bit return value goes in EAX
+ ret
+
    +
    + +

    By the end of code generation, the register allocator has coalesced + the registers and deleted the resultant identity moves producing the + following code:

    + +
    + 
    + ;; X is in EAX, Y is in ECX
+ mov %EAX, %EDX
+ sar %EDX, 31
+ idiv %ECX
+ ret 
+
    +
    + +

    This approach is extremely general (if it can handle the X86 architecture, + it can handle anything!) and allows all of the target specific + knowledge about the instruction stream to be isolated in the instruction + selector. Note that physical registers should have a short lifetime for good + code generation, and all physical registers are assumed dead on entry to and + exit from basic blocks (before register allocation). Thus, if you need a value + to be live across basic block boundaries, it must live in a virtual + register.

    + +
    + + +
    + Machine code in SSA form +
    + +
    + +

    MachineInstr's are initially selected in SSA-form, and + are maintained in SSA-form until register allocation happens. For the most + part, this is trivially simple since LLVM is already in SSA form; LLVM PHI nodes + become machine code PHI nodes, and virtual registers are only allowed to have a + single definition.

    + +

    After register allocation, machine code is no longer in SSA-form because there + are no virtual registers left in the code.

    + +
    + + +
    + The MachineBasicBlock class +
    + +
    + +

    The MachineBasicBlock class contains a list of machine instructions + (MachineInstr instances). It roughly + corresponds to the LLVM code input to the instruction selector, but there can be + a one-to-many mapping (i.e. one LLVM basic block can map to multiple machine + basic blocks). The MachineBasicBlock class has a + "getBasicBlock" method, which returns the LLVM basic block that it + comes from.

    + +
    + + +
    + The MachineFunction class +
    + +
    + +

    The MachineFunction class contains a list of machine basic blocks + (MachineBasicBlock instances). It + corresponds one-to-one with the LLVM function input to the instruction selector. + In addition to a list of basic blocks, the MachineFunction contains a + a MachineConstantPool, a MachineFrameInfo, a + MachineFunctionInfo, and a MachineRegisterInfo. See + include/llvm/CodeGen/MachineFunction.h for more information.

    + +
    + + +
    + Target-independent code generation algorithms +
    + + +
    + +

    This section documents the phases described in the high-level design of the code generator. It + explains how they work and some of the rationale behind their design.

    + +
    + + +
    + Instruction Selection +
    + +
    +

    + Instruction Selection is the process of translating LLVM code presented to the + code generator into target-specific machine instructions. There are several + well-known ways to do this in the literature. LLVM uses a SelectionDAG based + instruction selector. +

    + +

    Portions of the DAG instruction selector are generated from the target + description (*.td) files. Our goal is for the entire instruction + selector to be generated from these .td files, though currently + there are still things that require custom C++ code.

    +
    + + +
    + Introduction to SelectionDAGs +
    + +
    + +

    The SelectionDAG provides an abstraction for code representation in a way + that is amenable to instruction selection using automatic techniques + (e.g. dynamic-programming based optimal pattern matching selectors). It is also + well-suited to other phases of code generation; in particular, + instruction scheduling (SelectionDAG's are very close to scheduling DAGs + post-selection). Additionally, the SelectionDAG provides a host representation + where a large variety of very-low-level (but target-independent) + optimizations may be + performed; ones which require extensive information about the instructions + efficiently supported by the target.

    + +

    The SelectionDAG is a Directed-Acyclic-Graph whose nodes are instances of the + SDNode class. The primary payload of the SDNode is its + operation code (Opcode) that indicates what operation the node performs and + the operands to the operation. + The various operation node types are described at the top of the + include/llvm/CodeGen/SelectionDAGNodes.h file.

    + +

    Although most operations define a single value, each node in the graph may + define multiple values. For example, a combined div/rem operation will define + both the dividend and the remainder. Many other situations require multiple + values as well. Each node also has some number of operands, which are edges + to the node defining the used value. Because nodes may define multiple values, + edges are represented by instances of the SDOperand class, which is + a <SDNode, unsigned> pair, indicating the node and result + value being used, respectively. Each value produced by an SDNode has + an associated MVT::ValueType indicating what type the value is.

    + +

    SelectionDAGs contain two different kinds of values: those that represent + data flow and those that represent control flow dependencies. Data values are + simple edges with an integer or floating point value type. Control edges are + represented as "chain" edges which are of type MVT::Other. These edges + provide an ordering between nodes that have side effects (such as + loads, stores, calls, returns, etc). All nodes that have side effects should + take a token chain as input and produce a new one as output. By convention, + token chain inputs are always operand #0, and chain results are always the last + value produced by an operation.

    + +

    A SelectionDAG has designated "Entry" and "Root" nodes. The Entry node is + always a marker node with an Opcode of ISD::EntryToken. The Root node + is the final side-effecting node in the token chain. For example, in a single + basic block function it would be the return node.

    + +

    One important concept for SelectionDAGs is the notion of a "legal" vs. + "illegal" DAG. A legal DAG for a target is one that only uses supported + operations and supported types. On a 32-bit PowerPC, for example, a DAG with + a value of type i1, i8, i16, or i64 would be illegal, as would a DAG that uses a + SREM or UREM operation. The + legalize phase is responsible for turning + an illegal DAG into a legal DAG.

    + +
    + + +
    + SelectionDAG Instruction Selection Process +
    + +
    + +

    SelectionDAG-based instruction selection consists of the following steps:

    + +
      +
    1. Build initial DAG - This stage + performs a simple translation from the input LLVM code to an illegal + SelectionDAG.
      2. +
    2. Optimize SelectionDAG - This stage + performs simple optimizations on the SelectionDAG to simplify it, and + recognize meta instructions (like rotates and div/rem + pairs) for targets that support these meta operations. This makes the + resultant code more efficient and the select + instructions from DAG phase (below) simpler.
      3. +
    3. Legalize SelectionDAG - This stage + converts the illegal SelectionDAG to a legal SelectionDAG by eliminating + unsupported operations and data types.
      4. +
    4. Optimize SelectionDAG (#2) - This + second run of the SelectionDAG optimizes the newly legalized DAG to + eliminate inefficiencies introduced by legalization.
      5. +
    5. Select instructions from DAG - Finally, + the target instruction selector matches the DAG operations to target + instructions. This process translates the target-independent input DAG into + another DAG of target instructions.
      6. +
    6. SelectionDAG Scheduling and Formation + - The last phase assigns a linear order to the instructions in the + target-instruction DAG and emits them into the MachineFunction being + compiled. This step uses traditional prepass scheduling techniques.
      7. +
    + +

    After all of these steps are complete, the SelectionDAG is destroyed and the + rest of the code generation passes are run.

    + +

    One great way to visualize what is going on here is to take advantage of a + few LLC command line options. In particular, the -view-isel-dags + option pops up a window with the SelectionDAG input to the Select phase for all + of the code compiled (if you only get errors printed to the console while using + this, you probably need to configure + your system to add support for it). The -view-sched-dags option + views the SelectionDAG output from the Select phase and input to the Scheduler + phase. The -view-sunit-dags option views the ScheduleDAG, which is + based on the final SelectionDAG, with nodes that must be scheduled as a unit + bundled together into a single node, and with immediate operands and other + nodes that aren't relevent for scheduling omitted. +

    + +
    + + +
    + Initial SelectionDAG Construction +
    + +
    + +

    The initial SelectionDAG is naïvely peephole expanded from the LLVM + input by the SelectionDAGLowering class in the + lib/CodeGen/SelectionDAG/SelectionDAGISel.cpp file. The intent of this + pass is to expose as much low-level, target-specific details to the SelectionDAG + as possible. This pass is mostly hard-coded (e.g. an LLVM add turns + into an SDNode add while a geteelementptr is expanded into the + obvious arithmetic). This pass requires target-specific hooks to lower calls, + returns, varargs, etc. For these features, the + TargetLowering interface is used.

    + +
    + + +
    + SelectionDAG Legalize Phase +
    + +
    + +

    The Legalize phase is in charge of converting a DAG to only use the types and + operations that are natively supported by the target. This involves two major + tasks:

    + +
      +

    1. Convert values of unsupported types to values of supported types.

      +

      There are two main ways of doing this: converting small types to + larger types ("promoting"), and breaking up large integer types + into smaller ones ("expanding"). For example, a target might require + that all f32 values are promoted to f64 and that all i1/i8/i16 values + are promoted to i32. The same target might require that all i64 values + be expanded into i32 values. These changes can insert sign and zero + extensions as needed to make sure that the final code has the same + behavior as the input.

      +

      A target implementation tells the legalizer which types are supported + (and which register class to use for them) by calling the + addRegisterClass method in its TargetLowering constructor.

      +
      2. + +

    2. Eliminate operations that are not supported by the target.

      +

      Targets often have weird constraints, such as not supporting every + operation on every supported datatype (e.g. X86 does not support byte + conditional moves and PowerPC does not support sign-extending loads from + a 16-bit memory location). Legalize takes care of this by open-coding + another sequence of operations to emulate the operation ("expansion"), by + promoting one type to a larger type that supports the operation + ("promotion"), or by using a target-specific hook to implement the + legalization ("custom").

      +

      A target implementation tells the legalizer which operations are not + supported (and which of the above three actions to take) by calling the + setOperationAction method in its TargetLowering + constructor.

      +
      3. +
    + +

    Prior to the existance of the Legalize pass, we required that every target + selector supported and handled every + operator and type even if they are not natively supported. The introduction of + the Legalize phase allows all of the cannonicalization patterns to be shared + across targets, and makes it very easy to optimize the cannonicalized code + because it is still in the form of a DAG.

    + +
    + + +
    + SelectionDAG Optimization Phase: the DAG + Combiner +
    + +
    + +

    The SelectionDAG optimization phase is run twice for code generation: once + immediately after the DAG is built and once after legalization. The first run + of the pass allows the initial code to be cleaned up (e.g. performing + optimizations that depend on knowing that the operators have restricted type + inputs). The second run of the pass cleans up the messy code generated by the + Legalize pass, which allows Legalize to be very simple (it can focus on making + code legal instead of focusing on generating good and legal code).

    + +

    One important class of optimizations performed is optimizing inserted sign + and zero extension instructions. We currently use ad-hoc techniques, but could + move to more rigorous techniques in the future. Here are some good papers on + the subject:

    + +

    + "Widening + integer arithmetic"
    + Kevin Redwine and Norman Ramsey
    + International Conference on Compiler Construction (CC) 2004 +

    + + +

    + "Effective + sign extension elimination"
    + Motohiro Kawahito, Hideaki Komatsu, and Toshio Nakatani
    + Proceedings of the ACM SIGPLAN 2002 Conference on Programming Language Design + and Implementation. +

    + +
    + + +
    + SelectionDAG Select Phase +
    + +
    + +

    The Select phase is the bulk of the target-specific code for instruction + selection. This phase takes a legal SelectionDAG as input, pattern matches the + instructions supported by the target to this DAG, and produces a new DAG of + target code. For example, consider the following LLVM fragment:

    + +
    + 
    + %t1 = add float %W, %X
+ %t2 = mul float %t1, %Y
+ %t3 = add float %t2, %Z
+
    +
    + +

    This LLVM code corresponds to a SelectionDAG that looks basically like + this:

    + +
    + 
    + (fadd:f32 (fmul:f32 (fadd:f32 W, X), Y), Z)
+
    +
    + +

    If a target supports floating point multiply-and-add (FMA) operations, one + of the adds can be merged with the multiply. On the PowerPC, for example, the + output of the instruction selector might look like this DAG:

    + +
    + 
    + (FMADDS (FADDS W, X), Y, Z)
+
    +
    + +

    The FMADDS instruction is a ternary instruction that multiplies its + first two operands and adds the third (as single-precision floating-point + numbers). The FADDS instruction is a simple binary single-precision + add instruction. To perform this pattern match, the PowerPC backend includes + the following instruction definitions:

    + +
    + 
    + def FMADDS : AForm_1<59, 29,
+                     (ops F4RC:$FRT, F4RC:$FRA, F4RC:$FRC, F4RC:$FRB),
+                     "fmadds $FRT, $FRA, $FRC, $FRB",
+                     [(set F4RC:$FRT, (fadd (fmul F4RC:$FRA, F4RC:$FRC),
+                                            F4RC:$FRB))]>;
+ def FADDS : AForm_2<59, 21,
+                     (ops F4RC:$FRT, F4RC:$FRA, F4RC:$FRB),
+                     "fadds $FRT, $FRA, $FRB",
+                     [(set F4RC:$FRT, (fadd F4RC:$FRA, F4RC:$FRB))]>;
+
    +
    + +

    The portion of the instruction definition in bold indicates the pattern used + to match the instruction. The DAG operators (like fmul/fadd) + are defined in the lib/Target/TargetSelectionDAG.td file. + "F4RC" is the register class of the input and result values.

    + +

    The TableGen DAG instruction selector generator reads the instruction + patterns in the .td file and automatically builds parts of the pattern + matching code for your target. It has the following strengths:

    + +
      +
    • At compiler-compiler time, it analyzes your instruction patterns and tells + you if your patterns make sense or not.
      • +
    • It can handle arbitrary constraints on operands for the pattern match. In + particular, it is straight-forward to say things like "match any immediate + that is a 13-bit sign-extended value". For examples, see the + immSExt16 and related tblgen classes in the PowerPC + backend.
      • +
    • It knows several important identities for the patterns defined. For + example, it knows that addition is commutative, so it allows the + FMADDS pattern above to match "(fadd X, (fmul Y, Z))" as + well as "(fadd (fmul X, Y), Z)", without the target author having + to specially handle this case.
      • +
    • It has a full-featured type-inferencing system. In particular, you should + rarely have to explicitly tell the system what type parts of your patterns + are. In the FMADDS case above, we didn't have to tell + tblgen that all of the nodes in the pattern are of type 'f32'. It + was able to infer and propagate this knowledge from the fact that + F4RC has type 'f32'.
      • +
    • Targets can define their own (and rely on built-in) "pattern fragments". + Pattern fragments are chunks of reusable patterns that get inlined into your + patterns during compiler-compiler time. For example, the integer + "(not x)" operation is actually defined as a pattern fragment that + expands as "(xor x, -1)", since the SelectionDAG does not have a + native 'not' operation. Targets can define their own short-hand + fragments as they see fit. See the definition of 'not' and + 'ineg' for examples.
      • +
    • In addition to instructions, targets can specify arbitrary patterns that + map to one or more instructions using the 'Pat' class. For example, + the PowerPC has no way to load an arbitrary integer immediate into a + register in one instruction. To tell tblgen how to do this, it defines: +
      +
      +
      + 
      + // Arbitrary immediate support.  Implement in terms of LIS/ORI.
+ def : Pat<(i32 imm:$imm),
+           (ORI (LIS (HI16 imm:$imm)), (LO16 imm:$imm))>;
+
      +
      +
      + If none of the single-instruction patterns for loading an immediate into a + register match, this will be used. This rule says "match an arbitrary i32 + immediate, turning it into an ORI ('or a 16-bit immediate') and an + LIS ('load 16-bit immediate, where the immediate is shifted to the + left 16 bits') instruction". To make this work, the + LO16/HI16 node transformations are used to manipulate the + input immediate (in this case, take the high or low 16-bits of the + immediate).
      • +
    • While the system does automate a lot, it still allows you to write custom + C++ code to match special cases if there is something that is hard to + express.
      • +
    + +

    While it has many strengths, the system currently has some limitations, + primarily because it is a work in progress and is not yet finished:

    + +
      +
    • Overall, there is no way to define or match SelectionDAG nodes that define + multiple values (e.g. ADD_PARTS, LOAD, CALL, + etc). This is the biggest reason that you currently still have to + write custom C++ code for your instruction selector.
      • +
    • There is no great way to support matching complex addressing modes yet. In + the future, we will extend pattern fragments to allow them to define + multiple values (e.g. the four operands of the X86 + addressing mode, which are currently matched with custom C++ code). + In addition, we'll extend fragments so that a + fragment can match multiple different patterns.
      • +
    • We don't automatically infer flags like isStore/isLoad yet.
      • +
    • We don't automatically generate the set of supported registers and + operations for the Legalizer yet.
      • +
    • We don't have a way of tying in custom legalized nodes yet.
      • +
    + +

    Despite these limitations, the instruction selector generator is still quite + useful for most of the binary and logical operations in typical instruction + sets. If you run into any problems or can't figure out how to do something, + please let Chris know!

    + +
    + + +
    + SelectionDAG Scheduling and Formation Phase +
    + +
    + +

    The scheduling phase takes the DAG of target instructions from the selection + phase and assigns an order. The scheduler can pick an order depending on + various constraints of the machines (i.e. order for minimal register pressure or + try to cover instruction latencies). Once an order is established, the DAG is + converted to a list of MachineInstrs and + the SelectionDAG is destroyed.

    + +

    Note that this phase is logically separate from the instruction selection + phase, but is tied to it closely in the code because it operates on + SelectionDAGs.

    + +
    + + +
    + Future directions for the SelectionDAG +
    + +
    + +
      +
    1. Optional function-at-a-time selection.
      2. +
    2. Auto-generate entire selector from .td file.
      3. +
    + +
    + + +
    + SSA-based Machine Code Optimizations +
    +

    To Be Written

    + + +
    + Live Intervals +
    + +
    + +

    Live Intervals are the ranges (intervals) where a variable is live. + They are used by some register allocator passes to + determine if two or more virtual registers which require the same physical + register are live at the same point in the program (i.e., they conflict). When + this situation occurs, one virtual register must be spilled.

    + +
    + + +
    + Live Variable Analysis +
    + +
    + +

    The first step in determining the live intervals of variables is to + calculate the set of registers that are immediately dead after the + instruction (i.e., the instruction calculates the value, but it is + never used) and the set of registers that are used by the instruction, + but are never used after the instruction (i.e., they are killed). Live + variable information is computed for each virtual register and + register allocatable physical register in the function. This + is done in a very efficient manner because it uses SSA to sparsely + compute lifetime information for virtual registers (which are in SSA + form) and only has to track physical registers within a block. Before + register allocation, LLVM can assume that physical registers are only + live within a single basic block. This allows it to do a single, + local analysis to resolve physical register lifetimes within each + basic block. If a physical register is not register allocatable (e.g., + a stack pointer or condition codes), it is not tracked.

    + +

    Physical registers may be live in to or out of a function. Live in values + are typically arguments in registers. Live out values are typically return + values in registers. Live in values are marked as such, and are given a dummy + "defining" instruction during live intervals analysis. If the last basic block + of a function is a return, then it's marked as using all live out + values in the function.

    + +

    PHI nodes need to be handled specially, because the calculation + of the live variable information from a depth first traversal of the CFG of + the function won't guarantee that a virtual register used by the PHI + node is defined before it's used. When a PHI node is encounted, only + the definition is handled, because the uses will be handled in other basic + blocks.

    + +

    For each PHI node of the current basic block, we simulate an + assignment at the end of the current basic block and traverse the successor + basic blocks. If a successor basic block has a PHI node and one of + the PHI node's operands is coming from the current basic block, + then the variable is marked as alive within the current basic block + and all of its predecessor basic blocks, until the basic block with the + defining instruction is encountered.

    + +
    + + +
    + Live Intervals Analysis +
    + +
    + +

    We now have the information available to perform the live intervals analysis + and build the live intervals themselves. We start off by numbering the basic + blocks and machine instructions. We then handle the "live-in" values. These + are in physical registers, so the physical register is assumed to be killed by + the end of the basic block. Live intervals for virtual registers are computed + for some ordering of the machine instructions [1, N]. A live interval + is an interval [i, j), where 1 <= i <= j < N, for which a + variable is live.

    + +

    More to come...

    + +
    + + +
    + Register Allocation +
    + +
    + +

    The Register Allocation problem consists in mapping a program + Pv, that can use an unbounded number of virtual + registers, to a program Pp that contains a finite + (possibly small) number of physical registers. Each target architecture has + a different number of physical registers. If the number of physical + registers is not enough to accommodate all the virtual registers, some of + them will have to be mapped into memory. These virtuals are called + spilled virtuals.

    + +
    + + + +
    + How registers are represented in LLVM +
    + +
    + +

    In LLVM, physical registers are denoted by integer numbers that + normally range from 1 to 1023. To see how this numbering is defined + for a particular architecture, you can read the + GenRegisterNames.inc file for that architecture. For + instance, by inspecting + lib/Target/X86/X86GenRegisterNames.inc we see that the 32-bit + register EAX is denoted by 15, and the MMX register + MM0 is mapped to 48.

    + +

    Some architectures contain registers that share the same physical + location. A notable example is the X86 platform. For instance, in the + X86 architecture, the registers EAX, AX and + AL share the first eight bits. These physical registers are + marked as aliased in LLVM. Given a particular architecture, you + can check which registers are aliased by inspecting its + RegisterInfo.td file. Moreover, the method + MRegisterInfo::getAliasSet(p_reg) returns an array containing + all the physical registers aliased to the register p_reg.

    + +

    Physical registers, in LLVM, are grouped in Register Classes. + Elements in the same register class are functionally equivalent, and can + be interchangeably used. Each virtual register can only be mapped to + physical registers of a particular class. For instance, in the X86 + architecture, some virtuals can only be allocated to 8 bit registers. + A register class is described by TargetRegisterClass objects. + To discover if a virtual register is compatible with a given physical, + this code can be used: +

    + +
    + 
    + bool RegMapping_Fer::compatible_class(MachineFunction &mf,
+                                       unsigned v_reg,
+                                       unsigned p_reg) {
+   assert(MRegisterInfo::isPhysicalRegister(p_reg) &&
+          "Target register must be physical");
+   const TargetRegisterClass *trc = mf.getRegInfo().getRegClass(v_reg);
+   return trc->contains(p_reg);
+ }
+
    +
    + +

    Sometimes, mostly for debugging purposes, it is useful to change + the number of physical registers available in the target + architecture. This must be done statically, inside the + TargetRegsterInfo.td file. Just grep for + RegisterClass, the last parameter of which is a list of + registers. Just commenting some out is one simple way to avoid them + being used. A more polite way is to explicitly exclude some registers + from the allocation order. See the definition of the + GR register class in + lib/Target/IA64/IA64RegisterInfo.td for an example of this + (e.g., numReservedRegs registers are hidden.)

    + +

    Virtual registers are also denoted by integer numbers. Contrary to + physical registers, different virtual registers never share the same + number. The smallest virtual register is normally assigned the number + 1024. This may change, so, in order to know which is the first virtual + register, you should access + MRegisterInfo::FirstVirtualRegister. Any register whose + number is greater than or equal to + MRegisterInfo::FirstVirtualRegister is considered a virtual + register. Whereas physical registers are statically defined in a + TargetRegisterInfo.td file and cannot be created by the + application developer, that is not the case with virtual registers. + In order to create new virtual registers, use the method + MachineRegisterInfo::createVirtualRegister(). This method will return a + virtual register with the highest code. +

    + +

    Before register allocation, the operands of an instruction are + mostly virtual registers, although physical registers may also be + used. In order to check if a given machine operand is a register, use + the boolean function MachineOperand::isRegister(). To obtain + the integer code of a register, use + MachineOperand::getReg(). An instruction may define or use a + register. For instance, ADD reg:1026 := reg:1025 reg:1024 + defines the registers 1024, and uses registers 1025 and 1026. Given a + register operand, the method MachineOperand::isUse() informs + if that register is being used by the instruction. The method + MachineOperand::isDef() informs if that registers is being + defined.

    + +

    We will call physical registers present in the LLVM bitcode before + register allocation pre-colored registers. Pre-colored + registers are used in many different situations, for instance, to pass + parameters of functions calls, and to store results of particular + instructions. There are two types of pre-colored registers: the ones + implicitly defined, and those explicitly + defined. Explicitly defined registers are normal operands, and can be + accessed with MachineInstr::getOperand(int)::getReg(). In + order to check which registers are implicitly defined by an + instruction, use the + TargetInstrInfo::get(opcode)::ImplicitDefs, where + opcode is the opcode of the target instruction. One important + difference between explicit and implicit physical registers is that + the latter are defined statically for each instruction, whereas the + former may vary depending on the program being compiled. For example, + an instruction that represents a function call will always implicitly + define or use the same set of physical registers. To read the + registers implicitly used by an instruction, use + TargetInstrInfo::get(opcode)::ImplicitUses. Pre-colored + registers impose constraints on any register allocation algorithm. The + register allocator must make sure that none of them is been + overwritten by the values of virtual registers while still alive.

    + +
    + + + +
    + Mapping virtual registers to physical registers +
    + +
    + +

    There are two ways to map virtual registers to physical registers (or to + memory slots). The first way, that we will call direct mapping, + is based on the use of methods of the classes MRegisterInfo, + and MachineOperand. The second way, that we will call + indirect mapping, relies on the VirtRegMap class in + order to insert loads and stores sending and getting values to and from + memory.

    + +

    The direct mapping provides more flexibility to the developer of + the register allocator; however, it is more error prone, and demands + more implementation work. Basically, the programmer will have to + specify where load and store instructions should be inserted in the + target function being compiled in order to get and store values in + memory. To assign a physical register to a virtual register present in + a given operand, use MachineOperand::setReg(p_reg). To insert + a store instruction, use + MRegisterInfo::storeRegToStackSlot(...), and to insert a load + instruction, use MRegisterInfo::loadRegFromStackSlot.

    + +

    The indirect mapping shields the application developer from the + complexities of inserting load and store instructions. In order to map + a virtual register to a physical one, use + VirtRegMap::assignVirt2Phys(vreg, preg). In order to map a + certain virtual register to memory, use + VirtRegMap::assignVirt2StackSlot(vreg). This method will + return the stack slot where vreg's value will be located. If + it is necessary to map another virtual register to the same stack + slot, use VirtRegMap::assignVirt2StackSlot(vreg, + stack_location). One important point to consider when using the + indirect mapping, is that even if a virtual register is mapped to + memory, it still needs to be mapped to a physical register. This + physical register is the location where the virtual register is + supposed to be found before being stored or after being reloaded.

    + +

    If the indirect strategy is used, after all the virtual registers + have been mapped to physical registers or stack slots, it is necessary + to use a spiller object to place load and store instructions in the + code. Every virtual that has been mapped to a stack slot will be + stored to memory after been defined and will be loaded before being + used. The implementation of the spiller tries to recycle load/store + instructions, avoiding unnecessary instructions. For an example of how + to invoke the spiller, see + RegAllocLinearScan::runOnMachineFunction in + lib/CodeGen/RegAllocLinearScan.cpp.

    + +
    + + +
    + Handling two address instructions +
    + +
    + +

    With very rare exceptions (e.g., function calls), the LLVM machine + code instructions are three address instructions. That is, each + instruction is expected to define at most one register, and to use at + most two registers. However, some architectures use two address + instructions. In this case, the defined register is also one of the + used register. For instance, an instruction such as ADD %EAX, + %EBX, in X86 is actually equivalent to %EAX = %EAX + + %EBX.

    + +

    In order to produce correct code, LLVM must convert three address + instructions that represent two address instructions into true two + address instructions. LLVM provides the pass + TwoAddressInstructionPass for this specific purpose. It must + be run before register allocation takes place. After its execution, + the resulting code may no longer be in SSA form. This happens, for + instance, in situations where an instruction such as %a = ADD %b + %c is converted to two instructions such as:

    + +
    + 
    + %a = MOVE %b
+ %a = ADD %a %b
+
    +
    + +

    Notice that, internally, the second instruction is represented as + ADD %a[def/use] %b. I.e., the register operand %a is + both used and defined by the instruction.

    + +
    + + +
    + The SSA deconstruction phase +
    + +
    + +

    An important transformation that happens during register allocation is called + the SSA Deconstruction Phase. The SSA form simplifies many + analyses that are performed on the control flow graph of + programs. However, traditional instruction sets do not implement + PHI instructions. Thus, in order to generate executable code, compilers + must replace PHI instructions with other instructions that preserve their + semantics.

    + +

    There are many ways in which PHI instructions can safely be removed + from the target code. The most traditional PHI deconstruction + algorithm replaces PHI instructions with copy instructions. That is + the strategy adopted by LLVM. The SSA deconstruction algorithm is + implemented in nlib/CodeGen/>PHIElimination.cpp. In order to + invoke this pass, the identifier PHIEliminationID must be + marked as required in the code of the register allocator.

    + +
    + + +
    + Instruction folding +
    + +
    + +

    Instruction folding is an optimization performed during + register allocation that removes unnecessary copy instructions. For + instance, a sequence of instructions such as:

    + +
    + 
    + %EBX = LOAD %mem_address
+ %EAX = COPY %EBX
+
    +
    + +

    can be safely substituted by the single instruction: + +

    + 
    + %EAX = LOAD %mem_address
+
    +
    + +

    Instructions can be folded with the + MRegisterInfo::foldMemoryOperand(...) method. Care must be + taken when folding instructions; a folded instruction can be quite + different from the original instruction. See + LiveIntervals::addIntervalsForSpills in + lib/CodeGen/LiveIntervalAnalysis.cpp for an example of its use.

    + +
    + + + +
    + Built in register allocators +
    + +
    + +

    The LLVM infrastructure provides the application developer with + three different register allocators:

    + +
      +
    • Simple - This is a very simple implementation that does + not keep values in registers across instructions. This register + allocator immediately spills every value right after it is + computed, and reloads all used operands from memory to temporary + registers before each instruction.
      • +
    • Local - This register allocator is an improvement on the + Simple implementation. It allocates registers on a basic + block level, attempting to keep values in registers and reusing + registers as appropriate.
      • +
    • Linear Scan - The default allocator. This is the + well-know linear scan register allocator. Whereas the + Simple and Local algorithms use a direct mapping + implementation technique, the Linear Scan implementation + uses a spiller in order to place load and stores.
      • +
    + +

    The type of register allocator used in llc can be chosen with the + command line option -regalloc=...:

    + +
    + 
    + $ llc -f -regalloc=simple file.bc -o sp.s;
+ $ llc -f -regalloc=local file.bc -o lc.s;
+ $ llc -f -regalloc=linearscan file.bc -o ln.s;
+
    +
    + +
    + + +
    + Prolog/Epilog Code Insertion +
    +

    To Be Written

    + +
    + Late Machine Code Optimizations +
    +

    To Be Written

    + +
    + Code Emission +
    +

    To Be Written

    + +
    + Generating Assembly Code +
    +

    To Be Written

    + +
    + Generating Binary Machine Code +
    + +
    +

    For the JIT or .o file writer

    +
    + + + +
    + Target-specific Implementation Notes +
    + + +
    + +

    This section of the document explains features or design decisions that + are specific to the code generator for a particular target.

    + +
    + + + +
    + The X86 backend +
    + +
    + +

    The X86 code generator lives in the lib/Target/X86 directory. This + code generator is capable of targeting a variety of x86-32 and x86-64 + processors, and includes support for ISA extensions such as MMX and SSE. +

    + +
    + + +
    + X86 Target Triples Supported +
    + +
    + +

    The following are the known target triples that are supported by the X86 + backend. This is not an exhaustive list, and it would be useful to add those + that people test.

    + +
      +
    • i686-pc-linux-gnu - Linux
      • +
    • i386-unknown-freebsd5.3 - FreeBSD 5.3
      • +
    • i686-pc-cygwin - Cygwin on Win32
      • +
    • i686-pc-mingw32 - MingW on Win32
      • +
    • i386-pc-mingw32msvc - MingW crosscompiler on Linux
      • +
    • i686-apple-darwin* - Apple Darwin on X86
      • +
    + +
    + + +
    + X86 Calling Conventions supported +
    + + +
    + +

    The folowing target-specific calling conventions are known to backend:

    + +
      +
    • x86_StdCall - stdcall calling convention seen on Microsoft Windows + platform (CC ID = 64).
      • +
    • x86_FastCall - fastcall calling convention seen on Microsoft Windows + platform (CC ID = 65).
      • +
    + +
    + + +
    + Representing X86 addressing modes in MachineInstrs +
    + +
    + +

    The x86 has a very flexible way of accessing memory. It is capable of + forming memory addresses of the following expression directly in integer + instructions (which use ModR/M addressing):

    + +
    + 
    + Base + [1,2,4,8] * IndexReg + Disp32
+
    +
    + +

    In order to represent this, LLVM tracks no less than 4 operands for each + memory operand of this form. This means that the "load" form of 'mov' + has the following MachineOperands in this order:

    + + 
    + Index:        0     |    1        2       3           4
+ Meaning:   DestReg, | BaseReg,  Scale, IndexReg, Displacement
+ OperandTy: VirtReg, | VirtReg, UnsImm, VirtReg,   SignExtImm
+
    + +

    Stores, and all other instructions, treat the four memory operands in the + same way and in the same order.

    + +
    + + +
    + Instruction naming +
    + +
    + +

    An instruction name consists of the base name, a default operand size, and a + a character per operand with an optional special size. For example:

    + +

    + ADD8rr -> add, 8-bit register, 8-bit register
    + IMUL16rmi -> imul, 16-bit register, 16-bit memory, 16-bit immediate
    + IMUL16rmi8 -> imul, 16-bit register, 16-bit memory, 8-bit immediate
    + MOVSX32rm16 -> movsx, 32-bit register, 16-bit memory +

    + +
    + + +
    + The PowerPC backend +
    + +
    +

    The PowerPC code generator lives in the lib/Target/PowerPC directory. The + code generation is retargetable to several variations or subtargets of + the PowerPC ISA; including ppc32, ppc64 and altivec. +

    +
    + + +
    + LLVM PowerPC ABI +
    + +
    +

    LLVM follows the AIX PowerPC ABI, with two deviations. LLVM uses a PC + relative (PIC) or static addressing for accessing global values, so no TOC (r2) + is used. Second, r31 is used as a frame pointer to allow dynamic growth of a + stack frame. LLVM takes advantage of having no TOC to provide space to save + the frame pointer in the PowerPC linkage area of the caller frame. Other + details of PowerPC ABI can be found at PowerPC ABI. Note: This link describes the 32 bit ABI. The + 64 bit ABI is similar except space for GPRs are 8 bytes wide (not 4) and r13 is + reserved for system use.

    +
    + + +
    + Frame Layout +
    + +
    +

    The size of a PowerPC frame is usually fixed for the duration of a + function’s invocation. Since the frame is fixed size, all references into + the frame can be accessed via fixed offsets from the stack pointer. The + exception to this is when dynamic alloca or variable sized arrays are present, + then a base pointer (r31) is used as a proxy for the stack pointer and stack + pointer is free to grow or shrink. A base pointer is also used if llvm-gcc is + not passed the -fomit-frame-pointer flag. The stack pointer is always aligned to + 16 bytes, so that space allocated for altivec vectors will be properly + aligned.

    +

    An invocation frame is layed out as follows (low memory at top);

    +
    + +
    + + + + + + + + + + + + + + + + + + + + + + +
    Linkage

    Parameter area

    Dynamic area

    Locals area

    Saved registers area


    Previous Frame

    +
    + +
    +

    The linkage area is used by a callee to save special registers prior + to allocating its own frame. Only three entries are relevant to LLVM. The + first entry is the previous stack pointer (sp), aka link. This allows probing + tools like gdb or exception handlers to quickly scan the frames in the stack. A + function epilog can also use the link to pop the frame from the stack. The + third entry in the linkage area is used to save the return address from the lr + register. Finally, as mentioned above, the last entry is used to save the + previous frame pointer (r31.) The entries in the linkage area are the size of a + GPR, thus the linkage area is 24 bytes long in 32 bit mode and 48 bytes in 64 + bit mode.

    +
    + +
    +

    32 bit linkage area

    + + + + + + + + + + + + + + + + + + + + + + + + + +
    0Saved SP (r1)
    4Saved CR
    8Saved LR
    12Reserved
    16Reserved
    20Saved FP (r31)
    +
    + +
    +

    64 bit linkage area

    + + + + + + + + + + + + + + + + + + + + + + + + + +
    0Saved SP (r1)
    8Saved CR
    16Saved LR
    24Reserved
    32Reserved
    40Saved FP (r31)
    +
    + +
    +

    The parameter area is used to store arguments being passed to a callee + function. Following the PowerPC ABI, the first few arguments are actually + passed in registers, with the space in the parameter area unused. However, if + there are not enough registers or the callee is a thunk or vararg function, + these register arguments can be spilled into the parameter area. Thus, the + parameter area must be large enough to store all the parameters for the largest + call sequence made by the caller. The size must also be mimimally large enough + to spill registers r3-r10. This allows callees blind to the call signature, + such as thunks and vararg functions, enough space to cache the argument + registers. Therefore, the parameter area is minimally 32 bytes (64 bytes in 64 + bit mode.) Also note that since the parameter area is a fixed offset from the + top of the frame, that a callee can access its spilt arguments using fixed + offsets from the stack pointer (or base pointer.)

    +
    + +
    +

    Combining the information about the linkage, parameter areas and alignment. A + stack frame is minimally 64 bytes in 32 bit mode and 128 bytes in 64 bit + mode.

    +
    + +
    +

    The dynamic area starts out as size zero. If a function uses dynamic + alloca then space is added to the stack, the linkage and parameter areas are + shifted to top of stack, and the new space is available immediately below the + linkage and parameter areas. The cost of shifting the linkage and parameter + areas is minor since only the link value needs to be copied. The link value can + be easily fetched by adding the original frame size to the base pointer. Note + that allocations in the dynamic space need to observe 16 byte aligment.

    +
    + +
    +

    The locals area is where the llvm compiler reserves space for local + variables.

    +
    + +
    +

    The saved registers area is where the llvm compiler spills callee saved + registers on entry to the callee.

    +
    + + +
    + Prolog/Epilog +
    + +
    +

    The llvm prolog and epilog are the same as described in the PowerPC ABI, with + the following exceptions. Callee saved registers are spilled after the frame is + created. This allows the llvm epilog/prolog support to be common with other + targets. The base pointer callee saved register r31 is saved in the TOC slot of + linkage area. This simplifies allocation of space for the base pointer and + makes it convenient to locate programatically and during debugging.

    +
    + + +
    + Dynamic Allocation +
    + +
    +

    +
    + +
    +

    TODO - More to come.

    +
    + + + +
    +
    + Valid CSS! + Valid HTML 4.01! + + Chris Lattner
    + The LLVM Compiler Infrastructure
    + Last modified: $Date: 2008/02/12 06:05:03 $ +
    + + + Index: llvm-www/releases/2.2/docs/CodingStandards.html diff -c /dev/null llvm-www/releases/2.2/docs/CodingStandards.html:1.1 *** /dev/null Tue Feb 12 00:06:59 2008 --- llvm-www/releases/2.2/docs/CodingStandards.html Tue Feb 12 00:05:03 2008 *************** *** 0 **** --- 1,767 ---- + + + + + A Few Coding Standards + + + +
    + A Few Coding Standards +
    + +
      +
    1. Introduction
      2. +
    2. Mechanical Source Issues +
        +
      1. Source Code Formatting +
          +
        1. Commenting
          2. +
        2. Comment Formatting
          3. +
        3. #include Style
          4. +
        4. Source Code Width
          5. +
        5. Use Spaces Instead of Tabs
          6. +
        6. Indent Code Consistently
          7. +
        2. +
      2. Compiler Issues +
          +
        1. Treat Compiler Warnings Like + Errors
          2. +
        2. Write Portable Code
          3. +
        3. Use of class/struct Keywords
          4. +
        3. +
      3. +
    3. Style Issues +
        +
      1. The High Level Issues +
          +
        1. A Public Header File is a + Module
          2. +
        2. #include as Little as Possible
          3. +
        3. Keep "internal" Headers + Private
          4. +
        4. #include <iostream> is + forbidden
          5. +
        2. +
      2. The Low Level Issues +
          +
        1. Assert Liberally
          2. +
        2. Do not use 'using namespace std'
          3. +
        3. Provide a virtual method anchor for + classes in headers
          4. +
        4. Prefer Preincrement
          5. +
        5. Avoid std::endl
          6. +
        3. +
      4. +
    4. See Also
      5. +
    + +
    +

    Written by Chris Lattner and + Bill Wendling

    +
    + + + +
    + Introduction +
    + + +
    + +

    This document attempts to describe a few coding standards that are being used + in the LLVM source tree. Although no coding standards should be regarded as + absolute requirements to be followed in all instances, coding standards can be + useful.

    + +

    This document intentionally does not prescribe fixed standards for religious + issues such as brace placement and space usage. For issues like this, follow + the golden rule:

    + +
    + +

    If you are adding a significant body of source to a + project, feel free to use whatever style you are most comfortable with. If you + are extending, enhancing, or bug fixing already implemented code, use the style + that is already being used so that the source is uniform and easy to + follow.

    + +
    + +

    The ultimate goal of these guidelines is the increase readability and + maintainability of our common source base. If you have suggestions for topics to + be included, please mail them to Chris.

    + +
    + + +
    + Mechanical Source Issues +
    + + + +
    + Source Code Formatting +
    + + +
    + Commenting +
    + +
    + +

    Comments are one critical part of readability and maintainability. Everyone + knows they should comment, so should you. Although we all should probably + comment our code more than we do, there are a few very critical places that + documentation is very useful:

    + + File Headers + +

    Every source file should have a header on it that describes the basic + purpose of the file. If a file does not have a header, it should not be + checked into Subversion. Most source trees will probably have a standard + file header format. The standard format for the LLVM source tree looks like + this:

    + +
    + 
    + //===-- llvm/Instruction.h - Instruction class definition -------*- C++ -*-===//
+ // 
+ //                     The LLVM Compiler Infrastructure
+ //
+ // This file is distributed under the University of Illinois Open Source
+ // License. See LICENSE.TXT for details.
+ // 
+ //===----------------------------------------------------------------------===//
+ //
+ // This file contains the declaration of the Instruction class, which is the
+ // base class for all of the VM instructions.
+ //
+ //===----------------------------------------------------------------------===//
+
    +
    + +

    A few things to note about this particular format: The "-*- C++ + -*-" string on the first line is there to tell Emacs that the source file + is a C++ file, not a C file (Emacs assumes .h files are C files by default). + Note that this tag is not necessary in .cpp files. The name of the file is also + on the first line, along with a very short description of the purpose of the + file. This is important when printing out code and flipping though lots of + pages.

    + +

    The next section in the file is a concise note that defines the license + that the file is released under. This makes it perfectly clear what terms the + source code can be distributed under and should not be modified in any way.

    + +

    The main body of the description does not have to be very long in most cases. + Here it's only two lines. If an algorithm is being implemented or something + tricky is going on, a reference to the paper where it is published should be + included, as well as any notes or "gotchas" in the code to watch out for.

    + + Class overviews + +

    Classes are one fundamental part of a good object oriented design. As such, + a class definition should have a comment block that explains what the class is + used for... if it's not obvious. If it's so completely obvious your grandma + could figure it out, it's probably safe to leave it out. Naming classes + something sane goes a long ways towards avoiding writing documentation.

    + + + Method information + +

    Methods defined in a class (as well as any global functions) should also be + documented properly. A quick note about what it does any a description of the + borderline behaviour is all that is necessary here (unless something + particularly tricky or insideous is going on). The hope is that people can + figure out how to use your interfaces without reading the code itself... that is + the goal metric.

    + +

    Good things to talk about here are what happens when something unexpected + happens: does the method return null? Abort? Format your hard disk?

    + +
    + + +
    + Comment Formatting +
    + +
    + +

    In general, prefer C++ style (//) comments. They take less space, + require less typing, don't have nesting problems, etc. There are a few cases + when it is useful to use C style (/* */) comments however:

    + +
      +
    1. When writing a C code: Obviously if you are writing C code, use C style + comments.
      2. +
    2. When writing a header file that may be #included by a C source + file.
      3. +
    3. When writing a source file that is used by a tool that only accepts C + style comments.
      4. +
    + +

    To comment out a large block of code, use #if 0 and #endif. + These nest properly and are better behaved in general than C style comments.

    + +
    + + +
    + #include Style +
    + +
    + +

    Immediately after the header file comment (and + include guards if working on a header file), the minimal list of #includes required by the + file should be listed. We prefer these #includes to be listed in this + order:

    + +
      +
    1. Main Module header
      2. +
    2. Local/Private Headers
      3. +
    3. llvm/*
      4. +
    4. llvm/Analysis/*
      5. +
    5. llvm/Assembly/*
      6. +
    6. llvm/Bytecode/*
      7. +
    7. llvm/CodeGen/*
      8. +
    8. ...
      9. +
    9. Support/*
      10. +
    10. Config/*
      11. +
    11. System #includes
      12. +
    + +

    ... and each catagory should be sorted by name.

    + +

    The "Main Module Header" file applies to .cpp file + which implement an interface defined by a .h file. This #include + should always be included first regardless of where it lives on the file + system. By including a header file first in the .cpp files that implement the + interfaces, we ensure that the header does not have any hidden dependencies + which are not explicitly #included in the header, but should be. It is also a + form of documentation in the .cpp file to indicate where the interfaces it + implements are defined.

    + +
    + + +
    + Source Code Width +
    + +
    + +

    Write your code to fit within 80 columns of text. This helps those of us who + like to print out code and look at your code in an xterm without resizing + it.

    + +
    + + +
    + Use Spaces Instead of Tabs +
    + +
    + +

    In all cases, prefer spaces to tabs in source files. People have different + prefered indentation levels, and different styles of indentation that they + like... this is fine. What isn't is that different editors/viewers expand tabs + out to different tab stops. This can cause your code to look completely + unreadable, and it is not worth dealing with.

    + +

    As always, follow the Golden Rule above: follow the + style of existing code if your are modifying and extending it. If you like four + spaces of indentation, DO NOT do that in the middle of a chunk of code + with two spaces of indentation. Also, do not reindent a whole source file: it + makes for incredible diffs that are absolutely worthless.

    + +
    + + +
    + Indent Code Consistently +
    + +
    + +

    Okay, your first year of programming you were told that indentation is + important. If you didn't believe and internalize this then, now is the time. + Just do it.

    + +
    + + + +
    + Compiler Issues +
    + + + +
    + Treat Compiler Warnings Like Errors +
    + +
    + +

    If your code has compiler warnings in it, something is wrong: you aren't + casting values correctly, your have "questionable" constructs in your code, or + you are doing something legitimately wrong. Compiler warnings can cover up + legitimate errors in output and make dealing with a translation unit + difficult.

    + +

    It is not possible to prevent all warnings from all compilers, nor is it + desirable. Instead, pick a standard compiler (like gcc) that provides + a good thorough set of warnings, and stick to them. At least in the case of + gcc, it is possible to work around any spurious errors by changing the + syntax of the code slightly. For example, an warning that annoys me occurs when + I write code like this:

    + +
    + 
    + if (V = getValue()) {
+   ...
+ }
+
    +
    + +

    gcc will warn me that I probably want to use the == + operator, and that I probably mistyped it. In most cases, I haven't, and I + really don't want the spurious errors. To fix this particular problem, I + rewrite the code like this:

    + +
    + 
    + if ((V = getValue())) {
+   ...
+ }
+
    +
    + +

    ...which shuts gcc up. Any gcc warning that annoys you can + be fixed by massaging the code appropriately.

    + +

    These are the gcc warnings that I prefer to enable: -Wall + -Winline -W -Wwrite-strings -Wno-unused

    + +
    + + +
    + Write Portable Code +
    + +
    + +

    In almost all cases, it is possible and within reason to write completely + portable code. If there are cases where it isn't possible to write portable + code, isolate it behind a well defined (and well documented) interface.

    + +

    In practice, this means that you shouldn't assume much about the host + compiler, including its support for "high tech" features like partial + specialization of templates. In fact, Visual C++ 6 could be an important target + for our work in the future, and we don't want to have to rewrite all of our code + to support it.

    + +
    + + +
    + Use of class and struct Keywords +
    +
    + +

    In C++, the class and struct keywords can be used almost + interchangeably. The only difference is when they are used to declare a class: + class makes all members private by default while struct makes + all members public by default.

    + +

    Unfortunately, not all compilers follow the rules and some will generate + different symbols based on whether class or struct was used to + declare the symbol. This can lead to problems at link time.

    + +

    So, the rule for LLVM is to always use the class keyword, unless + all members are public, in which case struct is allowed.

    + +
    + + +
    + Style Issues +
    + + + + +
    + The High Level Issues +
    + + + +
    + A Public Header File is a Module +
    + +
    + +

    C++ doesn't do too well in the modularity department. There is no real + encapsulation or data hiding (unless you use expensive protocol classes), but it + is what we have to work with. When you write a public header file (in the LLVM + source tree, they live in the top level "include" directory), you are defining a + module of functionality.

    + +

    Ideally, modules should be completely independent of each other, and their + header files should only include the absolute minimum number of headers + possible. A module is not just a class, a function, or a namespace: it's a collection + of these that defines an interface. This interface may be several + functions, classes or data structures, but the important issue is how they work + together.

    + +

    In general, a module should be implemented with one or more .cpp + files. Each of these .cpp files should include the header that defines + their interface first. This ensure that all of the dependences of the module + header have been properly added to the module header itself, and are not + implicit. System headers should be included after user headers for a + translation unit.

    + +
    + + +
    + #include as Little as Possible +
    + +
    + +

    #include hurts compile time performance. Don't do it unless you + have to, especially in header files.

    + +

    But wait, sometimes you need to have the definition of a class to use it, or + to inherit from it. In these cases go ahead and #include that header + file. Be aware however that there are many cases where you don't need to have + the full definition of a class. If you are using a pointer or reference to a + class, you don't need the header file. If you are simply returning a class + instance from a prototyped function or method, you don't need it. In fact, for + most cases, you simply don't need the definition of a class... and not + #include'ing speeds up compilation.

    + +

    It is easy to try to go too overboard on this recommendation, however. You + must include all of the header files that you are using -- you can + include them either directly + or indirectly (through another header file). To make sure that you don't + accidently forget to include a header file in your module header, make sure to + include your module header first in the implementation file (as mentioned + above). This way there won't be any hidden dependencies that you'll find out + about later...

    + +
    + + +
    + Keep "internal" Headers Private +
    + +
    + +

    Many modules have a complex implementation that causes them to use more than + one implementation (.cpp) file. It is often tempting to put the + internal communication interface (helper classes, extra functions, etc) in the + public module header file. Don't do this.

    + +

    If you really need to do something like this, put a private header file in + the same directory as the source files, and include it locally. This ensures + that your private interface remains private and undisturbed by outsiders.

    + +

    Note however, that it's okay to put extra implementation methods a public + class itself... just make them private (or protected), and all is well.

    + +
    + + +
    + #include <iostream> is forbidden +
    + +
    + +

    The use of #include <iostream> in library files is + hereby forbidden. The primary reason for doing this is to + support clients using LLVM libraries as part of larger systems. In particular, + we statically link LLVM into some dynamic libraries. Even if LLVM isn't used, + the static c'tors are run whenever an application start up that uses the dynamic + library. There are two problems with this:

    + +
      +
    1. The time to run the static c'tors impacts startup time of + applications—a critical time for GUI apps.
      2. +
    2. The static c'tors cause the app to pull many extra pages of memory off the + disk: both the code for the static c'tors in each .o file and the + small amount of data that gets touched. In addition, touched/dirty pages + put more pressure on the VM system on low-memory machines.
      3. +
    + +
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    Old WayNew Way
    #include <iostream>
    #include "llvm/Support/Streams.h"
    DEBUG(std::cerr << ...);
+ DEBUG(dump(std::cerr));
    DOUT << ...;
+ DEBUG(dump(DOUT));
    std::cerr << "Hello world\n";
    llvm::cerr << "Hello world\n";
    std::cout << "Hello world\n";
    llvm::cout << "Hello world\n";
    std::cin >> Var;
    llvm::cin >> Var;
    std::ostream
    llvm::OStream
    std::istream
    llvm::IStream
    std::stringstream
    llvm::StringStream
    void print(std::ostream &Out);
+ // ...
+ print(std::cerr);
    void print(llvm::OStream Out);1
+ // ...
+ print(llvm::cerr);
    + +
    +
    + +
    +

    1llvm::OStream is a light-weight class so it should never + be passed by reference. This is important because in some configurations, + DOUT is an rvalue.

    +
    + +
    + + + +
    + The Low Level Issues +
    + + + +
    + Assert Liberally +
    + +
    + +

    Use the "assert" function to its fullest. Check all of your + preconditions and assumptions, you never know when a bug (not neccesarily even + yours) might be caught early by an assertion, which reduces debugging time + dramatically. The "<cassert>" header file is probably already + included by the header files you are using, so it doesn't cost anything to use + it.

    + +

    To further assist with debugging, make sure to put some kind of error message + in the assertion statement (which is printed if the assertion is tripped). This + helps the poor debugging make sense of why an assertion is being made and + enforced, and hopefully what to do about it. Here is one complete example:

    + +
    + 
    + inline Value *getOperand(unsigned i) { 
+   assert(i < Operands.size() && "getOperand() out of range!");
+   return Operands[i]; 
+ }
+
    +
    + +

    Here are some examples:

    + +
    + 
    + assert(Ty->isPointerType() && "Can't allocate a non pointer type!");
+ 
+ assert((Opcode == Shl || Opcode == Shr) && "ShiftInst Opcode invalid!");
+ 
+ assert(idx < getNumSuccessors() && "Successor # out of range!");
+ 
+ assert(V1.getType() == V2.getType() && "Constant types must be identical!");
+ 
+ assert(isa<PHINode>(Succ->front()) && "Only works on PHId BBs!");
+
    +
    + +

    You get the idea...

    + +
    + + +
    + Do not use 'using namespace std' +
    + +
    +

    In LLVM, we prefer to explicitly prefix all identifiers from the standard + namespace with an "std::" prefix, rather than rely on + "using namespace std;".

    + +

    In header files, adding a 'using namespace XXX' directive pollutes + the namespace of any source file that includes the header. This is clearly a + bad thing.

    + +

    In implementation files (e.g. .cpp files), the rule is more of a stylistic + rule, but is still important. Basically, using explicit namespace prefixes + makes the code clearer, because it is immediately obvious what facilities + are being used and where they are coming from, and more portable, because + namespace clashes cannot occur between LLVM code and other namespaces. The + portability rule is important because different standard library implementations + expose different symbols (potentially ones they shouldn't), and future revisions + to the C++ standard will add more symbols to the std namespace. As + such, we never use 'using namespace std;' in LLVM.

    + +

    The exception to the general rule (i.e. it's not an exception for + the std namespace) is for implementation files. For example, all of + the code in the LLVM project implements code that lives in the 'llvm' namespace. + As such, it is ok, and actually clearer, for the .cpp files to have a 'using + namespace llvm' directive at their top, after the #includes. The + general form of this rule is that any .cpp file that implements code in any + namespace may use that namespace (and its parents'), but should not use any + others.

    + +
    + + +
    + Provide a virtual method anchor for classes + in headers +
    + +
    + +

    If a class is defined in a header file and has a v-table (either it has + virtual methods or it derives from classes with virtual methods), it must + always have at least one out-of-line virtual method in the class. Without + this, the compiler will copy the vtable and RTTI into every .o file that + #includes the header, bloating .o file sizes and increasing link times. +

    + +
    + + + +
    + Prefer Preincrement +
    + +
    + +

    Hard fast rule: Preincrement (++X) may be no slower than + postincrement (X++) and could very well be a lot faster than it. Use + preincrementation whenever possible.

    + +

    The semantics of postincrement include making a copy of the value being + incremented, returning it, and then preincrementing the "work value". For + primitive types, this isn't a big deal... but for iterators, it can be a huge + issue (for example, some iterators contains stack and set objects in them... + copying an iterator could invoke the copy ctor's of these as well). In general, + get in the habit of always using preincrement, and you won't have a problem.

    + +
    + + +
    + Avoid std::endl +
    + +
    + +

    The std::endl modifier, when used with iostreams outputs a newline + to the output stream specified. In addition to doing this, however, it also + flushes the output stream. In other words, these are equivalent:

    + +
    + 
    + std::cout << std::endl;
+ std::cout << '\n' << std::flush;
+
    +
    + +

    Most of the time, you probably have no reason to flush the output stream, so + it's better to use a literal '\n'.

    + +
    + + + +
    + See Also +
    + + +
    + +

    A lot of these comments and recommendations have been culled for other + sources. Two particularly important books for our work are:

    + +
      + +
    1. Effective + C++ by Scott Meyers. Also + interesting and useful are "More Effective C++" and "Effective STL" by the same + author.
      2. + +
    2. Large-Scale C++ Software Design by John Lakos
      3. + +
    + +

    If you get some free time, and you haven't read them: do so, you might learn + something.

    + +
    + + + +
    +
    + Valid CSS! + Valid HTML 4.01! + + Chris Lattner
    + LLVM Compiler Infrastructure
    + Last modified: $Date: 2008/02/12 06:05:03 $ +
    + + + Index: llvm-www/releases/2.2/docs/CommandLine.html diff -c /dev/null llvm-www/releases/2.2/docs/CommandLine.html:1.1 *** /dev/null Tue Feb 12 00:06:59 2008 --- llvm-www/releases/2.2/docs/CommandLine.html Tue Feb 12 00:05:03 2008 *************** *** 0 **** --- 1,1935 ---- + + + + + CommandLine 2.0 Library Manual + + + + +
    + CommandLine 2.0 Library Manual +
    + +
      +
    1. Introduction
      2. + +
    2. Quick Start Guide +
        +
      1. Boolean Arguments
        2. +
      2. Argument Aliases
        3. +
      3. Selecting an alternative from a + set of possibilities
        4. +
      4. Named alternatives
        5. +
      5. Parsing a list of options
        6. +
      6. Collecting options as a set of flags
        7. +
      7. Adding freeform text to help output
        8. +
      3. + +
    3. Reference Guide +
        +
      1. Positional Arguments +
        2. + +
      2. Internal vs External Storage
        3. + +
      3. Option Attributes
        4. + +
      4. Option Modifiers +
        5. + +
      5. Top-Level Classes and Functions +
        6. + +
      6. Builtin parsers +
        7. +
      4. +
    4. Extension Guide +
        +
      1. Writing a custom parser
        2. +
      2. Exploiting external storage
        3. +
      3. Dynamically adding command line + options
        4. +
      5. +
    + +
    +

    Written by Chris Lattner

    +
    + + +
    + Introduction +
    + + +
    + +

    This document describes the CommandLine argument processing library. It will + show you how to use it, and what it can do. The CommandLine library uses a + declarative approach to specifying the command line options that your program + takes. By default, these options declarations implicitly hold the value parsed + for the option declared (of course this can be + changed).

    + +

    Although there are a lot of command line argument parsing libraries + out there in many different languages, none of them fit well with what I needed. + By looking at the features and problems of other libraries, I designed the + CommandLine library to have the following features:

    + +
      +
    1. Speed: The CommandLine library is very quick and uses little resources. The + parsing time of the library is directly proportional to the number of arguments + parsed, not the the number of options recognized. Additionally, command line + argument values are captured transparently into user defined global variables, + which can be accessed like any other variable (and with the same + performance).
      2. + +
    2. Type Safe: As a user of CommandLine, you don't have to worry about + remembering the type of arguments that you want (is it an int? a string? a + bool? an enum?) and keep casting it around. Not only does this help prevent + error prone constructs, it also leads to dramatically cleaner source code.
      3. + +
    3. No subclasses required: To use CommandLine, you instantiate variables that + correspond to the arguments that you would like to capture, you don't subclass a + parser. This means that you don't have to write any boilerplate + code.
      4. + +
    4. Globally accessible: Libraries can specify command line arguments that are + automatically enabled in any tool that links to the library. This is possible + because the application doesn't have to keep a list of arguments to pass to + the parser. This also makes supporting dynamically + loaded options trivial.
      5. + +
    5. Cleaner: CommandLine supports enum and other types directly, meaning that + there is less error and more security built into the library. You don't have to + worry about whether your integral command line argument accidentally got + assigned a value that is not valid for your enum type.
      6. + +
    6. Powerful: The CommandLine library supports many different types of + arguments, from simple boolean flags to scalars arguments (strings, integers, enums, doubles), to lists of + arguments. This is possible because CommandLine is...
      7. + +
    7. Extensible: It is very simple to add a new argument type to CommandLine. + Simply specify the parser that you want to use with the command line option when + you declare it. Custom parsers are no problem.
      8. + +
    8. Labor Saving: The CommandLine library cuts down on the amount of grunt work + that you, the user, have to do. For example, it automatically provides a + --help option that shows the available command line options for your + tool. Additionally, it does most of the basic correctness checking for + you.
      9. + +
    9. Capable: The CommandLine library can handle lots of different forms of + options often found in real programs. For example, positional arguments, ls style grouping options (to allow processing 'ls + -lad' naturally), ld style prefix + options (to parse '-lmalloc -L/usr/lib'), and interpreter style options.
      10. + +
    + +

    This document will hopefully let you jump in and start using CommandLine in + your utility quickly and painlessly. Additionally it should be a simple + reference manual to figure out how stuff works. If it is failing in some area + (or you want an extension to the library), nag the author, Chris Lattner.

    + +
    + + +
    + Quick Start Guide +
    + + +
    + +

    This section of the manual runs through a simple CommandLine'ification of a + basic compiler tool. This is intended to show you how to jump into using the + CommandLine library in your own program, and show you some of the cool things it + can do.

    + +

    To start out, you need to include the CommandLine header file into your + program:

    + + 
    +   #include "llvm/Support/CommandLine.h"
+
    + +

    Additionally, you need to add this as the first line of your main + program:

    + + 
    + int main(int argc, char **argv) {
+   cl::ParseCommandLineOptions(argc, argv);
+   ...
+ }
+
    + +

    ... which actually parses the arguments and fills in the variable + declarations.

    + +

    Now that you are ready to support command line arguments, we need to tell the + system which ones we want, and what type of arguments they are. The CommandLine + library uses a declarative syntax to model command line arguments with the + global variable declarations that capture the parsed values. This means that + for every command line option that you would like to support, there should be a + global variable declaration to capture the result. For example, in a compiler, + we would like to support the Unix-standard '-o <filename>' option + to specify where to put the output. With the CommandLine library, this is + represented like this:

    + + + 
    + cl::opt<string> OutputFilename("o", cl::desc("Specify output filename"), cl::value_desc("filename"));
+
    + +

    This declares a global variable "OutputFilename" that is used to + capture the result of the "o" argument (first parameter). We specify + that this is a simple scalar option by using the "cl::opt" template (as opposed to the "cl::list template), and tell the CommandLine library + that the data type that we are parsing is a string.

    + +

    The second and third parameters (which are optional) are used to specify what + to output for the "--help" option. In this case, we get a line that + looks like this:

    + + 
    + USAGE: compiler [options]
+ 
+ OPTIONS:
+   -help             - display available options (--help-hidden for more)
+   -o <filename>     - Specify output filename
+
    + +

    Because we specified that the command line option should parse using the + string data type, the variable declared is automatically usable as a + real string in all contexts that a normal C++ string object may be used. For + example:

    + + 
    +   ...
+   ofstream Output(OutputFilename.c_str());
+   if (Out.good()) ...
+   ...
+
    + +

    There are many different options that you can use to customize the command + line option handling library, but the above example shows the general interface + to these options. The options can be specified in any order, and are specified + with helper functions like cl::desc(...), so + there are no positional dependencies to remember. The available options are + discussed in detail in the Reference Guide.

    + +

    Continuing the example, we would like to have our compiler take an input + filename as well as an output filename, but we do not want the input filename to + be specified with a hyphen (ie, not -filename.c). To support this + style of argument, the CommandLine library allows for positional arguments to be specified for the program. + These positional arguments are filled with command line parameters that are not + in option form. We use this feature like this:

    + + 
    + cl::opt<string> InputFilename(cl::Positional, cl::desc("<input file>"), cl::init("-"));
+
    + +

    This declaration indicates that the first positional argument should be + treated as the input filename. Here we use the cl::init option to specify an initial value for the + command line option, which is used if the option is not specified (if you do not + specify a cl::init modifier for an option, then + the default constructor for the data type is used to initialize the value). + Command line options default to being optional, so if we would like to require + that the user always specify an input filename, we would add the cl::Required flag, and we could eliminate the + cl::init modifier, like this:

    + + 
    + cl::opt<string> InputFilename(cl::Positional, cl::desc("<input file>"), cl::Required);
+
    + +

    Again, the CommandLine library does not require the options to be specified + in any particular order, so the above declaration is equivalent to:

    + + 
    + cl::opt<string> InputFilename(cl::Positional, cl::Required, cl::desc("<input file>"));
+
    + +

    By simply adding the cl::Required flag, + the CommandLine library will automatically issue an error if the argument is not + specified, which shifts all of the command line option verification code out of + your application into the library. This is just one example of how using flags + can alter the default behaviour of the library, on a per-option basis. By + adding one of the declarations above, the --help option synopsis is now + extended to:

    + + 
    + USAGE: compiler [options] <input file>
+ 
+ OPTIONS:
+   -help             - display available options (--help-hidden for more)
+   -o <filename>     - Specify output filename
+
    + +

    ... indicating that an input filename is expected.

    + +
    + + +
    + Boolean Arguments +
    + +
    + +

    In addition to input and output filenames, we would like the compiler example + to support three boolean flags: "-f" to force overwriting of the output + file, "--quiet" to enable quiet mode, and "-q" for backwards + compatibility with some of our users. We can support these by declaring options + of boolean type like this:

    + + 
    + cl::opt<bool> Force ("f", cl::desc("Overwrite output files"));
+ cl::opt<bool> Quiet ("quiet", cl::desc("Don't print informational messages"));
+ cl::opt<bool> Quiet2("q", cl::desc("Don't print informational messages"), cl::Hidden);
+
    + +

    This does what you would expect: it declares three boolean variables + ("Force", "Quiet", and "Quiet2") to recognize these + options. Note that the "-q" option is specified with the "cl::Hidden" flag. This modifier prevents it + from being shown by the standard "--help" output (note that it is still + shown in the "--help-hidden" output).

    + +

    The CommandLine library uses a different parser + for different data types. For example, in the string case, the argument passed + to the option is copied literally into the content of the string variable... we + obviously cannot do that in the boolean case, however, so we must use a smarter + parser. In the case of the boolean parser, it allows no options (in which case + it assigns the value of true to the variable), or it allows the values + "true" or "false" to be specified, allowing any of the + following inputs:

    + + 
    +  compiler -f          # No value, 'Force' == true
+  compiler -f=true     # Value specified, 'Force' == true
+  compiler -f=TRUE     # Value specified, 'Force' == true
+  compiler -f=FALSE    # Value specified, 'Force' == false
+
    + +

    ... you get the idea. The bool parser just turns + the string values into boolean values, and rejects things like 'compiler + -f=foo'. Similarly, the float, double, and int parsers work + like you would expect, using the 'strtol' and 'strtod' C + library calls to parse the string value into the specified data type.

    + +

    With the declarations above, "compiler --help" emits this:

    + + 
    + USAGE: compiler [options] <input file>
+ 
+ OPTIONS:
+   -f     - Overwrite output files
+   -o     - Override output filename
+   -quiet - Don't print informational messages
+   -help  - display available options (--help-hidden for more)
+
    + +

    and "compiler --help-hidden" prints this:

    + + 
    + USAGE: compiler [options] <input file>
+ 
+ OPTIONS:
+   -f     - Overwrite output files
+   -o     - Override output filename
+   -q     - Don't print informational messages
+   -quiet - Don't print informational messages
+   -help  - display available options (--help-hidden for more)
+
    + +

    This brief example has shown you how to use the 'cl::opt' class to parse simple scalar command line + arguments. In addition to simple scalar arguments, the CommandLine library also + provides primitives to support CommandLine option aliases, + and lists of options.

    + +
    + + +
    + Argument Aliases +
    + +
    + +

    So far, the example works well, except for the fact that we need to check the + quiet condition like this now:

    + + 
    + ...
+   if (!Quiet && !Quiet2) printInformationalMessage(...);
+ ...
+
    + +

    ... which is a real pain! Instead of defining two values for the same + condition, we can use the "cl::alias" class to make the "-q" + option an alias for the "-quiet" option, instead of providing + a value itself:

    + + 
    + cl::opt<bool> Force ("f", cl::desc("Overwrite output files"));
+ cl::opt<bool> Quiet ("quiet", cl::desc("Don't print informational messages"));
+ cl::alias     QuietA("q", cl::desc("Alias for -quiet"), cl::aliasopt(Quiet));
+
    + +

    The third line (which is the only one we modified from above) defines a + "-q" alias that updates the "Quiet" variable (as specified by + the cl::aliasopt modifier) whenever it is + specified. Because aliases do not hold state, the only thing the program has to + query is the Quiet variable now. Another nice feature of aliases is + that they automatically hide themselves from the -help output + (although, again, they are still visible in the --help-hidden + output).

    + +

    Now the application code can simply use:

    + + 
    + ...
+   if (!Quiet) printInformationalMessage(...);
+ ...
+
    + +

    ... which is much nicer! The "cl::alias" + can be used to specify an alternative name for any variable type, and has many + uses.

    + +
    + + +
    + Selecting an alternative from a set of + possibilities +
    + +
    + +

    So far we have seen how the CommandLine library handles builtin types like + std::string, bool and int, but how does it handle + things it doesn't know about, like enums or 'int*'s?

    + +

    The answer is that it uses a table-driven generic parser (unless you specify + your own parser, as described in the Extension + Guide). This parser maps literal strings to whatever type is required, and + requires you to tell it what this mapping should be.

    + +

    Let's say that we would like to add four optimization levels to our + optimizer, using the standard flags "-g", "-O0", + "-O1", and "-O2". We could easily implement this with boolean + options like above, but there are several problems with this strategy:

    + +
      +
    1. A user could specify more than one of the options at a time, for example, + "compiler -O3 -O2". The CommandLine library would not be able to + catch this erroneous input for us.
      2. + +
    2. We would have to test 4 different variables to see which ones are set.
      3. + +
    3. This doesn't map to the numeric levels that we want... so we cannot easily + see if some level >= "-O1" is enabled.
      4. + +
    + +

    To cope with these problems, we can use an enum value, and have the + CommandLine library fill it in with the appropriate level directly, which is + used like this:

    + + 
    + enum OptLevel {
+   g, O1, O2, O3
+ };
+ 
+ cl::opt<OptLevel> OptimizationLevel(cl::desc("Choose optimization level:"),
+   cl::values(
+     clEnumVal(g , "No optimizations, enable debugging"),
+     clEnumVal(O1, "Enable trivial optimizations"),
+     clEnumVal(O2, "Enable default optimizations"),
+     clEnumVal(O3, "Enable expensive optimizations"),
+    clEnumValEnd));
+ 
+ ...
+   if (OptimizationLevel >= O2) doPartialRedundancyElimination(...);
+ ...
+
    + +

    This declaration defines a variable "OptimizationLevel" of the + "OptLevel" enum type. This variable can be assigned any of the values + that are listed in the declaration (Note that the declaration list must be + terminated with the "clEnumValEnd" argument!). The CommandLine + library enforces + that the user can only specify one of the options, and it ensure that only valid + enum values can be specified. The "clEnumVal" macros ensure that the + command line arguments matched the enum values. With this option added, our + help output now is:

    + + 
    + USAGE: compiler [options] <input file>
+ 
+ OPTIONS:
+   Choose optimization level:
+     -g          - No optimizations, enable debugging
+     -O1         - Enable trivial optimizations
+     -O2         - Enable default optimizations
+     -O3         - Enable expensive optimizations
+   -f            - Overwrite output files
+   -help         - display available options (--help-hidden for more)
+   -o <filename> - Specify output filename
+   -quiet        - Don't print informational messages
+
    + +

    In this case, it is sort of awkward that flag names correspond directly to + enum names, because we probably don't want a enum definition named "g" + in our program. Because of this, we can alternatively write this example like + this:

    + + 
    + enum OptLevel {
+   Debug, O1, O2, O3
+ };
+ 
+ cl::opt<OptLevel> OptimizationLevel(cl::desc("Choose optimization level:"),
+   cl::values(
+    clEnumValN(Debug, "g", "No optimizations, enable debugging"),
+     clEnumVal(O1        , "Enable trivial optimizations"),
+     clEnumVal(O2        , "Enable default optimizations"),
+     clEnumVal(O3        , "Enable expensive optimizations"),
+    clEnumValEnd));
+ 
+ ...
+   if (OptimizationLevel == Debug) outputDebugInfo(...);
+ ...
+
    + +

    By using the "clEnumValN" macro instead of "clEnumVal", we + can directly specify the name that the flag should get. In general a direct + mapping is nice, but sometimes you can't or don't want to preserve the mapping, + which is when you would use it.

    + +
    + + +
    + Named Alternatives +
    + +
    + +

    Another useful argument form is a named alternative style. We shall use this + style in our compiler to specify different debug levels that can be used. + Instead of each debug level being its own switch, we want to support the + following options, of which only one can be specified at a time: + "--debug-level=none", "--debug-level=quick", + "--debug-level=detailed". To do this, we use the exact same format as + our optimization level flags, but we also specify an option name. For this + case, the code looks like this:

    + + 
    + enum DebugLev {
+   nodebuginfo, quick, detailed
+ };
+ 
+ // Enable Debug Options to be specified on the command line
+ cl::opt<DebugLev> DebugLevel("debug_level", cl::desc("Set the debugging level:"),
+   cl::values(
+     clEnumValN(nodebuginfo, "none", "disable debug information"),
+      clEnumVal(quick,               "enable quick debug information"),
+      clEnumVal(detailed,            "enable detailed debug information"),
+     clEnumValEnd));
+
    + +

    This definition defines an enumerated command line variable of type "enum + DebugLev", which works exactly the same way as before. The difference here + is just the interface exposed to the user of your program and the help output by + the "--help" option:

    + + 
    + USAGE: compiler [options] <input file>
+ 
+ OPTIONS:
+   Choose optimization level:
+     -g          - No optimizations, enable debugging
+     -O1         - Enable trivial optimizations
+     -O2         - Enable default optimizations
+     -O3         - Enable expensive optimizations
+   -debug_level  - Set the debugging level:
+     =none       - disable debug information
+     =quick      - enable quick debug information
+     =detailed   - enable detailed debug information
+   -f            - Overwrite output files
+   -help         - display available options (--help-hidden for more)
+   -o <filename> - Specify output filename
+   -quiet        - Don't print informational messages
+
    + +

    Again, the only structural difference between the debug level declaration and + the optimization level declaration is that the debug level declaration includes + an option name ("debug_level"), which automatically changes how the + library processes the argument. The CommandLine library supports both forms so + that you can choose the form most appropriate for your application.

    + +
    + + +
    + Parsing a list of options +
    + +
    + +

    Now that we have the standard run-of-the-mill argument types out of the way, + lets get a little wild and crazy. Lets say that we want our optimizer to accept + a list of optimizations to perform, allowing duplicates. For example, we + might want to run: "compiler -dce -constprop -inline -dce -strip". In + this case, the order of the arguments and the number of appearances is very + important. This is what the "cl::list" + template is for. First, start by defining an enum of the optimizations that you + would like to perform:

    + + 
    + enum Opts {
+   // 'inline' is a C++ keyword, so name it 'inlining'
+   dce, constprop, inlining, strip
+ };
+
    + +

    Then define your "cl::list" variable:

    + + 
    + cl::list<Opts> OptimizationList(cl::desc("Available Optimizations:"),
+   cl::values(
+     clEnumVal(dce               , "Dead Code Elimination"),
+     clEnumVal(constprop         , "Constant Propagation"),
+    clEnumValN(inlining, "inline", "Procedure Integration"),
+     clEnumVal(strip             , "Strip Symbols"),
+   clEnumValEnd));
+
    + +

    This defines a variable that is conceptually of the type + "std::vector<enum Opts>". Thus, you can access it with standard + vector methods:

    + + 
    +   for (unsigned i = 0; i != OptimizationList.size(); ++i)
+     switch (OptimizationList[i])
+        ...
+
    + +

    ... to iterate through the list of options specified.

    + +

    Note that the "cl::list" template is + completely general and may be used with any data types or other arguments that + you can use with the "cl::opt" template. One + especially useful way to use a list is to capture all of the positional + arguments together if there may be more than one specified. In the case of a + linker, for example, the linker takes several '.o' files, and needs to + capture them into a list. This is naturally specified as:

    + + 
    + ...
+ cl::list<std::string> InputFilenames(cl::Positional, cl::desc("<Input files>"), cl::OneOrMore);
+ ...
+
    + +

    This variable works just like a "vector<string>" object. As + such, accessing the list is simple, just like above. In this example, we used + the cl::OneOrMore modifier to inform the + CommandLine library that it is an error if the user does not specify any + .o files on our command line. Again, this just reduces the amount of + checking we have to do.

    + +
    + + +
    + Collecting options as a set of flags +
    + +
    + +

    Instead of collecting sets of options in a list, it is also possible to + gather information for enum values in a bit vector. The represention used by + the cl::bits class is an unsigned + integer. An enum value is represented by a 0/1 in the enum's ordinal value bit + position. 1 indicating that the enum was specified, 0 otherwise. As each + specified value is parsed, the resulting enum's bit is set in the option's bit + vector:

    + + 
    +   bits |= 1 << (unsigned)enum;
+
    + +

    Options that are specified multiple times are redundant. Any instances after + the first are discarded.

    + +

    Reworking the above list example, we could replace + cl::list with cl::bits:

    + + 
    + cl::bits<Opts> OptimizationBits(cl::desc("Available Optimizations:"),
+   cl::values(
+     clEnumVal(dce               , "Dead Code Elimination"),
+     clEnumVal(constprop         , "Constant Propagation"),
+    clEnumValN(inlining, "inline", "Procedure Integration"),
+     clEnumVal(strip             , "Strip Symbols"),
+   clEnumValEnd));
+
    + +

    To test to see if constprop was specified, we can use the + cl:bits::isSet function:

    + + 
    +   if (OptimizationBits.isSet(constprop)) {
+     ...
+   }
+
    + +

    It's also possible to get the raw bit vector using the + cl::bits::getBits function:

    + + 
    +   unsigned bits = OptimizationBits.getBits();
+
    + +

    Finally, if external storage is used, then the location specified must be of + type unsigned. In all other ways a cl::bits option is equivalent to a cl::list option.

    + +
    + + + +
    + Adding freeform text to help output +
    + +
    + +

    As our program grows and becomes more mature, we may decide to put summary + information about what it does into the help output. The help output is styled + to look similar to a Unix man page, providing concise information about + a program. Unix man pages, however often have a description about what + the program does. To add this to your CommandLine program, simply pass a third + argument to the cl::ParseCommandLineOptions + call in main. This additional argument is then printed as the overview + information for your program, allowing you to include any additional information + that you want. For example:

    + + 
    + int main(int argc, char **argv) {
+   cl::ParseCommandLineOptions(argc, argv, " CommandLine compiler example\n\n"
+                               "  This program blah blah blah...\n");
+   ...
+ }
+
    + +

    would yield the help output:

    + + 
    + OVERVIEW: CommandLine compiler example
+ 
+   This program blah blah blah...
+ 
+ USAGE: compiler [options] <input file>
+ 
+ OPTIONS:
+   ...
+   -help             - display available options (--help-hidden for more)
+   -o <filename>     - Specify output filename
+
    + +
    + + + +
    + Reference Guide +
    + + +
    + +

    Now that you know the basics of how to use the CommandLine library, this + section will give you the detailed information you need to tune how command line + options work, as well as information on more "advanced" command line option + processing capabilities.

    + +
    + + +
    + Positional Arguments +
    + +
    + +

    Positional arguments are those arguments that are not named, and are not + specified with a hyphen. Positional arguments should be used when an option is + specified by its position alone. For example, the standard Unix grep + tool takes a regular expression argument, and an optional filename to search + through (which defaults to standard input if a filename is not specified). + Using the CommandLine library, this would be specified as:

    + + 
    + cl::opt<string> Regex   (cl::Positional, cl::desc("<regular expression>"), cl::Required);
+ cl::opt<string> Filename(cl::Positional, cl::desc("<input file>"), cl::init("-"));
+
    + +

    Given these two option declarations, the --help output for our grep + replacement would look like this:

    + + 
    + USAGE: spiffygrep [options] <regular expression> <input file>
+ 
+ OPTIONS:
+   -help - display available options (--help-hidden for more)
+
    + +

    ... and the resultant program could be used just like the standard + grep tool.

    + +

    Positional arguments are sorted by their order of construction. This means + that command line options will be ordered according to how they are listed in a + .cpp file, but will not have an ordering defined if the positional arguments + are defined in multiple .cpp files. The fix for this problem is simply to + define all of your positional arguments in one .cpp file.

    + +
    + + + +
    + Specifying positional options with hyphens +
    + +
    + +

    Sometimes you may want to specify a value to your positional argument that + starts with a hyphen (for example, searching for '-foo' in a file). At + first, you will have trouble doing this, because it will try to find an argument + named '-foo', and will fail (and single quotes will not save you). + Note that the system grep has the same problem:

    + + 
    +   $ spiffygrep '-foo' test.txt
+   Unknown command line argument '-foo'.  Try: spiffygrep --help'
+ 
+   $ grep '-foo' test.txt
+   grep: illegal option -- f
+   grep: illegal option -- o
+   grep: illegal option -- o
+   Usage: grep -hblcnsviw pattern file . . .
+
    + +

    The solution for this problem is the same for both your tool and the system + version: use the '--' marker. When the user specifies '--' on + the command line, it is telling the program that all options after the + '--' should be treated as positional arguments, not options. Thus, we + can use it like this:

    + + 
    +   $ spiffygrep -- -foo test.txt
+     ...output...
+
    + +
    + + +
    + Determining absolute position with getPosition() +
    +
    +

    Sometimes an option can affect or modify the meaning of another option. For + example, consider gcc's -x LANG option. This tells + gcc to ignore the suffix of subsequent positional arguments and force + the file to be interpreted as if it contained source code in language + LANG. In order to handle this properly , you need to know the + absolute position of each argument, especially those in lists, so their + interaction(s) can be applied correctly. This is also useful for options like + -llibname which is actually a positional argument that starts with + a dash.

    +

    So, generally, the problem is that you have two cl::list variables + that interact in some way. To ensure the correct interaction, you can use the + cl::list::getPosition(optnum) method. This method returns the + absolute position (as found on the command line) of the optnum + item in the cl::list.

    +

    The idiom for usage is like this:

    + + 
    +   static cl::list<std::string> Files(cl::Positional, cl::OneOrMore);
+   static cl::list<std::string> Libraries("l", cl::ZeroOrMore);
+ 
+   int main(int argc, char**argv) {
+     // ...
+     std::vector<std::string>::iterator fileIt = Files.begin();
+     std::vector<std::string>::iterator libIt  = Libraries.begin();
+     unsigned libPos = 0, filePos = 0;
+     while ( 1 ) {
+       if ( libIt != Libraries.end() )
+         libPos = Libraries.getPosition( libIt - Libraries.begin() );
+       else
+         libPos = 0;
+       if ( fileIt != Files.end() )
+         filePos = Files.getPosition( fileIt - Files.begin() );
+       else
+         filePos = 0;
+ 
+       if ( filePos != 0 && (libPos == 0 || filePos < libPos) ) {
+         // Source File Is next
+         ++fileIt;
+       }
+       else if ( libPos != 0 && (filePos == 0 || libPos < filePos) ) {
+         // Library is next
+         ++libIt;
+       }
+       else
+         break; // we're done with the list
+     }
+   }
    + +

    Note that, for compatibility reasons, the cl::opt also supports an + unsigned getPosition() option that will provide the absolute position + of that option. You can apply the same approach as above with a + cl::opt and a cl::list option as you can with two lists.

    +
    + + +
    + The cl::ConsumeAfter modifier +
    + +
    + +

    The cl::ConsumeAfter formatting option is + used to construct programs that use "interpreter style" option processing. With + this style of option processing, all arguments specified after the last + positional argument are treated as special interpreter arguments that are not + interpreted by the command line argument.

    + +

    As a concrete example, lets say we are developing a replacement for the + standard Unix Bourne shell (/bin/sh). To run /bin/sh, first + you specify options to the shell itself (like -x which turns on trace + output), then you specify the name of the script to run, then you specify + arguments to the script. These arguments to the script are parsed by the Bourne + shell command line option processor, but are not interpreted as options to the + shell itself. Using the CommandLine library, we would specify this as:

    + + 
    + cl::opt<string> Script(cl::Positional, cl::desc("<input script>"), cl::init("-"));
+ cl::list<string>  Argv(cl::ConsumeAfter, cl::desc("<program arguments>..."));
+ cl::opt<bool>    Trace("x", cl::desc("Enable trace output"));
+
    + +

    which automatically provides the help output:

    + + 
    + USAGE: spiffysh [options] <input script> <program arguments>...
+ 
+ OPTIONS:
+   -help - display available options (--help-hidden for more)
+   -x    - Enable trace output
+
    + +

    At runtime, if we run our new shell replacement as `spiffysh -x test.sh + -a -x -y bar', the Trace variable will be set to true, the + Script variable will be set to "test.sh", and the + Argv list will contain ["-a", "-x", "-y", "bar"], because they + were specified after the last positional argument (which is the script + name).

    + +

    There are several limitations to when cl::ConsumeAfter options can + be specified. For example, only one cl::ConsumeAfter can be specified + per program, there must be at least one positional + argument specified, there must not be any cl::list + positional arguments, and the cl::ConsumeAfter option should be a cl::list option.

    + +
    + + +
    + Internal vs External Storage +
    + +
    + +

    By default, all command line options automatically hold the value that they + parse from the command line. This is very convenient in the common case, + especially when combined with the ability to define command line options in the + files that use them. This is called the internal storage model.

    + +

    Sometimes, however, it is nice to separate the command line option processing + code from the storage of the value parsed. For example, lets say that we have a + '-debug' option that we would like to use to enable debug information + across the entire body of our program. In this case, the boolean value + controlling the debug code should be globally accessable (in a header file, for + example) yet the command line option processing code should not be exposed to + all of these clients (requiring lots of .cpp files to #include + CommandLine.h).

    + +

    To do this, set up your .h file with your option, like this for example:

    + +
    + 
    + // DebugFlag.h - Get access to the '-debug' command line option
+ //
+ 
+ // DebugFlag - This boolean is set to true if the '-debug' command line option
+ // is specified.  This should probably not be referenced directly, instead, use
+ // the DEBUG macro below.
+ //
+ extern bool DebugFlag;
+ 
+ // DEBUG macro - This macro should be used by code to emit debug information.
+ // In the '-debug' option is specified on the command line, and if this is a
+ // debug build, then the code specified as the option to the macro will be
+ // executed.  Otherwise it will not be.
+ #ifdef NDEBUG
+ #define DEBUG(X)
+ #else
+ #define DEBUG(X) do { if (DebugFlag) { X; } } while (0)
+ #endif
+
    +
    + +

    This allows clients to blissfully use the DEBUG() macro, or the + DebugFlag explicitly if they want to. Now we just need to be able to + set the DebugFlag boolean when the option is set. To do this, we pass + an additional argument to our command line argument processor, and we specify + where to fill in with the cl::location + attribute:

    + +
    + 
    + bool DebugFlag;                  // the actual value
+ static cl::opt<bool, true>       // The parser
+ Debug("debug", cl::desc("Enable debug output"), cl::Hidden, cl::location(DebugFlag));
+
    +
    + +

    In the above example, we specify "true" as the second argument to + the cl::opt template, indicating that the + template should not maintain a copy of the value itself. In addition to this, + we specify the cl::location attribute, so + that DebugFlag is automatically set.

    + +
    + + +
    + Option Attributes +
    + +
    + +

    This section describes the basic attributes that you can specify on + options.

    + +
      + +
    • The option name attribute (which is required for all options, except positional options) specifies what the option name is. + This option is specified in simple double quotes: + + 
      + cl::opt<bool> Quiet("quiet");
+
      + +
      • + +
    • The cl::desc attribute specifies a + description for the option to be shown in the --help output for the + program.
      • + +
    • The cl::value_desc attribute + specifies a string that can be used to fine tune the --help output for + a command line option. Look here for an + example.
      • + +
    • The cl::init attribute specifies an + inital value for a scalar option. If this attribute is + not specified then the command line option value defaults to the value created + by the default constructor for the type. Warning: If you specify both + cl::init and cl::location for an option, + you must specify cl::location first, so that when the + command-line parser sees cl::init, it knows where to put the + initial value. (You will get an error at runtime if you don't put them in + the right order.)
      • + +
    • The cl::location attribute where to + store the value for a parsed command line option if using external storage. See + the section on Internal vs External Storage for more + information.
      • + +
    • The cl::aliasopt attribute + specifies which option a cl::alias option is + an alias for.
      • + +
    • The cl::values attribute specifies + the string-to-value mapping to be used by the generic parser. It takes a + clEnumValEnd terminated list of (option, value, description) triplets + that + specify the option name, the value mapped to, and the description shown in the + --help for the tool. Because the generic parser is used most + frequently with enum values, two macros are often useful: + +
        + +
      1. The clEnumVal macro is used as a + nice simple way to specify a triplet for an enum. This macro automatically + makes the option name be the same as the enum name. The first option to the + macro is the enum, the second is the description for the command line + option.
        2. + +
      2. The clEnumValN macro is used to + specify macro options where the option name doesn't equal the enum name. For + this macro, the first argument is the enum value, the second is the flag name, + and the second is the description.
        3. + +
      + + You will get a compile time error if you try to use cl::values with a parser + that does not support it.
      • + +
    + +
    + + +
    + Option Modifiers +
    + +
    + +

    Option modifiers are the flags and expressions that you pass into the + constructors for cl::opt and cl::list. These modifiers give you the ability to + tweak how options are parsed and how --help output is generated to fit + your application well.

    + +

    These options fall into five main catagories:

    + +
      +
    1. Hiding an option from --help output
      2. +
    2. Controlling the number of occurrences + required and allowed
      3. +
    3. Controlling whether or not a value must be + specified
      4. +
    4. Controlling other formatting options
      5. +
    5. Miscellaneous option modifiers
      6. +
    + +

    It is not possible to specify two options from the same catagory (you'll get + a runtime error) to a single option, except for options in the miscellaneous + catagory. The CommandLine library specifies defaults for all of these settings + that are the most useful in practice and the most common, which mean that you + usually shouldn't have to worry about these.

    + +
    + + +
    + Hiding an option from --help output +
    + +
    + +

    The cl::NotHidden, cl::Hidden, and + cl::ReallyHidden modifiers are used to control whether or not an option + appears in the --help and --help-hidden output for the + compiled program:

    + +
      + +
    • The cl::NotHidden modifier + (which is the default for cl::opt and cl::list options) indicates the option is to appear + in both help listings.
      • + +
    • The cl::Hidden modifier (which is the + default for cl::alias options) indicates that + the option should not appear in the --help output, but should appear in + the --help-hidden output.
      • + +
    • The cl::ReallyHidden modifier + indicates that the option should not appear in any help output.
      • + +
    + +
    + + +
    + Controlling the number of occurrences required and + allowed +
    + +
    + +

    This group of options is used to control how many time an option is allowed + (or required) to be specified on the command line of your program. Specifying a + value for this setting allows the CommandLine library to do error checking for + you.

    + +

    The allowed values for this option group are:

    + +
      + +
    • The cl::Optional modifier (which + is the default for the cl::opt and cl::alias classes) indicates that your program will + allow either zero or one occurrence of the option to be specified.
      • + +
    • The cl::ZeroOrMore modifier + (which is the default for the cl::list class) + indicates that your program will allow the option to be specified zero or more + times.
      • + +
    • The cl::Required modifier + indicates that the specified option must be specified exactly one time.
      • + +
    • The cl::OneOrMore modifier + indicates that the option must be specified at least one time.
      • + +
    • The cl::ConsumeAfter modifier is described in the Positional arguments section.
      • + +
    + +

    If an option is not specified, then the value of the option is equal to the + value specified by the cl::init attribute. If + the cl::init attribute is not specified, the + option value is initialized with the default constructor for the data type.

    + +

    If an option is specified multiple times for an option of the cl::opt class, only the last value will be + retained.

    + +
    + + +
    + Controlling whether or not a value must be specified +
    + +
    + +

    This group of options is used to control whether or not the option allows a + value to be present. In the case of the CommandLine library, a value is either + specified with an equal sign (e.g. '-index-depth=17') or as a trailing + string (e.g. '-o a.out').

    + +

    The allowed values for this option group are:

    + +
      + +
    • The cl::ValueOptional modifier + (which is the default for bool typed options) specifies that it is + acceptable to have a value, or not. A boolean argument can be enabled just by + appearing on the command line, or it can have an explicit '-foo=true'. + If an option is specified with this mode, it is illegal for the value to be + provided without the equal sign. Therefore '-foo true' is illegal. To + get this behavior, you must use the cl::ValueRequired modifier.
      • + +
    • The cl::ValueRequired modifier + (which is the default for all other types except for unnamed alternatives using the generic parser) + specifies that a value must be provided. This mode informs the command line + library that if an option is not provides with an equal sign, that the next + argument provided must be the value. This allows things like '-o + a.out' to work.
      • + +
    • The cl::ValueDisallowed + modifier (which is the default for unnamed + alternatives using the generic parser) indicates that it is a runtime error + for the user to specify a value. This can be provided to disallow users from + providing options to boolean options (like '-foo=true').
      • + +
    + +

    In general, the default values for this option group work just like you would + want them to. As mentioned above, you can specify the cl::ValueDisallowed modifier to a boolean + argument to restrict your command line parser. These options are mostly useful + when extending the library.

    + +
    + + +
    + Controlling other formatting options +
    + +
    + +

    The formatting option group is used to specify that the command line option + has special abilities and is otherwise different from other command line + arguments. As usual, you can only specify one of these arguments at most.

    + +
      + +
    • The cl::NormalFormatting + modifier (which is the default all options) specifies that this option is + "normal".
      • + +
    • The cl::Positional modifier + specifies that this is a positional argument that does not have a command line + option associated with it. See the Positional + Arguments section for more information.
      • + +
    • The cl::ConsumeAfter modifier + specifies that this option is used to capture "interpreter style" arguments. See this section for more information.
      • + +
    • The cl::Prefix modifier specifies + that this option prefixes its value. With 'Prefix' options, the equal sign does + not separate the value from the option name specified. Instead, the value is + everything after the prefix, including any equal sign if present. This is useful + for processing odd arguments like -lmalloc and -L/usr/lib in a + linker tool or -DNAME=value in a compiler tool. Here, the + 'l', 'D' and 'L' options are normal string (or list) + options, that have the cl::Prefix + modifier added to allow the CommandLine library to recognize them. Note that + cl::Prefix options must not have the + cl::ValueDisallowed modifier + specified.
      • + +
    • The cl::Grouping modifier is used + to implement Unix-style tools (like ls) that have lots of single letter + arguments, but only require a single dash. For example, the 'ls -labF' + command actually enables four different options, all of which are single + letters. Note that cl::Grouping + options cannot have values.
      • + +
    + +

    The CommandLine library does not restrict how you use the cl::Prefix or cl::Grouping modifiers, but it is possible to + specify ambiguous argument settings. Thus, it is possible to have multiple + letter options that are prefix or grouping options, and they will still work as + designed.

    + +

    To do this, the CommandLine library uses a greedy algorithm to parse the + input option into (potentially multiple) prefix and grouping options. The + strategy basically looks like this:

    + +
    parse(string OrigInput) { + +
      +
    1. string input = OrigInput; +
    2. if (isOption(input)) return getOption(input).parse();    // Normal option +
    3. while (!isOption(input) && !input.empty()) input.pop_back();    // Remove the last letter +
    4. if (input.empty()) return error();    // No matching option +
    5. if (getOption(input).isPrefix())
      +   return getOption(input).parse(input);       +
    6. while (!input.empty()) {    // Must be grouping options
      +   getOption(input).parse();
      +   OrigInput.erase(OrigInput.begin(), OrigInput.begin()+input.length());
      +   input = OrigInput;
      +   while (!isOption(input) && !input.empty()) input.pop_back();
      + }       +
    7. if (!OrigInput.empty()) error();
      8. +
    + +

    }

    +
    + +
    + + +
    + Miscellaneous option modifiers +
    + +
    + +

    The miscellaneous option modifiers are the only flags where you can specify + more than one flag from the set: they are not mutually exclusive. These flags + specify boolean properties that modify the option.

    + +
      + +
    • The cl::CommaSeparated modifier + indicates that any commas specified for an option's value should be used to + split the value up into multiple values for the option. For example, these two + options are equivalent when cl::CommaSeparated is specified: + "-foo=a -foo=b -foo=c" and "-foo=a,b,c". This option only + makes sense to be used in a case where the option is allowed to accept one or + more values (i.e. it is a cl::list option).
      • + +
    • The + cl::PositionalEatsArgs modifier (which only applies to + positional arguments, and only makes sense for lists) indicates that positional + argument should consume any strings after it (including strings that start with + a "-") up until another recognized positional argument. For example, if you + have two "eating" positional arguments, "pos1" and "pos2", the + string "-pos1 -foo -bar baz -pos2 -bork" would cause the "-foo -bar + -baz" strings to be applied to the "-pos1" option and the + "-bork" string to be applied to the "-pos2" option.
      • + +
    + +

    So far, these are the only two miscellaneous option modifiers.

    + +
    + + +
    + Top-Level Classes and Functions +
    + +
    + +

    Despite all of the built-in flexibility, the CommandLine option library + really only consists of one function (cl::ParseCommandLineOptions) + and three main classes: cl::opt, cl::list, and cl::alias. This section describes these three + classes in detail.

    + +
    + + +
    + The cl::ParseCommandLineOptions + function +
    + +
    + +

    The cl::ParseCommandLineOptions function is designed to be called + directly from main, and is used to fill in the values of all of the + command line option variables once argc and argv are + available.

    + +

    The cl::ParseCommandLineOptions function requires two parameters + (argc and argv), but may also take an optional third parameter + which holds additional extra text to emit when the + --help option is invoked.

    + +
    + + +
    + The cl::ParseEnvironmentOptions + function +
    + +
    + +

    The cl::ParseEnvironmentOptions function has mostly the same effects + as cl::ParseCommandLineOptions, + except that it is designed to take values for options from an environment + variable, for those cases in which reading the command line is not convenient or + desired. It fills in the values of all the command line option variables just + like cl::ParseCommandLineOptions + does.

    + +

    It takes three parameters: the name of the program (since argv may + not be available, it can't just look in argv[0]), the name of the + environment variable to examine, and the optional + additional extra text to emit when the + --help option is invoked.

    + +

    cl::ParseEnvironmentOptions will break the environment + variable's value up into words and then process them using + cl::ParseCommandLineOptions. + Note: Currently cl::ParseEnvironmentOptions does not support + quoting, so an environment variable containing -option "foo bar" will + be parsed as three words, -option, "foo, and bar", + which is different from what you would get from the shell with the same + input.

    + +
    + + +
    + The cl::SetVersionPrinter + function +
    + +
    + +

    The cl::SetVersionPrinter function is designed to be called + directly from main and before + cl::ParseCommandLineOptions. Its use is optional. It simply arranges + for a function to be called in response to the --version option instead + of having the CommandLine library print out the usual version string + for LLVM. This is useful for programs that are not part of LLVM but wish to use + the CommandLine facilities. Such programs should just define a small + function that takes no arguments and returns void and that prints out + whatever version information is appropriate for the program. Pass the address + of that function to cl::SetVersionPrinter to arrange for it to be + called when the --version option is given by the user.

    + +
    + +
    + The cl::opt class +
    + +
    + +

    The cl::opt class is the class used to represent scalar command line + options, and is the one used most of the time. It is a templated class which + can take up to three arguments (all except for the first have default values + though):

    + + 
    + namespace cl {
+   template <class DataType, bool ExternalStorage = false,
+             class ParserClass = parser<DataType> >
+   class opt;
+ }
+
    + +

    The first template argument specifies what underlying data type the command + line argument is, and is used to select a default parser implementation. The + second template argument is used to specify whether the option should contain + the storage for the option (the default) or whether external storage should be + used to contain the value parsed for the option (see Internal + vs External Storage for more information).

    + +

    The third template argument specifies which parser to use. The default value + selects an instantiation of the parser class based on the underlying + data type of the option. In general, this default works well for most + applications, so this option is only used when using a custom parser.

    + +
    + + +
    + The cl::list class +
    + +
    + +

    The cl::list class is the class used to represent a list of command + line options. It too is a templated class which can take up to three + arguments:

    + + 
    + namespace cl {
+   template <class DataType, class Storage = bool,
+             class ParserClass = parser<DataType> >
+   class list;
+ }
+
    + +

    This class works the exact same as the cl::opt class, except that the second argument is + the type of the external storage, not a boolean value. For this class, + the marker type 'bool' is used to indicate that internal storage should + be used.

    + +
    + + +
    + The cl::bits class +
    + +
    + +

    The cl::bits class is the class used to represent a list of command + line options in the form of a bit vector. It is also a templated class which + can take up to three arguments:

    + + 
    + namespace cl {
+   template <class DataType, class Storage = bool,
+             class ParserClass = parser<DataType> >
+   class bits;
+ }
+
    + +

    This class works the exact same as the cl::lists class, except that the second argument + must be of type unsigned if external storage is used.

    + +
    + + +
    + The cl::alias class +
    + +
    + +

    The cl::alias class is a nontemplated class that is used to form + aliases for other arguments.

    + + 
    + namespace cl {
+   class alias;
+ }
+
    + +

    The cl::aliasopt attribute should be + used to specify which option this is an alias for. Alias arguments default to + being Hidden, and use the aliased options parser to do + the conversion from string to data.

    + +
    + + +
    + The cl::extrahelp class +
    + +
    + +

    The cl::extrahelp class is a nontemplated class that allows extra + help text to be printed out for the --help option.

    + + 
    + namespace cl {
+   struct extrahelp;
+ }
+
    + +

    To use the extrahelp, simply construct one with a const char* + parameter to the constructor. The text passed to the constructor will be printed + at the bottom of the help message, verbatim. Note that multiple + cl::extrahelp can be used, but this practice is discouraged. If + your tool needs to print additional help information, put all that help into a + single cl::extrahelp instance.

    +

    For example:

    + 
    +   cl::extrahelp("\nADDITIONAL HELP:\n\n  This is the extra help\n");
+
    +
    + + +
    + Builtin parsers +
    + +
    + +

    Parsers control how the string value taken from the command line is + translated into a typed value, suitable for use in a C++ program. By default, + the CommandLine library uses an instance of parser<type> if the + command line option specifies that it uses values of type 'type'. + Because of this, custom option processing is specified with specializations of + the 'parser' class.

    + +

    The CommandLine library provides the following builtin parser + specializations, which are sufficient for most applications. It can, however, + also be extended to work with new data types and new ways of interpreting the + same data. See the Writing a Custom Parser for more + details on this type of library extension.

    + +
      + +
    • The generic parser<t> parser + can be used to map strings values to any data type, through the use of the cl::values property, which specifies the mapping + information. The most common use of this parser is for parsing enum values, + which allows you to use the CommandLine library for all of the error checking to + make sure that only valid enum values are specified (as opposed to accepting + arbitrary strings). Despite this, however, the generic parser class can be used + for any data type.
      • + +
    • The parser<bool> specialization + is used to convert boolean strings to a boolean value. Currently accepted + strings are "true", "TRUE", "True", "1", + "false", "FALSE", "False", and "0".
      • + +
    • The parser<boolOrDefault> + specialization is used for cases where the value is boolean, + but we also need to know whether the option was specified at all. boolOrDefault + is an enum with 3 values, BOU_UNSET, BOU_TRUE and BOU_FALSE. This parser accepts + the same strings as parser<bool>.
      • + +
    • The parser<string> + specialization simply stores the parsed string into the string value + specified. No conversion or modification of the data is performed.
      • + +
    • The parser<int> specialization + uses the C strtol function to parse the string input. As such, it will + accept a decimal number (with an optional '+' or '-' prefix) which must start + with a non-zero digit. It accepts octal numbers, which are identified with a + '0' prefix digit, and hexadecimal numbers with a prefix of + '0x' or '0X'.
      • + +
    • The parser<double> and + parser<float> specializations use the standard C + strtod function to convert floating point strings into floating point + values. As such, a broad range of string formats is supported, including + exponential notation (ex: 1.7e15) and properly supports locales. +
      • + +
    + +
    + + +
    + Extension Guide +
    + + +
    + +

    Although the CommandLine library has a lot of functionality built into it + already (as discussed previously), one of its true strengths lie in its + extensibility. This section discusses how the CommandLine library works under + the covers and illustrates how to do some simple, common, extensions.

    + +
    + + +
    + Writing a custom parser +
    + +
    + +

    One of the simplest and most common extensions is the use of a custom parser. + As discussed previously, parsers are the portion + of the CommandLine library that turns string input from the user into a + particular parsed data type, validating the input in the process.

    + +

    There are two ways to use a new parser:

    + +
      + +
    1. + +

      Specialize the cl::parser template for + your custom data type.

      + +

      This approach has the advantage that users of your custom data type will + automatically use your custom parser whenever they define an option with a value + type of your data type. The disadvantage of this approach is that it doesn't + work if your fundamental data type is something that is already supported.

      + +
      2. + +
    2. + +

      Write an independent class, using it explicitly from options that need + it.

      + +

      This approach works well in situations where you would line to parse an + option using special syntax for a not-very-special data-type. The drawback of + this approach is that users of your parser have to be aware that they are using + your parser instead of the builtin ones.

      + +
      3. + +
    + +

    To guide the discussion, we will discuss a custom parser that accepts file + sizes, specified with an optional unit after the numeric size. For example, we + would like to parse "102kb", "41M", "1G" into the appropriate integer value. In + this case, the underlying data type we want to parse into is + 'unsigned'. We choose approach #2 above because we don't want to make + this the default for all unsigned options.

    + +

    To start out, we declare our new FileSizeParser class:

    + + 
    + struct FileSizeParser : public cl::basic_parser<unsigned> {
+   // parse - Return true on error.
+   bool parse(cl::Option &O, const char *ArgName, const std::string &ArgValue,
+              unsigned &Val);
+ };
+
    + +

    Our new class inherits from the cl::basic_parser template class to + fill in the default, boiler plate code for us. We give it the data type that + we parse into, the last argument to the parse method, so that clients of + our custom parser know what object type to pass in to the parse method. (Here we + declare that we parse into 'unsigned' variables.)

    + +

    For most purposes, the only method that must be implemented in a custom + parser is the parse method. The parse method is called + whenever the option is invoked, passing in the option itself, the option name, + the string to parse, and a reference to a return value. If the string to parse + is not well-formed, the parser should output an error message and return true. + Otherwise it should return false and set 'Val' to the parsed value. In + our example, we implement parse as:

    + + 
    + bool FileSizeParser::parse(cl::Option &O, const char *ArgName,
+                            const std::string &Arg, unsigned &Val) {
+   const char *ArgStart = Arg.c_str();
+   char *End;
+  
+   // Parse integer part, leaving 'End' pointing to the first non-integer char
+   Val = (unsigned)strtol(ArgStart, &End, 0);
+ 
+   while (1) {
+     switch (*End++) {
+     case 0: return false;   // No error
+     case 'i':               // Ignore the 'i' in KiB if people use that
+     case 'b': case 'B':     // Ignore B suffix
+       break;
+ 
+     case 'g': case 'G': Val *= 1024*1024*1024; break;
+     case 'm': case 'M': Val *= 1024*1024;      break;
+     case 'k': case 'K': Val *= 1024;           break;
+ 
+     default:
+       // Print an error message if unrecognized character!
+       return O.error(": '" + Arg + "' value invalid for file size argument!");
+     }
+   }
+ }
+
    + +

    This function implements a very simple parser for the kinds of strings we are + interested in. Although it has some holes (it allows "123KKK" for + example), it is good enough for this example. Note that we use the option + itself to print out the error message (the error method always returns + true) in order to get a nice error message (shown below). Now that we have our + parser class, we can use it like this:

    + + 
    + static cl::opt<unsigned, false, FileSizeParser>
+ MFS("max-file-size", cl::desc("Maximum file size to accept"),
+     cl::value_desc("size"));
+
    + +

    Which adds this to the output of our program:

    + + 
    + OPTIONS:
+   -help                 - display available options (--help-hidden for more)
+   ...
+   -max-file-size=<size> - Maximum file size to accept
+
    + +

    And we can test that our parse works correctly now (the test program just + prints out the max-file-size argument value):

    + + 
    + $ ./test
+ MFS: 0
+ $ ./test -max-file-size=123MB
+ MFS: 128974848
+ $ ./test -max-file-size=3G
+ MFS: 3221225472
+ $ ./test -max-file-size=dog
+ -max-file-size option: 'dog' value invalid for file size argument!
+
    + +

    It looks like it works. The error message that we get is nice and helpful, + and we seem to accept reasonable file sizes. This wraps up the "custom parser" + tutorial.

    + +
    + + +
    + Exploiting external storage +
    + +
    +

    Several of the LLVM libraries define static cl::opt instances that + will automatically be included in any program that links with that library. + This is a feature. However, sometimes it is necessary to know the value of the + command line option outside of the library. In these cases the library does or + should provide an external storage location that is accessible to users of the + library. Examples of this include the llvm::DebugFlag exported by the + lib/Support/Debug.cpp file and the llvm::TimePassesIsEnabled + flag exported by the lib/VMCore/Pass.cpp file.

    + +

    TODO: complete this section

    + +
    + + +
    + Dynamically adding command line options +
    + +
    + +

    TODO: fill in this section

    + +
    + + + +
    +
    + Valid CSS! + Valid HTML 4.01! + + Chris Lattner
    + LLVM Compiler Infrastructure
    + Last modified: $Date: 2008/02/12 06:05:03 $ +
    + + + Index: llvm-www/releases/2.2/docs/CompilerDriver.html diff -c /dev/null llvm-www/releases/2.2/docs/CompilerDriver.html:1.1 *** /dev/null Tue Feb 12 00:07:01 2008 --- llvm-www/releases/2.2/docs/CompilerDriver.html Tue Feb 12 00:05:03 2008 *************** *** 0 **** --- 1,823 ---- + + + + + The LLVM Compiler Driver (llvmc) + + + + + +
    The LLVM Compiler Driver (llvmc)
    +

    NOTE: This document is a work in progress!

    +
      +
    1. Abstract
      2. +
    2. Introduction +
        +
      1. Purpose
        2. +
      2. Operation
        3. +
      3. Phases
        4. +
      4. Actions
        5. +
      +
      3. +
    3. Configuration +
        +
      1. Overview
        2. +
      2. Configuration Files
        3. +
      3. Syntax
        4. +
      4. Substitutions
        5. +
      5. Sample Config File
        6. +
      +
    4. Glossary +
    +
    +

    Written by Reid Spencer +

    +
    + + +
    Abstract
    + +
    +

    This document describes the requirements, design, and configuration of the + LLVM compiler driver, llvmc. The compiler driver knows about LLVM's + tool set and can be configured to know about a variety of compilers for + source languages. It uses this knowledge to execute the tools necessary + to accomplish general compilation, optimization, and linking tasks. The main + purpose of llvmc is to provide a simple and consistent interface to + all compilation tasks. This reduces the burden on the end user who can just + learn to use llvmc instead of the entire LLVM tool set and all the + source language compilers compatible with LLVM.

    +
    + +
    Introduction
    + +
    +

    The llvmc tool is a configurable compiler + driver. As such, it isn't a compiler, optimizer, + or a linker itself but it drives (invokes) other software that perform those + tasks. If you are familiar with the GNU Compiler Collection's gcc + tool, llvmc is very similar.

    +

    The following introductory sections will help you understand why this tool + is necessary and what it does.

    +
    + + +
    Purpose
    +
    +

    llvmc was invented to make compilation of user programs with + LLVM-based tools easier. To accomplish this, llvmc strives to:

    +
      +
    • Be the single point of access to most of the LLVM tool set.
      • +
    • Hide the complexities of the LLVM tools through a single interface.
      • +
    • Provide a consistent interface for compiling all languages.
      • +
    +

    Additionally, llvmc makes it easier to write a compiler for use + with LLVM, because it:

    +
      +
    • Makes integration of existing non-LLVM tools simple.
      • +
    • Extends the capabilities of minimal compiler tools by optimizing their + output.
      • +
    • Reduces the number of interfaces a compiler writer must know about + before a working compiler can be completed (essentially only the VMCore + interfaces need to be understood).
      • +
    • Supports source language translator invocation via both dynamically + loadable shared objects and invocation of an executable.
      • +
    +
    + + +
    Operation
    +
    +

    At a high level, llvmc operation is very simple. The basic action + taken by llvmc is to simply invoke some tool or set of tools to fill + the user's request for compilation. Every execution of llvmctakes the + following sequence of steps:

    +
    +
    Collect Command Line Options
    +
    The command line options provide the marching orders to llvmc + on what actions it should perform. This is the request the user is making + of llvmc and it is interpreted first. See the llvmc + manual page for details on the + options.
    +
    Read Configuration Files
    +
    Based on the options and the suffixes of the filenames presented, a set + of configuration files are read to configure the actions llvmc will + take. Configuration files are provided by either LLVM or the + compiler tools that llvmc invokes. These files determine what + actions llvmc will take in response to the user's request. See + the section on configuration for more details. +
    +
    Determine Phases To Execute
    +
    Based on the command line options and configuration files, + llvmc determines the compilation phases that + must be executed by the user's request. This is the primary work of + llvmc.
    +
    Determine Actions To Execute
    +
    Each phase to be executed can result in the + invocation of one or more actions. An action is + either a whole program or a function in a dynamically linked shared library. + In this step, llvmc determines the sequence of actions that must be + executed. Actions will always be executed in a deterministic order.
    +
    Execute Actions
    +
    The actions necessary to support the user's + original request are executed sequentially and deterministically. All + actions result in either the invocation of a whole program to perform the + action or the loading of a dynamically linkable shared library and invocation + of a standard interface function within that library.
    +
    Termination
    +
    If any action fails (returns a non-zero result code), llvmc + also fails and returns the result code from the failing action. If + everything succeeds, llvmc will return a zero result code.
    +
    +

    llvmc's operation must be simple, regular and predictable. + Developers need to be able to rely on it to take a consistent approach to + compilation. For example, the invocation:

    + + llvmc -O2 x.c y.c z.c -o xyz +

    must produce exactly the same results as:

    + 
    
+     llvmc -O2 x.c -o x.o
+     llvmc -O2 y.c -o y.o
+     llvmc -O2 z.c -o z.o
+     llvmc -O2 x.o y.o z.o -o xyz
    +

    To accomplish this, llvmc uses a very simple goal oriented + procedure to do its work. The overall goal is to produce a functioning + executable. To accomplish this, llvmc always attempts to execute a + series of compilation phases in the same sequence. + However, the user's options to llvmc can cause the sequence of phases + to start in the middle or finish early.

    +
    + + +
    Phases
    +
    +

    llvmc breaks every compilation task into the following five + distinct phases:

    +
    Preprocessing
    Not all languages support preprocessing; + but for those that do, this phase can be invoked. This phase is for + languages that provide combining, filtering, or otherwise altering with the + source language input before the translator parses it. Although C and C++ + are the most common users of this phase, other languages may provide their + own preprocessor (whether its the C pre-processor or not).
    +
    +
    Translation
    The translation phase converts the source + language input into something that LLVM can interpret and use for + downstream phases. The translation is essentially from "non-LLVM form" to + "LLVM form".
    +
    +
    Optimization
    Once an LLVM Module has been obtained from + the translation phase, the program enters the optimization phase. This phase + attempts to optimize all of the input provided on the command line according + to the options provided.
    +
    +
    Linking
    The inputs are combined to form a complete + program.
    +
    +

    The following table shows the inputs, outputs, and command line options + applicable to each phase.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    PhaseInputsOutputsOptions
    Preprocessing
    • Source Language File
    • Source Language File
    +
    -E
    +
    Stops the compilation after preprocessing
    +
    Translation
      +
    • Source Language File
      • +
      +
    • LLVM Assembly
      • +
    • LLVM Bitcode
      • +
    • LLVM C++ IR
      • +
    +
    -c
    +
    Stops the compilation after translation so that optimization and + linking are not done.
    +
    -S
    +
    Stops the compilation before object code is written so that only + assembly code remains.
    +
    Optimization
      +
    • LLVM Assembly
      • +
    • LLVM Bitcode
      • +
      +
    • LLVM Bitcode
      • +
    +
    -Ox +
    This group of options controls the amount of optimization + performed.
    +
    Linking
      +
    • LLVM Bitcode
      • +
    • Native Object Code
      • +
    • LLVM Library
      • +
    • Native Library
      • +
      +
    • LLVM Bitcode Executable
      • +
    • Native Executable
      • +
    +
    -L
    Specifies a path for library search.
    +
    -l
    Specifies a library to link in.
    +
    +
    + + +
    Actions
    +
    +

    An action, with regard to llvmc is a basic operation that it takes + in order to fulfill the user's request. Each phase of compilation will invoke + zero or more actions in order to accomplish that phase.

    +

    Actions come in two forms:

    +
      +
    • Invokable Executables
      • +
    • Functions in a shared library
      • +
    +
    + + +
    Configuration
    + +
    +

    This section of the document describes the configuration files used by + llvmc. Configuration information is relatively static for a + given release of LLVM and a compiler tool. However, the details may + change from release to release of either. Users are encouraged to simply use + the various options of the llvmc command and ignore the configuration + of the tool. These configuration files are for compiler writers and LLVM + developers. Those wishing to simply use llvmc don't need to understand + this section but it may be instructive on how the tool works.

    +
    + + +
    Overview
    +
    +

    llvmc is highly configurable both on the command line and in + configuration files. The options it understands are generic, consistent and + simple by design. Furthermore, the llvmc options apply to the + compilation of any LLVM enabled programming language. To be enabled as a + supported source language compiler, a compiler writer must provide a + configuration file that tells llvmc how to invoke the compiler + and what its capabilities are. The purpose of the configuration files then + is to allow compiler writers to specify to llvmc how the compiler + should be invoked. Users may but are not advised to alter the compiler's + llvmc configuration.

    + +

    Because llvmc just invokes other programs, it must deal with the + available command line options for those programs regardless of whether they + were written for LLVM or not. Furthermore, not all compiler tools will + have the same capabilities. Some compiler tools will simply generate LLVM assembly + code, others will be able to generate fully optimized bitcode. In general, + llvmc doesn't make any assumptions about the capabilities or command + line options of a sub-tool. It simply uses the details found in the + configuration files and leaves it to the compiler writer to specify the + configuration correctly.

    + +

    This approach means that new compiler tools can be up and working very + quickly. As a first cut, a tool can simply compile its source to raw + (unoptimized) bitcode or LLVM assembly and llvmc can be configured + to pick up the slack (translate LLVM assembly to bitcode, optimize the + bitcode, generate native assembly, link, etc.). In fact, the compiler tools + need not use any LLVM libraries, and it could be written in any language + (instead of C++). The configuration data will allow the full range of + optimization, assembly, and linking capabilities that LLVM provides to be added + to these kinds of tools. Enabling the rapid development of front-ends is one + of the primary goals of llvmc.

    + +

    As a compiler tool matures, it may utilize the LLVM libraries and tools + to more efficiently produce optimized bitcode directly in a single compilation + and optimization program. In these cases, multiple tools would not be needed + and the configuration data for the compiler would change.

    + +

    Configuring llvmc to the needs and capabilities of a source language + compiler is relatively straight-forward. A compiler writer must provide a + definition of what to do for each of the five compilation phases for each of + the optimization levels. The specification consists simply of prototypical + command lines into which llvmc can substitute command line + arguments and file names. Note that any given phase can be completely blank if + the source language's compiler combines multiple phases into a single program. + For example, quite often pre-processing, translation, and optimization are + combined into a single program. The specification for such a compiler would have + blank entries for pre-processing and translation but a full command line for + optimization.

    +
    + + +
    Configuration Files
    +
    File Contents
    +
    +

    Each configuration file provides the details for a single source language + that is to be compiled. This configuration information tells llvmc + how to invoke the language's pre-processor, translator, optimizer, assembler + and linker. Note that a given source language needn't provide all these tools + as many of them exist in llvm currently.

    +
    + + +
    Directory Search
    +
    +

    llvmc always looks for files of a specific name. It uses the + first file with the name its looking for by searching directories in the + following order:
    +

      +
    1. Any directory specified by the -config-dir option will be + checked first.
      2. +
    2. If the environment variable LLVM_CONFIG_DIR is set, and it contains + the name of a valid directory, that directory will be searched next.
      3. +
    3. If the user's home directory (typically /home/user contains + a sub-directory named .llvm and that directory contains a + sub-directory named etc then that directory will be tried + next.
      4. +
    4. If the LLVM installation directory (typically /usr/local/llvm + contains a sub-directory named etc then that directory will be + tried last.
      5. +
    5. A standard "system" directory will be searched next. This is typically + /etc/llvm on UNIX™ and C:\WINNT on Microsoft + Windows™.
      6. +
    6. If the configuration file sought still can't be found, llvmc + will print an error message and exit.
      7. +
    +

    The first file found in this search will be used. Other files with the + same name will be ignored even if they exist in one of the subsequent search + locations.

    +
    + +
    File Names
    +
    +

    In the directories searched, each configuration file is given a specific + name to foster faster lookup (so llvmc doesn't have to do directory searches). + The name of a given language specific configuration file is simply the same + as the suffix used to identify files containing source in that language. + For example, a configuration file for C++ source might be named + cpp, C, or cxx. For languages that support multiple + file suffixes, multiple (probably identical) files (or symbolic links) will + need to be provided.

    +
    + +
    What Gets Read
    +
    +

    Which configuration files are read depends on the command line options and + the suffixes of the file names provided on llvmc's command line. Note + that the -x LANGUAGE option alters the language that llvmc + uses for the subsequent files on the command line. Only the configuration + files actually needed to complete llvmc's task are read. Other + language specific files will be ignored.

    +
    + + +
    Syntax
    +
    +

    The syntax of the configuration files is very simple and somewhat + compatible with Java's property files. Here are the syntax rules:

    +
      +
    • The file encoding is ASCII.
      • +
    • The file is line oriented. There should be one configuration definition + per line. Lines are terminated by the newline (0x0A) and/or carriage return + characters (0x0D)
      • +
    • A backslash (\) before a newline causes the newline to be + ignored. This is useful for line continuation of long definitions. A + backslash anywhere else is recognized as a backslash.
      • +
    • A configuration item consists of a name, an = and a value.
      • +
    • A name consists of a sequence of identifiers separated by period.
      • +
    • An identifier consists of specific keywords made up of only lower case + and upper case letters (e.g. lang.name).
      • +
    • Values come in four flavors: booleans, integers, commands and + strings.
      • +
    • Valid "false" boolean values are false False FALSE no No NO + off Off and OFF.
      • +
    • Valid "true" boolean values are true True TRUE yes Yes YES + on On and ON.
      • +
    • Integers are simply sequences of digits.
      • +
    • Commands start with a program name and are followed by a sequence of + words that are passed to that program as command line arguments. Program + arguments that begin and end with the % sign will have their value + substituted. Program names beginning with / are considered to be + absolute. Otherwise the PATH will be applied to find the program to + execute.
      • +
    • Strings are composed of multiple sequences of characters from the + character class [-A-Za-z0-9_:%+/\\|,] separated by white + space.
      • +
    • White space on a line is folded. Multiple blanks or tabs will be + reduced to a single blank.
      • +
    • White space before the configuration item's name is ignored.
      • +
    • White space on either side of the = is ignored.
      • +
    • White space in a string value is used to separate the individual + components of the string value but otherwise ignored.
      • +
    • Comments are introduced by the # character. Everything after a + # and before the end of line is ignored.
      • +
    +
    + + +
    Configuration Items
    +
    +

    The table below provides definitions of the allowed configuration items + that may appear in a configuration file. Every item has a default value and + does not need to appear in the configuration file. Missing items will have the + default value. Each identifier may appear as all lower case, first letter + capitalized or all upper case.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    NameValue TypeDescriptionDefault

    LLVMC ITEMS

    versionstringProvides the version string for the contents of this + configuration file. What is accepted as a legal configuration file + will change over time and this item tells llvmc which version + should be expected.b

    LANG ITEMS

    lang.namestringProvides the common name for a language definition. + For example "C++", "Pascal", "FORTRAN", etc.blank
    lang.opt1stringSpecifies the parameters to give the optimizer when + -O1 is specified on the llvmc command line.-simplifycfg -instcombine -mem2reg
    lang.opt2stringSpecifies the parameters to give the optimizer when + -O2 is specified on the llvmc command line.TBD
    lang.opt3stringSpecifies the parameters to give the optimizer when + -O3 is specified on the llvmc command line.TBD
    lang.opt4stringSpecifies the parameters to give the optimizer when + -O4 is specified on the llvmc command line.TBD
    lang.opt5stringSpecifies the parameters to give the optimizer when + -O5 is specified on the llvmc command line.TBD

    PREPROCESSOR ITEMS

    preprocessor.commandcommandThis provides the command prototype that will be used + to run the preprocessor. This is generally only used with the + -E option.<blank>
    preprocessor.requiredbooleanThis item specifies whether the pre-processing phase + is required by the language. If the value is true, then the + preprocessor.command value must not be blank. With this option, + llvmc will always run the preprocessor as it assumes that the + translation and optimization phases don't know how to pre-process their + input.false

    TRANSLATOR ITEMS

    translator.commandcommandThis provides the command prototype that will be used + to run the translator. Valid substitutions are %in% for the + input file and %out% for the output file.<blank>
    translator.outputbitcode or assemblyThis item specifies the kind of output the language's + translator generates.bitcode
    translator.preprocessesbooleanIndicates that the translator also preprocesses. If + this is true, then llvmc will skip the pre-processing phase + whenever the final phase is not pre-processing.false

    OPTIMIZER ITEMS

    optimizer.commandcommandThis provides the command prototype that will be used + to run the optimizer. Valid substitutions are %in% for the + input file and %out% for the output file.<blank>
    optimizer.outputbitcode or assemblyThis item specifies the kind of output the language's + optimizer generates. Valid values are "assembly" and "bitcode"bitcode
    optimizer.preprocessesbooleanIndicates that the optimizer also preprocesses. If + this is true, then llvmc will skip the pre-processing phase + whenever the final phase is optimization or later.false
    optimizer.translatesbooleanIndicates that the optimizer also translates. If + this is true, then llvmc will skip the translation phase + whenever the final phase is optimization or later.false

    ASSEMBLER ITEMS

    assembler.commandcommandThis provides the command prototype that will be used + to run the assembler. Valid substitutions are %in% for the + input file and %out% for the output file.<blank>
    +
    + + +
    Substitutions
    +
    +

    On any configuration item that ends in command, you must + specify substitution tokens. Substitution tokens begin and end with a percent + sign (%) and are replaced by the corresponding text. Any substitution + token may be given on any command line but some are more useful than + others. In particular each command should have both an %in% + and an %out% substitution. The table below provides definitions of + each of the allowed substitution tokens.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    Substitution TokenReplacement Description
    %args%Replaced with all the tool-specific arguments given + to llvmc via the -T set of options. This just allows + you to place these arguments in the correct place on the command line. + If the %args% option does not appear on your command line, + then you are explicitly disallowing the -T option for your + tool. +
    %force%Replaced with the -f option if it was + specified on the llvmc command line. This is intended to tell + the compiler tool to force the overwrite of output files. +
    %in%Replaced with the full path of the input file. You + needn't worry about the cascading of file names. llvmc will + create temporary files and ensure that the output of one phase is the + input to the next phase.
    %opt%Replaced with the optimization options for the + tool. If the tool understands the -O options then that will + be passed. Otherwise, the lang.optN series of configuration + items will specify which arguments are to be given.
    %out%Replaced with the full path of the output file. + Note that this is not necessarily the output file specified with the + -o option on llvmc's command line. It might be a + temporary file that will be passed to a subsequent phase's input. +
    %stats%If your command accepts the -stats option, + use this substitution token. If the user requested -stats + from the llvmc command line then this token will be replaced + with -stats, otherwise it will be ignored. +
    %target%Replaced with the name of the target "machine" for + which code should be generated. The value used here is taken from the + llvmc option -march. +
    %time%If your command accepts the -time-passes + option, use this substitution token. If the user requested + -time-passes from the llvmc command line then this + token will be replaced with -time-passes, otherwise it will + be ignored. +
    +
    + + +
    Sample Config File
    +
    +

    Since an example is always instructive, here's how the Stacker language + configuration file looks.

    + 
    
+ # Stacker Configuration File For llvmc
+ 
+ ##########################################################
+ # Language definitions
+ ##########################################################
+   lang.name=Stacker 
+   lang.opt1=-simplifycfg -instcombine -mem2reg
+   lang.opt2=-simplifycfg -instcombine -mem2reg -load-vn \
+     -gcse -dse -scalarrepl -sccp 
+   lang.opt3=-simplifycfg -instcombine -mem2reg -load-vn \
+     -gcse -dse -scalarrepl -sccp -branch-combine -adce \
+     -globaldce -inline -licm 
+   lang.opt4=-simplifycfg -instcombine -mem2reg -load-vn \
+     -gcse -dse -scalarrepl -sccp -ipconstprop \
+     -branch-combine -adce -globaldce -inline -licm 
+   lang.opt5=-simplifycfg -instcombine -mem2reg --load-vn \
+     -gcse -dse scalarrepl -sccp -ipconstprop \
+     -branch-combine -adce -globaldce -inline -licm \
+     -block-placement
+ 
+ ##########################################################
+ # Pre-processor definitions
+ ##########################################################
+ 
+   # Stacker doesn't have a preprocessor but the following
+   # allows the -E option to be supported
+   preprocessor.command=cp %in% %out%
+   preprocessor.required=false
+ 
+ ##########################################################
+ # Translator definitions
+ ##########################################################
+ 
+   # To compile stacker source, we just run the stacker
+   # compiler with a default stack size of 2048 entries.
+   translator.command=stkrc -s 2048 %in% -o %out% %time% \
+     %stats% %force% %args%
+ 
+   # stkrc doesn't preprocess but we set this to true so
+   # that we don't run the cp command by default.
+   translator.preprocesses=true
+ 
+   # The translator is required to run.
+   translator.required=true
+ 
+   # stkrc doesn't handle the -On options
+   translator.output=bitcode
+ 
+ ##########################################################
+ # Optimizer definitions
+ ##########################################################
+   
+   # For optimization, we use the LLVM "opt" program
+   optimizer.command=opt %in% -o %out% %opt% %time% %stats% \
+     %force% %args%
+ 
+   optimizer.required = true
+ 
+   # opt doesn't translate
+   optimizer.translates = no
+ 
+   # opt doesn't preprocess
+   optimizer.preprocesses=no
+ 
+   # opt produces bitcode
+   optimizer.output = bc
+ 
+ ##########################################################
+ # Assembler definitions
+ ##########################################################
+   assembler.command=llc %in% -o %out% %target% %time% %stats%
+
    +
    + + +
    Glossary
    + +
    +

    This document uses precise terms in reference to the various artifacts and + concepts related to compilation. The terms used throughout this document are + defined below.

    +
    +
    assembly
    +
    A compilation phase in which LLVM bitcode or + LLVM assembly code is assembled to a native code format (either target + specific aseembly language or the platform's native object file format). +
    + +
    compiler
    +
    Refers to any program that can be invoked by llvmc to accomplish + the work of one or more compilation phases.
    + +
    driver
    +
    Refers to llvmc itself.
    + +
    linking
    +
    A compilation phase in which LLVM bitcode files + and (optionally) native system libraries are combined to form a complete + executable program.
    + +
    optimization
    +
    A compilation phase in which LLVM bitcode is + optimized.
    + +
    phase
    +
    Refers to any one of the five compilation phases that that + llvmc supports. The five phases are: + preprocessing, + translation, + optimization, + assembly, + linking.
    + +
    source language
    +
    Any common programming language (e.g. C, C++, Java, Stacker, ML, + FORTRAN). These languages are distinguished from any of the lower level + languages (such as LLVM or native assembly), by the fact that a + translation phase + is required before LLVM can be applied.
    + +
    tool
    +
    Refers to any program in the LLVM tool set.
    + +
    translation
    +
    A compilation phase in which + source language code is translated into + either LLVM assembly language or LLVM bitcode.
    +
    +
    + +
    +
    Valid CSS!Valid HTML 4.01!Reid Spencer
    + The LLVM Compiler Infrastructure
    + Last modified: $Date: 2008/02/12 06:05:03 $ +
    + + + Index: llvm-www/releases/2.2/docs/CompilerWriterInfo.html diff -c /dev/null llvm-www/releases/2.2/docs/CompilerWriterInfo.html:1.1 *** /dev/null Tue Feb 12 00:07:01 2008 --- llvm-www/releases/2.2/docs/CompilerWriterInfo.html Tue Feb 12 00:05:03 2008 *************** *** 0 **** --- 1,261 ---- + + + + + Architecture/platform information for compiler writers + + + +
    + Architecture/platform information for compiler writers +
    + +
    +

    Note: This document is a work-in-progress. Additions and clarifications + are welcome.

    +
    + +
      +
    1. Hardware +
        +
      1. Alpha
        2. +
      2. ARM
        3. +
      3. Itanium
        4. +
      4. MIPS
        5. +
      5. PowerPC
        6. +
      6. SPARC
        7. +
      7. X86
        8. +
      8. Other lists
        9. +
      2. +
    2. Application Binary Interface (ABI) +
        +
      1. Linux
        2. +
      2. OS X
        3. +
      3. +
    3. Miscellaneous resources
      4. +
    + +
    +

    Compiled by Misha Brukman

    +
    + + +
    Hardware
    + + + +
    Alpha
    + +
    + +
    + + +
    ARM
    + +
    + +
    + + +
    Itanium (ia64)
    + +
    + +
    + + +
    MIPS
    + +
    + +
    + + +
    PowerPC
    + + +
    IBM - Official manuals and docs
    + +
    + + + +
    + + +
    Other documents, collections, notes
    + +
    + + + +
    + + +
    SPARC
    + +
    + + + +
    + + +
    X86
    + + +
    AMD - Official manuals and docs
    + +
    + +
    + + +
    Intel - Official manuals and docs
    + +
    + +
    + + +
    Other x86-specific information
    + +
    + +
    + + +
    Other relevant lists
    + +
    + + + +
    + + +
    ABI
    + + + +
    Linux
    + +
    +
      +
    1. PowerPC 64-bit ELF ABI + Supplement
      2. +
    +
    + + +
    OS X
    + +
    +
      +
    1. Mach-O + Runtime Architecture
      2. +
    2. Notes on Mach-O + ABI
      3. +
    + +
    + + +
    Miscellaneous resources
    + + + + + + +
    +
    + Valid CSS! + Valid HTML 4.01! + + Misha Brukman
    + LLVM Compiler Infrastructure
    + Last modified: $Date: 2008/02/12 06:05:03 $ +
    + + + Index: llvm-www/releases/2.2/docs/DeveloperPolicy.html diff -c /dev/null llvm-www/releases/2.2/docs/DeveloperPolicy.html:1.1 *** /dev/null Tue Feb 12 00:07:02 2008 --- llvm-www/releases/2.2/docs/DeveloperPolicy.html Tue Feb 12 00:05:03 2008 *************** *** 0 **** --- 1,555 ---- + + + + LLVM Developer Policy + + + + +
    LLVM Developer Policy
    +
      +
    1. Introduction
      2. +
    2. Developer Policies +
        +
      1. Stay Informed
        2. +
      2. Making a Patch
        3. +
      3. Code Reviews
        4. +
      4. Code Owners
        5. +
      5. Test Cases
        6. +
      6. Quality
        7. +
      7. Obtaining Commit Access
        8. +
      8. Making a Major Change
        9. +
      9. Incremental Development
        10. +
      10. Attribution of Changes
        11. +
      3. +
    3. Copyright, License, and Patents +
        +
      1. Copyright
        2. +
      2. License
        3. +
      3. Patents
        4. +
      4. Developer Agreements
        5. +
      4. +
    +
    Written by the LLVM Oversight Team
    + + +
    Introduction
    + +
    +

    This document contains the LLVM Developer Policy which defines the + project's policy towards developers and their contributions. The intent of + this policy is to eliminate mis-communication, rework, and confusion that + might arise from the distributed nature of LLVM's development. By stating + the policy in clear terms, we hope each developer can know ahead of time + what to expect when making LLVM contributions.

    +

    This policy is also designed to accomplish the following objectives:

    +
      +
    1. Attract both users and developers to the LLVM project.
      2. +
    2. Make life as simple and easy for contributors as possible.
      3. +
    3. Keep the top of Subversion trees as stable as possible.
      4. +
    + +

    This policy is aimed at frequent contributors to LLVM. People interested in + contributing one-off patches can do so in an informal way by sending them to + the + llvm-commits mailing list and engaging another developer to see it through + the process.

    + +
    + + +
    Developer Policies
    + +
    +

    This section contains policies that pertain to frequent LLVM + developers. We always welcome one-off patches from + people who do not routinely contribute to LLVM, but we expect more from + frequent contributors to keep the system as efficient as possible for + everyone. + Frequent LLVM contributors are expected to meet the following requirements in + order for LLVM to maintain a high standard of quality.

    +

    + + +
    Stay Informed
    +
    +

    Developers should stay informed by reading at least the + llvmdev + email list. If you are doing anything more than just casual work on LLVM, + it is suggested that you also subscribe to the + llvm-commits + list and pay attention to changes being made by others.

    +

    We recommend that active developers register an email account with + LLVM Bugzilla and preferably subscribe to + the llvm-bugs + email list to keep track of bugs and enhancements occurring in LLVM.

    +
    + + +
    Making a Patch
    + +
    + +

    When making a patch for review, the goal is to make it as easy for the + reviewer to read it as possible. As such, we recommend that you:

    +
      +
    1. Make your patch against the Subversion trunk, not a branch, and not an + old version of LLVM. This makes it easy to apply the patch.
      2. + +
    2. Similarly, patches should be submitted soon after they are generated. + Old patches may not apply correctly if the underlying code changes between + the time the patch was created and the time it is applied.
      3. + +
    3. Patches should be made with this command: + 
      svn diff -x -u
      + or with the utility utils/mkpatch, which makes it easy to read the + diff.
      4. + +
    4. Patches should not include differences in generated code such as the + code generated by flex, bison or tblgen. The + utils/mkpatch utility takes care of this for you.
      5. + +
    + +

    When sending a patch to a mailing list, it is a good idea to send it as an + attachment to the message, not embedded into the text of the + message. This ensures that your mailer will not mangle the patch when it + sends it (e.g. by making whitespace changes or by wrapping lines).

    +
    + + +
    Code Reviews
    +
    +

    LLVM has a code review policy. Code review is one way to increase the + quality of software. We generally follow these policies:

    +
      +
    1. All developers are required to have significant changes reviewed + before they are committed to the repository.
      2. +
    2. Code reviews are conducted by email, usually on the llvm-commits + list.
      3. +
    3. Code can be reviewed either before it is committed or after. We expect + major changes to be reviewed before being committed, but smaller + changes (or changes where the developer owns the component) can be + reviewed after commit.
      4. +
    4. The developer responsible for a code change is also responsible for + making all necessary review-related changes.
      5. +
    5. Code review can be an iterative process, which continues until the patch + is ready to be committed.
      6. +
    + +

    Developers should participate in code reviews as both reviewers and + reviewees. If someone is kind enough to review your code, you should + return the favor for someone else. Note that anyone is welcome to review + and give feedback on a patch, but only people with Subversion write access + can approve it.

    + +
    + + +
    Code Owners
    +
    + +

    The LLVM Project relies on two features of its process to maintain rapid + development in addition to the high quality of its source base: the + combination of code review plus post-commit review for trusted maintainers. + Having both is a great way for the project to take advantage of the fact + that most people do the right thing most of the time, and only commit + patches without pre-commit review when they are confident they are + right.

    + +

    The trick to this is that the project has to guarantee that all patches + that are committed are reviewed after they go in: you don't want everyone + to assume someone else will review it, allowing the patch to go unreviewed. + To solve this problem, we have a notion of an 'owner' for a piece of the + code. The sole responsibility of a code owner is to ensure that a commit + to their area of the code is appropriately reviewed, either by themself or + by someone else. The current code owners are:

    + +
      +
    1. Anton Korobeynikov: Exception handling, debug information, and + Windows codegen.
      2. +
    2. Duncan Sands: llvm-gcc 4.2.
      3. +
    3. Evan Cheng: Code generator and all targets.
      4. +
    4. Chris Lattner: Everything else.
      5. +
    + +

    Note that code ownership is completely different than reviewers: anyone can + review a piece of code, and we welcome code review from anyone who is + interested. Code owners are the "last line of defense" to guarantee that + all patches that are committed are actually reviewed.

    + +

    Being a code owner is a somewhat unglamorous position, but it is incredibly + important for the ongoing success of the project. Because people get busy, + interests change, and unexpected things happen, code ownership is purely + opt-in, and anyone can choose to resign their "title" at any time. For now, + we do not have an official policy on how one gets elected to be a code + owner. +

    + +
    + + + +
    Test Cases
    +
    +

    Developers are required to create test cases for any bugs fixed and any new + features added. Some tips for getting your testcase approved:

    +
      +
    1. All feature and regression test cases are added to the + llvm/test directory. The appropriate sub-directory should be + selected (see the Testing Guide for + details).
      2. +
    2. Test cases should be written in + LLVM assembly language unless the + feature or regression being tested requires another language (e.g. the + bug being fixed or feature being implemented is in the llvm-gcc C++ + front-end, in which case it must be written in C++).
      3. +
    3. Test cases, especially for regressions, should be reduced as much as + possible, by bugpoint or + manually. It is unacceptable + to place an entire failing program into llvm/test as this creates + a time-to-test burden on all developers. Please keep them short.
      4. +
    + +

    Note that llvm/test is designed for regression and small feature tests + only. More extensive test cases (e.g., entire applications, benchmarks, + etc) should be added to the llvm-test test suite. The llvm-test + suite is for coverage (correctness, performance, etc) testing, not feature + or regression testing.

    +
    + + +
    Quality
    +
    +

    The minimum quality standards that any change must satisfy before being + committed to the main development branch are:

    +
      +
    1. Code must adhere to the + LLVM Coding Standards.
      2. +
    2. Code must compile cleanly (no errors, no warnings) on at least one + platform.
      3. +
    3. Bug fixes and new features should include a + testcase so we know if the fix/feature ever regresses in the + future.
      4. +
    4. Code must pass the dejagnu (llvm/test) test suite.
      5. +
    5. The code must not cause regressions on a reasonable subset of llvm-test, + where "reasonable" depends on the contributor's judgement and the scope + of the change (more invasive changes require more testing). A reasonable + subset is "llvm-test/MultiSource/Benchmarks".
      6. +
    +

    Additionally, the committer is responsible for addressing any problems + found in the future that the change is responsible for. For example:

    +
      +
    • The code should compile cleanly on all supported platforms.
      • +
    • The changes should not cause any correctness regressions in the + llvm-test suite and must not cause any major performance + regressions.
      • +
    • The change set should not cause performance or correctness regressions + for the LLVM tools.
      • +
    • The changes should not cause performance or correctness regressions in + code compiled by LLVM on all applicable targets.
      • +
    • You are expected to address any bugzilla + bugs that result from your change.
      • +
    + +

    We prefer for this to be handled before submission but understand that it + isn't possible to test all of this for every submission. Our nightly + testing + infrastructure normally finds these problems. A good rule of thumb is to + check the nightly testers for regressions the day after your change.

    + +

    Commits that violate these quality standards (e.g. are very broken) may + be reverted. This is necessary when the change blocks other developers from + making progress. The developer is welcome to re-commit the change after + the problem has been fixed.

    +
    + + +
    + Obtaining Commit Access
    +
    + +

    + We grant commit access to contributors with a track record of submitting high + quality patches. If you would like commit access, please send an email to + Chris with the following information:

    + +
      +
    1. The user name you want to commit with, e.g. "sabre".
      2. +
    2. The full name and email address you want message to llvm-commits to come + from, e.g. "Chris Lattner <sabre at nondot.org>".
      3. +
    3. A "password hash" of the password you want to use, e.g. "2ACR96qjUqsyM". + Note that you don't ever tell us what your password is, you just give it + to us in an encrypted form. To get this, run "htpasswd" (a utility that + comes with apache) in crypt mode (often enabled with "-d"), or find a web + page that will do it for you.
      4. +
    + +

    Once you've been granted commit access, you should be able to check out an + LLVM tree with an SVN URL of "https://username at llvm.org/..." instead of the + normal anonymous URL of "http://llvm.org/...". The first time you commit + you'll have to type in your password. Note that you may get a warning from + SVN about an untrusted key, you can ignore this. To verify that your commit + access works, please do a test commit (e.g. change a comment or add a blank + line). Your first commit to a repository may require the autogenerated email + to be approved by a mailing list. This is normal, and will be done when + the mailing list owner has time.

    + +

    If you have recently been granted commit access, these policies apply:

    + +
      +
    1. You are granted commit-after-approval to all parts of LLVM. + To get approval, submit a patch to + + llvm-commits. When approved you may commit it yourself.
      2. +
    2. You are allowed to commit patches without approval which you think are + obvious. This is clearly a subjective decision — we simply expect you + to use good judgement. Examples include: fixing build breakage, reverting + obviously broken patches, documentation/comment changes, any other minor + changes.
      3. +
    3. You are allowed to commit patches without approval to those portions + of LLVM that you have contributed or maintain (i.e., have been assigned + responsibility for), with the proviso that such commits must not break the + build. This is a "trust but verify" policy and commits of this nature are + reviewed after they are committed.
      4. +
    4. Multiple violations of these policies or a single egregious violation + may cause commit access to be revoked.
      5. +
    + +

    In any case, your changes are still subject to code + review (either before or after they are committed, depending on the nature + of the change). You are encouraged to review other peoples' patches as well, + but you aren't required to.

    + +
    + + +
    Making a Major Change
    +
    +

    When a developer begins a major new project with the aim of contributing + it back to LLVM, s/he should inform the community with an email to + the llvmdev + email list, to the extent possible. The reason for this is to: +

      +
    1. keep the community informed about future changes to LLVM,
      2. +
    2. avoid duplication of effort by preventing multiple parties working on + the same thing and not knowing about it, and
      3. +
    3. ensure that any technical issues around the proposed work are + discussed and resolved before any significant work is done.
      4. +
    + +

    The design of LLVM is carefully controlled to ensure that all the pieces + fit together well and are as consistent as possible. If you plan to make a + major change to the way LLVM works or want to add a major new extension, it + is a good idea to get consensus with the development + community before you start working on it.

    + +

    Once the design of the new feature is finalized, the work itself should be + done as a series of incremental changes, not as + a long-term development branch.

    + +
    + + +
    Incremental Development +
    +
    +

    In the LLVM project, we do all significant changes as a series of + incremental patches. We have a strong dislike for huge changes or + long-term development branches. Long-term development branches have a + number of drawbacks:

    + +
      +
    1. Branches must have mainline merged into them periodically. If the branch + development and mainline development occur in the same pieces of code, + resolving merge conflicts can take a lot of time.
      2. +
    2. Other people in the community tend to ignore work on branches.
      3. +
    3. Huge changes (produced when a branch is merged back onto mainline) are + extremely difficult to code review.
      4. +
    4. Branches are not routinely tested by our nightly tester + infrastructure.
      5. +
    5. Changes developed as monolithic large changes often don't work until the + entire set of changes is done. Breaking it down into a set of smaller + changes increases the odds that any of the work will be committed to the + main repository.
      6. +
    + +

    + To address these problems, LLVM uses an incremental development style and we + require contributors to follow this practice when making a large/invasive + change. Some tips:

    + +
      +
    • Large/invasive changes usually have a number of secondary changes that + are required before the big change can be made (e.g. API cleanup, etc). + These sorts of changes can often be done before the major change is done, + independently of that work.
      • +
    • The remaining inter-related work should be decomposed into unrelated + sets of changes if possible. Once this is done, define the first increment + and get consensus on what the end goal of the change is.
      • + +
    • Each change in the set can be stand alone (e.g. to fix a bug), or part + of a planned series of changes that works towards the development goal.
      • + +
    • Each change should be kept as small as possible. This simplifies your + work (into a logical progression), simplifies code review and reduces the + chance that you will get negative feedback on the change. Small increments + also facilitate the maintenance of a high quality code base.
      • + +
    • Often, an independent precursor to a big change is to add a new API and + slowly migrate clients to use the new API. Each change to use the new + API is often "obvious" and can be committed without review. Once the + new API is in place and used, it is much easier to replace the + underlying implementation of the API. This implementation change is + logically separate from the API change.
      • +
    + +

    If you are interested in making a large change, and this scares you, please + make sure to first discuss the change/gather + consensus then ask about the best way to go about making + the change.

    +
    + + +
    Attribution of + Changes
    +
    +

    We believe in correct attribution of contributions to + their contributors. However, we do not want the source code to be littered + with random attributions "this code written by J Random Guy" (this is noisy + and distracting. In practice, the revision control system keeps a perfect + history of who change what, and the CREDITS.txt file describes higher-level + contributions.

    + +

    Overall, please do not add contributor names to the source base.

    +
    + + + + +
    + Copyright, License, and Patents +
    + + +
    +

    This section addresses the issues of copyright, license and patents for + the LLVM project. + Currently, the University of Illinois is the LLVM copyright holder and the + terms of its license to LLVM users and developers is the + University of + Illinois/NCSA Open Source License.

    + +
    +

    NOTE: This section deals with legal matters but does not provide + legal advice. We are not lawyers, please seek legal counsel from an + attorney.

    +
    +
    + + +
    Copyright
    +
    +

    +

    For consistency and ease of management, the project requires the + copyright for all LLVM software to be held by a single copyright holder: + the University of Illinois (UIUC).

    + +

    + Although UIUC may eventually reassign the copyright of the software to another + entity (e.g. a dedicated non-profit "LLVM Organization", or something) + the intent for the project is to always have a single entity hold the + copyrights to LLVM at any given time.

    + +

    We believe that having a single copyright + holder is in the best interests of all developers and users as it greatly + reduces the managerial burden for any kind of administrative or technical + decisions about LLVM. The goal of the LLVM project is to always keep the code + open and licensed under a very liberal license.

    +
    + + +
    License
    +
    +

    We intend to keep LLVM perpetually open source + and to use a liberal open source license. The current license is the + + University of Illinois/NCSA Open Source License, which boils + down to this:

    +
      +
    • You can freely distribute LLVM.
      • +
    • You must retain the copyright notice if you redistribute LLVM.
      • +
    • Binaries derived from LLVM must reproduce the copyright notice.
      • +
    • You can't use our names to promote your LLVM derived products.
      • +
    • There's no warranty on LLVM at all.
      • +
    + +

    We believe this fosters the widest adoption of LLVM because it allows + commercial products to be derived from LLVM with few restrictions and + without a requirement for making any derived works also open source (i.e. + LLVM's license is not a "copyleft" license like the GPL). We suggest that you + read the License + if further clarification is needed.

    + +

    Note that the LLVM Project does distribute llvm-gcc, which is GPL. + This means that anything "linked" into llvm-gcc must itself be compatible + with the GPL, and must be releasable under the terms of the GPL. This implies + that any code linked into llvm-gcc and distributed to others may be subject + to the viral aspects of the GPL (for example, a proprietary code generator + linked into llvm-gcc must be made available under the GPL). This is not a + problem for code already distributed under a more liberal license (like the + UIUC license), and does not affect code generated by llvm-gcc. It may be a + problem if you intend to base commercial development on llvm-gcc without + redistributing your source code.

    + +

    We have no plans to change the license of LLVM. If you have questions + or comments about the license, please contact the LLVM Oversight Group.

    + +
    + + +
    Patents
    +
    + +

    To the best of our knowledge, LLVM does not infringe on any patents (we have + actually removed code from LLVM in the past that was found to infringe). + Having code in LLVM that infringes on patents would violate an important + goal of the project by making it hard or impossible to reuse the code for + arbitrary purposes (including commercial use).

    + +

    When contributing code, we expect contributors to notify us of any potential + for patent-related trouble with their changes. If you own the rights to a + patent and would like to contribute code to LLVM that relies on it, we + require that you sign an agreement that allows any other user of LLVM to + freely use your patent. Please contact the oversight group for more + details.

    +
    + + + +
    Developer Agreements
    +
    +

    With regards to the LLVM copyright and licensing, developers agree to + assign their copyrights to UIUC for any contribution made so that + the entire software base can be managed by a single copyright holder. This + implies that any contributions can be licensed under the license that the + project uses.

    +
    + + +
    +
    + Valid CSS! + Valid HTML 4.01! + Written by the + LLVM Oversight Group
    + The LLVM Compiler Infrastructure
    + Last modified: $Date: 2008/02/12 06:05:03 $ +
    + + Index: llvm-www/releases/2.2/docs/ExceptionHandling.html diff -c /dev/null llvm-www/releases/2.2/docs/ExceptionHandling.html:1.1 *** /dev/null Tue Feb 12 00:07:02 2008 --- llvm-www/releases/2.2/docs/ExceptionHandling.html Tue Feb 12 00:05:03 2008 *************** *** 0 **** --- 1,478 ---- + + + + Exception Handling in LLVM + + + + +
    Exception Handling in LLVM
    + + + + +
    + +
    + +
    +

    Written by Jim Laskey

    +
    + + + +
    Introduction
    + + +
    + +

    This document is the central repository for all information pertaining to + exception handling in LLVM. It describes the format that LLVM exception + handling information takes, which is useful for those interested in creating + front-ends or dealing directly with the information. Further, this document + provides specific examples of what exception handling information is used for + C/C++.

    + +
    + + +
    + Itanium ABI Zero-cost Exception Handling +
    + +
    + +

    Exception handling for most programming languages is designed to recover from + conditions that rarely occur during general use of an application. To that end, + exception handling should not interfere with the main flow of an + application's algorithm by performing checkpointing tasks such as saving + the current pc or register state.

    + +

    The Itanium ABI Exception Handling Specification defines a methodology for + providing outlying data in the form of exception tables without inlining + speculative exception handling code in the flow of an application's main + algorithm. Thus, the specification is said to add "zero-cost" to the normal + execution of an application.

    + +

    A more complete description of the Itanium ABI exception handling runtime + support of can be found at Itanium C++ ABI: + Exception Handling. A description of the exception frame format can be found + at Exception Frames, with details of the Dwarf + specification at Dwarf 3 + Standard. A description for the C++ exception table formats can be found at + Exception Handling + Tables.

    + +
    + + +
    + Overview +
    + +
    + +

    When an exception is thrown in llvm code, the runtime does a best effort to + find a handler suited to process the circumstance.

    + +

    The runtime first attempts to find an exception frame corresponding to + the function where the exception was thrown. If the programming language (ex. + C++) supports exception handling, the exception frame contains a reference to an + exception table describing how to process the exception. If the language (ex. + C) does not support exception handling or if the exception needs to be forwarded + to a prior activation, the exception frame contains information about how to + unwind the current activation and restore the state of the prior activation. + This process is repeated until the exception is handled. If the exception is + not handled and no activations remain, then the application is terminated with + an appropriate error message.

    + +

    Since different programming languages have different behaviors when handling + exceptions, the exception handling ABI provides a mechanism for supplying + personalities. An exception handling personality is defined by way of a + personality function (ex. for C++ __gxx_personality_v0) which + receives the context of the exception, an exception structure containing + the exception object type and value, and a reference to the exception table for + the current function. The personality function for the current compile unit is + specified in a common exception frame.

    + +

    The organization of an exception table is language dependent. For C++, an + exception table is organized as a series of code ranges defining what to do if + an exception occurs in that range. Typically, the information associated with a + range defines which types of exception objects (using C++ type info) that + are handled in that range, and an associated action that should take place. + Actions typically pass control to a landing pad.

    + +

    A landing pad corresponds to the code found in the catch portion of a + try/catch sequence. When execution resumes at a landing pad, it receives the + exception structure and a selector corresponding to the type of exception + thrown. The selector is then used to determine which catch should actually + process the exception.

    + +
    + + +
    + LLVM Code Generation +
    + +
    + +

    At the time of this writing, only C++ exception handling support is available + in LLVM. So the remainder of this document will be somewhat C++-centric.

    + +

    From the C++ developers perspective, exceptions are defined in terms of the + throw and try/catch statements. In this section we will + describe the implementation of llvm exception handling in terms of C++ + examples.

    + +
    + + +
    + Throw +
    + +
    + +

    Languages that support exception handling typically provide a throw + operation to initiate the exception process. Internally, a throw operation + breaks down into two steps. First, a request is made to allocate exception + space for an exception structure. This structure needs to survive beyond the + current activation. This structure will contain the type and value of the + object being thrown. Second, a call is made to the runtime to raise the + exception, passing the exception structure as an argument.

    + +

    In C++, the allocation of the exception structure is done by the + __cxa_allocate_exception runtime function. The exception raising is + handled by __cxa_throw. The type of the exception is represented using + a C++ RTTI type info structure.

    + +
    + + +
    + Try/Catch +
    + +
    + +

    A call within the scope of a try statement can potentially raise an exception. + In those circumstances, the LLVM C++ front-end replaces the call with an + invoke instruction. Unlike a call, the invoke has two potential + continuation points; where to continue when the call succeeds as per normal, and + where to continue if the call raises an exception, either by a throw or the + unwinding of a throw.

    + +

    The term used to define a the place where an invoke continues after an + exception is called a landing pad. LLVM landing pads are conceptually + alternative function entry points where a exception structure reference and a type + info index are passed in as arguments. The landing pad saves the exception + structure reference and then proceeds to select the catch block that corresponds + to the type info of the exception object.

    + +

    Two llvm intrinsic functions are used convey information about the landing + pad to the back end.

    + +

    llvm.eh.exception takes no + arguments and returns the exception structure reference. The backend replaces + this intrinsic with the code that accesses the first argument of a call. The + LLVM C++ front end generates code to save this value in an alloca location for + further use in the landing pad and catch code.

    + +

    llvm.eh.selector takes a minimum of + three arguments. The first argument is the reference to the exception + structure. The second argument is a reference to the personality function to be + used for this try catch sequence. Each of the remaining arguments is either a + reference to the type info for a catch statement, + a filter expression, + or the number zero representing a cleanup. + The exception is tested against the arguments sequentially from first to last. + The result of the llvm.eh.selector is a + positive number if the exception matched a type info, a negative number if it matched + a filter, and zero if it matched a cleanup. If nothing is matched, the behaviour of + the program is undefined. + The LLVM C++ front end generates code to save the selector value in an alloca + location for further use in the landing pad and catch code. + If a type info matched then the selector value is the index of the type info in + the exception table, which can be obtained using the + llvm.eh.typeid.for intrinsic.

    + +

    Once the landing pad has the type info selector, the code branches to the + code for the first catch. The catch then checks the value of the type info + selector against the index of type info for that catch. Since the type info + index is not known until all the type info have been gathered in the backend, + the catch code will call the llvm.eh.typeid.for intrinsic to + determine the index for a given type info. If the catch fails to match the + selector then control is passed on to the next catch. Note: Since the landing + pad will not be used if there is no match in the list of type info on the call + to llvm.eh.selector, then neither the + last catch nor catch all need to perform the the check against the + selector.

    + +

    Finally, the entry and exit of catch code is bracketed with calls to + __cxa_begin_catch and __cxa_end_catch. + __cxa_begin_catch takes a exception structure reference as an argument + and returns the value of the exception object. __cxa_end_catch + takes a exception structure reference as an argument. This function clears the + exception from the exception space. Note: a rethrow from within the catch may + replace this call with a __cxa_rethrow.

    + +
    + + +
    + Cleanups +
    + +
    + +

    To handle destructors and cleanups in try code, control may not run directly + from a landing pad to the first catch. Control may actually flow from the + landing pad to clean up code and then to the first catch. Since the required + clean up for each invoke in a try may be different (ex., intervening + constructor), there may be several landing pads for a given try. If cleanups + need to be run, the number zero should be passed as the last + llvm.eh.selector argument. + However for C++ a null i8* must be passed + instead. +

    + +
    + + +
    + Throw Filters +
    + +
    + +

    C++ allows the specification of which exception types that can be thrown from + a function. To represent this a top level landing pad may exist to filter out + invalid types. To express this in LLVM code the landing pad will call llvm.eh.selector. The arguments are the + length of the filter expression (the number of type infos plus one), followed by + the type infos themselves. + llvm.eh.selector will return a negative + value if the exception does not match any of the type infos. If no match is + found then a call to __cxa_call_unexpected should be made, otherwise + _Unwind_Resume. Each of these functions require a reference to the + exception structure.

    + +
    + + +
    + Restrictions +
    + +
    + +

    The semantics of the invoke instruction require that any exception that + unwinds through an invoke call should result in a branch to the invoke's unwind + label. However such a branch will only happen if the + llvm.eh.selector matches. + Thus in order to ensure correct operation, the front-end must only generate + llvm.eh.selector calls that are + guaranteed to always match whatever exception unwinds through the invoke. + For most languages it is enough to pass zero, indicating the presence of + a cleanup, as the last + llvm.eh.selector argument. + However for C++ this is not sufficient, because the C++ personality function + will terminate the program if it detects that unwinding the exception only + results in matches with cleanups. For C++ a null i8* should + be passed as the last + llvm.eh.selector argument instead. + This is interpreted as a catch-all by the C++ personality function, and will + always match. +

    + +
    + + +
    + Exception Handling Intrinsics +
    + +
    + +

    LLVM uses several intrinsic functions (name prefixed with "llvm.eh") to + provide exception handling information at various points in generated code.

    + +
    + + +
    + llvm.eh.exception +
    + +
    + 
    +   i8* %llvm.eh.exception( )
+
    + +

    This intrinsic indicates that the exception structure is available at this + point in the code. The backend will replace this intrinsic with code to fetch + the first argument of a call. The effect is that the intrinsic result is the + exception structure reference.

    + +
    + + +
    + llvm.eh.selector +
    + +
    + 
    +   i32 %llvm.eh.selector.i32(i8*, i8*, i8*, ...)
+   i64 %llvm.eh.selector.i64(i8*, i8*, i8*, ...)
+
    + +

    This intrinsic indicates that the exception selector is available at this + point in the code. The backend will replace this intrinsic with code to fetch + the second argument of a call. The effect is that the intrinsic result is the + exception selector.

    + +

    llvm.eh.selector takes a minimum of + three arguments. The first argument is the reference to the exception + structure. The second argument is a reference to the personality function to be + used for this try catch sequence. Each of the remaining arguments is either a + reference to the type info for a catch statement, + a filter expression, + or the number zero representing a cleanup. + The exception is tested against the arguments sequentially from first to last. + The result of the llvm.eh.selector is a + positive number if the exception matched a type info, a negative number if it matched + a filter, and zero if it matched a cleanup. If nothing is matched, the behaviour of + the program is undefined. + If a type info matched then the selector value is the index of the type info in + the exception table, which can be obtained using the + llvm.eh.typeid.for intrinsic.

    + +
    + + +
    + llvm.eh.typeid.for +
    + +
    + 
    +   i32 %llvm.eh.typeid.for.i32(i8*)
+   i64 %llvm.eh.typeid.for.i64(i8*)
+
    + +

    This intrinsic returns the type info index in the exception table of the + current function. This value can be used to compare against the result of llvm.eh.selector. The single argument is + a reference to a type info.

    + +
    + + +
    + Asm Table Formats +
    + +
    + +

    There are two tables that are used by the exception handling runtime to + determine which actions should take place when an exception is thrown.

    + +
    + + +
    + Exception Handling Frame +
    + +
    + +

    An exception handling frame eh_frame is very similar to the unwind + frame used by dwarf debug info. The frame contains all the information + necessary to tear down the current frame and restore the state of the prior + frame. There is an exception handling frame for each function in a compile + unit, plus a common exception handling frame that defines information common to + all functions in the unit.

    + +

    Todo - Table details here.

    + +
    + + +
    + Exception Tables +
    + +
    + +

    An exception table contains information about what actions to take when an + exception is thrown in a particular part of a function's code. There is + one exception table per function except leaf routines and functions that have + only calls to non-throwing functions will not need an exception table.

    + +

    Todo - Table details here.

    + +
    + + +
    + ToDo +
    + +
    + +
      + +

    1. Testing/Testing/Testing.

      2. + +
    + +
    + + + +
    +
    + Valid CSS! + Valid HTML 4.01! + + Chris Lattner
    + LLVM Compiler Infrastructure
    + Last modified: $Date: 2008/02/12 06:05:03 $ +
    + + + Index: llvm-www/releases/2.2/docs/ExtendingLLVM.html diff -c /dev/null llvm-www/releases/2.2/docs/ExtendingLLVM.html:1.1 *** /dev/null Tue Feb 12 00:07:03 2008 --- llvm-www/releases/2.2/docs/ExtendingLLVM.html Tue Feb 12 00:05:03 2008 *************** *** 0 **** --- 1,391 ---- + + + + Extending LLVM: Adding instructions, intrinsics, types, etc. + + + + + +
    + Extending LLVM: Adding instructions, intrinsics, types, etc. +
    + +
      +
    1. Introduction and Warning
      2. +
    2. Adding a new intrinsic function
      3. +
    3. Adding a new instruction
      4. +
    4. Adding a new SelectionDAG node
      5. +
    5. Adding a new type +
        +
      1. Adding a new fundamental type
        2. +
      2. Adding a new derived type
        3. +
      6. +
    + +
    +

    Written by Misha Brukman, + Brad Jones, Nate Begeman, + and Chris Lattner

    +
    + + +
    + Introduction and Warning +
    + + +
    + +

    During the course of using LLVM, you may wish to customize it for your + research project or for experimentation. At this point, you may realize that + you need to add something to LLVM, whether it be a new fundamental type, a new + intrinsic function, or a whole new instruction.

    + +

    When you come to this realization, stop and think. Do you really need to + extend LLVM? Is it a new fundamental capability that LLVM does not support at + its current incarnation or can it be synthesized from already pre-existing LLVM + elements? If you are not sure, ask on the LLVM-dev list. The + reason is that extending LLVM will get involved as you need to update all the + different passes that you intend to use with your extension, and there are + many LLVM analyses and transformations, so it may be quite a bit of + work.

    + +

    Adding an intrinsic function is far easier than + adding an instruction, and is transparent to optimization passes. If your added + functionality can be expressed as a + function call, an intrinsic function is the method of choice for LLVM + extension.

    + +

    Before you invest a significant amount of effort into a non-trivial + extension, ask on the list if what you are + looking to do can be done with already-existing infrastructure, or if maybe + someone else is already working on it. You will save yourself a lot of time and + effort by doing so.

    + +
    + + +
    + Adding a new intrinsic function +
    + + +
    + +

    Adding a new intrinsic function to LLVM is much easier than adding a new + instruction. Almost all extensions to LLVM should start as an intrinsic + function and then be turned into an instruction if warranted.

    + +
      +
    1. llvm/docs/LangRef.html: + Document the intrinsic. Decide whether it is code generator specific and + what the restrictions are. Talk to other people about it so that you are + sure it's a good idea.
      2. + +
    2. llvm/include/llvm/Intrinsics*.td: + Add an entry for your intrinsic. Describe its memory access characteristics + for optimization (this controls whether it will be DCE'd, CSE'd, etc). Note + that any intrinsic using the llvm_int_ty type for an argument will + be deemed by tblgen as overloaded and the corresponding suffix + will be required on the intrinsic's name.
      3. + +
    3. llvm/lib/Analysis/ConstantFolding.cpp: If it is possible to + constant fold your intrinsic, add support to it in the + canConstantFoldCallTo and ConstantFoldCall functions.
      4. + +
    4. llvm/test/Regression/*: Add test cases for your test cases to the + test suite
      5. +
    + +

    Once the intrinsic has been added to the system, you must add code generator + support for it. Generally you must do the following steps:

    + +
    +
    Add support to the C backend in lib/Target/CBackend/
    + +
    Depending on the intrinsic, there are a few ways to implement this. For + most intrinsics, it makes sense to add code to lower your intrinsic in + LowerIntrinsicCall in lib/CodeGen/IntrinsicLowering.cpp. + Second, if it makes sense to lower the intrinsic to an expanded sequence of + C code in all cases, just emit the expansion in visitCallInst in + Writer.cpp. If the intrinsic has some way to express it with GCC + (or any other compiler) extensions, it can be conditionally supported based + on the compiler compiling the CBE output (see llvm.prefetch for an + example). Third, if the intrinsic really has no way to be lowered, just + have the code generator emit code that prints an error message and calls + abort if executed.
    + +
    Add support to the .td file for the target(s) of your choice in + lib/Target/*/*.td.
    + +
    This is usually a matter of adding a pattern to the .td file that matches + the intrinsic, though it may obviously require adding the instructions you + want to generate as well. There are lots of examples in the PowerPC and X86 + backend to follow.
    +
    + +
    + + +
    + Adding a new SelectionDAG node +
    + + +
    + +

    As with intrinsics, adding a new SelectionDAG node to LLVM is much easier + than adding a new instruction. New nodes are often added to help represent + instructions common to many targets. These nodes often map to an LLVM + instruction (add, sub) or intrinsic (byteswap, population count). In other + cases, new nodes have been added to allow many targets to perform a common task + (converting between floating point and integer representation) or capture more + complicated behavior in a single node (rotate).

    + +
      +
    1. include/llvm/CodeGen/SelectionDAGNodes.h: + Add an enum value for the new SelectionDAG node.
      2. +
    2. lib/CodeGen/SelectionDAG/SelectionDAG.cpp: + Add code to print the node to getOperationName. If your new node + can be evaluated at compile time when given constant arguments (such as an + add of a constant with another constant), find the getNode method + that takes the appropriate number of arguments, and add a case for your node + to the switch statement that performs constant folding for nodes that take + the same number of arguments as your new node.
      3. +
    3. lib/CodeGen/SelectionDAG/LegalizeDAG.cpp: + Add code to legalize, + promote, and expand the node as necessary. At a minimum, you will need + to add a case statement for your node in LegalizeOp which calls + LegalizeOp on the node's operands, and returns a new node if any of the + operands changed as a result of being legalized. It is likely that not all + targets supported by the SelectionDAG framework will natively support the + new node. In this case, you must also add code in your node's case + statement in LegalizeOp to Expand your node into simpler, legal + operations. The case for ISD::UREM for expanding a remainder into + a divide, multiply, and a subtract is a good example.
      4. +
    4. lib/CodeGen/SelectionDAG/LegalizeDAG.cpp: + If targets may support the new node being added only at certain sizes, you + will also need to add code to your node's case statement in + LegalizeOp to Promote your node's operands to a larger size, and + perform the correct operation. You will also need to add code to + PromoteOp to do this as well. For a good example, see + ISD::BSWAP, + which promotes its operand to a wider size, performs the byteswap, and then + shifts the correct bytes right to emulate the narrower byteswap in the + wider type.
      5. +
    5. lib/CodeGen/SelectionDAG/LegalizeDAG.cpp: + Add a case for your node in ExpandOp to teach the legalizer how to + perform the action represented by the new node on a value that has been + split into high and low halves. This case will be used to support your + node with a 64 bit operand on a 32 bit target.
      6. +
    6. lib/CodeGen/SelectionDAG/DAGCombiner.cpp: + If your node can be combined with itself, or other existing nodes in a + peephole-like fashion, add a visit function for it, and call that function + from . There are several good examples for simple combines you + can do; visitFABS and visitSRL are good starting places. +
      7. +
    7. lib/Target/PowerPC/PPCISelLowering.cpp: + Each target has an implementation of the TargetLowering class, + usually in its own file (although some targets include it in the same + file as the DAGToDAGISel). The default behavior for a target is to + assume that your new node is legal for all types that are legal for + that target. If this target does not natively support your node, then + tell the target to either Promote it (if it is supported at a larger + type) or Expand it. This will cause the code you wrote in + LegalizeOp above to decompose your new node into other legal + nodes for this target.
      8. +
    8. lib/Target/TargetSelectionDAG.td: + Most current targets supported by LLVM generate code using the DAGToDAG + method, where SelectionDAG nodes are pattern matched to target-specific + nodes, which represent individual instructions. In order for the targets + to match an instruction to your new node, you must add a def for that node + to the list in this file, with the appropriate type constraints. Look at + add, bswap, and fadd for examples.
      9. +
    9. lib/Target/PowerPC/PPCInstrInfo.td: + Each target has a tablegen file that describes the target's instruction + set. For targets that use the DAGToDAG instruction selection framework, + add a pattern for your new node that uses one or more target nodes. + Documentation for this is a bit sparse right now, but there are several + decent examples. See the patterns for rotl in + PPCInstrInfo.td.
      10. +
    10. TODO: document complex patterns.
      11. +
    11. llvm/test/Regression/CodeGen/*: Add test cases for your new node + to the test suite. llvm/test/Regression/CodeGen/X86/bswap.ll is + a good example.
      12. +
    + +
    + + +
    + Adding a new instruction +
    + + +
    + +

    WARNING: adding instructions changes the bitcode + format, and it will take some effort to maintain compatibility with + the previous version. Only add an instruction if it is absolutely + necessary.

    + +
      + +
    1. llvm/include/llvm/Instruction.def: + add a number for your instruction and an enum name
      2. + +
    2. llvm/include/llvm/Instructions.h: + add a definition for the class that will represent your instruction
      3. + +
    3. llvm/include/llvm/Support/InstVisitor.h: + add a prototype for a visitor to your new instruction type
      4. + +
    4. llvm/lib/AsmParser/Lexer.l: + add a new token to parse your instruction from assembly text file
      5. + +
    5. llvm/lib/AsmParser/llvmAsmParser.y: + add the grammar on how your instruction can be read and what it will + construct as a result
      6. + +
    6. llvm/lib/Bitcode/Reader/Reader.cpp: + add a case for your instruction and how it will be parsed from bitcode
      7. + +
    7. llvm/lib/VMCore/Instruction.cpp: + add a case for how your instruction will be printed out to assembly
      8. + +
    8. llvm/lib/VMCore/Instructions.cpp: + implement the class you defined in + llvm/include/llvm/Instructions.h
      9. + +
    9. Test your instruction
      10. + +
    10. llvm/lib/Target/*: + Add support for your instruction to code generators, or add a lowering + pass.
      11. + +
    11. llvm/test/Regression/*: add your test cases to the test suite.
      12. + +
    + +

    Also, you need to implement (or modify) any analyses or passes that you want + to understand this new instruction.

    + +
    + + + +
    + Adding a new type +
    + + +
    + +

    WARNING: adding new types changes the bitcode + format, and will break compatibility with currently-existing LLVM + installations. Only add new types if it is absolutely necessary.

    + +
    + + +
    + Adding a fundamental type +
    + +
    + +
      + +
    1. llvm/include/llvm/Type.h: + add enum for the new type; add static Type* for this type
      2. + +
    2. llvm/lib/VMCore/Type.cpp: + add mapping from TypeID => Type*; + initialize the static Type*
      3. + +
    3. llvm/lib/AsmReader/Lexer.l: + add ability to parse in the type from text assembly
      4. + +
    4. llvm/lib/AsmReader/llvmAsmParser.y: + add a token for that type
      5. + +
    + +
    + + +
    + Adding a derived type +
    + +
    + +
      +
    1. llvm/include/llvm/Type.h: + add enum for the new type; add a forward declaration of the type + also
      2. + +
    2. llvm/include/llvm/DerivedTypes.h: + add new class to represent new class in the hierarchy; add forward + declaration to the TypeMap value type
      3. + +
    3. llvm/lib/VMCore/Type.cpp: + add support for derived type to: +
      + 
      + std::string getTypeDescription(const Type &Ty,
+   std::vector<const Type*> &TypeStack)
+ bool TypesEqual(const Type *Ty, const Type *Ty2,
+   std::map<const Type*, const Type*> & EqTypes)
+
      +
      + add necessary member functions for type, and factory methods
      4. + +
    4. llvm/lib/AsmReader/Lexer.l: + add ability to parse in the type from text assembly
      5. + +
    5. llvm/lib/BitCode/Writer/Writer.cpp: + modify void BitcodeWriter::outputType(const Type *T) to serialize + your type
      6. + +
    6. llvm/lib/BitCode/Reader/Reader.cpp: + modify const Type *BitcodeReader::ParseType() to read your data + type
      7. + +
    7. llvm/lib/VMCore/AsmWriter.cpp: + modify +
      + 
      + void calcTypeName(const Type *Ty,
+                   std::vector<const Type*> &TypeStack,
+                   std::map<const Type*,std::string> &TypeNames,
+                   std::string & Result)
+
      +
      + to output the new derived type +
      8. + + +
    + +
    + + + +
    +
    + Valid CSS! + Valid HTML 4.01! + + The LLVM Compiler Infrastructure +
    + Last modified: $Date: 2008/02/12 06:05:03 $ +
    + + + Index: llvm-www/releases/2.2/docs/FAQ.html diff -c /dev/null llvm-www/releases/2.2/docs/FAQ.html:1.1 *** /dev/null Tue Feb 12 00:07:03 2008 --- llvm-www/releases/2.2/docs/FAQ.html Tue Feb 12 00:05:03 2008 *************** *** 0 **** --- 1,682 ---- + + + + LLVM: Frequently Asked Questions + + + + +
    + LLVM: Frequently Asked Questions +
    + +
      +
    1. License +
        +
      1. Why are the LLVM source code and the front-end distributed under different + licenses?
        2. +
      2. Does the University of Illinois Open Source License really qualify as an + "open source" license?
        3. +
      3. Can I modify LLVM source code and redistribute the modified source?
        4. +
      4. Can I modify LLVM source code and redistribute binaries or other tools + based on it, without redistributing the source?
        5. +
      2. + +
    2. Source code +
        +
      1. In what language is LLVM written?
        2. +
      2. How portable is the LLVM source code?
        3. +
      3. + +
    3. Build Problems +
        +
      1. When I run configure, it finds the wrong C compiler.
        2. +
      2. The configure script finds the right C compiler, but it uses the + LLVM linker from a previous build. What do I do?
        3. +
      3. When creating a dynamic library, I get a strange GLIBC error.
        4. +
      4. I've updated my source tree from Subversion, and now my build is trying + to use a file/directory that doesn't exist.
        5. +
      5. I've modified a Makefile in my source tree, but my build tree keeps using + the old version. What do I do?
        6. +
      6. I've upgraded to a new version of LLVM, and I get strange build + errors.
        7. +
      7. I've built LLVM and am testing it, but the tests freeze.
        8. +
      8. Why do test results differ when I perform different types of builds?
        9. +
      9. Compiling LLVM with GCC 3.3.2 fails, what should I do?
        10. +
      10. When I use the test suite, all of the C Backend tests fail. What is + wrong?
        11. +
      11. After Subversion update, rebuilding gives the error "No rule to make + target".
        12. +
      12. The llvmc program gives me errors/doesn't + work.
        13. +
      4. + +
    4. Source Languages +
        +
      1. What source languages are supported?
        2. +
      2. What support is there for higher level source + language constructs for building a compiler?
        3. +
      3. I don't understand the GetElementPtr + instruction. Help!
        4. +
      + +
    5. Using the GCC Front End +
        +
      1. + When I compile software that uses a configure script, the configure script + thinks my system has all of the header files and libraries it is testing + for. How do I get configure to work correctly? +
        2. + +
      2. + When I compile code using the LLVM GCC front end, it complains that it + cannot find libcrtend.a. +
        3. + +
      3. + How can I disable all optimizations when compiling code using the LLVM GCC front end? +
        4. + +
      4. Can I use LLVM to convert C++ code to C code?
        5. + +
      +
      6. + +
    6. Questions about code generated by the GCC front-end +
        +
      1. What is this llvm.global_ctors and + _GLOBAL__I__tmp_webcompile... stuff that happens when I + #include <iostream>?
        2. +
      2. Where did all of my code go??
        3. +
      3. What is this "undef" thing that shows up in my code?
        4. +
      +
      7. +
    + +
    +

    Written by The LLVM Team

    +
    + + + +
    + License +
    + + +
    +

    Why are the LLVM source code and the front-end distributed under different + licenses?

    +
    + +
    +

    The C/C++ front-ends are based on GCC and must be distributed under the GPL. + Our aim is to distribute LLVM source code under a much less restrictive + license, in particular one that does not compel users who distribute tools based + on modifying the source to redistribute the modified source code as well.

    +
    + +
    +

    Does the University of Illinois Open Source License really qualify as an + "open source" license?

    +
    + +
    +

    Yes, the license is certified by the Open + Source Initiative (OSI).

    +
    + +
    +

    Can I modify LLVM source code and redistribute the modified source?

    +
    + +
    +

    Yes. The modified source distribution must retain the copyright notice and + follow the three bulletted conditions listed in the LLVM license.

    +
    + +
    +

    Can I modify LLVM source code and redistribute binaries or other tools based + on it, without redistributing the source?

    +
    + +
    +

    Yes, this is why we distribute LLVM under a less restrictive license than + GPL, as explained in the first question above.

    +
    + + +
    + Source Code +
    + + +
    +

    In what language is LLVM written?

    +
    + +
    +

    All of the LLVM tools and libraries are written in C++ with extensive use of + the STL.

    +
    + +
    +

    How portable is the LLVM source code?

    +
    + +
    +

    The LLVM source code should be portable to most modern UNIX-like operating + systems. Most of the code is written in standard C++ with operating system + services abstracted to a support library. The tools required to build and test + LLVM have been ported to a plethora of platforms.

    + +

    Some porting problems may exist in the following areas:

    + +
      +
    • The GCC front end code is not as portable as the LLVM suite, so it may not + compile as well on unsupported platforms.
      • + +
    • The LLVM build system relies heavily on UNIX shell tools, like the Bourne + Shell and sed. Porting to systems without these tools (MacOS 9, Plan 9) + will require more effort.
      • +
    + +
    + + +
    + Build Problems +
    + + +
    +

    When I run configure, it finds the wrong C compiler.

    +
    + +
    + +

    The configure script attempts to locate first gcc and then + cc, unless it finds compiler paths set in CC and CXX + for the C and C++ compiler, respectively.

    + +

    If configure finds the wrong compiler, either adjust your + PATH environment variable or set CC and CXX + explicitly.

    + +
    + +
    +

    The configure script finds the right C compiler, but it uses the + LLVM linker from a previous build. What do I do?

    +
    + +
    +

    The configure script uses the PATH to find executables, so + if it's grabbing the wrong linker/assembler/etc, there are two ways to fix + it:

    + +
      +

    1. Adjust your PATH environment variable so that the correct + program appears first in the PATH. This may work, but may not be + convenient when you want them first in your path for other + work.

      2. + +

    2. Run configure with an alternative PATH that is + correct. In a Borne compatible shell, the syntax would be:

      + +
      + 
      + % PATH=[the path without the bad program] ./configure ...
+
      +
      + +

      This is still somewhat inconvenient, but it allows configure + to do its work without having to adjust your PATH + permanently.

      3. +
    + +
    + +
    +

    When creating a dynamic library, I get a strange GLIBC error.

    +
    + +
    +

    Under some operating systems (i.e. Linux), libtool does not work correctly if + GCC was compiled with the --disable-shared option. To work around this, install + your own version of GCC that has shared libraries enabled by default.

    +
    + +
    +

    I've updated my source tree from Subversion, and now my build is trying to + use a file/directory that doesn't exist.

    +
    + +
    +

    You need to re-run configure in your object directory. When new Makefiles + are added to the source tree, they have to be copied over to the object tree in + order to be used by the build.

    +
    + +
    +

    I've modified a Makefile in my source tree, but my build tree keeps using the + old version. What do I do?

    +
    + +
    +

    If the Makefile already exists in your object tree, you + can just run the following command in the top level directory of your object + tree:

    + +
    + 
    % ./config.status <relative path to Makefile>
    +
    + +

    If the Makefile is new, you will have to modify the configure script to copy + it over.

    + +
    + +
    +

    I've upgraded to a new version of LLVM, and I get strange build errors.

    +
    + +
    + +

    Sometimes, changes to the LLVM source code alters how the build system works. + Changes in libtool, autoconf, or header file dependencies are especially prone + to this sort of problem.

    + +

    The best thing to try is to remove the old files and re-build. In most + cases, this takes care of the problem. To do this, just type make + clean and then make in the directory that fails to build.

    + +
    + +
    +

    I've built LLVM and am testing it, but the tests freeze.

    +
    + +
    + +

    This is most likely occurring because you built a profile or release + (optimized) build of LLVM and have not specified the same information on the + gmake command line.

    + +

    For example, if you built LLVM with the command:

    + +
    + 
    % gmake ENABLE_PROFILING=1
    +
    + +

    ...then you must run the tests with the following commands:

    + +
    + 
    + % cd llvm/test
+ % gmake ENABLE_PROFILING=1
+
    +
    + +
    + +
    +

    Why do test results differ when I perform different types of builds?

    +
    + +
    + +

    The LLVM test suite is dependent upon several features of the LLVM tools and + libraries.

    + +

    First, the debugging assertions in code are not enabled in optimized or + profiling builds. Hence, tests that used to fail may pass.

    + +

    Second, some tests may rely upon debugging options or behavior that is only + available in the debug build. These tests will fail in an optimized or profile + build.

    + +
    + +
    +

    Compiling LLVM with GCC 3.3.2 fails, what should I do?

    +
    + +
    +

    This is a bug in GCC, and + affects projects other than LLVM. Try upgrading or downgrading your GCC.

    +
    + +
    +

    After Subversion update, rebuilding gives the error "No rule to make + target".

    +
    + +
    +

    If the error is of the form:

    + +
    + 
    + gmake[2]: *** No rule to make target `/path/to/somefile', needed by
+ `/path/to/another/file.d'.
    
+ Stop.
+
    +
    + +

    This may occur anytime files are moved within the Subversion repository or + removed entirely. In this case, the best solution is to erase all + .d files, which list dependencies for source files, and rebuild:

    + +
    + 
    + % cd $LLVM_OBJ_DIR
+ % rm -f `find . -name \*\.d` 
+ % gmake 
+
    +
    + +

    In other cases, it may be necessary to run make clean before + rebuilding.

    +
    + +

    + The llvmc program gives me errors/doesn't work.

    +
    + +
    +

    llvmc is experimental and isn't really supported. We suggest + using llvm-gcc instead.

    +
    + + +
    Source Languages
    + +

    + What source languages are supported?

    +
    +
    +

    LLVM currently has full support for C and C++ source languages. These are + available through a special version of GCC that LLVM calls the + C Front End

    +

    There is an incomplete version of a Java front end available in the + java module. There is no documentation on this yet so + you'll need to download the code, compile it, and try it.

    +

    In the stacker module is a compiler and runtime + library for the Stacker language, a "toy" language loosely based on Forth.

    +

    The PyPy developers are working on integrating LLVM into the PyPy backend + so that PyPy language can translate to LLVM.

    +
    +

    + What support is there for a higher level source language constructs for + building a compiler?

    +
    +
    +

    Currently, there isn't much. LLVM supports an intermediate representation + which is useful for code representation but will not support the high level + (abstract syntax tree) representation needed by most compilers. There are no + facilities for lexical nor semantic analysis. There is, however, a mostly + implemented configuration-driven + compiler driver which simplifies the task + of running optimizations, linking, and executable generation.

    +
    + +

    + I don't understand the GetElementPtr instruction. Help!

    +
    +
    +

    See The Often Misunderstood GEP + Instruction.

    +
    + + +
    + Using the GCC Front End +
    + +
    +

    + When I compile software that uses a configure script, the configure script + thinks my system has all of the header files and libraries it is testing for. + How do I get configure to work correctly? +

    +
    + +
    +

    + The configure script is getting things wrong because the LLVM linker allows + symbols to be undefined at link time (so that they can be resolved during JIT + or translation to the C back end). That is why configure thinks your system + "has everything." +

    +

    + To work around this, perform the following steps: +

    +
      +
    1. Make sure the CC and CXX environment variables contains the full path to + the LLVM GCC front end.
      2. + +
    2. Make sure that the regular C compiler is first in your PATH.
      3. + +
    3. Add the string "-Wl,-native" to your CFLAGS environment variable.
      4. +
    + +

    + This will allow the llvm-ld linker to create a native code executable + instead of shell script that runs the JIT. Creating native code requires + standard linkage, which in turn will allow the configure script to find out if + code is not linking on your system because the feature isn't available on your + system.

    +
    + +
    +

    + When I compile code using the LLVM GCC front end, it complains that it cannot + find libcrtend.a. +

    +
    + +
    +

    + The only way this can happen is if you haven't installed the runtime library. To + correct this, do:

    + +
    + 
    + % cd llvm/runtime
+ % make clean ; make install-bytecode
+
    +
    +
    + +
    +

    + How can I disable all optimizations when compiling code using the LLVM GCC front end? +

    +
    + +
    +

    + Passing "-Wa,-disable-opt -Wl,-disable-opt" will disable *all* cleanup and + optimizations done at the llvm level, leaving you with the truly horrible + code that you desire. +

    +
    + + +
    +

    + Can I use LLVM to convert C++ code to C code? +

    +
    + +
    +

    Yes, you can use LLVM to convert code from any language LLVM supports to C. + Note that the generated C code will be very low level (all loops are lowered + to gotos, etc) and not very pretty (comments are stripped, original source + formatting is totally lost, variables are renamed, expressions are regrouped), + so this may not be what you're looking for. However, this is a good way to add + C++ support for a processor that does not otherwise have a C++ compiler. +

    + +

    Use commands like this:

    + +
      +

    1. Compile your program as normal with llvm-g++:

      + +
      + 
      + % llvm-g++ x.cpp -o program
+
      +
      + +

      or:

      + +
      + 
      + % llvm-g++ a.cpp -c
+ % llvm-g++ b.cpp -c
+ % llvm-g++ a.o b.o -o program
+
      +
      + +

      With llvm-gcc3, this will generate program and program.bc. The .bc + file is the LLVM version of the program all linked together.

      2. + +

    2. Convert the LLVM code to C code, using the LLC tool with the C + backend:

      + +
      + 
      + % llc -march=c program.bc -o program.c
+
      +
      3. + +

    3. Finally, compile the C file:

      + +
      + 
      + % cc x.c
+
      +
      4. + +
    + +

    Note that, by default, the C backend does not support exception handling. If + you want/need it for a certain program, you can enable it by passing + "-enable-correct-eh-support" to the llc program. The resultant code will use + setjmp/longjmp to implement exception support that is correct but relatively + slow.

    + +

    Also note: this specific sequence of commands won't work if you use a + function defined in the C++ runtime library (or any other C++ library). To + access an external C++ library, you must manually compile libstdc++ to LLVM + bitcode, statically link it into your program, then use the commands above to + convert the whole result into C code. Alternatively, you can compile the + libraries and your application into two different chunks of C code and link + them.

    + +
    + + +
    + Questions about code generated by the GCC front-end +
    + +
    + +

    What is this llvm.global_ctors and + _GLOBAL__I__tmp_webcompile... stuff that happens when I #include + <iostream>?

    +
    + +
    + +

    If you #include the <iostream> header into a C++ translation unit, the + file will probably use the std::cin/std::cout/... global + objects. However, C++ does not guarantee an order of initialization between + static objects in different translation units, so if a static ctor/dtor in your + .cpp file used std::cout, for example, the object would not necessarily + be automatically initialized before your use.

    + +

    To make std::cout and friends work correctly in these scenarios, the + STL that we use declares a static object that gets created in every translation + unit that includes <iostream>. This object has a static + constructor and destructor that initializes and destroys the global iostream + objects before they could possibly be used in the file. The code that you see + in the .ll file corresponds to the constructor and destructor registration code. +

    + +

    If you would like to make it easier to understand the LLVM code + generated by the compiler in the demo page, consider using printf() + instead of iostreams to print values.

    + +
    + + + +

    + + Where did all of my code go?? +

    + +
    +

    + If you are using the LLVM demo page, you may often wonder what happened to all + of the code that you typed in. Remember that the demo script is running the + code through the LLVM optimizers, so if your code doesn't actually do anything + useful, it might all be deleted. +

    + +

    + To prevent this, make sure that the code is actually needed. For example, if + you are computing some expression, return the value from the function instead of + leaving it in a local variable. If you really want to constrain the optimizer, + you can read from and assign to volatile global variables. +

    +
    + + + +

    + +

    What is this "undef" thing that shows up in my code? +

    + +
    +

    + undef is the LLVM way of representing + a value that is not defined. You can get these if you do not initialize a + variable before you use it. For example, the C function:

    + +
    + 
    + int X() { int i; return i; }
+
    +
    + +

    Is compiled to "ret i32 undef" because "i" never has + a value specified for it.

    +
    + + + +
    +
    + Valid CSS! + Valid HTML 4.01! + + LLVM Compiler Infrastructure
    + Last modified: $Date: 2008/02/12 06:05:03 $ +
    + + + Index: llvm-www/releases/2.2/docs/GarbageCollection.html diff -c /dev/null llvm-www/releases/2.2/docs/GarbageCollection.html:1.1 *** /dev/null Tue Feb 12 00:07:03 2008 --- llvm-www/releases/2.2/docs/GarbageCollection.html Tue Feb 12 00:05:03 2008 *************** *** 0 **** --- 1,1419 ---- + + + + + Accurate Garbage Collection with LLVM + + + + + +
    + Accurate Garbage Collection with LLVM +
    + +
      +
    1. Introduction + +
      2. + +
    2. Using the collectors + +
      3. + +
    3. Core support + +
      4. + +
    4. Recommended runtime interface + +
      5. + +
    5. Implementing a collector plugin + +
      6. + +
    6. Implementing a collector runtime + +
      7. + +
    7. References
      8. + +
    + +
    +

    Written by Chris Lattner and + Gordon Henriksen

    +
    + + +
    + Introduction +
    + + +
    + +

    Garbage collection is a widely used technique that frees the programmer from + having to know the lifetimes of heap objects, making software easier to produce + and maintain. Many programming languages rely on garbage collection for + automatic memory management. There are two primary forms of garbage collection: + conservative and accurate.

    + +

    Conservative garbage collection often does not require any special support + from either the language or the compiler: it can handle non-type-safe + programming languages (such as C/C++) and does not require any special + information from the compiler. The + Boehm collector is + an example of a state-of-the-art conservative collector.

    + +

    Accurate garbage collection requires the ability to identify all pointers in + the program at run-time (which requires that the source-language be type-safe in + most cases). Identifying pointers at run-time requires compiler support to + locate all places that hold live pointer variables at run-time, including the + processor stack and registers.

    + +

    Conservative garbage collection is attractive because it does not require any + special compiler support, but it does have problems. In particular, because the + conservative garbage collector cannot know that a particular word in the + machine is a pointer, it cannot move live objects in the heap (preventing the + use of compacting and generational GC algorithms) and it can occasionally suffer + from memory leaks due to integer values that happen to point to objects in the + program. In addition, some aggressive compiler transformations can break + conservative garbage collectors (though these seem rare in practice).

    + +

    Accurate garbage collectors do not suffer from any of these problems, but + they can suffer from degraded scalar optimization of the program. In particular, + because the runtime must be able to identify and update all pointers active in + the program, some optimizations are less effective. In practice, however, the + locality and performance benefits of using aggressive garbage allocation + techniques dominates any low-level losses.

    + +

    This document describes the mechanisms and interfaces provided by LLVM to + support accurate garbage collection.

    + +
    + + +
    + GC features provided and algorithms supported +
    + +
    + +

    LLVM's intermediate representation provides garbage + collection intrinsics which offer support for a broad class of + collector models. For instance, the intrinsics permit:

    + +
      +
    • semi-space collectors
      • +
    • mark-sweep collectors
      • +
    • generational collectors
      • +
    • reference counting
      • +
    • incremental collectors
      • +
    • concurrent collectors
      • +
    • cooperative collectors
      • +
    + +

    We hope that the primitive support built into the LLVM IR is sufficient to + support a broad class of garbage collected languages including Scheme, ML, Java, + C#, Perl, Python, Lua, Ruby, other scripting languages, and more.

    + +

    However, LLVM does not itself implement a garbage collector. This is because + collectors are tightly coupled to object models, and LLVM is agnostic to object + models. Since LLVM is agnostic to object models, it would be inappropriate for + LLVM to dictate any particular collector. Instead, LLVM provides a framework for + garbage collector implementations in two manners:

    + +
      +
    • At compile time with collector plugins for + the compiler. Collector plugins have ready access to important garbage + collector algorithms. Leveraging these tools, it is straightforward to + emit type-accurate stack maps for your runtime in as little as ~100 lines of + C++ code.
      • + +
    • At runtime with suggested runtime + interfaces, which allow front-end compilers to support a range of + collection runtimes.
      • +
    + +
    + + +
    + Using the collectors +
    + + +
    + +

    In general, using a collector implies:

    + +
      +
    • Emitting compatible code, including initialization in the main + program if necessary.
      • +
    • Loading a compiler plugin if the collector is not statically linked with + your compiler. For llc, use the -load option.
      • +
    • Selecting the collection algorithm by applying the gc "..." + attribute to your garbage collected functions, or equivalently with + the setCollector method.
      • +
    • Linking your final executable with the garbage collector runtime.
      • +
    + +

    This table summarizes the available runtimes.

    + + + + + + + + + + + + + + + + + + + + + + + + + + +
    Collectorgc attributeLinkagegcrootgcreadgcwrite
    SemiSpacegc "shadow-stack"TODO FIXMErequiredoptionaloptional
    Ocamlgc "ocaml"provided by ocamloptrequiredoptionaloptional
    + +

    The sections for Collection intrinsics and + Recommended runtime interface detail the interfaces that + collectors may require user programs to utilize.

    + +
    + + +
    + ShadowStack - A highly portable collector +
    + +
    + Collector *llvm::createShadowStackCollector(); +
    + +
    + +

    The ShadowStack backend is invoked with the gc "shadow-stack" + function attribute. + Unlike many collectors which rely on a cooperative code generator to generate + stack maps, this algorithm carefully maintains a linked list of stack root + descriptors [Henderson2002]. This so-called "shadow + stack" mirrors the machine stack. Maintaining this data structure is slower + than using stack maps, but has a significant portability advantage because it + requires no special support from the target code generator.

    + +

    The ShadowStack collector does not use read or write barriers, so the user + program may use load and store instead of llvm.gcread + and llvm.gcwrite.

    + +

    ShadowStack is a code generator plugin only. It must be paired with a + compatible runtime.

    + +
    + + +
    + SemiSpace - A simple copying collector runtime +
    + +
    + +

    The SemiSpace runtime implements with the suggested + runtime interface and is compatible the ShadowStack backend.

    + +

    SemiSpace is a very simple copying collector. When it starts up, it + allocates two blocks of memory for the heap. It uses a simple bump-pointer + allocator to allocate memory from the first block until it runs out of space. + When it runs out of space, it traces through all of the roots of the program, + copying blocks to the other half of the memory space.

    + +

    This runtime is highly experimental and has not been used in a real project. + Enhancements would be welcomed.

    + +
    + + +
    + Ocaml - An Objective Caml-compatible collector +
    + +
    + Collector *llvm::createOcamlCollector(); +
    + +
    + +

    The ocaml backend is invoked with the gc "ocaml" function attribute. + It supports the + Objective Caml language runtime by emitting + a type-accurate stack map in the form of an ocaml 3.10.0-compatible frametable. + The linkage requirements are satisfied automatically by the ocamlopt + compiler when linking an executable.

    + +

    The ocaml collector does not use read or write barriers, so the user program + may use load and store instead of llvm.gcread and + llvm.gcwrite.

    + +
    + + + +
    + Core support +
    + + +
    + +

    This section describes the garbage collection facilities provided by the + LLVM intermediate representation.

    + +

    These facilities are limited to those strictly necessary for compilation. + They are not intended to be a complete interface to any garbage collector. + Notably, heap allocation is not among the supplied primitives. A user program + will also need to interface with the runtime, using either the + suggested runtime interface or another interface + specified by the runtime.

    + +
    + + +
    + Specifying GC code generation: gc "..." +
    + +
    + define ty @name(...) gc "collector" { ... +
    + +
    + +

    The gc function attribute is used to specify the desired collector + algorithm to the compiler. It is equivalent to specify the collector name + programmatically using the setCollector method of + Function.

    + +

    Specifying the collector on a per-function basis allows LLVM to link together + programs which use different garbage collection algorithms.

    + +
    + + +
    + Identifying GC roots on the stack: llvm.gcroot +
    + +
    + void %llvm.gcroot(i8** %ptrloc, i8* %metadata) +
    + +
    + +

    The llvm.gcroot intrinsic is used to inform LLVM of a pointer + variable on the stack. The first argument must be an alloca instruction + or a bitcast of an alloca. The second contains a pointer to metadata that + should be associated with the pointer, and must be a constant or global + value address. If your target collector uses tags, use a null pointer for + metadata.

    + +

    Consider the following fragment of Java code:

    + + 
    +        {
+          Object X;   // A null-initialized reference to an object
+          ...
+        }
+
    + +

    This block (which may be located in the middle of a function or in a loop + nest), could be compiled to this LLVM code:

    + + 
    + Entry:
+    ;; In the entry block for the function, allocate the
+    ;; stack space for X, which is an LLVM pointer.
+    %X = alloca %Object*
+    
+    ;; Tell LLVM that the stack space is a stack root.
+    ;; Java has type-tags on objects, so we pass null as metadata.
+    %tmp = bitcast %Object** %X to i8**
+    call void %llvm.gcroot(%i8** %X, i8* null)
+    ...
+ 
+    ;; "CodeBlock" is the block corresponding to the start
+    ;;  of the scope above.
+ CodeBlock:
+    ;; Java null-initializes pointers.
+    store %Object* null, %Object** %X
+ 
+    ...
+ 
+    ;; As the pointer goes out of scope, store a null value into
+    ;; it, to indicate that the value is no longer live.
+    store %Object* null, %Object** %X
+    ...
+
    + +
    + + +
    + Reading and writing references in the heap +
    + +
    + +

    Some collectors need to be informed when the mutator (the program that needs + garbage collection) either reads a pointer from or writes a pointer to a field + of a heap object. The code fragments inserted at these points are called + read barriers and write barriers, respectively. The amount of + code that needs to be executed is usually quite small and not on the critical + path of any computation, so the overall performance impact of the barrier is + tolerable.

    + +

    Barriers often require access to the object pointer rather than the + derived pointer (which is a pointer to the field within the + object). Accordingly, these intrinsics take both pointers as separate arguments + for completeness. In this snippet, %object is the object pointer, and + %derived is the derived pointer:

    + + 
        ;; An array type.
+     %class.Array = type { %class.Object, i32, [0 x %class.Object*] }
+ ...
+ 
+     ;; Load the object pointer from a gcroot.
+     %object = load %class.Array** %object_addr
+ 
+     ;; Compute the derived pointer.
+     %derived = getelementptr %obj, i32 0, i32 2, i32 %n
    + +
    + + +
    + Write barrier: llvm.gcwrite +
    + +
    + void @llvm.gcwrite(i8* %value, i8* %object, i8** %derived) +
    + +
    + +

    For write barriers, LLVM provides the llvm.gcwrite intrinsic + function. It has exactly the same semantics as a non-volatile store to + the derived pointer (the third argument).

    + +

    Many important algorithms require write barriers, including generational + and concurrent collectors. Additionally, write barriers could be used to + implement reference counting.

    + +

    The use of this intrinsic is optional if the target collector does use + write barriers. If so, the collector will replace it with the corresponding + store.

    + +
    + + +
    + Read barrier: llvm.gcread +
    + +
    + i8* @llvm.gcread(i8* %object, i8** %derived)
    +
    + +
    + +

    For read barriers, LLVM provides the llvm.gcread intrinsic function. + It has exactly the same semantics as a non-volatile load from the + derived pointer (the second argument).

    + +

    Read barriers are needed by fewer algorithms than write barriers, and may + have a greater performance impact since pointer reads are more frequent than + writes.

    + +

    As with llvm.gcwrite, a target collector might not require the use + of this intrinsic.

    + +
    + + +
    + Recommended runtime interface +
    + + +
    + +

    LLVM specifies the following recommended runtime interface to the garbage + collection at runtime. A program should use these interfaces to accomplish the + tasks not supported by the intrinsics.

    + +

    Unlike the intrinsics, which are integral to LLVM's code generator, there is + nothing unique about these interfaces; a front-end compiler and runtime are free + to agree to a different specification.

    + +

    Note: This interface is a work in progress.

    + +
    + + +
    + Garbage collector startup and initialization +
    + +
    + +
    + void llvm_gc_initialize(unsigned InitialHeapSize); +
    + +

    + The llvm_gc_initialize function should be called once before any other + garbage collection functions are called. This gives the garbage collector the + chance to initialize itself and allocate the heap. The initial heap size to + allocate should be specified as an argument. +

    + +
    + + +
    + Allocating memory from the GC +
    + +
    + +
    + void *llvm_gc_allocate(unsigned Size); +
    + +

    The llvm_gc_allocate function is a global function defined by the + garbage collector implementation to allocate memory. It returns a + zeroed-out block of memory of the specified size, sufficiently aligned to store + any object.

    + +
    + + +
    + Explicit invocation of the garbage collector +
    + +
    + +
    + void llvm_gc_collect(); +
    + +

    + The llvm_gc_collect function is exported by the garbage collector + implementations to provide a full collection, even when the heap is not + exhausted. This can be used by end-user code as a hint, and may be ignored by + the garbage collector. +

    + +
    + + +
    + Tracing GC pointers from the program stack +
    + +
    +
    + void llvm_cg_walk_gcroots(void (*FP)(void **Root, void *Meta)); +
    + +

    + The llvm_cg_walk_gcroots function is a function provided by the code + generator that iterates through all of the GC roots on the stack, calling the + specified function pointer with each record. For each GC root, the address of + the pointer and the meta-data (from the llvm.gcroot intrinsic) are provided. +

    +
    + + +
    + Tracing GC pointers from static roots +
    + +
    + TODO +
    + + + +
    + Implementing a collector plugin +
    + + +
    + +

    User code specifies which collector plugin to use with the gc + function attribute or, equivalently, with the setCollector method of + Function.

    + +

    To implement a collector plugin, it is necessary to subclass + llvm::Collector, which can be accomplished in a few lines of + boilerplate code. LLVM's infrastructure provides access to several important + algorithms. For an uncontroversial collector, all that remains may be to emit + the assembly code for the collector's unique stack map data structure, which + might be accomplished in as few as 100 LOC.

    + +

    To subclass llvm::Collector and register a collector:

    + + 
    // lib/MyGC/MyGC.cpp - Example LLVM collector plugin
+ 
+ #include "llvm/CodeGen/Collector.h"
+ #include "llvm/CodeGen/Collectors.h"
+ #include "llvm/CodeGen/CollectorMetadata.h"
+ #include "llvm/Support/Compiler.h"
+ 
+ using namespace llvm;
+ 
+ namespace {
+   class VISIBILITY_HIDDEN MyCollector : public Collector {
+   public:
+     MyCollector() {}
+   };
+   
+   CollectorRegistry::Add<MyCollector>
+   X("mygc", "My bespoke garbage collector.");
+ }
    + +

    Using the LLVM makefiles (like the sample + project), this can be built into a plugin using a simple makefile:

    + + 
    # lib/MyGC/Makefile
+ 
+ LEVEL := ../..
+ LIBRARYNAME = MyGC
+ LOADABLE_MODULE = 1
+ 
+ include $(LEVEL)/Makefile.common
    + +

    Once the plugin is compiled, code using it may be compiled using llc + -load=MyGC.so (though MyGC.so may have some other + platform-specific extension):

    + + 
    $ cat sample.ll
+ define void @f() gc "mygc" {
+ entry:
+         ret void
+ }
+ $ llvm-as < sample.ll | llc -load=MyGC.so
    + +

    It is also possible to statically link the collector plugin into tools, such + as a language-specific compiler front-end.

    + +
    + + +
    + Overview of available features +
    + +
    + +

    The boilerplate collector above does nothing. More specifically:

    + +
      +
    • llvm.gcread calls are replaced with the corresponding + load instruction.
      • +
    • llvm.gcwrite calls are replaced with the corresponding + store instruction.
      • +
    • No stack map is emitted, and no safe points are added.
      • +
    + +

    Collector provides a range of features through which a plugin + collector may do useful work. This matrix summarizes the supported (and planned) + features and correlates them with the collection techniques which typically + require them.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    AlgorithmDoneshadow stackrefcountmark-sweepcopyingincrementalthreadedconcurrent
    stack map✔✘✘✘✘✘
    initialize roots✔✘✘✘✘✘✘✘
    derived pointersNO✘*✘*
    custom lowering✔
    gcroot✔✘✘
    gcwrite✔✘✘✘
    gcread✔✘
    safe points
    in calls✔✘✘✘✘✘
    before calls✔✘✘
    for loopsNO✘✘
    before escape✔✘✘
    emit code at safe pointsNO✘✘
    output
    assembly✔✘✘✘✘✘
    JITNO✘✘✘✘✘
    objNO✘✘✘✘✘
    live analysisNO✘✘✘✘✘
    register mapNO✘✘✘✘✘
    +
    * Derived pointers only pose a + hazard to copying collectors.
    +
    ✘ in gray denotes a feature which + could be utilized if available.
    +
    + +

    To be clear, the collection techniques above are defined as:

    + +
    +
    Shadow Stack
    +
    The mutator carefully maintains a linked list of stack root + descriptors.
    +
    Reference Counting
    +
    The mutator maintains a reference count for each object and frees an + object when its count falls to zero.
    +
    Mark-Sweep
    +
    When the heap is exhausted, the collector marks reachable objects starting + from the roots, then deallocates unreachable objects in a sweep + phase.
    +
    Copying
    +
    As reachability analysis proceeds, the collector copies objects from one + heap area to another, compacting them in the process. Copying collectors + enable highly efficient "bump pointer" allocation and can improve locality + of reference.
    +
    Incremental
    +
    (Including generational collectors.) Incremental collectors generally have + all the properties of a copying collector (regardless of whether the + mature heap is compacting), but bring the added complexity of requiring + write barriers.
    +
    Threaded
    +
    Denotes a multithreaded mutator; the collector must still stop the mutator + ("stop the world") before beginning reachability analysis. Stopping a + multithreaded mutator is a complicated problem. It generally requires + highly platform specific code in the runtime, and the production of + carefully designed machine code at safe points.
    +
    Concurrent
    +
    In this technique, the mutator and the collector run concurrently, with + the goal of eliminating pause times. In a cooperative collector, + the mutator further aids with collection should a pause occur, allowing + collection to take advantage of multiprocessor hosts. The "stop the world" + problem of threaded collectors is generally still present to a limited + extent. Sophisticated marking algorithms are necessary. Read barriers may + be necessary.
    +
    + +

    As the matrix indicates, LLVM's garbage collection infrastructure is already + suitable for a wide variety of collectors, but does not currently extend to + multithreaded programs. This will be added in the future as there is + interest.

    + +
    + + +
    + Computing stack maps +
    + +
    + + 
    for (iterator I = begin(), E = end(); I != E; ++I) {
+   CollectorMetadata *MD = *I;
+   unsigned FrameSize = MD->getFrameSize();
+   size_t RootCount = MD->roots_size();
+ 
+   for (CollectorMetadata::roots_iterator RI = MD->roots_begin(),
+                                          RE = MD->roots_end();
+                                          RI != RE; ++RI) {
+     int RootNum = RI->Num;
+     int RootStackOffset = RI->StackOffset;
+     Constant *RootMetadata = RI->Metadata;
+   }
+ }
    + +

    LLVM automatically computes a stack map. All a Collector needs to do + is access it using CollectorMetadata::roots_begin() and + -end(). If the llvm.gcroot intrinsic is eliminated before code + generation by a custom lowering pass, LLVM's stack map will be empty.

    + +
    + + + +
    + Initializing roots to null: InitRoots +
    + +
    + + 
    MyCollector::MyCollector() {
+   InitRoots = true;
+ }
    + +

    When set, LLVM will automatically initialize each root to null upon + entry to the function. This prevents the reachability analysis from finding + uninitialized values in stack roots at runtime, which will almost certainly + cause it to segfault. This initialization occurs before custom lowering, so the + two may be used together.

    + +

    Since LLVM does not yet compute liveness information, this feature should be + used by all collectors which do not custom lower llvm.gcroot, and even + some that do.

    + +
    + + + +
    + Custom lowering of intrinsics: CustomRoots, + CustomReadBarriers, and CustomWriteBarriers +
    + +
    + +

    For collectors with barriers or unusual treatment of stack roots, these + flags allow the collector to perform any required transformation on the LLVM + IR:

    + + 
    class MyCollector : public Collector {
+ public:
+   MyCollector() {
+     CustomRoots = true;
+     CustomReadBarriers = true;
+     CustomWriteBarriers = true;
+   }
+   
+   virtual bool initializeCustomLowering(Module &M);
+   virtual bool performCustomLowering(Function &F);
+ };
    + +

    If any of these flags are set, then LLVM suppresses its default lowering for + the corresponding intrinsics and instead passes them on to a custom lowering + pass specified by the collector.

    + +

    LLVM's default action for each intrinsic is as follows:

    + +
      +
    • llvm.gcroot: Pass through to the code generator to generate a + stack map.
      • +
    • llvm.gcread: Substitute a load instruction.
      • +
    • llvm.gcwrite: Substitute a store instruction.
      • +
    + +

    If CustomReadBarriers or CustomWriteBarriers are specified, + then performCustomLowering must eliminate the + corresponding barriers.

    + +

    performCustomLowering, must comply with the same restrictions as runOnFunction, and + that initializeCustomLowering has the same semantics as doInitialization(Module + &).

    + +

    The following can be used as a template:

    + + 
    #include "llvm/Module.h"
+ #include "llvm/IntrinsicInst.h"
+ 
+ bool MyCollector::initializeCustomLowering(Module &M) {
+   return false;
+ }
+ 
+ bool MyCollector::performCustomLowering(Function &F) {
+   bool MadeChange = false;
+   
+   for (Function::iterator BB = F.begin(), E = F.end(); BB != E; ++BB)
+     for (BasicBlock::iterator II = BB->begin(), E = BB->end(); II != E; )
+       if (IntrinsicInst *CI = dyn_cast<IntrinsicInst>(II++))
+         if (Function *F = CI->getCalledFunction())
+           switch (F->getIntrinsicID()) {
+           case Intrinsic::gcwrite:
+             // Handle llvm.gcwrite.
+             CI->eraseFromParent();
+             MadeChange = true;
+             break;
+           case Intrinsic::gcread:
+             // Handle llvm.gcread.
+             CI->eraseFromParent();
+             MadeChange = true;
+             break;
+           case Intrinsic::gcroot:
+             // Handle llvm.gcroot.
+             CI->eraseFromParent();
+             MadeChange = true;
+             break;
+           }
+   
+   return MadeChange;
+ }
    + +
    + + + +
    + Generating safe points: NeededSafePoints +
    + +
    + +

    LLVM can compute four kinds of safe points:

    + + 
    namespace GC {
+   /// PointKind - The type of a collector-safe point.
+   /// 
+   enum PointKind {
+     Loop,    //< Instr is a loop (backwards branch).
+     Return,  //< Instr is a return instruction.
+     PreCall, //< Instr is a call instruction.
+     PostCall //< Instr is the return address of a call.
+   };
+ }
    + +

    A collector can request any combination of the four by setting the + NeededSafePoints mask:

    + + 
    MyCollector::MyCollector() {
+   NeededSafePoints = 1 << GC::Loop
+                    | 1 << GC::Return
+                    | 1 << GC::PreCall
+                    | 1 << GC::PostCall;
+ }
    + +

    It can then use the following routines to access safe points.

    + + 
    for (iterator I = begin(), E = end(); I != E; ++I) {
+   CollectorMetadata *MD = *I;
+   size_t PointCount = MD->size();
+ 
+   for (CollectorMetadata::iterator PI = MD->begin(),
+                                    PE = MD->end(); PI != PE; ++PI) {
+     GC::PointKind PointKind = PI->Kind;
+     unsigned PointNum = PI->Num;
+   }
+ }
+
    + +

    Almost every collector requires PostCall safe points, since these + correspond to the moments when the function is suspended during a call to a + subroutine.

    + +

    Threaded programs generally require Loop safe points to guarantee + that the application will reach a safe point within a bounded amount of time, + even if it is executing a long-running loop which contains no function + calls.

    + +

    Threaded collectors may also require Return and PreCall + safe points to implement "stop the world" techniques using self-modifying code, + where it is important that the program not exit the function without reaching a + safe point (because only the topmost function has been patched).

    + +
    + + + +
    + Emitting assembly code: + beginAssembly and finishAssembly +
    + +
    + +

    LLVM allows a collector to print arbitrary assembly code before and after + the rest of a module's assembly code. From the latter callback, the collector + can print stack maps built by the code generator.

    + +

    Note that LLVM does not currently have analogous APIs to support code + generation in the JIT, nor using the object writers.

    + + 
    class MyCollector : public Collector {
+ public:
+   virtual void beginAssembly(std::ostream &OS, AsmPrinter &AP,
+                              const TargetAsmInfo &TAI);
+ 
+   virtual void finishAssembly(std::ostream &OS, AsmPrinter &AP,
+                               const TargetAsmInfo &TAI);
+ }
    + +

    The collector should use AsmPrinter and TargetAsmInfo to + print portable assembly code to the std::ostream. The collector itself + contains the stack map for the entire module, and may access the + CollectorMetadata using its own begin() and end() + methods. Here's a realistic example:

    + + 
    #include "llvm/CodeGen/AsmPrinter.h"
+ #include "llvm/Function.h"
+ #include "llvm/Target/TargetMachine.h"
+ #include "llvm/Target/TargetData.h"
+ #include "llvm/Target/TargetAsmInfo.h"
+ 
+ void MyCollector::beginAssembly(std::ostream &OS, AsmPrinter &AP,
+                                 const TargetAsmInfo &TAI) {
+   // Nothing to do.
+ }
+ 
+ void MyCollector::finishAssembly(std::ostream &OS, AsmPrinter &AP,
+                                  const TargetAsmInfo &TAI) {
+   // Set up for emitting addresses.
+   const char *AddressDirective;
+   int AddressAlignLog;
+   if (AP.TM.getTargetData()->getPointerSize() == sizeof(int32_t)) {
+     AddressDirective = TAI.getData32bitsDirective();
+     AddressAlignLog = 2;
+   } else {
+     AddressDirective = TAI.getData64bitsDirective();
+     AddressAlignLog = 3;
+   }
+   
+   // Put this in the data section.
+   AP.SwitchToDataSection(TAI.getDataSection());
+   
+   // For each function...
+   for (iterator FI = begin(), FE = end(); FI != FE; ++FI) {
+     CollectorMetadata &MD = **FI;
+     
+     // Emit this data structure:
+     // 
+     // struct {
+     //   int32_t PointCount;
+     //   struct {
+     //     void *SafePointAddress;
+     //     int32_t LiveCount;
+     //     int32_t LiveOffsets[LiveCount];
+     //   } Points[PointCount];
+     // } __gcmap_<FUNCTIONNAME>;
+     
+     // Align to address width.
+     AP.EmitAlignment(AddressAlignLog);
+     
+     // Emit the symbol by which the stack map can be found.
+     std::string Symbol;
+     Symbol += TAI.getGlobalPrefix();
+     Symbol += "__gcmap_";
+     Symbol += MD.getFunction().getName();
+     if (const char *GlobalDirective = TAI.getGlobalDirective())
+       OS << GlobalDirective << Symbol << "\n";
+     OS << TAI.getGlobalPrefix() << Symbol << ":\n";
+     
+     // Emit PointCount.
+     AP.EmitInt32(MD.size());
+     AP.EOL("safe point count");
+     
+     // And each safe point...
+     for (CollectorMetadata::iterator PI = MD.begin(),
+                                      PE = MD.end(); PI != PE; ++PI) {
+       // Align to address width.
+       AP.EmitAlignment(AddressAlignLog);
+       
+       // Emit the address of the safe point.
+       OS << AddressDirective
+          << TAI.getPrivateGlobalPrefix() << "label" << PI->Num;
+       AP.EOL("safe point address");
+       
+       // Emit the stack frame size.
+       AP.EmitInt32(MD.getFrameSize());
+       AP.EOL("stack frame size");
+       
+       // Emit the number of live roots in the function.
+       AP.EmitInt32(MD.live_size(PI));
+       AP.EOL("live root count");
+       
+       // And for each live root...
+       for (CollectorMetadata::live_iterator LI = MD.live_begin(PI),
+                                             LE = MD.live_end(PI);
+                                             LI != LE; ++LI) {
+         // Print its offset within the stack frame.
+         AP.EmitInt32(LI->StackOffset);
+         AP.EOL("stack offset");
+       }
+     }
+   }
+ }
+
    + +
    + + + +
    + Implementing a collector runtime +
    + + +
    + +

    Implementing a garbage collector for LLVM is fairly straightforward. The + LLVM garbage collectors are provided in a form that makes them easy to link into + the language-specific runtime that a language front-end would use. They require + functionality from the language-specific runtime to get information about where pointers are located in heap objects.

    + +

    The implementation must include the + llvm_gc_allocate and + llvm_gc_collect functions. To do this, it will + probably have to trace through the roots + from the stack and understand the GC descriptors + for heap objects. Luckily, there are some example + implementations available. +

    +
    + + + +
    + Tracing GC pointers from heap objects +
    + +
    +

    + The three most common ways to keep track of where pointers live in heap objects + are (listed in order of space overhead required):

    + +
      +
    1. In languages with polymorphic objects, pointers from an object header are + usually used to identify the GC pointers in the heap object. This is common for + object-oriented languages like Self, Smalltalk, Java, or C#.
      2. + +
    2. If heap objects are not polymorphic, often the "shape" of the heap can be + determined from the roots of the heap or from some other meta-data [Appel89, Goldberg91, Tolmach94]. In this case, the garbage collector can + propagate the information around from meta data stored with the roots. This + often eliminates the need to have a header on objects in the heap. This is + common in the ML family.
      3. + +
    3. If all heap objects have pointers in the same locations, or pointers can be + distinguished just by looking at them (e.g., the low order bit is clear), no + book-keeping is needed at all. This is common for Lisp-like languages.
      4. +
    + +

    The LLVM garbage collectors are capable of supporting all of these styles of + language, including ones that mix various implementations. To do this, it + allows the source-language to associate meta-data with the stack roots, and the heap tracing routines can propagate the + information. In addition, LLVM allows the front-end to extract GC information + in any form from a specific object pointer (this supports situations #1 and #3). +

    + +
    + + + +
    + References +
    + + +
    + +

    [Appel89] Runtime Tags Aren't Necessary. Andrew + W. Appel. Lisp and Symbolic Computation 19(7):703-705, July 1989.

    + +

    [Goldberg91] Tag-free garbage collection for + strongly typed programming languages. Benjamin Goldberg. ACM SIGPLAN + PLDI'91.

    + +

    [Tolmach94] Tag-free garbage collection using + explicit type parameters. Andrew Tolmach. Proceedings of the 1994 ACM + conference on LISP and functional programming.

    + +

    [Henderson2002] + Accurate Garbage Collection in an Uncooperative Environment. + Fergus Henderson. International Symposium on Memory Management 2002.

    + +
    + + + + +
    +
    + Valid CSS! + Valid HTML 4.01! + + Chris Lattner
    + LLVM Compiler Infrastructure
    + Last modified: $Date: 2008/02/12 06:05:03 $ +
    + + + Index: llvm-www/releases/2.2/docs/GetElementPtr.html diff -c /dev/null llvm-www/releases/2.2/docs/GetElementPtr.html:1.1 *** /dev/null Tue Feb 12 00:07:03 2008 --- llvm-www/releases/2.2/docs/GetElementPtr.html Tue Feb 12 00:05:03 2008 *************** *** 0 **** --- 1,370 ---- + + + + + The Often Misunderstood GEP Instruction + + + + + +
    + The Often Misunderstood GEP Instruction +
    + +
      +
    1. Introduction
      2. +
    2. The Questions +
        +
      1. Why is the extra 0 index required?
        2. +
      2. What is dereferenced by GEP?
        3. +
      3. Why can you index through the first pointer but not + subsequent ones?
        4. +
      4. Why don't GEP x,0,0,1 and GEP x,1 alias?
        5. +
      5. Why do GEP x,1,0,0 and GEP x,1 alias?
        6. +
      3. +
    3. Summary
      4. +
    + +
    +

    Written by: Reid Spencer.

    +
    + + + +
    Introduction
    + +
    +

    This document seeks to dispel the mystery and confusion surrounding LLVM's + GetElementPtr (GEP) instruction. Questions about the wiley GEP instruction are + probably the most frequently occuring questions once a developer gets down to + coding with LLVM. Here we lay out the sources of confusion and show that the + GEP instruction is really quite simple. +

    +
    + + +
    The Questions
    + +
    +

    When people are first confronted with the GEP instruction, they tend to + relate it to known concepts from other programming paradigms, most notably C + array indexing and field selection. However, GEP is a little different and + this leads to the following questions; all of which are answered in the + following sections.

    +
      +
    1. What is the first index of the GEP instruction? +
      2. +
    2. Why is the extra 0 index required?
      3. +
    3. What is dereferenced by GEP?
      4. +
    4. Why don't GEP x,0,0,1 and GEP x,1 alias?
      5. +
    5. Why do GEP x,1,0,0 and GEP x,1 alias?
      6. +
    +
    + + +
    + What is the first index of the GEP instruction? +
    +
    +

    Quick answer: The index stepping through the first operand.

    +

    The confusion with the first index usually arises from thinking about + the GetElementPtr instruction as if it was a C index operator. They aren't the + same. For example, when we write, in "C":

    + +
    + 
    + AType *Foo;
+ ...
+ X = &Foo->F;
+
    +
    + +

    it is natural to think that there is only one index, the selection of the + field F. However, in this example, Foo is a pointer. That + pointer must be indexed explicitly in LLVM. C, on the other hand, indexs + through it transparently. To arrive at the same address location as the C + code, you would provide the GEP instruction with two index operands. The + first operand indexes through the pointer; the second operand indexes the + field F of the structure, just as if you wrote:

    + +
    + 
    + X = &Foo[0].F;
+
    +
    + +

    Sometimes this question gets rephrased as:

    +

    Why is it okay to index through the first pointer, but + subsequent pointers won't be dereferenced?

    +

    The answer is simply because memory does not have to be accessed to + perform the computation. The first operand to the GEP instruction must be a + value of a pointer type. The value of the pointer is provided directly to + the GEP instruction as an operand without any need for accessing memory. It + must, therefore be indexed and requires an index operand. Consider this + example:

    + +
    + 
    + struct munger_struct {
+   int f1;
+   int f2;
+ };
+ void munge(struct munger_struct *P) {
+   P[0].f1 = P[1].f1 + P[2].f2;
+ }
+ ...
+ munger_struct Array[3];
+ ...
+ munge(Array);
+
    +
    + +

    In this "C" example, the front end compiler (llvm-gcc) will generate three + GEP instructions for the three indices through "P" in the assignment + statement. The function argument P will be the first operand of each + of these GEP instructions. The second operand indexes through that pointer. + The third operand will be the field offset into the + struct munger_struct type, for either the f1 or + f2 field. So, in LLVM assembly the munge function looks + like:

    + +
    + 
    + void %munge(%struct.munger_struct* %P) {
+ entry:
+   %tmp = getelementptr %struct.munger_struct* %P, i32 1, i32 0
+   %tmp = load i32* %tmp
+   %tmp6 = getelementptr %struct.munger_struct* %P, i32 2, i32 1
+   %tmp7 = load i32* %tmp6
+   %tmp8 = add i32 %tmp7, %tmp
+   %tmp9 = getelementptr %struct.munger_struct* %P, i32 0, i32 0
+   store i32 %tmp8, i32* %tmp9
+   ret void
+ }
+
    +
    + +

    In each case the first operand is the pointer through which the GEP + instruction starts. The same is true whether the first operand is an + argument, allocated memory, or a global variable.

    +

    To make this clear, let's consider a more obtuse example:

    + +
    + 
    + %MyVar = unintialized global i32
+ ...
+ %idx1 = getelementptr i32* %MyVar, i64 0
+ %idx2 = getelementptr i32* %MyVar, i64 1
+ %idx3 = getelementptr i32* %MyVar, i64 2
+
    +
    + +

    These GEP instructions are simply making address computations from the + base address of MyVar. They compute, as follows (using C syntax): +

    + +
    + 
    + idx1 = (char*) &MyVar + 0
+ idx2 = (char*) &MyVar + 4
+ idx3 = (char*) &MyVar + 8
+
    +
    + +

    Since the type i32 is known to be four bytes long, the indices + 0, 1 and 2 translate into memory offsets of 0, 4, and 8, respectively. No + memory is accessed to make these computations because the address of + %MyVar is passed directly to the GEP instructions.

    +

    The obtuse part of this example is in the cases of %idx2 and + %idx3. They result in the computation of addresses that point to + memory past the end of the %MyVar global, which is only one + i32 long, not three i32s long. While this is legal in LLVM, + it is inadvisable because any load or store with the pointer that results + from these GEP instructions would produce undefined results.

    +
    + + +
    + Why is the extra 0 index required? +
    + +
    +

    Quick answer: there are no superfluous indices.

    +

    This question arises most often when the GEP instruction is applied to a + global variable which is always a pointer type. For example, consider + this:

    + +
    + 
    + %MyStruct = uninitialized global { float*, i32 }
+ ...
+ %idx = getelementptr { float*, i32 }* %MyStruct, i64 0, i32 1
+
    +
    + +

    The GEP above yields an i32* by indexing the i32 typed + field of the structure %MyStruct. When people first look at it, they + wonder why the i64 0 index is needed. However, a closer inspection + of how globals and GEPs work reveals the need. Becoming aware of the following + facts will dispell the confusion:

    +
      +
    1. The type of %MyStruct is not { float*, i32 } + but rather { float*, i32 }*. That is, %MyStruct is a + pointer to a structure containing a pointer to a float and an + i32.
      2. +
    2. Point #1 is evidenced by noticing the type of the first operand of + the GEP instruction (%MyStruct) which is + { float*, i32 }*.
      3. +
    3. The first index, i64 0 is required to step over the global + variable %MyStruct. Since the first argument to the GEP + instruction must always be a value of pointer type, the first index + steps through that pointer. A value of 0 means 0 elements offset from that + pointer.
      4. +
    4. The second index, i32 1 selects the second field of the + structure (the i32).
      5. +
    +
    + + +
    + What is dereferenced by GEP? +
    +
    +

    Quick answer: nothing.

    +

    The GetElementPtr instruction dereferences nothing. That is, it doesn't + access memory in any way. That's what the Load and Store instructions are for. + GEP is only involved in the computation of addresses. For example, consider + this:

    + +
    + 
    + %MyVar = uninitialized global { [40 x i32 ]* }
+ ...
+ %idx = getelementptr { [40 x i32]* }* %MyVar, i64 0, i32 0, i64 0, i64 17
+
    +
    + +

    In this example, we have a global variable, %MyVar that is a + pointer to a structure containing a pointer to an array of 40 ints. The + GEP instruction seems to be accessing the 18th integer of the structure's + array of ints. However, this is actually an illegal GEP instruction. It + won't compile. The reason is that the pointer in the structure must + be dereferenced in order to index into the array of 40 ints. Since the + GEP instruction never accesses memory, it is illegal.

    +

    In order to access the 18th integer in the array, you would need to do the + following:

    + +
    + 
    + %idx = getelementptr { [40 x i32]* }* %, i64 0, i32 0
+ %arr = load [40 x i32]** %idx
+ %idx = getelementptr [40 x i32]* %arr, i64 0, i64 17
+
    +
    + +

    In this case, we have to load the pointer in the structure with a load + instruction before we can index into the array. If the example was changed + to:

    + +
    + 
    + %MyVar = uninitialized global { [40 x i32 ] }
+ ...
+ %idx = getelementptr { [40 x i32] }*, i64 0, i32 0, i64 17
+
    +
    + +

    then everything works fine. In this case, the structure does not contain a + pointer and the GEP instruction can index through the global variable, + into the first field of the structure and access the 18th i32 in the + array there.

    +
    + + +
    + Why don't GEP x,0,0,1 and GEP x,1 alias? +
    +
    +

    Quick Answer: They compute different address locations.

    +

    If you look at the first indices in these GEP + instructions you find that they are different (0 and 1), therefore the address + computation diverges with that index. Consider this example:

    + +
    + 
    + %MyVar = global { [10 x i32 ] }
+ %idx1 = getlementptr { [10 x i32 ] }* %MyVar, i64 0, i32 0, i64 1
+ %idx2 = getlementptr { [10 x i32 ] }* %MyVar, i64 1
+
    +
    + +

    In this example, idx1 computes the address of the second integer + in the array that is in the structure in %MyVar, that is MyVar+4. The + type of idx1 is i32*. However, idx2 computes the + address of the next structure after %MyVar. The type of + idx2 is { [10 x i32] }* and its value is equivalent + to MyVar + 40 because it indexes past the ten 4-byte integers + in MyVar. Obviously, in such a situation, the pointers don't + alias.

    +
    + + +
    + Why do GEP x,1,0,0 and GEP x,1 alias? +
    +
    +

    Quick Answer: They compute the same address location.

    +

    These two GEP instructions will compute the same address because indexing + through the 0th element does not change the address. However, it does change + the type. Consider this example:

    + +
    + 
    + %MyVar = global { [10 x i32 ] }
+ %idx1 = getlementptr { [10 x i32 ] }* %MyVar, i64 1, i32 0, i64 0
+ %idx2 = getlementptr { [10 x i32 ] }* %MyVar, i64 1
+
    +
    + +

    In this example, the value of %idx1 is %MyVar+40 and + its type is i32*. The value of %idx2 is also + MyVar+40 but its type is { [10 x i32] }*.

    +
    + + +
    Summary
    + + +
    +

    In summary, here's some things to always remember about the GetElementPtr + instruction:

    +
      +
    1. The GEP instruction never accesses memory, it only provides pointer + computations.
      2. +
    2. The first operand to the GEP instruction is always a pointer and it must + be indexed.
      3. +
    3. There are no superfluous indices for the GEP instruction.
      4. +
    4. Trailing zero indices are superfluous for pointer aliasing, but not for + the types of the pointers.
      5. +
    5. Leading zero indices are not superfluous for pointer aliasing nor the + types of the pointers.
      6. +
    +
    + + + +
    +
    + Valid CSS! + Valid HTML 4.01! + The LLVM Compiler Infrastructure
    + Last modified: $Date: 2008/02/12 06:05:03 $ +
    + + Index: llvm-www/releases/2.2/docs/GettingStarted.html diff -c /dev/null llvm-www/releases/2.2/docs/GettingStarted.html:1.1 *** /dev/null Tue Feb 12 00:07:03 2008 --- llvm-www/releases/2.2/docs/GettingStarted.html Tue Feb 12 00:05:03 2008 *************** *** 0 **** --- 1,1642 ---- + + + + + Getting Started with LLVM System + + + + +
    + Getting Started with the LLVM System +
    + + + +
    +

    Written by: + John Criswell, + Chris Lattner, + Misha Brukman, + Vikram Adve, and + Guochun Shi. +

    +
    + + + +
    + Overview +
    + + +
    + +

    Welcome to LLVM! In order to get started, you first need to know some + basic information.

    + +

    First, LLVM comes in two pieces. The first piece is the LLVM suite. This + contains all of the tools, libraries, and header files needed to use the low + level virtual machine. It contains an assembler, disassembler, bitcode + analyzer and bitcode optimizer. It also contains a test suite that can be + used to test the LLVM tools and the GCC front end.

    + +

    The second piece is the GCC front end. This component provides a version of + GCC that compiles C and C++ code into LLVM bitcode. Currently, the GCC front + end uses the GCC parser to convert code to LLVM. Once + compiled into LLVM bitcode, a program can be manipulated with the LLVM tools + from the LLVM suite.

    + +

    + There is a third, optional piece called llvm-test. It is a suite of programs + with a testing harness that can be used to further test LLVM's functionality + and performance. +

    + +
    + + +
    + Getting Started Quickly (A Summary) +
    + + +
    + +

    Here's the short story for getting up and running quickly with LLVM:

    + +
      +
    1. Read the documentation.
      2. +
    2. Read the documentation.
      3. +
    3. Remember that you were warned twice about reading the documentation.
      4. +
    4. Install the llvm-gcc4.0 (or llvm-gcc4.2) front end if you intend to compile C or C++: +
        +
      1. cd where-you-want-the-C-front-end-to-live
        2. +
      2. gunzip --stdout llvm-gcc.platform.tar.gz | tar -xvf - +
        3. +
        • If the binary extension is ".bz" use bunzip2 instead of gunzip.
          • +
        +
      3. Add llvm-gcc's "bin" directory to your PATH variable.
        4. +
      5. + +
    5. Get the LLVM Source Code +
        +
      • With the distributed files (or use SVN): +
          +
        1. cd where-you-want-llvm-to-live +
        2. gunzip --stdout llvm-version.tar.gz | tar -xvf - +
        • + +
      6. + +
    6. [Optional] Get the Test Suite Source Code +
        +
      • With the distributed files (or use SVN): +
          +
        1. cd where-you-want-llvm-to-live +
        2. cd llvm/projects +
        3. gunzip --stdout llvm-test-version.tar.gz | tar -xvf - +
        • + +
      7. + + +
    7. Configure the LLVM Build Environment +
        +
      1. cd where-you-want-to-build-llvm
        2. +
      2. /path/to/llvm/configure [options]
        + Some common options: + +
          +
        • --prefix=directory +

          Specify for directory the full pathname of where you + want the LLVM tools and libraries to be installed (default + /usr/local).

          • +
        • --with-llvmgccdir=directory +

          Optionally, specify for directory the full pathname of the + C/C++ front end installation to use with this LLVM configuration. If + not specified, the PATH will be searched.

          • +
        • --enable-spec2000=directory +

          Enable the SPEC2000 benchmarks for testing. The SPEC2000 + benchmarks should be available in + directory.

          • +
        +
      8. + +
    8. Build the LLVM Suite: +
        +
      1. gmake -k |& tee gnumake.out +    # this is csh or tcsh syntax
        2. +
      2. If you get an "internal compiler error (ICE)" or test failures, see + below.
        3. +
      + +
    + +

    Consult the Getting Started with LLVM section for + detailed information on configuring and compiling LLVM. See Setting Up Your Environment for tips that simplify + working with the GCC front end and LLVM tools. Go to Program + Layout to learn about the layout of the source code tree.

    + +
    + + +
    + Requirements +
    + + +
    + +

    Before you begin to use the LLVM system, review the requirements given below. + This may save you some trouble by knowing ahead of time what hardware and + software you will need.

    + +
    + + +
    + Hardware +
    + +
    + +

    LLVM is known to work on the following platforms:

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    OSArchCompilers
    Linuxx861GCC
    SolarisV9 (Ultrasparc)GCC
    FreeBSDx861GCC
    MacOS X2PowerPCGCC
    MacOS X2x86GCC
    Cygwin/Win32x861,8GCC 3.4.X, binutils 2.15
    MinGW/Win32x861,6,8GCC 3.4.X, binutils 2.15
    Linuxamd643GCC
    + +

    LLVM has partial support for the following platforms:

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    OSArchCompilers
    Windowsx861Visual Studio .NET4,5
    AIX3,4PowerPCGCC
    Linux3,5PowerPCGCC
    Linux7AlphaGCC
    Linux7Itanium (IA-64)GCC
    HP-UX7Itanium (IA-64)HP aCC
    + +

    Notes:

    + +
    +
      +
    1. Code generation supported for Pentium processors and + up
      2. +
    2. Code generation supported for 32-bit ABI only
      3. +
    3. No native code generation
      4. +
    4. Build is not complete: one or more tools don't link
      5. +
    5. The GCC-based C/C++ frontend does not build
      6. +
    6. The port is done using the MSYS shell. + Download and install + bison (excl. M4.exe) and flex in that order. Build binutils-2.15 from source, + if necessary. Bison & flex can be also grabbed from GNUWin32 sf.net + project.
      7. +
    7. Native code generation exists but is not complete.
      8. +
    8. Binutils up to post-2.17 has bug in bfd/cofflink.c + preventing LLVM from building correctly. Several workarounds have been + introduced into LLVM build system, but the bug can occur anytime in the + future. We highly recommend that you rebuild your current binutils with the + patch from + Binutils bugzilla, if it wasn't already applied.
      9. +
    +
    + +

    Note that you will need about 1-3 GB of space for a full LLVM build in Debug + mode, depending on the system (it is so large because of all the debugging + information and the fact that the libraries are statically linked into multiple + tools). If you do not need many of the tools and you are space-conscious, + you can disable them individually in llvm/tools/Makefile. The Release + build requires considerably less space.

    + +

    The LLVM suite may compile on other platforms, but it is not + guaranteed to do so. If compilation is successful, the LLVM utilities should be + able to assemble, disassemble, analyze, and optimize LLVM bitcode. Code + generation should work as well, although the generated native code may not work + on your platform.

    + +

    The GCC front end is not very portable at the moment. If you want to get it + to work on another platform, you can download a copy of the source and try to compile it on your platform.

    + +
    + + +
    Software
    +
    +

    Compiling LLVM requires that you have several software packages + installed. The table below lists those required packages. The Package column + is the usual name for the software package that LLVM depends on. The Version + column provides "known to work" versions of the package. The Notes column + describes how LLVM uses the package and provides other details.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    PackageVersionNotes
    GNU Make3.79, 3.79.1Makefile/build processor
    GCC3.4.2C/C++ compiler1
    TeXinfo4.5For building the CFE
    Flex2.5.4LEX compiler
    Bison1.28, 1.35, 1.75, 1.875d, 2.0, or 2.1
    (not 1.85 or 1.875)    		YACC compiler
    SVN≥1.3Subversion access to LLVM2
    DejaGnu1.4.2Automated test suite3
    tcl8.3, 8.4Automated test suite3
    expect5.38.0Automated test suite3
    perl≥5.6.0Nightly tester, utilities
    GNU M4 + 1.4Macro processor for configuration4
    GNU Autoconf2.59Configuration script builder4
    GNU Automake1.9.2aclocal macro generator4
    libtool1.5.10Shared library manager4
    + +

    Notes:

    +
    +
      +
    1. Only the C and C++ languages are needed so there's no + need to build the other languages for LLVM's purposes. See + below for specific version info.
      2. +
    2. You only need Subversion if you intend to build from the + latest LLVM sources. If you're working from a release distribution, you + don't need Subversion.
      3. +
    3. Only needed if you want to run the automated test + suite in the llvm/test directory.
      4. +
    4. If you want to make changes to the configure scripts, + you will need GNU autoconf (2.59), and consequently, GNU M4 (version 1.4 + or higher). You will also need automake (1.9.2). We only use aclocal + from that package.
      5. +
    +
    + +

    Additionally, your compilation host is expected to have the usual + plethora of Unix utilities. Specifically:

    +
      +
    • ar - archive library builder
      • +
    • bzip2* - bzip2 command for distribution generation
      • +
    • bunzip2* - bunzip2 command for distribution checking
      • +
    • chmod - change permissions on a file
      • +
    • cat - output concatenation utility
      • +
    • cp - copy files
      • +
    • date - print the current date/time
      • +
    • echo - print to standard output
      • +
    • egrep - extended regular expression search utility
      • +
    • find - find files/dirs in a file system
      • +
    • grep - regular expression search utility
      • +
    • gzip* - gzip command for distribution generation
      • +
    • gunzip* - gunzip command for distribution checking
      • +
    • install - install directories/files
      • +
    • mkdir - create a directory
      • +
    • mv - move (rename) files
      • +
    • ranlib - symbol table builder for archive libraries
      • +
    • rm - remove (delete) files and directories
      • +
    • sed - stream editor for transforming output
      • +
    • sh - Bourne shell for make build scripts
      • +
    • tar - tape archive for distribution generation
      • +
    • test - test things in file system
      • +
    • unzip* - unzip command for distribution checking
      • +
    • zip* - zip command for distribution generation
      • +
    +
    + + +
    + Broken versions of GCC and other tools +
    + +
    + +

    LLVM is very demanding of the host C++ compiler, and as such tends to expose + bugs in the compiler. In particular, several versions of GCC crash when trying + to compile LLVM. We routinely use GCC 3.3.3, 3.4.0, and Apple 4.0.1 + successfully with them (however, see important notes below). Other versions + of GCC will probably work as well. GCC versions listed + here are known to not work. If you are using one of these versions, please try + to upgrade your GCC to something more recent. If you run into a problem with a + version of GCC not listed here, please let + us know. Please use the "gcc -v" command to find out which version + of GCC you are using. +

    + +

    GCC versions prior to 3.0: GCC 2.96.x and before had several + problems in the STL that effectively prevent it from compiling LLVM. +

    + +

    GCC 3.2.2: This version of GCC fails to compile LLVM.

    + +

    GCC 3.3.2: This version of GCC suffered from a serious bug which causes it to crash in + the "convert_from_eh_region_ranges_1" GCC function.

    + +

    Cygwin GCC 3.3.3: The version of GCC 3.3.3 commonly shipped with + Cygwin does not work. Please upgrade + to a newer version if possible.

    +

    SuSE GCC 3.3.3: The version of GCC 3.3.3 shipped with SuSE 9.1 (and + possibly others) does not compile LLVM correctly (it appears that exception + handling is broken in some cases). Please download the FSF 3.3.3 or upgrade + to a newer version of GCC.

    +

    GCC 3.4.0 on linux/x86 (32-bit): GCC miscompiles portions of the + code generator, causing an infinite loop in the llvm-gcc build when built + with optimizations enabled (i.e. a release build).

    +

    GCC 3.4.2 on linux/x86 (32-bit): GCC miscompiles portions of the + code generator at -O3, as with 3.4.0. However gcc 3.4.2 (unlike 3.4.0) + correctly compiles LLVM at -O2. A work around is to build release LLVM + builds with "make ENABLE_OPTIMIZED=1 OPTIMIZE_OPTION=-O2 ..."

    +

    GCC 3.4.x on X86-64/amd64: GCC + miscompiles portions of LLVM.

    +

    GCC 3.4.4 (CodeSourcery ARM 2005q3-2): this compiler miscompiles LLVM + when building with optimizations enabled. It appears to work with + "make ENABLE_OPTIMIZED=1 OPTIMIZE_OPTION=-O1" or build a debug + build.

    +

    IA-64 GCC 4.0.0: The IA-64 version of GCC 4.0.0 is known to + miscompile LLVM.

    +

    Apple Xcode 2.3: GCC crashes when compiling LLVM at -O3 (which is the + default with ENABLE_OPTIMIZED=1. To work around this, build with + "ENABLE_OPTIMIZED=1 OPTIMIZE_OPTION=-O2".

    +

    GCC 4.1.1: GCC fails to build LLVM with template concept check errors + compiling some files. At the time of this writing, GCC mainline (4.2) + did not share the problem.

    +

    GCC 4.1.1 on X86-64/amd64: GCC + miscompiles portions of LLVM when compiling llvm itself into 64-bit + code. LLVM will appear to mostly work but will be buggy, e.g. failing + portions of its testsuite.

    +

    GCC 4.1.2 on OpenSUSE: Seg faults during libstdc++ build and on x86_64 + platforms compiling md5.c gets a mangled constant.

    +

    GNU ld 2.16.X. Some 2.16.X versions of the ld linker will produce very + long warning messages complaining that some ".gnu.linkonce.t.*" symbol was + defined in a discarded section. You can safely ignore these messages as they are + erroneous and the linkage is correct. These messages disappear using ld + 2.17.

    + +

    GNU binutils 2.17: Binutils 2.17 contains a bug which + causes huge link times (minutes instead of seconds) when building LLVM. We + recommend upgrading to a newer version (2.17.50.0.4 or later).

    + +
    + + + + +
    + Getting Started with LLVM +
    + + +
    + +

    The remainder of this guide is meant to get you up and running with + LLVM and to give you some basic information about the LLVM environment.

    + +

    The later sections of this guide describe the general layout of the the LLVM source tree, a simple example using the LLVM tool chain, and links to find more information about LLVM or to get + help via e-mail.

    +
    + + +
    + Terminology and Notation +
    + +
    + +

    Throughout this manual, the following names are used to denote paths + specific to the local system and working environment. These are not + environment variables you need to set but just strings used in the rest + of this document below. In any of the examples below, simply replace + each of these names with the appropriate pathname on your local system. + All these paths are absolute:

    + +
    +
    SRC_ROOT +
    + This is the top level directory of the LLVM source tree. +

    + +
    OBJ_ROOT +
    + This is the top level directory of the LLVM object tree (i.e. the + tree where object files and compiled programs will be placed. It + can be the same as SRC_ROOT). +

    + +
    LLVMGCCDIR +
    + This is where the LLVM GCC Front End is installed. +

    + For the pre-built GCC front end binaries, the LLVMGCCDIR is + llvm-gcc/platform/llvm-gcc. +

    + +
    + + +
    + Setting Up Your Environment +
    + +
    + +

    + In order to compile and use LLVM, you may need to set some environment + variables. + +

    +
    LLVM_LIB_SEARCH_PATH=/path/to/your/bitcode/libs
    +
    [Optional] This environment variable helps LLVM linking tools find the + locations of your bitcode libraries. It is provided only as a + convenience since you can specify the paths using the -L options of the + tools and the C/C++ front-end will automatically use the bitcode files + installed in its + lib directory.
    +
    + +
    + + +
    + Unpacking the LLVM Archives +
    + +
    + +

    + If you have the LLVM distribution, you will need to unpack it before you + can begin to compile it. LLVM is distributed as a set of two files: the LLVM + suite and the LLVM GCC front end compiled for your platform. There is an + additional test suite that is optional. Each file is a TAR archive that is + compressed with the gzip program. +

    + +

    The files are as follows, with x.y marking the version number: +

    +
    llvm-x.y.tar.gz
    +
    Source release for the LLVM libraries and tools.
    + +
    llvm-test-x.y.tar.gz
    +
    Source release for the LLVM test suite.
    + +
    llvm-gcc4-x.y.source.tar.gz
    +
    Source release of the llvm-gcc4 front end. See README.LLVM in the root + directory for build instructions.
    + +
    llvm-gcc4-x.y-platform.tar.gz
    +
    Binary release of the llvm-gcc4 front end for a specific platform.
    + +
    + +

    It is also possible to download the sources of the llvm-gcc4 front end from a + read-only subversion mirror at + svn://anonsvn.opensource.apple.com/svn/llvm/trunk.

    + +
    + + +
    + Checkout LLVM from Subversion +
    + +
    + +

    If you have access to our Subversion repository, you can get a fresh copy of + the entire source code. All you need to do is check it out from Subvresion as + follows:

    + +
      +
    • cd where-you-want-llvm-to-live
      • +
    • Read-Only: svn co http://llvm.org/svn/llvm-project/llvm/trunk llvm
      • +
    • Read-Write:svn co https://user at llvm.org/svn/llvm-project/llvm/trunk + llvm
      • +
    + + +

    This will create an 'llvm' directory in the current + directory and fully populate it with the LLVM source code, Makefiles, + test directories, and local copies of documentation files.

    + +

    If you want to get a specific release (as opposed to the most recent + revision), you can checkout it from the 'tags' directory (instead of + 'trunk'). The following releases are located in the following + subdirectories of the 'tags' directory:

    + +
      +
    • Release 2.2: RELEASE_22
      • +
    • Release 2.1: RELEASE_21
      • +
    • Release 2.0: RELEASE_20
      • +
    • Release 1.9: RELEASE_19
      • +
    • Release 1.8: RELEASE_18
      • +
    • Release 1.7: RELEASE_17
      • +
    • Release 1.6: RELEASE_16
      • +
    • Release 1.5: RELEASE_15
      • +
    • Release 1.4: RELEASE_14
      • +
    • Release 1.3: RELEASE_13
      • +
    • Release 1.2: RELEASE_12
      • +
    • Release 1.1: RELEASE_11
      • +
    • Release 1.0: RELEASE_1
      • +
    + +

    If you would like to get the LLVM test suite (a separate package as of 1.4), + you get it from the Subversion repository:

    + +
    + 
    + % cd llvm/projects
+ % svn co http://llvm.org/svn/llvm-project/test-suite/trunk llvm-test
+
    +
    + +

    By placing it in the llvm/projects, it will be automatically + configured by the LLVM configure script as well as automatically updated when + you run svn update.

    + +

    If you would like to get the GCC front end source code, you can also get it + and build it yourself. Please follow these + instructions to successfully get and build the LLVM GCC front-end.

    + +
    + + +
    + Install the GCC Front End +
    + +
    + +

    Before configuring and compiling the LLVM suite, you can optionally extract the + LLVM GCC front end from the binary distribution. It is used for running the + llvm-test testsuite and for compiling C/C++ programs. Note that you can optionally + build llvm-gcc yourself after building the + main LLVM repository.

    + +

    To install the GCC front end, do the following:

    + +
      +
    1. cd where-you-want-the-front-end-to-live
      2. +
    2. gunzip --stdout llvmgcc-version.platform.tar.gz | tar -xvf + -
      3. +
    + +

    Once the binary is uncompressed, you should add a symlink for llvm-gcc and + llvm-g++ to some directory in your path. When you configure LLVM, it will + automatically detect llvm-gcc's presence (if it is in your path) enabling its + use in llvm-test. Note that you can always build or install llvm-gcc at any + pointer after building the main LLVM repository: just reconfigure llvm and + llvm-test will pick it up. +

    + +

    The binary versions of the GCC front end may not suit all of your needs. For + example, the binary distribution may include an old version of a system header + file, not "fix" a header file that needs to be fixed for GCC, or it may be + linked with libraries not available on your system.

    + +

    In cases like these, you may want to try building the GCC front end from source. This is + much easier now than it was in the past.

    + +
    + + +
    + Local LLVM Configuration +
    + +
    + +

    Once checked out from the Subversion repository, the LLVM suite source + code must be + configured via the configure script. This script sets variables in the + various *.in files, most notably llvm/Makefile.config and + llvm/include/Config/config.h. It also populates OBJ_ROOT with + the Makefiles needed to begin building LLVM.

    + +

    The following environment variables are used by the configure + script to configure the build system:

    + + + + + + + + + + + +
    VariablePurpose
    CCTells configure which C compiler to use. By default, + configure will look for the first GCC C compiler in + PATH. Use this variable to override + configure's default behavior.
    CXXTells configure which C++ compiler to use. By default, + configure will look for the first GCC C++ compiler in + PATH. Use this variable to override + configure's default behavior.
    + +

    The following options can be used to set or enable LLVM specific options:

    + +
    +
    --with-llvmgccdir
    +
    Path to the LLVM C/C++ FrontEnd to be used with this LLVM configuration. + The value of this option should specify the full pathname of the C/C++ Front + End to be used. If this option is not provided, the PATH will be searched for + a program named llvm-gcc and the C/C++ FrontEnd install directory will + be inferred from the path found. If the option is not given, and no llvm-gcc + can be found in the path then a warning will be produced by + configure indicating this situation. LLVM may still be built with + the tools-only target but attempting to build the runtime libraries + will fail as these libraries require llvm-gcc and llvm-g++. See + Install the GCC Front End for details on installing + the C/C++ Front End. See + Bootstrapping the LLVM C/C++ Front-End + for details on building the C/C++ Front End.
    +
    --with-tclinclude
    +
    Path to the tcl include directory under which tclsh can be + found. Use this if you have multiple tcl installations on your machine and you + want to use a specific one (8.x) for LLVM. LLVM only uses tcl for running the + dejagnu based test suite in llvm/test. If you don't specify this + option, the LLVM configure script will search for the tcl 8.4 and 8.3 + releases. +

    +
    +
    --enable-optimized
    +
    + Enables optimized compilation by default (debugging symbols are removed + and GCC optimization flags are enabled). The default is to use an + unoptimized build (also known as a debug build). +

    +
    +
    --enable-debug-runtime
    +
    + Enables debug symbols in the runtime libraries. The default is to strip + debug symbols from the runtime libraries. +
    +
    --enable-jit
    +
    + Compile the Just In Time (JIT) compiler functionality. This is not + available + on all platforms. The default is dependent on platform, so it is best + to explicitly enable it if you want it. +

    +
    +
    --enable-targets=target-option
    +
    Controls which targets will be built and linked into llc. The default + value for target_options is "all" which builds and links all + available targets. The value "host-only" can be specified to build only a + native compiler (no cross-compiler targets available). The "native" target is + selected as the target of the build host. You can also specify a comma + separated list of target names that you want available in llc. The target + names use all lower case. The current set of targets is:
    + alpha, ia64, powerpc, skeleton, sparc, x86. +

    +
    --enable-doxygen
    +
    Look for the doxygen program and enable construction of doxygen based + documentation from the source code. This is disabled by default because + generating the documentation can take a long time and producess 100s of + megabytes of output.
    +
    --with-udis86
    +
    LLVM can use external disassembler library for various purposes (now it's + used only for examining code produced by JIT). This option will enable usage + of udis86 x86 (both 32 and 64 + bits) disassembler library.
    +
    + +

    To configure LLVM, follow these steps:

    + +
      +

    1. Change directory into the object root directory:

      + + 
      % cd OBJ_ROOT
      2. + +

    2. Run the configure script located in the LLVM source + tree:

      + +
      + 
      % SRC_ROOT/configure --prefix=/install/path [other options]
      +
      3. +
    + +
    + + +
    + Compiling the LLVM Suite Source Code +
    + +
    + +

    Once you have configured LLVM, you can build it. There are three types of + builds:

    + +
    +
    Debug Builds +
    + These builds are the default when one types gmake (unless the + --enable-optimized option was used during configuration). The + build system will compile the tools and libraries with debugging + information. +

    + +
    Release (Optimized) Builds +
    + These builds are enabled with the --enable-optimized option to + configure or by specifying ENABLE_OPTIMIZED=1 on the + gmake command line. For these builds, the build system will + compile the tools and libraries with GCC optimizations enabled and strip + debugging information from the libraries and executables it generates. +

    + +
    Profile Builds +
    + These builds are for use with profiling. They compile profiling + information into the code for use with programs like gprof. + Profile builds must be started by specifying ENABLE_PROFILING=1 + on the gmake command line. +
    + +

    Once you have LLVM configured, you can build it by entering the + OBJ_ROOT directory and issuing the following command:

    + + 
    % gmake
    + +

    If the build fails, please check here to see if you + are using a version of GCC that is known not to compile LLVM.

    + +

    + If you have multiple processors in your machine, you may wish to use some of + the parallel build options provided by GNU Make. For example, you could use the + command:

    + + 
    % gmake -j2
    + +

    There are several special targets which are useful when working with the LLVM + source code:

    + +
    +
    gmake clean +
    + Removes all files generated by the build. This includes object files, + generated C/C++ files, libraries, and executables. +

    + +
    gmake dist-clean +
    + Removes everything that gmake clean does, but also removes files + generated by configure. It attempts to return the source tree to the + original state in which it was shipped. +

    + +
    gmake install +
    + Installs LLVM header files, libraries, tools, and documentation in a + hierarchy + under $PREFIX, specified with ./configure --prefix=[dir], which + defaults to /usr/local. +

    + +
    gmake -C runtime install-bytecode +
    + Assuming you built LLVM into $OBJDIR, when this command is run, it will + install bitcode libraries into the GCC front end's bitcode library + directory. If you need to update your bitcode libraries, + this is the target to use once you've built them. +

    +
    + +

    Please see the Makefile Guide for further + details on these make targets and descriptions of other targets + available.

    + +

    It is also possible to override default values from configure by + declaring variables on the command line. The following are some examples:

    + +
    +
    gmake ENABLE_OPTIMIZED=1 +
    + Perform a Release (Optimized) build. +

    + +
    gmake ENABLE_OPTIMIZED=1 DISABLE_ASSERTIONS=1 +
    + Perform a Release (Optimized) build without assertions enabled. +

    + +
    gmake ENABLE_PROFILING=1 +
    + Perform a Profiling build. +

    + +
    gmake VERBOSE=1 +
    + Print what gmake is doing on standard output. +

    + +
    gmake TOOL_VERBOSE=1
    +
    Ask each tool invoked by the makefiles to print out what it is doing on + the standard output. This also implies VERBOSE=1. +

    +
    + +

    Every directory in the LLVM object tree includes a Makefile to build + it and any subdirectories that it contains. Entering any directory inside the + LLVM object tree and typing gmake should rebuild anything in or below + that directory that is out of date.

    + +
    + + +
    + Cross-Compiling LLVM +
    + +
    +

    It is possible to cross-compile LLVM. That is, you can create LLVM + executables and libraries for a platform different than the one one which you + are compiling. To do this, a few additional steps are + required. 1 To cross-compile LLVM, use + these instructions:

    +
      +
    1. Configure and build LLVM as a native compiler. You will need + just TableGen from that build. +
        +
      • If you have $LLVM_OBJ_ROOT=$LLVM_SRC_ROOT just execute + make -C utils/TableGen after configuring.
        • +
      • Otherwise you will need to monitor building process and terminate + it just after TableGen was built.
        • +
      +
      2. +
    2. Copy the TableGen binary to somewhere safe (out of your build tree). +
      3. +
    3. Configure LLVM to build with a cross-compiler. To do this, supply the + configure script with --build and --host options that + are different. The values of these options must be legal target triples + that your GCC compiler supports.
      4. +
    4. Put the saved TableGen executable into the + into $LLVM_OBJ_ROOT/{BUILD_TYPE}/bin directory (e.g. into + .../Release/bin for a Release build).
      5. +
    5. Build LLVM as usual.
      6. +
    +

    The result of such a build will produce executables that are not executable + on your build host (--build option) but can be executed on your compile host + (--host option).

    +

    Notes:

    +
    +
      +
    1. Cross-compiling was tested only with Linux as + build platform and Windows as host using mingw32 cross-compiler. Other + combinations have not been tested.
      2. +
    +
    +
    + + +
    + The Location of LLVM Object Files +
    + +
    + +

    The LLVM build system is capable of sharing a single LLVM source tree among + several LLVM builds. Hence, it is possible to build LLVM for several different + platforms or configurations using the same source tree.

    + +

    This is accomplished in the typical autoconf manner:

    + +
      +

    • Change directory to where the LLVM object files should live:

      + + 
      % cd OBJ_ROOT
      • + +

    • Run the configure script found in the LLVM source + directory:

      + + 
      % SRC_ROOT/configure
      • +
    + +

    The LLVM build will place files underneath OBJ_ROOT in directories + named after the build type:

    + +
    +
    Debug Builds +
    +
    +
    Tools +
    OBJ_ROOT/Debug/bin +
    Libraries +
    OBJ_ROOT/Debug/lib +
    +

    + +
    Release Builds +
    +
    +
    Tools +
    OBJ_ROOT/Release/bin +
    Libraries +
    OBJ_ROOT/Release/lib +
    +

    + +
    Profile Builds +
    +
    +
    Tools +
    OBJ_ROOT/Profile/bin +
    Libraries +
    OBJ_ROOT/Profile/lib +
    +
    + +
    + + +
    + Optional Configuration Items +
    + +
    + +

    + If you're running on a Linux system that supports the "binfmt_misc" + module, and you have root access on the system, you can set your system up to + execute LLVM bitcode files directly. To do this, use commands like this (the + first command may not be required if you are already using the module):

    + +
    + 
    + $ mount -t binfmt_misc none /proc/sys/fs/binfmt_misc
+ $ echo ':llvm:M::llvm::/path/to/lli:' > /proc/sys/fs/binfmt_misc/register
+ $ chmod u+x hello.bc   (if needed)
+ $ ./hello.bc
+
    +
    + +

    + This allows you to execute LLVM bitcode files directly. Thanks to Jack + Cummings for pointing this out! +

    + +
    + + + +
    + Program Layout +
    + + +
    + +

    One useful source of information about the LLVM source base is the LLVM doxygen documentation available at http://llvm.org/doxygen/. + The following is a brief introduction to code layout:

    + +
    + + +
    llvm/examples
    +
    +

    This directory contains some simple examples of how to use the LLVM IR and + JIT.

    +
    + + +
    llvm/include
    +
    + +

    This directory contains public header files exported from the LLVM + library. The three main subdirectories of this directory are:

    + +
    +
    llvm/include/llvm
    +
    This directory contains all of the LLVM specific header files. This + directory also has subdirectories for different portions of LLVM: + Analysis, CodeGen, Target, Transforms, + etc...
    + +
    llvm/include/llvm/Support
    +
    This directory contains generic support libraries that are provided with + LLVM but not necessarily specific to LLVM. For example, some C++ STL utilities + and a Command Line option processing library store their header files here. +
    + +
    llvm/include/llvm/Config
    +
    This directory contains header files configured by the configure + script. They wrap "standard" UNIX and C header files. Source code can + include these header files which automatically take care of the conditional + #includes that the configure script generates.
    +
    +
    + + +
    llvm/lib
    +
    + +

    This directory contains most of the source files of the LLVM system. In LLVM, + almost all code exists in libraries, making it very easy to share code among the + different tools.

    + +
    +
    llvm/lib/VMCore/
    +
    This directory holds the core LLVM source files that implement core + classes like Instruction and BasicBlock.
    + +
    llvm/lib/AsmParser/
    +
    This directory holds the source code for the LLVM assembly language parser + library.
    + +
    llvm/lib/BitCode/
    +
    This directory holds code for reading and write LLVM bitcode.
    + +
    llvm/lib/Analysis/
    This directory contains a variety of + different program analyses, such as Dominator Information, Call Graphs, + Induction Variables, Interval Identification, Natural Loop Identification, + etc.
    + +
    llvm/lib/Transforms/
    +
    This directory contains the source code for the LLVM to LLVM program + transformations, such as Aggressive Dead Code Elimination, Sparse Conditional + Constant Propagation, Inlining, Loop Invariant Code Motion, Dead Global + Elimination, and many others.
    + +
    llvm/lib/Target/
    +
    This directory contains files that describe various target architectures + for code generation. For example, the llvm/lib/Target/X86 + directory holds the X86 machine description while + llvm/lib/Target/CBackend implements the LLVM-to-C converter.
    + +
    llvm/lib/CodeGen/
    +
    This directory contains the major parts of the code generator: Instruction + Selector, Instruction Scheduling, and Register Allocation.
    + +
    llvm/lib/Debugger/
    +
    This directory contains the source level debugger library that makes + it possible to instrument LLVM programs so that a debugger could identify + source code locations at which the program is executing.
    + +
    llvm/lib/ExecutionEngine/
    +
    This directory contains libraries for executing LLVM bitcode directly + at runtime in both interpreted and JIT compiled fashions.
    + +
    llvm/lib/Support/
    +
    This directory contains the source code that corresponds to the header + files located in llvm/include/Support/.
    + +
    llvm/lib/System/
    +
    This directory contains the operating system abstraction layer that + shields LLVM from platform-specific coding.
    +
    + +
    + + +
    llvm/projects
    +
    +

    This directory contains projects that are not strictly part of LLVM but are + shipped with LLVM. This is also the directory where you should create your own + LLVM-based projects. See llvm/projects/sample for an example of how + to set up your own project. See llvm/projects/Stacker for a fully + functional example of a compiler front end.

    +
    + + +
    llvm/runtime
    +
    + +

    This directory contains libraries which are compiled into LLVM bitcode and + used when linking programs with the GCC front end. Most of these libraries are + skeleton versions of real libraries; for example, libc is a stripped down + version of glibc.

    + +

    Unlike the rest of the LLVM suite, this directory needs the LLVM GCC front + end to compile.

    + +
    + + +
    llvm/test
    +
    +

    This directory contains feature and regression tests and other basic sanity + checks on the LLVM infrastructure. These are intended to run quickly and cover + a lot of territory without being exhaustive.

    +
    + + +
    test-suite
    +
    +

    This is not a directory in the normal llvm module; it is a separate + Subversion + module that must be checked out (usually to projects/test-suite). + This + module contains a comprehensive correctness, performance, and benchmarking + test + suite for LLVM. It is a separate Subversion module because not every LLVM + user is + interested in downloading or building such a comprehensive test suite. For + further details on this test suite, please see the + Testing Guide document.

    +
    + + +
    llvm/tools
    +
    + +

    The tools directory contains the executables built out of the + libraries above, which form the main part of the user interface. You can + always get help for a tool by typing tool_name --help. The + following is a brief introduction to the most important tools. More detailed + information is in the Command Guide.

    + +
    + +
    bugpoint
    +
    bugpoint is used to debug + optimization passes or code generation backends by narrowing down the + given test case to the minimum number of passes and/or instructions that + still cause a problem, whether it is a crash or miscompilation. See HowToSubmitABug.html for more information + on using bugpoint.
    + +
    llvmc
    +
    The LLVM Compiler Driver. This program can + be configured to utilize both LLVM and non-LLVM compilation tools to enable + pre-processing, translation, optimization, assembly, and linking of programs + all from one command line. llvmc also takes care of processing the + dependent libraries found in bitcode. This reduces the need to get the + traditional -l<name> options right on the command line. Please + note that this tool, while functional, is still experimental and not feature + complete.
    + +
    llvm-ar
    +
    The archiver produces an archive containing + the given LLVM bitcode files, optionally with an index for faster + lookup.
    + +
    llvm-as
    +
    The assembler transforms the human readable LLVM assembly to LLVM + bitcode.
    + +
    llvm-dis
    +
    The disassembler transforms the LLVM bitcode to human readable + LLVM assembly.
    + +
    llvm-ld
    +
    llvm-ld is a general purpose and extensible linker for LLVM. + This is the linker invoked by llvmc. It performsn standard link time + optimizations and allows optimization modules to be loaded and run so that + language specific optimizations can be applied at link time.
    + +
    llvm-link
    +
    llvm-link, not surprisingly, links multiple LLVM modules into + a single program.
    + +
    lli
    +
    lli is the LLVM interpreter, which + can directly execute LLVM bitcode (although very slowly...). For architectures + that support it (currently x86, Sparc, and PowerPC), by default, lli + will function as a Just-In-Time compiler (if the functionality was compiled + in), and will execute the code much faster than the interpreter.
    + +
    llc
    +
    llc is the LLVM backend compiler, which + translates LLVM bitcode to a native code assembly file or to C code (with + the -march=c option).
    + +
    llvm-gcc
    +
    llvm-gcc is a GCC-based C frontend that has been retargeted to + use LLVM as its backend instead of GCC's RTL backend. It can also emit LLVM + bitcode or assembly (with the -emit-llvm option) instead of the + usual machine code output. It works just like any other GCC compiler, + taking the typical -c, -S, -E, -o options that are typically used. + Additionally, the the source code for llvm-gcc is available as a + separate Subversion module.
    + +
    opt
    +
    opt reads LLVM bitcode, applies a series of LLVM to LLVM + transformations (which are specified on the command line), and then outputs + the resultant bitcode. The 'opt --help' command is a good way to + get a list of the program transformations available in LLVM.
    +
    opt can also be used to run a specific analysis on an input + LLVM bitcode file and print out the results. It is primarily useful for + debugging analyses, or familiarizing yourself with what an analysis does.
    +
    +
    + + +
    llvm/utils
    +
    + +

    This directory contains utilities for working with LLVM source code, and some + of the utilities are actually required as part of the build process because they + are code generators for parts of LLVM infrastructure.

    + +
    +
    codegen-diff
    codegen-diff is a script + that finds differences between code that LLC generates and code that LLI + generates. This is a useful tool if you are debugging one of them, + assuming that the other generates correct output. For the full user + manual, run `perldoc codegen-diff'.

    + +
    emacs/
    The emacs directory contains + syntax-highlighting files which will work with Emacs and XEmacs editors, + providing syntax highlighting support for LLVM assembly files and TableGen + description files. For information on how to use the syntax files, consult + the README file in that directory.

    + +
    getsrcs.sh
    The getsrcs.sh script finds + and outputs all non-generated source files, which is useful if one wishes + to do a lot of development across directories and does not want to + individually find each file. One way to use it is to run, for example: + xemacs `utils/getsources.sh` from the top of your LLVM source + tree.

    + +
    llvmgrep
    +
    This little tool performs an "egrep -H -n" on each source file in LLVM and + passes to it a regular expression provided on llvmgrep's command + line. This is a very efficient way of searching the source base for a + particular regular expression.
    + +
    makellvm
    The makellvm script compiles all + files in the current directory and then compiles and links the tool that + is the first argument. For example, assuming you are in the directory + llvm/lib/Target/Sparc, if makellvm is in your path, + simply running makellvm llc will make a build of the current + directory, switch to directory llvm/tools/llc and build it, + causing a re-linking of LLC.

    + +
    NewNightlyTest.pl and + NightlyTestTemplate.html
    These files are used in a + cron script to generate nightly status reports of the functionality of + tools, and the results can be seen by following the appropriate link on + the LLVM homepage.

    + +
    TableGen/
    The TableGen directory contains + the tool used to generate register descriptions, instruction set + descriptions, and even assemblers from common TableGen description + files.

    + +
    vim/
    The vim directory contains + syntax-highlighting files which will work with the VIM editor, providing + syntax highlighting support for LLVM assembly files and TableGen + description files. For information on how to use the syntax files, consult + the README file in that directory.

    + +
    + +
    + + +
    llvm/win32
    +
    +

    This directory contains build scripts and project files for use with + Visual C++. This allows developers on Windows to build LLVM without the need + for Cygwin. The contents of this directory should be considered experimental + at this time. +

    +
    + +
    + An Example Using the LLVM Tool Chain +
    + + +
    +

    This section gives an example of using LLVM. llvm-gcc3 is now obsolete, + so we only include instructiosn for llvm-gcc4. +

    + +

    Note: The gcc4 frontend's invocation is considerably different + from the previous gcc3 frontend. In particular, the gcc4 frontend does not + create bitcode by default: gcc4 produces native code. As the example below illustrates, + the '--emit-llvm' flag is needed to produce LLVM bitcode output. For makefiles and + configure scripts, the CFLAGS variable needs '--emit-llvm' to produce bitcode + output.

    +
    + + +
    Example with llvm-gcc4
    + +
    + +
      +

    1. First, create a simple C file, name it 'hello.c':

      + +
      + 
      + #include <stdio.h>
+ 
+ int main() {
+   printf("hello world\n");
+   return 0;
+ }
+
      2. + +

    2. Next, compile the C file into a native executable:

      + + 
      % llvm-gcc hello.c -o hello
      + +

      Note that llvm-gcc works just like GCC by default. The standard -S and + -c arguments work as usual (producing a native .s or .o file, + respectively).

      3. + +

    3. Next, compile the C file into a LLVM bitcode file:

      + +
      + 
      % llvm-gcc -O3 -emit-llvm hello.c -c -o hello.bc
      + +

      The -emit-llvm option can be used with the -S or -c options to emit an + LLVM ".ll" or ".bc" file (respectively) for the code. This allows you + to use the standard LLVM tools on + the bitcode file.

      + +

      Unlike llvm-gcc3, llvm-gcc4 correctly responds to -O[0123] arguments. +

      4. + +

    4. Run the program in both forms. To run the program, use:

      + + 
      % ./hello
      + +

      and

      + + 
      % lli hello.bc
      + +

      The second examples shows how to invoke the LLVM JIT, lli.

      5. + +

    5. Use the llvm-dis utility to take a look at the LLVM assembly + code:

      + +
      + 
      llvm-dis < hello.bc | less
      +
      6. + +

    6. Compile the program to native assembly using the LLC code + generator:

      + + 
      % llc hello.bc -o hello.s
      7. + +

    7. Assemble the native assembly language file into a program:

      + +
      + 
      + Solaris: % /opt/SUNWspro/bin/cc -xarch=v9 hello.s -o hello.native
+ 
+ Others:  % gcc hello.s -o hello.native
+
      +
      8. + +

    8. Execute the native code program:

      + + 
      % ./hello.native
      + +

      Note that using llvm-gcc to compile directly to native code (i.e. when + the -emit-llvm option is not present) does steps 6/7/8 for you.

      +
      9. + +
    + +
    + + + +
    + Common Problems +
    + + +
    + +

    If you are having problems building or using LLVM, or if you have any other + general questions about LLVM, please consult the Frequently + Asked Questions page.

    + +
    + + +
    + Links +
    + + +
    + +

    This document is just an introduction to how to use LLVM to do + some simple things... there are many more interesting and complicated things + that you can do that aren't documented here (but we'll gladly accept a patch + if you want to write something up!). For more information about LLVM, check + out:

    + + + +
    + + + +
    +
    + Valid CSS! + Valid HTML 4.01! + + Chris Lattner
    + Reid Spencer
    + The LLVM Compiler Infrastructure
    + Last modified: $Date: 2008/02/12 06:05:03 $ +
    + + Index: llvm-www/releases/2.2/docs/GettingStartedVS.html diff -c /dev/null llvm-www/releases/2.2/docs/GettingStartedVS.html:1.1 *** /dev/null Tue Feb 12 00:07:03 2008 --- llvm-www/releases/2.2/docs/GettingStartedVS.html Tue Feb 12 00:05:03 2008 *************** *** 0 **** --- 1,380 ---- + + + + + Getting Started with LLVM System for Microsoft Visual Studio + + + + +
    + Getting Started with the LLVM System using Microsoft Visual Studio +
    + + + +
    +

    Written by: + Jeff Cohen +

    +
    + + + +
    + Overview +
    + + +
    + +

    The Visual Studio port at this time is experimental. It is suitable for + use only if you are writing your own compiler front end or otherwise have a + need to dynamically generate machine code. The JIT and interpreter are + functional, but it is currently not possible to generate assembly code which + is then assembled into an executable. You can indirectly create executables + by using the C back end.

    + +

    To emphasize, there is no C/C++ front end currently available. + llvm-gcc is based on GCC, which cannot be bootstrapped using VC++. + Eventually there should be a llvm-gcc based on Cygwin or MinGW that + is usable. There is also the option of generating bitcode files on Unix and + copying them over to Windows. But be aware the odds of linking C++ code + compiled with llvm-gcc with code compiled with VC++ is essentially + zero.

    + +

    The LLVM test suite cannot be run on the Visual Studio port at this + time.

    + +

    Most of the tools build and work. llvm-db does not build at this + time. bugpoint does build, but does not work. + +

    Additional information about the LLVM directory structure and tool chain + can be found on the main Getting Started + page.

    + +
    + + +
    + Getting Started Quickly (A Summary) +
    + + +
    + +

    Here's the short story for getting up and running quickly with LLVM:

    + +
      +
    1. Read the documentation.
      2. +
    2. Seriously, read the documentation.
      3. +
    3. Remember that you were warned twice about reading the documentation.
      4. + +
    4. Get the Source Code +
        +
      • With the distributed files: +
          +
        1. cd where-you-want-llvm-to-live +
        2. gunzip --stdout llvm-version.tar.gz | tar -xvf - +       or use WinZip +
        3. cd llvm
          4. +
        • + +
      • With anonymous Subversion access: +
          +
        1. cd where-you-want-llvm-to-live
          2. +
        2. svn co http://llvm.org/svn/llvm-project/llvm-top/trunk llvm-top +
          3. +
        3. make checkout MODULE=llvm +
        4. cd llvm
          5. +
        • +
      5. + +
    5. Start Visual Studio +
        +
      1. Simply double click on the solution file llvm/win32/llvm.sln. +
        2. +
      6. + +
    6. Build the LLVM Suite: +
        +
      1. Simply build the solution.
        2. +
      2. The Fibonacci project is a sample program that uses the JIT. Modify + the project's debugging properties to provide a numeric command line + argument. The program will print the corresponding fibonacci value.
        3. +
      7. + +
    + +

    It is strongly encouraged that you get the latest version from Subversion as + changes are continually making the VS support better.

    + +
    + + +
    + Requirements +
    + + +
    + +

    Before you begin to use the LLVM system, review the requirements given + below. This may save you some trouble by knowing ahead of time what hardware + and software you will need.

    + +
    + + +
    + Hardware +
    + +
    + +

    Any system that can adequately run Visual Studio .NET 2003 is fine. The + LLVM source tree and object files, libraries and executables will consume + approximately 3GB.

    + +
    + + +
    Software
    +
    + +

    You will need Visual Studio .NET 2003. Earlier versions cannot open the + solution/project files. The VS 2005 beta can, but will migrate these files + to its own format in the process. While it should work with the VS 2005 + beta, there are no guarantees and there is no support for it at this time. + It has been reported that VC++ Express also works.

    + +

    If you plan to modify any .y or .l files, you will need to have bison + and/or flex installed where Visual Studio can find them. Otherwise, you do + not need them and the pre-generated files that come with the source tree + will be used.

    + +

    + Do not install the LLVM directory tree into a path containing spaces (e.g. + C:\Documents and Settings\...) as the configure step will fail.

    + +
    + + +
    + Getting Started with LLVM +
    + + +
    + +

    The remainder of this guide is meant to get you up and running with + LLVM using Visual Studio and to give you some basic information about the LLVM + environment.

    + +
    + + +
    + Terminology and Notation +
    + +
    + +

    Throughout this manual, the following names are used to denote paths + specific to the local system and working environment. These are not + environment variables you need to set but just strings used in the rest + of this document below. In any of the examples below, simply replace + each of these names with the appropriate pathname on your local system. + All these paths are absolute:

    + +
    +
    SRC_ROOT
    +

    This is the top level directory of the LLVM source tree.

    + +
    OBJ_ROOT
    +

    This is the top level directory of the LLVM object tree (i.e. the + tree where object files and compiled programs will be placed. It is + fixed at SRC_ROOT/win32).

    +
    + +
    + + +
    + The Location of LLVM Object Files +
    + +
    + +

    The object files are placed under OBJ_ROOT/Debug for debug builds + and OBJ_ROOT/Release for release (optimized) builds. These include + both executables and libararies that your application can link against.

    + +

    The files that configure would create when building on Unix are + created by the Configure project and placed in + OBJ_ROOT/llvm. You application must have OBJ_ROOT in its include + search path just before SRC_ROOT/include.

    + +
    + + +
    + An Example Using the LLVM Tool Chain +
    + + +
    + +
      +

    1. First, create a simple C file, name it 'hello.c':

      + +
      + 
      + #include <stdio.h>
+ int main() {
+   printf("hello world\n");
+   return 0;
+ }
+
      2. + +

    2. Next, compile the C file into a LLVM bitcode file:

      + +
      + 
      + % llvm-gcc -c hello.c -emit-llvm -o hello.bc
+
      +
      + +

      This will create the result file hello.bc which is the LLVM + bitcode that corresponds the the compiled program and the library + facilities that it required. You can execute this file directly using + lli tool, compile it to native assembly with the llc, + optimize or analyze it further with the opt tool, etc.

      + +

      Note: while you cannot do this step on Windows, you can do it on a + Unix system and transfer hello.bc to Windows. Important: + transfer as a binary file!

      3. + +

    3. Run the program using the just-in-time compiler:

      + +
      + 
      + % lli hello.bc
+
      +
      + +

      Note: this will only work for trivial C programs. Non-trivial programs + (and any C++ program) will have dependencies on the GCC runtime that + won't be satisfied by the Microsoft runtime libraries.

      4. + +

    4. Use the llvm-dis utility to take a look at the LLVM assembly + code:

      + +
      + 
      + % llvm-dis < hello.bc | more
+
      +
      5. + +

    5. Compile the program to C using the LLC code generator:

      + +
      + 
      + % llc -march=c hello.bc
+
      +
      6. + +

    6. Compile to binary using Microsoft C:

      + +
      + 
      + % cl hello.cbe.c
+
      +
      + +

      Note: this will only work for trivial C programs. Non-trivial programs + (and any C++ program) will have dependencies on the GCC runtime that + won't be satisfied by the Microsoft runtime libraries.

      7. + +

    7. Execute the native code program:

      + +
      + 
      + % hello.cbe.exe
+
      +
      8. +
    + +
    + + +
    + Common Problems +
    + + +
    + +

    If you are having problems building or using LLVM, or if you have any other + general questions about LLVM, please consult the Frequently + Asked Questions page.

    + +
    + + +
    + Links +
    + + +
    + +

    This document is just an introduction to how to use LLVM to do + some simple things... there are many more interesting and complicated things + that you can do that aren't documented here (but we'll gladly accept a patch + if you want to write something up!). For more information about LLVM, check + out:

    + + + +
    + + + +
    +
    + Valid CSS! + Valid HTML 4.01! + + Jeff Cohen
    + The LLVM Compiler Infrastructure
    + Last modified: $Date: 2008/02/12 06:05:03 $ +
    + + Index: llvm-www/releases/2.2/docs/HowToReleaseLLVM.html diff -c /dev/null llvm-www/releases/2.2/docs/HowToReleaseLLVM.html:1.1 *** /dev/null Tue Feb 12 00:07:03 2008 --- llvm-www/releases/2.2/docs/HowToReleaseLLVM.html Tue Feb 12 00:05:03 2008 *************** *** 0 **** --- 1,608 ---- + + + + How To Release LLVM To The Public + + + + +
    How To Release LLVM To The Public
    +
      +
    1. Introduction
      2. +
    2. Release Timeline
      3. +
    3. Release Process
      4. +
    4. Distribution Targets
      5. +
    +
    +

    Written by Reid Spencer, + John Criswell, + Tanya Lattner

    +
    + + +
    Introduction
    + + +
    +

    + This document collects information about successfully releasing LLVM to the + public. It is the release manager's guide to ensuring that a high quality + build of LLVM is released. +

    + +

    + The following is the basic criteria for releasing LLVM: +

    + +
      +
    1. Successful configure and build.
      2. +
    2. Clean 'make check'.
      3. +
    3. No regressions in the testsuite from the previous release. This may + include performance regressions for major benchmarks.
      4. +
    +
    + + +
    Release Timeline
    + +
    + The release manager should attempt to have a release every 3-4 months because LLVM + does time based releases (instead of feature based). The release schedule should + be roughly as follows: +
      +
    1. Set code freeze and branch creation date for 3 months after last release + date. Announce release schedule to the LLVM community and update the website.
      2. +
    2. Create release branch and begin release process.
      3. +
    3. Send out pre-release for first round of testing. Testing will last 7-10 days. + During the first round of testing, regressions should be found and fixed. Patches + are merged from mainline to the release branch.
      4. +
    4. Generate and send out second pre-release. Bugs found during this time will + not be fixed unless absolutely critical. Bugs introduce by patches merged in + will be fixed and if so, a 3rd round of testing is needed.
      5. +
    5. The release notes should be updated during the first and second round of + pre-release testing.
      6. +
    6. Finally, release!
      7. +
    +
    + + + +
    Release Process
    + + + +
    Process Overview
    +
    +
      +
    1. Create Release Branch
      2. +
    2. Update LLVM Version
      3. +
    3. Build the LLVM Source Distributions
      4. +
    4. Build LLVM
      5. +
    5. Build the LLVM GCC Binary Distribution
      6. +
    6. Build RPM Packages (optional)
      7. +
    7. Run 'make check'
      8. +
    8. Run LLVM Test Suite
      9. +
    9. Pre-Release Testing
      10. +
    10. Tag the LLVM Release Branch
      11. +
    11. Update Documentation
      12. +
    12. Update the LLVM Demo Page
      13. +
    13. Update the LLVM Website
      14. +
    14. Announce the Release
      15. + +
    +
    + + +
    Create Release Branch
    +
    +

    Branch the Subversion HEAD using the following procedure:

    +
      +
    1. +

      Verify that the current Subversion HEAD is in decent shape by examining nightly + tester results.

      2. +
    2. +

      Request all developers to refrain from committing. Offenders get commit + rights taken away (temporarily).

      3. +
    3. +

      Create the release branch for llvm, llvm-gcc4.0, + llvm-gcc4.2, and the test-suite. The + branch name will be release_XX, where XX is the major and + minor release numbers. These branches can be created without checking out + anything from subversion. +

      + +
      + 
      + svn copy https://llvm.org/svn/llvm-project/llvm/trunk \
+          https://llvm.org/svn/llvm-project/llvm/branches/release_XX
+ svn copy https://llvm.org/svn/llvm-project/llvm-gcc-4.0/trunk \
+          https://llvm.org/svn/llvm-project/llvm-gcc-4.0/branches/release_XX
+ svn copy https://llvm.org/svn/llvm-project/llvm-gcc-4.2/trunk \
+          https://llvm.org/svn/llvm-project/llvm-gcc-4.2/branches/release_XX
+ svn copy https://llvm.org/svn/llvm-project/test-suite/trunk \
+          https://llvm.org/svn/llvm-project/test-suite/branches/release_XX
+
      +
      + +
    4. +

      Advise developers they can work on Subversion HEAD again.

      5. + +
    5. +

      The Release Manager should switch to the release branch (as all changes + to the release will now be done in the branch). The easiest way to do this + is to grab another working copy using the following commands:

      + +
      + 
      + svn co https://llvm.org/svn/llvm-project/llvm/branches/release_XX
+ svn co https://llvm.org/svn/llvm-project/llvm-gcc-4.0/branches/release_XX
+ svn co https://llvm.org/svn/llvm-project/llvm-gcc-4.2/branches/release_XX
+ svn co https://llvm.org/svn/llvm-project/test-suite/branches/release_XX
+
      +
      6. + +
    + + + + +
    Update LLVM Version
    +
    +

    + After creating the LLVM release branch, update the release branches' + autoconf/configure.ac version from X.Xsvn to just X.X. Update it on mainline + as well to be the next version (X.X+1svn). Regenerated the configure script + for both. This must be done for both llvm and the test-suite. +

    +

    In addition, the version number of all the Bugzilla components must be + updated for the next release. +

    +
    + + +
    Build the LLVM Source Distributions
    +
    +

    + Create source distributions for LLVM, LLVM GCC, and the LLVM Test Suite by + exporting the source from Subversion and archiving it. This can be done with + the following commands: +

    + +
    + 
    + svn export https://llvm.org/svn/llvm-project/llvm/branches/release_XX llvm-X.X
+ svn export https://llvm.org/svn/llvm-project/llvm-gcc-4.0/branches/release_XX llvm-gcc4.0-X.X.source
+ svn export https://llvm.org/svn/llvm-project/llvm-gcc-4.2/branches/release_XX llvm-gcc4.2-X.X.source
+ svn export https://llvm.org/svn/llvm-project/test-suite/branches/release_XX llvm-test-X.X
+ tar -cvf - llvm-X.X          | gzip > llvm-X.X.tar.gz
+ tar -cvf - llvm-test-X.X     | gzip > llvm-test-X.X.tar.gz
+ tar -cvf - llvm-gcc4.0-X.X.source | gzip > llvm-gcc-4.0-X.X.source.tar.gz
+ tar -cvf - llvm-gcc4.2-X.X.source | gzip > llvm-gcc-4.2-X.X.source.tar.gz
+
    +
    +
    + + +
    Build LLVM
    +
    +

    + Build both debug and release (optimized) versions of LLVM on all + platforms. Ensure the build is warning and error free on each platform. + Note that when building the LLVM GCC Binary, use a release build of LLVM. +

    +
    + + +
    Build the LLVM GCC Binary Distribution
    +
    +

    + Creating the LLVM GCC binary distribution (release/optimized) requires + performing the following steps for each supported platform: +

    + +
      +
    1. + Build the LLVM GCC front-end by following the directions in the README.LLVM + file. Be sure to build with LLVM_VERSION_INFO=X.X, where X is the major and + minor release numbers. +
      2. + +
    2. + Copy the installation directory to a directory named for the specific target. + For example on Red Hat Enterprise Linux, the directory would be named + llvm-gcc4.0-2.1-x86-linux-RHEL4. Archive and compress the new directory. +
      3. +
    +
    + + +
    Run 'make check'
    +
    +

    + Using the newly built llvm-gcc and llvm, reconfigure llvm to locate llvm-gcc. + Run make check and ensure there are no unexpected failures. If there + are, resolve the failures or file a bug. If there is a fix commited to mainline, + merge back into the release branch, and restart testing by + re-building LLVM and llvm-gcc. If no + fix will be made, XFAIL the test and commit back to the release branch. +

    + +

    + Ensure that 'make check' passes on all platforms for all targets. The + test suite must complete with "0 unexpected failures" before sending out the + pre-releases for testing. +

    +
    + + +
    LLVM Test Suite
    +
    +

    + Run the llvm-test suite and ensure there are no unacceptable + failures. Unacceptable failures are regression from the previous release + and (optionally) major performance regressions from the previous release. + If a regression is found a bug is filled, but the pre-releases may still go + out.

    +
    + + +
    Building RPM packages (optional)
    +
    +

    + You can, optionally, create source and binary RPM packages for LLVM. These may + make it easier to get LLVM into a distribution. This can be done with the + following commands: +

    + +
    + 
    + make dist        # Build the distribution source tarball
+ make dist-check  # Check that the source tarball can build itself.
+ cp llvm-M.m.tar.gz /usr/src/redhat/SOURCES  # Required by rpmbuild
+ make srpm # for source rpm
+ make rpm  # for binary rpm
+
    +
    + +

    + First, use make dist to simply build the distribution. Any failures + need to be corrected (on the branch). Once make dist can be + successful, do make dist-check. This target will do the same thing as + the 'dist' target but also test that distribution to make sure it can build + itself and runs make check as well. This ensures that needed files + are not missing and that the src tarball can be successfully unpacked, built, + installed, and cleaned. Once you have a reliable tarball, you need to copy it + to the /usr/src/redhat/SOURCES directory which is a requirement of + the rpmbuild tool. The last two make invocations just run rpmbuild to + build either a source (srpm) or binary (rpm) RPM package. +

    +
    + + +
    Pre-Release Testing
    +
    +

    + Once all testing has been completed and appropriate bugs filed, the pre-release + tar balls may be put on the website and the LLVM community is notified. Ask that + all LLVM developers test the release in 2 ways:

    +
      +
    1. Download llvm-X.X, llvm-test-X.X, and the appropriate llvm-gcc4 binary. + Run "make check" and the full llvm-test suite (make TEST=nightly report).
    2. +
    3. Download llvm-X.X, llvm-test-X.X, and the llvm-gcc4 source. Compile + everything. Run "make check" and the full llvm-test suite (make TEST=nightly + report).
      4. +
    +

    Ask LLVM developers to submit the report and make check results to the list. + Verify that there are no regressions from the previous release. For + unsupported targets, verify that make check at least is clean.

    + +

    The first round of pre-release testing will be the longest. During this time, + all regressions must be fixed before the second pre-release is created (repeat + steps 4-8).

    + +

    If this is the second round of testing, this is only to ensure the bug fixes + previously merged in have not created new major problems. This is not the time + to solve additional and unrelated bugs. If no patches are merged in, the release + is determined to be ready and the release manager may move onto the next step.

    +
    + + + +
    Tag the Release Branch
    +
    +

    Tag the release branch using the following procedure:

    +
    + 
    + svn copy https://llvm.org/svn/llvm-project/llvm/branches/release_XX \
+          https://llvm.org/svn/llvm-project/llvm/tags/RELEASE_XX
+ svn copy https://llvm.org/svn/llvm-project/llvm-gcc-4.0/branches/release_XX \
+          https://llvm.org/svn/llvm-project/llvm-gcc-4.0/tags/RELEASE_XX
+ svn copy https://llvm.org/svn/llvm-project/llvm-gcc-4.2/branches/release_XX \
+          https://llvm.org/svn/llvm-project/llvm-gcc-4.2/tags/RELEASE_XX
+ svn copy https://llvm.org/svn/llvm-project/test-suite/branches/release_XX \
+          https://llvm.org/svn/llvm-project/test-suite/tags/RELEASE_XX
+
    +
    +
    + + +
    Update Documentation
    +
    +

    + Review the documentation and ensure that it is up to date. The Release Notes + must be updated to reflect bug fixes, new known issues, and changes in the + list of supported platforms. The Getting Started Guide should be updated to + reflect the new release version number tag avaiable from Subversion and + changes in basic system requirements. Merge both changes from mainline into + the release branch. +

    +
    + + +
    Update the LLVM Demo Page
    +
    +

    + The LLVM demo page must be updated to use the new release. This consists of + using the llvm-gcc binary and building LLVM. Update the website demo page + configuration to use the new release.

    +
    + + +
    Update the LLVM Website
    +
    +

    + The website must be updated before the release announcement is sent out. Here is + what to do:

    +
      +
    1. Check out the website module from CVS.
      2. +
    2. Create a new subdirectory X.X in the releases directory.
      3. +
    3. Commit the llvm, test-suite, llvm-gcc source, + and llvm-gcc binaries in this new directory.
      4. +
    4. Copy and commit the llvm/docs and LICENSE.txt + files into this new directory. The docs should be built with BUILD_FOR_WEBSITE=1.
      5. +
    5. Commit the index.html to the release/X.X directory to redirect (use from previous + release.
      6. +
    6. Update the releases/download.html file with the new release.
      7. +
    7. Update the releases/index.html with the new release and link to + release documentation.
      8. +
    8. Finally, update the main page (index.html and sidebar) to + point to the new release and release announcement. Make sure this all gets + commited back into Subversion.
      9. +
    +
    + + +
    Announce the Release
    +
    +

    Have Chris send out the release announcement when everything is finished.

    +
    + + +
    Distribution Targets
    + + + +
    Overview
    +
    +

    + The first thing you need to understand is that there are multiple make targets + to support this feature. Here's an overview, we'll delve into the details + later. +

    + +
      +
    • distdir - builds the distribution directory from which the + distribution will be packaged
      • +
    • dist - builds each of the distribution tarballs (tar.gz, + tar.bzip2, .zip). These can be built individually as well, with separate + targets.
      • +
    • dist-check - this is identical to dist but includes a + check on the distribution that ensures the tarball can: unpack + successfully, compile correctly, pass 'make check', and pass + 'make clean'.
      • +
    • dist-clean- this just does a normal clean but also cleans up the + stuff generated by the other three dist targets (above).
      • +
    + +

    + Okay, that's the basic functionality. When making a release, we want to ensure + that the tree you build the distribution from passes + dist-check. Beyond fixing the usual bugs, there is generally one + impediment to making the release in this fashion: missing files. The + dist-check process guards against that possibility. It will either + fail and that failure will indicate what's missing, or it will succeed meaning + that it has proved that the tarballs can actually succeed in building LLVM + correctly and that it passes make check. +

    +
    + + + +
    distdir
    +
    +

    + This target builds the distribution directory which is the directory from + which the tarballs are generated. The distribution directory has the same + name as the release, e.g. LLVM-1.7). This target goes through the following + process: +

    + +
      +
    1. First, if there was an old distribution directory (for the current + release), it is removed in its entirety and you see Removing old + LLVM-1.7
      2. +
    2. Second, it issues a make all ENABLE_OPTIMIZED=3D1 to ensure + that the everything in your tree can be built in release mode. Often + times there are discrepancies in building between debug and release + modes so it enforces release mode first. If that fails, the + distdir target fails too. This is preceded by the message + Making 'all' to verify build.
      3. +
    3. Next, it traverses your source tree and copies it to a new directory + that has the name of the release (LLVM-M.m in our current + case). This is the directory that will get tar'd. It contains all the + software that needs to be in the distribution. During the copying + process, it omits generated files, SVN directories, and any other + "cruft" that's in your build tree. This is done to eliminate the + possibility of huge distribution tarballs that include useless or + irrelevant stuff in them. This is the trickiest part of making the + distribution. Done manually you will either include stuff that + shouldn't be in the distribution or exclude stuff that should. This + step is preceded by the message Building Distribution Directory + LLVM-1.7
      4. +
    4. The distribution directory is then traversed and all CVS or + .svn directories are removed. You see: Eliminating CVS/.svn + directories from distribution
      5. +
    5. The recursive dist-hook target is executed. This gives each + directory a chance to modify the distribution in some way (more on this + below).
      6. +
    6. The distribution directory is traversed and the correct file + permissions and modes are set based on the type of file.
      7. +
    + +

    + To control the process of making the distribution directory correctly, each + Makefile can utilize two features: +

    + +
      +
    1. EXTRA_DIST - this make variable specifies which files + it should distribute. By default, all source files are automatically + included for distribution as well as certain well known files + (see DistAlways variable in Makefile.rules for details). Each Makefile + specifies, via the EXTRA_DIST variable, which additional files + need to be distributed. Only those files that are needed to build LLVM + should be added to EXTRA_DIST. EXTRA_DIST contains a + list of file or directory names that should be distributed. For example, + the top level Makefile contains EXTRA_DIST := test llvm.spec + include. This means that in addition to regular things that are + distributed at the top level (CREDITS.txt, LICENSE.txt, etc.) + the distribution should contain the entire test and + include directories as well as the llvm.spec file.
      2. +
    2. dist-hook - this make target can be used to alter the + content of the distribution directory. For example, in the top level + Makefile there is some logic to eliminate files in the include + subtree that are generated by the configure script. These should not be + distributed. Similarly, any dist-hook target found in any + directory can add or remove or modify things just before it gets + packaged. Any transformation is permitted. Generally, not much is + needed.
      3. +
    + +

    + You will see various messages if things go wrong: +

    + +
      +
    1. During the copying process, any files that are missing will be flagged + with: ===== WARNING: Distribution Source 'dir/file' Not Found! + These must be corrected by either adding the file or removing it from + EXTRA_DIST.
      2. +
    2. If you build the distribution with VERBOSE=1, then you might + also see: Skipping non-existent 'dir/file' in certain cases + where it's okay to skip the file.
      3. +
    3. The target can fail if any of the things it does fail. Error messages + should indicate what went wrong.
      4. +
    +
    + + +
    dist
    +
    +

    + This target does exactly what distdir target does, but also includes + assembling the tarballs. There are actually four related targets here: +

    + +
      +
    • dist-gzip: package the gzipped distribution tar + file. The distribution directory is packaged into a single file ending + in .tar.gz which is gzip compressed.
      • +
    • dist-bzip2: package the bzip2 distribution tar file. + The distribution directory is packaged into a single file ending in + .tar.bzip2 which is bzip2 compressed.
      • +
    • dist-zip: package the zip distribution file. The + distribution directory is packaged into a single file ending in + .zip which is zip compressed.
      • +
    • dist: does all three, dist-gzip, dist-bzip2, + dist-zip
      • +
    +
    + + +
    dist-check
    +
    +

    + This target checks the distribution. The basic idea is that it unpacks the + distribution tarball and ensures that it can build. It takes the following + actions: +

    + +
      +
    1. It depends on the dist-gzip target which, if it hasn't already + been built, builds the gzip tar bundle (see dist and distdir + above).
      2. +
    2. removes any pre-existing _distcheckdir at the top level.
      3. +
    3. creates a new _distcheckdir directory at the top level.
      4. +
    4. creates a build subdirectory and an install + subdirectory under _distcheckdir.
      5. +
    5. unzips and untars the release tarball into _distcheckdir, + creating LLVM-1.7 directory (from the tarball).
      6. +
    6. in the build subdirectory, it configures with appropriate options to + build from the unpacked source tarball into the build directory + with installation in the install directory.
      7. +
    7. runs make all
      8. +
    8. runs make check
      9. +
    9. runs make install
      10. +
    10. runs make uninstall
      11. +
    11. runs make dist
      12. +
    12. runs make clean
      13. +
    13. runs make dist-clean
      14. +
    + +

    + If it can pass all that, the distribution will be deemed distribution worth y + and you will see: +

    + + 
    ===== LLVM-1.7.tar.gz Ready For Distribution =====
    + +

    + This means the tarball should then be tested on other platforms and have the + nightly test run against it. If those all pass, THEN it is ready for + distribution. +

    + +

    + A note about disk space: using dist-check will easily triple the + amount of disk space your build tree is using. You might want to check + available space before you begin. +

    +
    + + +
    dist-clean
    +
    +

    + In addition to doing a normal clean, this target will clean up the + files and directories created by the distribution targets. In particular the + distribution directory (LLVM-X.X), check directory + (_distcheckdir), and the various tarballs will be removed. You do + this after the release has shipped and you no longer need this stuff in your + build tree. +

    +
    + + +
    +
    + Valid CSS! + Valid HTML 4.01! + The LLVM Compiler Infrastructure +
    + Last modified: $Date: 2008/02/12 06:05:03 $ +
    + + Index: llvm-www/releases/2.2/docs/HowToSubmitABug.html diff -c /dev/null llvm-www/releases/2.2/docs/HowToSubmitABug.html:1.1 *** /dev/null Tue Feb 12 00:07:03 2008 --- llvm-www/releases/2.2/docs/HowToSubmitABug.html Tue Feb 12 00:05:03 2008 *************** *** 0 **** --- 1,355 ---- + + + + How to submit an LLVM bug report + + + + +
    + How to submit an LLVM bug report +
    + + + + + + +
    +
      +
    1. Introduction - Got bugs?
      2. +
    2. Crashing Bugs +
      3. +
    3. Miscompilations
      4. +
    4. Incorrect code generation (JIT and LLC)
      5. +
    +
    +

    Written by Chris Lattner and + Misha Brukman

    +
    +     		+ Debugging +
    + + +
    + Introduction - Got bugs? +
    + + +
    + +

    If you're working with LLVM and run into a bug, we definitely want to know + about it. This document describes what you can do to increase the odds of + getting it fixed quickly.

    + +

    Basically you have to do two things at a minimum. First, decide whether the + bug crashes the compiler (or an LLVM pass), or if the + compiler is miscompiling the program (i.e., the + compiler successfully produces an executable, but it doesn't run right). Based + on + what type of bug it is, follow the instructions in the linked section to narrow + down the bug so that the person who fixes it will be able to find the problem + more easily.

    + +

    Once you have a reduced test-case, go to the LLVM Bug Tracking + System and fill out the form with the necessary details (note that you don't + need to pick a catagory, just use the "new-bugs" catagory if you're not sure). + The bug description should contain the following + information:

    + +
      +
    • All information necessary to reproduce the problem.
      • +
    • The reduced test-case that triggers the bug.
      • +
    • The location where you obtained LLVM (if not from our Subversion + repository).
      • +
    + +

    Thanks for helping us make LLVM better!

    + +
    + + +
    + Crashing Bugs +
    + + +
    + +

    More often than not, bugs in the compiler cause it to crash—often due + to an assertion failure of some sort. The most important + piece of the puzzle is to figure out if it is crashing in the GCC front-end + or if it is one of the LLVM libraries (e.g. the optimizer or code generator) + that has problems.

    + +

    To figure out which component is crashing (the front-end, + optimizer or code generator), run the + llvm-gcc command line as you were when the crash occurred, but + with the following extra command line options:

    + +
      +
    • -O0 -emit-llvm: If llvm-gcc still crashes when + passed these options (which disable the optimizer and code generator), then + the crash is in the front-end. Jump ahead to the section on front-end bugs.
      • + +
    • -emit-llvm: If llvm-gcc crashes with this option + (which disables the code generator), you found an optimizer bug. Jump ahead + to compile-time optimization bugs.
      • + +
    • Otherwise, you have a code generator crash. Jump ahead to code generator bugs.
      • + +
    + +
    + + +
    + Front-end bugs +
    + +
    + +

    If the problem is in the front-end, you should re-run the same + llvm-gcc command that resulted in the crash, but add the + -save-temps option. The compiler will crash again, but it will leave + behind a foo.i file (containing preprocessed C source code) and + possibly foo.s for each + compiled foo.c file. Send us the foo.i file, + along with the options you passed to llvm-gcc, and a brief description of the + error it caused.

    + +

    The delta tool helps to reduce the + preprocessed file down to the smallest amount of code that still replicates the + problem. You're encouraged to use delta to reduce the code to make the + developers' lives easier. This website + has instructions on the best way to use delta.

    + +
    + + +
    + Compile-time optimization bugs +
    + +
    + +

    If you find that a bug crashes in the optimizer, compile your test-case to a + .bc file by passing "-emit-llvm -O0 -c -o foo.bc". + Then run:

    + +
    +

    opt -std-compile-opts -debug-pass=Arguments foo.bc + -disable-output

    +
    + +

    This command should do two things: it should print out a list of passes, and + then it should crash in the same was as llvm-gcc. If it doesn't crash, please + follow the instructions for a front-end bug.

    + +

    If this does crash, then you should be able to debug this with the following + bugpoint command:

    + +
    +

    bugpoint foo.bc <list of passes printed by + opt>

    +
    + +

    Please run this, then file a bug with the instructions and reduced .bc files + that bugpoint emits. If something goes wrong with bugpoint, please submit the + "foo.bc" file and the list of passes printed by opt.

    + +
    + + +
    + Code generator bugs +
    + +
    + +

    If you find a bug that crashes llvm-gcc in the code generator, compile your + source file to a .bc file by passing "-emit-llvm -c -o foo.bc" + to llvm-gcc (in addition to the options you already pass). Once your have + foo.bc, one of the following commands should fail:

    + +
      +
    1. llc foo.bc -f
      2. +
    2. llc foo.bc -f -relocation-model=pic
      3. +
    3. llc foo.bc -f -relocation-model=static
      4. +
    4. llc foo.bc -f -enable-eh
      5. +
    5. llc foo.bc -f -relocation-model=pic -enable-eh
      6. +
    6. llc foo.bc -f -relocation-model=static -enable-eh
      7. +
    + +

    If none of these crash, please follow the instructions for a + front-end bug. If one of these do crash, you should + be able to reduce this with one of the following bugpoint command lines (use + the one corresponding to the command above that failed):

    + +
      +
    1. bugpoint -run-llc foo.bc
      2. +
    2. bugpoint -run-llc foo.bc --tool-args + -relocation-model=pic
      3. +
    3. bugpoint -run-llc foo.bc --tool-args + -relocation-model=static
      4. +
    4. bugpoint -run-llc foo.bc --tool-args -enable-eh
      5. +
    5. bugpoint -run-llc foo.bc --tool-args + -relocation-model=pic -enable-eh
      6. +
    6. bugpoint -run-llc foo.bc --tool-args + -relocation-model=static -enable-eh
      7. +
    + +

    Please run this, then file a bug with the instructions and reduced .bc file + that bugpoint emits. If something goes wrong with bugpoint, please submit the + "foo.bc" file and the option that llc crashes with.

    + +
    + + +
    + Miscompilations +
    + + +
    + +

    If llvm-gcc successfully produces an executable, but that executable doesn't + run right, this is either a bug in the code or a bug in the + compiler. The first thing to check is to make sure it is not using undefined + behavior (e.g. reading a variable before it is defined). In particular, check + to see if the program valgrinds clean, + passes purify, or some other memory checker tool. Many of the "LLVM bugs" that + we have chased down ended up being bugs in the program being compiled, not + LLVM.

    + +

    Once you determine that the program itself is not buggy, you should choose + which code generator you wish to compile the program with (e.g. C backend, the + JIT, or LLC) and optionally a series of LLVM passes to run. For example:

    + +
    +

    + bugpoint -run-cbe [... optzn passes ...] file-to-test.bc --args -- [program arguments]

    +
    + +

    bugpoint will try to narrow down your list of passes to the one pass + that causes an error, and simplify the bitcode file as much as it can to assist + you. It will print a message letting you know how to reproduce the resulting + error.

    + +
    + + +
    + Incorrect code generation +
    + + +
    + +

    Similarly to debugging incorrect compilation by mis-behaving passes, you can + debug incorrect code generation by either LLC or the JIT, using + bugpoint. The process bugpoint follows in this case is to try + to narrow the code down to a function that is miscompiled by one or the other + method, but since for correctness, the entire program must be run, + bugpoint will compile the code it deems to not be affected with the C + Backend, and then link in the shared object it generates.

    + +

    To debug the JIT:

    + +
    + 
    + bugpoint -run-jit -output=[correct output file] [bitcode file]  \
+          --tool-args -- [arguments to pass to lli]               \
+          --args -- [program arguments]
+
    +
    + +

    Similarly, to debug the LLC, one would run:

    + +
    + 
    + bugpoint -run-llc -output=[correct output file] [bitcode file]  \
+          --tool-args -- [arguments to pass to llc]               \
+          --args -- [program arguments]
+
    +
    + +

    Special note: if you are debugging MultiSource or SPEC tests that + already exist in the llvm/test hierarchy, there is an easier way to + debug the JIT, LLC, and CBE, using the pre-written Makefile targets, which + will pass the program options specified in the Makefiles:

    + +
    +

    + cd llvm/test/../../program
    + make bugpoint-jit +

    +
    + +

    At the end of a successful bugpoint run, you will be presented + with two bitcode files: a safe file which can be compiled with the C + backend and the test file which either LLC or the JIT + mis-codegenerates, and thus causes the error.

    + +

    To reproduce the error that bugpoint found, it is sufficient to do + the following:

    + +
      + +

    1. Regenerate the shared object from the safe bitcode file:

      + +
      +

      + llc -march=c safe.bc -o safe.c
      + gcc -shared safe.c -o safe.so +

      +
      2. + +

    2. If debugging LLC, compile test bitcode native and link with the shared + object:

      + +
      +

      + llc test.bc -o test.s -f
      + gcc test.s safe.so -o test.llc
      + ./test.llc [program options] +

      +
      3. + +

    3. If debugging the JIT, load the shared object and supply the test + bitcode:

      + +
      +

      lli -load=safe.so test.bc [program options]

      +
      4. + +
    + +
    + + +
    +
    + Valid CSS! + Valid HTML 4.01! + + Chris Lattner
    + The LLVM Compiler Infrastructure +
    + Last modified: $Date: 2008/02/12 06:05:03 $ +
    + + + Index: llvm-www/releases/2.2/docs/LangRef.html diff -c /dev/null llvm-www/releases/2.2/docs/LangRef.html:1.1 *** /dev/null Tue Feb 12 00:07:04 2008 --- llvm-www/releases/2.2/docs/LangRef.html Tue Feb 12 00:05:03 2008 *************** *** 0 **** --- 1,5338 ---- + + + + LLVM Assembly Language Reference Manual + + + + + + + + +
    LLVM Language Reference Manual
    +
      +
    1. Abstract
      2. +
    2. Introduction
      3. +
    3. Identifiers
      4. +
    4. High Level Structure +
        +
      1. Module Structure
        2. +
      2. Linkage Types
        3. +
      3. Calling Conventions
        4. +
      4. Global Variables
        5. +
      5. Functions
        6. +
      6. Aliases +
      7. Parameter Attributes
        8. +
      8. Garbage Collector Names
        9. +
      9. Module-Level Inline Assembly
        10. +
      10. Data Layout
        11. +
      +
      5. +
    5. Type System +
        +
      1. Type Classifications
        2. +
      2. Primitive Types +
          +
        1. Floating Point Types
          2. +
        2. Void Type
          3. +
        3. Label Type
          4. +
        +
        3. +
      3. Derived Types +
          +
        1. Integer Type
          2. +
        2. Array Type
          3. +
        3. Function Type
          4. +
        4. Pointer Type
          5. +
        5. Structure Type
          6. +
        6. Packed Structure Type
          7. +
        7. Vector Type
          8. +
        8. Opaque Type
          9. +
        +
        4. +
      +
      6. +
    6. Constants +
        +
      1. Simple Constants +
      2. Aggregate Constants +
      3. Global Variable and Function Addresses +
      4. Undefined Values +
      5. Constant Expressions +
      +
      7. +
    7. Other Values +
        +
      1. Inline Assembler Expressions +
      +
      8. +
    8. Instruction Reference +
        +
      1. Terminator Instructions +
          +
        1. 'ret' Instruction
          2. +
        2. 'br' Instruction
          3. +
        3. 'switch' Instruction
          4. +
        4. 'invoke' Instruction
          5. +
        5. 'unwind' Instruction
          6. +
        6. 'unreachable' Instruction
          7. +
        +
        2. +
      2. Binary Operations +
          +
        1. 'add' Instruction
          2. +
        2. 'sub' Instruction
          3. +
        3. 'mul' Instruction
          4. +
        4. 'udiv' Instruction
          5. +
        5. 'sdiv' Instruction
          6. +
        6. 'fdiv' Instruction
          7. +
        7. 'urem' Instruction
          8. +
        8. 'srem' Instruction
          9. +
        9. 'frem' Instruction
          10. +
        +
        3. +
      3. Bitwise Binary Operations +
          +
        1. 'shl' Instruction
          2. +
        2. 'lshr' Instruction
          3. +
        3. 'ashr' Instruction
          4. +
        4. 'and' Instruction
          5. +
        5. 'or' Instruction
          6. +
        6. 'xor' Instruction
          7. +
        +
        4. +
      4. Vector Operations +
          +
        1. 'extractelement' Instruction
          2. +
        2. 'insertelement' Instruction
          3. +
        3. 'shufflevector' Instruction
          4. +
        +
        5. +
      5. Memory Access and Addressing Operations +
          +
        1. 'malloc' Instruction
          2. +
        2. 'free' Instruction
          3. +
        3. 'alloca' Instruction
          4. +
        4. 'load' Instruction
          5. +
        5. 'store' Instruction
          6. +
        6. 'getelementptr' Instruction
          7. +
        +
        6. +
      6. Conversion Operations +
          +
        1. 'trunc .. to' Instruction
          2. +
        2. 'zext .. to' Instruction
          3. +
        3. 'sext .. to' Instruction
          4. +
        4. 'fptrunc .. to' Instruction
          5. +
        5. 'fpext .. to' Instruction
          6. +
        6. 'fptoui .. to' Instruction
          7. +
        7. 'fptosi .. to' Instruction
          8. +
        8. 'uitofp .. to' Instruction
          9. +
        9. 'sitofp .. to' Instruction
          10. +
        10. 'ptrtoint .. to' Instruction
          11. +
        11. 'inttoptr .. to' Instruction
          12. +
        12. 'bitcast .. to' Instruction
          13. +
        +
      7. Other Operations +
          +
        1. 'icmp' Instruction
          2. +
        2. 'fcmp' Instruction
          3. +
        3. 'phi' Instruction
          4. +
        4. 'select' Instruction
          5. +
        5. 'call' Instruction
          6. +
        6. 'va_arg' Instruction
          7. +
        +
        8. +
      +
      9. +
    9. Intrinsic Functions +
        +
      1. Variable Argument Handling Intrinsics +
          +
        1. 'llvm.va_start' Intrinsic
          2. +
        2. 'llvm.va_end' Intrinsic
          3. +
        3. 'llvm.va_copy' Intrinsic
          4. +
        +
        2. +
      2. Accurate Garbage Collection Intrinsics +
          +
        1. 'llvm.gcroot' Intrinsic
          2. +
        2. 'llvm.gcread' Intrinsic
          3. +
        3. 'llvm.gcwrite' Intrinsic
          4. +
        +
        3. +
      3. Code Generator Intrinsics +
          +
        1. 'llvm.returnaddress' Intrinsic
          2. +
        2. 'llvm.frameaddress' Intrinsic
          3. +
        3. 'llvm.stacksave' Intrinsic
          4. +
        4. 'llvm.stackrestore' Intrinsic
          5. +
        5. 'llvm.prefetch' Intrinsic
          6. +
        6. 'llvm.pcmarker' Intrinsic
          7. +
        7. llvm.readcyclecounter' Intrinsic
          8. +
        +
        4. +
      4. Standard C Library Intrinsics +
          +
        1. 'llvm.memcpy.*' Intrinsic
          2. +
        2. 'llvm.memmove.*' Intrinsic
          3. +
        3. 'llvm.memset.*' Intrinsic
          4. +
        4. 'llvm.sqrt.*' Intrinsic
          5. +
        5. 'llvm.powi.*' Intrinsic
          6. +
        6. 'llvm.sin.*' Intrinsic
          7. +
        7. 'llvm.cos.*' Intrinsic
          8. +
        8. 'llvm.pow.*' Intrinsic
          9. +
        +
        5. +
      5. Bit Manipulation Intrinsics +
          +
        1. 'llvm.bswap.*' Intrinsics
          2. +
        2. 'llvm.ctpop.*' Intrinsic
          3. +
        3. 'llvm.ctlz.*' Intrinsic
          4. +
        4. 'llvm.cttz.*' Intrinsic
          5. +
        5. 'llvm.part.select.*' Intrinsic
          6. +
        6. 'llvm.part.set.*' Intrinsic
          7. +
        +
        6. +
      6. Debugger intrinsics
        7. +
      7. Exception Handling intrinsics
        8. +
      8. Trampoline Intrinsic +
          +
        1. 'llvm.init.trampoline' Intrinsic
          2. +
        +
        9. +
      9. General intrinsics +
          +
        1. + llvm.var.annotation' Intrinsic
          2. +
        2. + llvm.annotation.*' Intrinsic
          3. +
        3. + llvm.trap' Intrinsic
          4. +
        +
        10. +
      +
      10. +
    + +
    +

    Written by Chris Lattner + and Vikram Adve

    +
    + + +
    Abstract
    + + +
    +

    This document is a reference manual for the LLVM assembly language. + LLVM is an SSA based representation that provides type safety, + low-level operations, flexibility, and the capability of representing + 'all' high-level languages cleanly. It is the common code + representation used throughout all phases of the LLVM compilation + strategy.

    +
    + + +
    Introduction
    + + +
    + +

    The LLVM code representation is designed to be used in three + different forms: as an in-memory compiler IR, as an on-disk bitcode + representation (suitable for fast loading by a Just-In-Time compiler), + and as a human readable assembly language representation. This allows + LLVM to provide a powerful intermediate representation for efficient + compiler transformations and analysis, while providing a natural means + to debug and visualize the transformations. The three different forms + of LLVM are all equivalent. This document describes the human readable + representation and notation.

    + +

    The LLVM representation aims to be light-weight and low-level + while being expressive, typed, and extensible at the same time. It + aims to be a "universal IR" of sorts, by being at a low enough level + that high-level ideas may be cleanly mapped to it (similar to how + microprocessors are "universal IR's", allowing many source languages to + be mapped to them). By providing type information, LLVM can be used as + the target of optimizations: for example, through pointer analysis, it + can be proven that a C automatic variable is never accessed outside of + the current function... allowing it to be promoted to a simple SSA + value instead of a memory location.

    + +
    + + +
    Well-Formedness
    + +
    + +

    It is important to note that this document describes 'well formed' + LLVM assembly language. There is a difference between what the parser + accepts and what is considered 'well formed'. For example, the + following instruction is syntactically okay, but not well formed:

    + +
    + 
    + %x = add i32 1, %x
+
    +
    + +

    ...because the definition of %x does not dominate all of + its uses. The LLVM infrastructure provides a verification pass that may + be used to verify that an LLVM module is well formed. This pass is + automatically run by the parser after parsing input assembly and by + the optimizer before it outputs bitcode. The violations pointed out + by the verifier pass indicate bugs in transformation passes or input to + the parser.

    +
    + + + + +
    Identifiers
    + + +
    + +

    LLVM identifiers come in two basic types: global and local. Global + identifiers (functions, global variables) begin with the @ character. Local + identifiers (register names, types) begin with the % character. Additionally, + there are three different formats for identifiers, for different purposes: + +

      +
    1. Named values are represented as a string of characters with their prefix. + For example, %foo, @DivisionByZero, %a.really.long.identifier. The actual + regular expression used is '[%@][a-zA-Z$._][a-zA-Z$._0-9]*'. + Identifiers which require other characters in their names can be surrounded + with quotes. In this way, anything except a " character can + be used in a named value.
      2. + +
    2. Unnamed values are represented as an unsigned numeric value with their + prefix. For example, %12, @2, %44.
      3. + +
    3. Constants, which are described in a section about + constants, below.
      4. +
    + +

    LLVM requires that values start with a prefix for two reasons: Compilers + don't need to worry about name clashes with reserved words, and the set of + reserved words may be expanded in the future without penalty. Additionally, + unnamed identifiers allow a compiler to quickly come up with a temporary + variable without having to avoid symbol table conflicts.

    + +

    Reserved words in LLVM are very similar to reserved words in other + languages. There are keywords for different opcodes + ('add', + 'bitcast', + 'ret', etc...), for primitive type names ('void', 'i32', etc...), + and others. These reserved words cannot conflict with variable names, because + none of them start with a prefix character ('%' or '@').

    + +

    Here is an example of LLVM code to multiply the integer variable + '%X' by 8:

    + +

    The easy way:

    + +
    + 
    + %result = mul i32 %X, 8
+
    +
    + +

    After strength reduction:

    + +
    + 
    + %result = shl i32 %X, i8 3
+
    +
    + +

    And the hard way:

    + +
    + 
    + add i32 %X, %X           ; yields {i32}:%0
+ add i32 %0, %0           ; yields {i32}:%1
+ %result = add i32 %1, %1
+
    +
    + +

    This last way of multiplying %X by 8 illustrates several + important lexical features of LLVM:

    + +
      + +
    1. Comments are delimited with a ';' and go until the end of + line.
      2. + +
    2. Unnamed temporaries are created when the result of a computation is not + assigned to a named value.
      3. + +
    3. Unnamed temporaries are numbered sequentially
      4. + +
    + +

    ...and it also shows a convention that we follow in this document. When + demonstrating instructions, we will follow an instruction with a comment that + defines the type and name of value produced. Comments are shown in italic + text.

    + +
    + + +
    High Level Structure
    + + + +
    Module Structure +
    + +
    + +

    LLVM programs are composed of "Module"s, each of which is a + translation unit of the input programs. Each module consists of + functions, global variables, and symbol table entries. Modules may be + combined together with the LLVM linker, which merges function (and + global variable) definitions, resolves forward declarations, and merges + symbol table entries. Here is an example of the "hello world" module:

    + +
    + 
    ; Declare the string constant as a global constant...
+ @.LC0 = internal constant [13 x i8] c"hello world\0A\00"          ; [13 x i8]*
+ 
+ ; External declaration of the puts function
+ declare i32 @puts(i8 *)                                            ; i32(i8 *)* 
+ 
+ ; Definition of main function
+ define i32 @main() {                                                 ; i32()* 
+         ; Convert [13x i8 ]* to i8  *...
+         %cast210 = getelementptr [13 x i8 ]* @.LC0, i64 0, i64 0 ; i8 *
+ 
+         ; Call puts function to write out the string to stdout...
+         call i32 @puts(i8 * %cast210)                              ; i32
+         ret i32 0
    }
    
+
    +
    + +

    This example is made up of a global variable + named ".LC0", an external declaration of the "puts" + function, and a function definition + for "main".

    + +

    In general, a module is made up of a list of global values, + where both functions and global variables are global values. Global values are + represented by a pointer to a memory location (in this case, a pointer to an + array of char, and a pointer to a function), and have one of the following linkage types.

    + +
    + + +
    + Linkage Types +
    + +
    + +

    + All Global Variables and Functions have one of the following types of linkage: +

    + +
    + +
    internal
    + +
    Global values with internal linkage are only directly accessible by + objects in the current module. In particular, linking code into a module with + an internal global value may cause the internal to be renamed as necessary to + avoid collisions. Because the symbol is internal to the module, all + references can be updated. This corresponds to the notion of the + 'static' keyword in C. +
    + +
    linkonce:
    + +
    Globals with "linkonce" linkage are merged with other globals of + the same name when linkage occurs. This is typically used to implement + inline functions, templates, or other code which must be generated in each + translation unit that uses it. Unreferenced linkonce globals are + allowed to be discarded. +
    + +
    weak:
    + +
    "weak" linkage is exactly the same as linkonce linkage, + except that unreferenced weak globals may not be discarded. This is + used for globals that may be emitted in multiple translation units, but that + are not guaranteed to be emitted into every translation unit that uses them. + One example of this are common globals in C, such as "int X;" at + global scope. +
    + +
    appending:
    + +
    "appending" linkage may only be applied to global variables of + pointer to array type. When two global variables with appending linkage are + linked together, the two global arrays are appended together. This is the + LLVM, typesafe, equivalent of having the system linker append together + "sections" with identical names when .o files are linked. +
    + +
    extern_weak:
    +
    The semantics of this linkage follow the ELF model: the symbol is weak + until linked, if not linked, the symbol becomes null instead of being an + undefined reference. +
    + +
    externally visible:
    + +
    If none of the above identifiers are used, the global is externally + visible, meaning that it participates in linkage and can be used to resolve + external symbol references. +
    +
    + +

    + The next two types of linkage are targeted for Microsoft Windows platform + only. They are designed to support importing (exporting) symbols from (to) + DLLs. +

    + +
    +
    dllimport:
    + +
    "dllimport" linkage causes the compiler to reference a function + or variable via a global pointer to a pointer that is set up by the DLL + exporting the symbol. On Microsoft Windows targets, the pointer name is + formed by combining _imp__ and the function or variable name. +
    + +
    dllexport:
    + +
    "dllexport" linkage causes the compiler to provide a global + pointer to a pointer in a DLL, so that it can be referenced with the + dllimport attribute. On Microsoft Windows targets, the pointer + name is formed by combining _imp__ and the function or variable + name. +
    + +
    + +

    For example, since the ".LC0" + variable is defined to be internal, if another module defined a ".LC0" + variable and was linked with this one, one of the two would be renamed, + preventing a collision. Since "main" and "puts" are + external (i.e., lacking any linkage declarations), they are accessible + outside of the current module.

    +

    It is illegal for a function declaration + to have any linkage type other than "externally visible", dllimport, + or extern_weak.

    +

    Aliases can have only external, internal and weak + linkages. +

    + + +
    + Calling Conventions +
    + +
    + +

    LLVM functions, calls + and invokes can all have an optional calling convention + specified for the call. The calling convention of any pair of dynamic + caller/callee must match, or the behavior of the program is undefined. The + following calling conventions are supported by LLVM, and more may be added in + the future:

    + +
    +
    "ccc" - The C calling convention:
    + +
    This calling convention (the default if no other calling convention is + specified) matches the target C calling conventions. This calling convention + supports varargs function calls and tolerates some mismatch in the declared + prototype and implemented declaration of the function (as does normal C). +
    + +
    "fastcc" - The fast calling convention:
    + +
    This calling convention attempts to make calls as fast as possible + (e.g. by passing things in registers). This calling convention allows the + target to use whatever tricks it wants to produce fast code for the target, + without having to conform to an externally specified ABI. Implementations of + this convention should allow arbitrary tail call optimization to be supported. + This calling convention does not support varargs and requires the prototype of + all callees to exactly match the prototype of the function definition. +
    + +
    "coldcc" - The cold calling convention:
    + +
    This calling convention attempts to make code in the caller as efficient + as possible under the assumption that the call is not commonly executed. As + such, these calls often preserve all registers so that the call does not break + any live ranges in the caller side. This calling convention does not support + varargs and requires the prototype of all callees to exactly match the + prototype of the function definition. +
    + +
    "cc <n>" - Numbered convention:
    + +
    Any calling convention may be specified by number, allowing + target-specific calling conventions to be used. Target specific calling + conventions start at 64. +
    +
    + +

    More calling conventions can be added/defined on an as-needed basis, to + support pascal conventions or any other well-known target-independent + convention.

    + +
    + + +
    + Visibility Styles +
    + +
    + +

    + All Global Variables and Functions have one of the following visibility styles: +

    + +
    +
    "default" - Default style:
    + +
    On ELF, default visibility means that the declaration is visible to other + modules and, in shared libraries, means that the declared entity may be + overridden. On Darwin, default visibility means that the declaration is + visible to other modules. Default visibility corresponds to "external + linkage" in the language. +
    + +
    "hidden" - Hidden style:
    + +
    Two declarations of an object with hidden visibility refer to the same + object if they are in the same shared object. Usually, hidden visibility + indicates that the symbol will not be placed into the dynamic symbol table, + so no other module (executable or shared library) can reference it + directly. +
    + +
    "protected" - Protected style:
    + +
    On ELF, protected visibility indicates that the symbol will be placed in + the dynamic symbol table, but that references within the defining module will + bind to the local symbol. That is, the symbol cannot be overridden by another + module. +
    +
    + +
    + + +
    + Global Variables +
    + +
    + +

    Global variables define regions of memory allocated at compilation time + instead of run-time. Global variables may optionally be initialized, may have + an explicit section to be placed in, and may have an optional explicit alignment + specified. A variable may be defined as "thread_local", which means that it + will not be shared by threads (each thread will have a separated copy of the + variable). A variable may be defined as a global "constant," which indicates + that the contents of the variable will never be modified (enabling better + optimization, allowing the global data to be placed in the read-only section of + an executable, etc). Note that variables that need runtime initialization + cannot be marked "constant" as there is a store to the variable.

    + +

    + LLVM explicitly allows declarations of global variables to be marked + constant, even if the final definition of the global is not. This capability + can be used to enable slightly better optimization of the program, but requires + the language definition to guarantee that optimizations based on the + 'constantness' are valid for the translation units that do not include the + definition. +

    + +

    As SSA values, global variables define pointer values that are in + scope (i.e. they dominate) all basic blocks in the program. Global + variables always define a pointer to their "content" type because they + describe a region of memory, and all memory objects in LLVM are + accessed through pointers.

    + +

    A global variable may be declared to reside in a target-specifc numbered + address space. For targets that support them, address spaces may affect how + optimizations are performed and/or what target instructions are used to access + the variable. The default address space is zero. The address space qualifier + must precede any other attributes.

    + +

    LLVM allows an explicit section to be specified for globals. If the target + supports it, it will emit globals to the section specified.

    + +

    An explicit alignment may be specified for a global. If not present, or if + the alignment is set to zero, the alignment of the global is set by the target + to whatever it feels convenient. If an explicit alignment is specified, the + global is forced to have at least that much alignment. All alignments must be + a power of 2.

    + +

    For example, the following defines a global in a numbered address space with + an initializer, section, and alignment:

    + +
    + 
    + @G = constant float 1.0 addrspace(5), section "foo", align 4
+
    +
    + +
    + + + +
    + Functions +
    + +
    + +

    LLVM function definitions consist of the "define" keyord, + an optional linkage type, an optional + visibility style, an optional + calling convention, a return type, an optional + parameter attribute for the return type, a function + name, a (possibly empty) argument list (each with optional + parameter attributes), an optional section, an + optional alignment, an optional garbage collector name, an + opening curly brace, a list of basic blocks, and a closing curly brace. + + LLVM function declarations consist of the "declare" keyword, an + optional linkage type, an optional + visibility style, an optional + calling convention, a return type, an optional + parameter attribute for the return type, a function + name, a possibly empty list of arguments, an optional alignment, and an optional + garbage collector name.

    + +

    A function definition contains a list of basic blocks, forming the CFG for + the function. Each basic block may optionally start with a label (giving the + basic block a symbol table entry), contains a list of instructions, and ends + with a terminator instruction (such as a branch or + function return).

    + +

    The first basic block in a function is special in two ways: it is immediately + executed on entrance to the function, and it is not allowed to have predecessor + basic blocks (i.e. there can not be any branches to the entry block of a + function). Because the block can have no predecessors, it also cannot have any + PHI nodes.

    + +

    LLVM allows an explicit section to be specified for functions. If the target + supports it, it will emit functions to the section specified.

    + +

    An explicit alignment may be specified for a function. If not present, or if + the alignment is set to zero, the alignment of the function is set by the target + to whatever it feels convenient. If an explicit alignment is specified, the + function is forced to have at least that much alignment. All alignments must be + a power of 2.

    + +
    + + + +
    + Aliases +
    +
    +

    Aliases act as "second name" for the aliasee value (which can be either + function or global variable or bitcast of global value). Aliases may have an + optional linkage type, and an + optional visibility style.

    + +
    Syntax:
    + +
    + 
    + @<Name> = [Linkage] [Visibility] alias <AliaseeTy> @<Aliasee>
+
    +
    + +
    + + + + +
    Parameter Attributes
    +
    +

    The return type and each parameter of a function type may have a set of + parameter attributes associated with them. Parameter attributes are + used to communicate additional information about the result or parameters of + a function. Parameter attributes are considered to be part of the function, + not of the function type, so functions with different parameter attributes + can have the same function type.

    + +

    Parameter attributes are simple keywords that follow the type specified. If + multiple parameter attributes are needed, they are space separated. For + example:

    + +
    + 
    + declare i32 @printf(i8* noalias , ...) nounwind
+ declare i32 @atoi(i8*) nounwind readonly
+
    +
    + +

    Note that any attributes for the function result (nounwind, + readonly) come immediately after the argument list.

    + +

    Currently, only the following parameter attributes are defined:

    +
    +
    zeroext
    +
    This indicates that the parameter should be zero extended just before + a call to this function.
    + +
    signext
    +
    This indicates that the parameter should be sign extended just before + a call to this function.
    + +
    inreg
    +
    This indicates that the parameter should be placed in register (if + possible) during assembling function call. Support for this attribute is + target-specific
    + +
    byval
    +
    This indicates that the pointer parameter should really be passed by + value to the function. The attribute implies that a hidden copy of the + pointee is made between the caller and the callee, so the callee is unable + to modify the value in the callee. This attribute is only valid on llvm + pointer arguments. It is generally used to pass structs and arrays by + value, but is also valid on scalars (even though this is silly).
    + +
    sret
    +
    This indicates that the parameter specifies the address of a structure + that is the return value of the function in the source program.
    + +
    noalias
    +
    This indicates that the parameter not alias any other object or any + other "noalias" objects during the function call. + +
    noreturn
    +
    This function attribute indicates that the function never returns. This + indicates to LLVM that every call to this function should be treated as if + an unreachable instruction immediately followed the call.
    + +
    nounwind
    +
    This function attribute indicates that the function type does not use + the unwind instruction and does not allow stack unwinding to propagate + through it.
    + +
    nest
    +
    This indicates that the parameter can be excised using the + trampoline intrinsics.
    +
    readonly
    +
    This function attribute indicates that the function has no side-effects + except for producing a return value or throwing an exception. The value + returned must only depend on the function arguments and/or global variables. + It may use values obtained by dereferencing pointers.
    +
    readnone
    +
    A readnone function has the same restrictions as a readonly + function, but in addition it is not allowed to dereference any pointer arguments + or global variables. +
    + +
    + + +
    + Garbage Collector Names +
    + +
    +

    Each function may specify a garbage collector name, which is simply a + string.

    + + 
    define void @f() gc "name" { ...
    + +

    The compiler declares the supported values of name. Specifying a + collector which will cause the compiler to alter its output in order to support + the named garbage collection algorithm.

    +
    + + +
    + Module-Level Inline Assembly +
    + +
    +

    + Modules may contain "module-level inline asm" blocks, which corresponds to the + GCC "file scope inline asm" blocks. These blocks are internally concatenated by + LLVM and treated as a single unit, but may be separated in the .ll file if + desired. The syntax is very simple: +

    + +
    + 
    + module asm "inline asm code goes here"
+ module asm "more can go here"
+
    +
    + +

    The strings can contain any character by escaping non-printable characters. + The escape sequence used is simply "\xx" where "xx" is the two digit hex code + for the number. +

    + +

    + The inline asm code is simply printed to the machine code .s file when + assembly code is generated. +

    +
    + + +
    + Data Layout +
    + +
    +

    A module may specify a target specific data layout string that specifies how + data is to be laid out in memory. The syntax for the data layout is simply:

    + 
        target datalayout = "layout specification"
    +

    The layout specification consists of a list of specifications + separated by the minus sign character ('-'). Each specification starts with a + letter and may include other information after the letter to define some + aspect of the data layout. The specifications accepted are as follows:

    +
    +
    E
    +
    Specifies that the target lays out data in big-endian form. That is, the + bits with the most significance have the lowest address location.
    +
    e
    +
    Specifies that hte target lays out data in little-endian form. That is, + the bits with the least significance have the lowest address location.
    +
    p:size:abi:pref
    +
    This specifies the size of a pointer and its abi and + preferred alignments. All sizes are in bits. Specifying the pref + alignment is optional. If omitted, the preceding : should be omitted + too.
    +
    isize:abi:pref
    +
    This specifies the alignment for an integer type of a given bit + size. The value of size must be in the range [1,2^23).
    +
    vsize:abi:pref
    +
    This specifies the alignment for a vector type of a given bit + size.
    +
    fsize:abi:pref
    +
    This specifies the alignment for a floating point type of a given bit + size. The value of size must be either 32 (float) or 64 + (double).
    +
    asize:abi:pref
    +
    This specifies the alignment for an aggregate type of a given bit + size.
    +
    +

    When constructing the data layout for a given target, LLVM starts with a + default set of specifications which are then (possibly) overriden by the + specifications in the datalayout keyword. The default specifications + are given in this list:

    +
      +
    • E - big endian
      • +
    • p:32:64:64 - 32-bit pointers with 64-bit alignment
      • +
    • i1:8:8 - i1 is 8-bit (byte) aligned
      • +
    • i8:8:8 - i8 is 8-bit (byte) aligned
      • +
    • i16:16:16 - i16 is 16-bit aligned
      • +
    • i32:32:32 - i32 is 32-bit aligned
      • +
    • i64:32:64 - i64 has abi alignment of 32-bits but preferred + alignment of 64-bits
      • +
    • f32:32:32 - float is 32-bit aligned
      • +
    • f64:64:64 - double is 64-bit aligned
      • +
    • v64:64:64 - 64-bit vector is 64-bit aligned
      • +
    • v128:128:128 - 128-bit vector is 128-bit aligned
      • +
    • a0:0:1 - aggregates are 8-bit aligned
      • +
    +

    When llvm is determining the alignment for a given type, it uses the + following rules: +

      +
    1. If the type sought is an exact match for one of the specifications, that + specification is used.
      2. +
    2. If no match is found, and the type sought is an integer type, then the + smallest integer type that is larger than the bitwidth of the sought type is + used. If none of the specifications are larger than the bitwidth then the the + largest integer type is used. For example, given the default specifications + above, the i7 type will use the alignment of i8 (next largest) while both + i65 and i256 will use the alignment of i64 (largest specified).
      3. +
    3. If no match is found, and the type sought is a vector type, then the + largest vector type that is smaller than the sought vector type will be used + as a fall back. This happens because <128 x double> can be implemented in + terms of 64 <2 x double>, for example.
      4. +
    +
    + + +
    Type System
    + + +
    + +

    The LLVM type system is one of the most important features of the + intermediate representation. Being typed enables a number of + optimizations to be performed on the IR directly, without having to do + extra analyses on the side before the transformation. A strong type + system makes it easier to read the generated code and enables novel + analyses and transformations that are not feasible to perform on normal + three address code representations.

    + +
    + + +
    Type + Classifications
    +
    +

    The types fall into a few useful + classifications:

    + + + + + + + + + + + + + + + + + + + + + + + + +
    ClassificationTypes
    integeri1, i2, i3, ... i8, ... i16, ... i32, ... i64, ...
    floating pointfloat, double, x86_fp80, fp128, ppc_fp128
    first classinteger, + floating point, + pointer, + vector +
    primitivelabel, + void, + integer, + floating point.
    derivedinteger, + array, + function, + pointer, + structure, + packed structure, + vector, + opaque. +
    + +

    The first class types are perhaps the + most important. Values of these types are the only ones which can be + produced by instructions, passed as arguments, or used as operands to + instructions. This means that all structures and arrays must be + manipulated either by pointer or by component.

    +
    + + +
    Primitive Types
    + +
    +

    The primitive types are the fundamental building blocks of the LLVM + system.

    + +
    + + +
    Floating Point Types
    + +
    + + + + + + + + + +
    TypeDescription
    float32-bit floating point value
    double64-bit floating point value
    fp128128-bit floating point value (112-bit mantissa)
    x86_fp8080-bit floating point value (X87)
    ppc_fp128128-bit floating point value (two 64-bits)
    +
    + + +
    Void Type
    + +
    +
    Overview:
    +

    The void type does not represent any value and has no size.

    + +
    Syntax:
    + + 
    +   void
+
    +
    + + +
    Label Type
    + +
    +
    Overview:
    +

    The label type represents code labels.

    + +
    Syntax:
    + + 
    +   label
+
    +
    + + + +
    Derived Types
    + +
    + +

    The real power in LLVM comes from the derived types in the system. + This is what allows a programmer to represent arrays, functions, + pointers, and other useful types. Note that these derived types may be + recursive: For example, it is possible to have a two dimensional array.

    + +
    + + +
    Integer Type
    + +
    + +
    Overview:
    +

    The integer type is a very simple derived type that simply specifies an + arbitrary bit width for the integer type desired. Any bit width from 1 bit to + 2^23-1 (about 8 million) can be specified.

    + +
    Syntax:
    + + 
    +   iN
+
    + +

    The number of bits the integer will occupy is specified by the N + value.

    + +
    Examples:
    + + + + + + + + + + + + + +
    i1a single-bit integer.
    i32a 32-bit integer.
    i1942652a really big integer of over 1 million bits.
    +
    + + +
    Array Type
    + +
    + +
    Overview:
    + +

    The array type is a very simple derived type that arranges elements + sequentially in memory. The array type requires a size (number of + elements) and an underlying data type.

    + +
    Syntax:
    + + 
    +   [<# elements> x <elementtype>]
+
    + +

    The number of elements is a constant integer value; elementtype may + be any type with a size.

    + +
    Examples:
    + + + + + + + + + + + + + +
    [40 x i32]Array of 40 32-bit integer values.
    [41 x i32]Array of 41 32-bit integer values.
    [4 x i8]Array of 4 8-bit integer values.
    +

    Here are some examples of multidimensional arrays:

    + + + + + + + + + + + + + +
    [3 x [4 x i32]]3x4 array of 32-bit integer values.
    [12 x [10 x float]]12x10 array of single precision floating point values.
    [2 x [3 x [4 x i16]]]2x3x4 array of 16-bit integer values.
    + +

    Note that 'variable sized arrays' can be implemented in LLVM with a zero + length array. Normally, accesses past the end of an array are undefined in + LLVM (e.g. it is illegal to access the 5th element of a 3 element array). + As a special case, however, zero length arrays are recognized to be variable + length. This allows implementation of 'pascal style arrays' with the LLVM + type "{ i32, [0 x float]}", for example.

    + +
    + + +
    Function Type
    +
    +
    Overview:
    +

    The function type can be thought of as a function signature. It + consists of a return type and a list of formal parameter types. + Function types are usually used to build virtual function tables + (which are structures of pointers to functions), for indirect function + calls, and when defining a function.

    +

    + The return type of a function type cannot be an aggregate type. +

    +
    Syntax:
    + 
      <returntype> (<parameter list>)
    +

    ...where '<parameter list>' is a comma-separated list of type + specifiers. Optionally, the parameter list may include a type ..., + which indicates that the function takes a variable number of arguments. + Variable argument functions can access their arguments with the variable argument handling intrinsic functions.

    +
    Examples:
    + + + + + + + + + + + +
    i32 (i32)function taking an i32, returning an i32 +
    float (i16 signext, i32 *) * + Pointer to a function that takes + an i16 that should be sign extended and a + pointer to i32, returning + float. +
    i32 (i8*, ...)A vararg function that takes at least one + pointer to i8 (char in C), + which returns an integer. This is the signature for printf in + LLVM. +
    + +
    + +
    Structure Type
    +
    +
    Overview:
    +

    The structure type is used to represent a collection of data members + together in memory. The packing of the field types is defined to match + the ABI of the underlying processor. The elements of a structure may + be any type that has a size.

    +

    Structures are accessed using 'load + and 'store' by getting a pointer to a + field with the 'getelementptr' + instruction.

    +
    Syntax:
    + 
      { <type list> }
    +
    Examples:
    + + + + + + + + +
    { i32, i32, i32 }A triple of three i32 values
    { float, i32 (i32) * }A pair, where the first element is a float and the + second element is a pointer to a + function that takes an i32, returning + an i32.
    +
    + + +
    Packed Structure Type +
    +
    +
    Overview:
    +

    The packed structure type is used to represent a collection of data members + together in memory. There is no padding between fields. Further, the alignment + of a packed structure is 1 byte. The elements of a packed structure may + be any type that has a size.

    +

    Structures are accessed using 'load + and 'store' by getting a pointer to a + field with the 'getelementptr' + instruction.

    +
    Syntax:
    + 
      < { <type list> } >
    +
    Examples:
    + + + + + + + + +
    < { i32, i32, i32 } >A triple of three i32 values
    < { float, i32 (i32)* } >A pair, where the first element is a float and the + second element is a pointer to a + function that takes an i32, returning + an i32.
    +
    + + +
    Pointer Type
    +
    +
    Overview:
    +

    As in many languages, the pointer type represents a pointer or + reference to another object, which must live in memory. Pointer types may have + an optional address space attribute defining the target-specific numbered + address space where the pointed-to object resides. The default address space is + zero.

    +
    Syntax:
    + 
      <type> *
    +
    Examples:
    + + + + + + + + + + + + + +
    [4x i32]*A pointer to array of four i32 values.
    i32 (i32 *) * A pointer to a function that takes an i32*, returning an + i32.
    i32 addrspace(5)*A pointer to an i32 value + that resides in address space #5.
    +
    + + +
    Vector Type
    +
    + +
    Overview:
    + +

    A vector type is a simple derived type that represents a vector + of elements. Vector types are used when multiple primitive data + are operated in parallel using a single instruction (SIMD). + A vector type requires a size (number of + elements) and an underlying primitive data type. Vectors must have a power + of two length (1, 2, 4, 8, 16 ...). Vector types are + considered first class.

    + +
    Syntax:
    + + 
    +   < <# elements> x <elementtype> >
+
    + +

    The number of elements is a constant integer value; elementtype may + be any integer or floating point type.

    + +
    Examples:
    + + + + + + + + + + + + + + +
    <4 x i32>Vector of 4 32-bit integer values.
    <8 x float>Vector of 8 32-bit floating-point values.
    <2 x i64>Vector of 2 64-bit integer values.
    +
    + + +
    Opaque Type
    +
    + +
    Overview:
    + +

    Opaque types are used to represent unknown types in the system. This + corresponds (for example) to the C notion of a forward declared structure type. + In LLVM, opaque types can eventually be resolved to any type (not just a + structure type).

    + +
    Syntax:
    + + 
    +   opaque
+
    + +
    Examples:
    + + + + + + +
    opaqueAn opaque type.
    +
    + + + +
    Constants
    + + +
    + +

    LLVM has several different basic types of constants. This section describes + them all and their syntax.

    + +
    + + +
    Simple Constants
    + +
    + +
    +
    Boolean constants
    + +
    The two strings 'true' and 'false' are both valid + constants of the i1 type. +
    + +
    Integer constants
    + +
    Standard integers (such as '4') are constants of the integer type. Negative numbers may be used with + integer types. +
    + +
    Floating point constants
    + +
    Floating point constants use standard decimal notation (e.g. 123.421), + exponential notation (e.g. 1.23421e+2), or a more precise hexadecimal + notation (see below). Floating point constants must have a floating point type.
    + +
    Null pointer constants
    + +
    The identifier 'null' is recognized as a null pointer constant + and must be of pointer type.
    + +
    + +

    The one non-intuitive notation for constants is the optional hexadecimal form + of floating point constants. For example, the form 'double + 0x432ff973cafa8000' is equivalent to (but harder to read than) 'double + 4.5e+15'. The only time hexadecimal floating point constants are required + (and the only time that they are generated by the disassembler) is when a + floating point constant must be emitted but it cannot be represented as a + decimal floating point number. For example, NaN's, infinities, and other + special values are represented in their IEEE hexadecimal format so that + assembly and disassembly do not cause any bits to change in the constants.

    + +
    + + +
    Aggregate Constants +
    + +
    +

    Aggregate constants arise from aggregation of simple constants + and smaller aggregate constants.

    + +
    +
    Structure constants
    + +
    Structure constants are represented with notation similar to structure + type definitions (a comma separated list of elements, surrounded by braces + ({})). For example: "{ i32 4, float 17.0, i32* @G }", + where "@G" is declared as "@G = external global i32". Structure constants + must have structure type, and the number and + types of elements must match those specified by the type. +
    + +
    Array constants
    + +
    Array constants are represented with notation similar to array type + definitions (a comma separated list of elements, surrounded by square brackets + ([])). For example: "[ i32 42, i32 11, i32 74 ]". Array + constants must have array type, and the number and + types of elements must match those specified by the type. +
    + +
    Vector constants
    + +
    Vector constants are represented with notation similar to vector type + definitions (a comma separated list of elements, surrounded by + less-than/greater-than's (<>)). For example: "< i32 42, + i32 11, i32 74, i32 100 >". Vector constants must have vector type, and the number and types of elements must + match those specified by the type. +
    + +
    Zero initialization
    + +
    The string 'zeroinitializer' can be used to zero initialize a + value to zero of any type, including scalar and aggregate types. + This is often used to avoid having to print large zero initializers (e.g. for + large arrays) and is always exactly equivalent to using explicit zero + initializers. +
    +
    + +
    + + +
    + Global Variable and Function Addresses +
    + +
    + +

    The addresses of global variables and functions are always implicitly valid (link-time) + constants. These constants are explicitly referenced when the identifier for the global is used and always have pointer type. For example, the following is a legal LLVM + file:

    + +
    + 
    + @X = global i32 17
+ @Y = global i32 42
+ @Z = global [2 x i32*] [ i32* @X, i32* @Y ]
+
    +
    + +
    + + +
    Undefined Values
    +
    +

    The string 'undef' is recognized as a type-less constant that has + no specific value. Undefined values may be of any type and be used anywhere + a constant is permitted.

    + +

    Undefined values indicate to the compiler that the program is well defined + no matter what value is used, giving the compiler more freedom to optimize. +

    +
    + + +
    Constant Expressions +
    + +
    + +

    Constant expressions are used to allow expressions involving other constants + to be used as constants. Constant expressions may be of any first class type and may involve any LLVM operation + that does not have side effects (e.g. load and call are not supported). The + following is the syntax for constant expressions:

    + +
    +
    trunc ( CST to TYPE )
    +
    Truncate a constant to another type. The bit size of CST must be larger + than the bit size of TYPE. Both types must be integers.
    + +
    zext ( CST to TYPE )
    +
    Zero extend a constant to another type. The bit size of CST must be + smaller or equal to the bit size of TYPE. Both types must be integers.
    + +
    sext ( CST to TYPE )
    +
    Sign extend a constant to another type. The bit size of CST must be + smaller or equal to the bit size of TYPE. Both types must be integers.
    + +
    fptrunc ( CST to TYPE )
    +
    Truncate a floating point constant to another floating point type. The + size of CST must be larger than the size of TYPE. Both types must be + floating point.
    + +
    fpext ( CST to TYPE )
    +
    Floating point extend a constant to another type. The size of CST must be + smaller or equal to the size of TYPE. Both types must be floating point.
    + +
    fptoui ( CST to TYPE )
    +
    Convert a floating point constant to the corresponding unsigned integer + constant. TYPE must be a scalar or vector integer type. CST must be of scalar + or vector floating point type. Both CST and TYPE must be scalars, or vectors + of the same number of elements. If the value won't fit in the integer type, + the results are undefined.
    + +
    fptosi ( CST to TYPE )
    +
    Convert a floating point constant to the corresponding signed integer + constant. TYPE must be a scalar or vector integer type. CST must be of scalar + or vector floating point type. Both CST and TYPE must be scalars, or vectors + of the same number of elements. If the value won't fit in the integer type, + the results are undefined.
    + +
    uitofp ( CST to TYPE )
    +
    Convert an unsigned integer constant to the corresponding floating point + constant. TYPE must be a scalar or vector floating point type. CST must be of + scalar or vector integer type. Both CST and TYPE must be scalars, or vectors + of the same number of elements. If the value won't fit in the floating point + type, the results are undefined.
    + +
    sitofp ( CST to TYPE )
    +
    Convert a signed integer constant to the corresponding floating point + constant. TYPE must be a scalar or vector floating point type. CST must be of + scalar or vector integer type. Both CST and TYPE must be scalars, or vectors + of the same number of elements. If the value won't fit in the floating point + type, the results are undefined.
    + +
    ptrtoint ( CST to TYPE )
    +
    Convert a pointer typed constant to the corresponding integer constant + TYPE must be an integer type. CST must be of pointer type. The CST value is + zero extended, truncated, or unchanged to make it fit in TYPE.
    + +
    inttoptr ( CST to TYPE )
    +
    Convert a integer constant to a pointer constant. TYPE must be a + pointer type. CST must be of integer type. The CST value is zero extended, + truncated, or unchanged to make it fit in a pointer size. This one is + really dangerous!
    + +
    bitcast ( CST to TYPE )
    +
    Convert a constant, CST, to another TYPE. The size of CST and TYPE must be + identical (same number of bits). The conversion is done as if the CST value + was stored to memory and read back as TYPE. In other words, no bits change + with this operator, just the type. This can be used for conversion of + vector types to any other type, as long as they have the same bit width. For + pointers it is only valid to cast to another pointer type. +
    + +
    getelementptr ( CSTPTR, IDX0, IDX1, ... )
    + +
    Perform the getelementptr operation on + constants. As with the getelementptr + instruction, the index list may have zero or more indexes, which are required + to make sense for the type of "CSTPTR".
    + +
    select ( COND, VAL1, VAL2 )
    + +
    Perform the select operation on + constants.
    + +
    icmp COND ( VAL1, VAL2 )
    +
    Performs the icmp operation on constants.
    + +
    fcmp COND ( VAL1, VAL2 )
    +
    Performs the fcmp operation on constants.
    + +
    extractelement ( VAL, IDX )
    + +
    Perform the extractelement + operation on constants. + +
    insertelement ( VAL, ELT, IDX )
    + +
    Perform the insertelement + operation on constants.
    + + +
    shufflevector ( VEC1, VEC2, IDXMASK )
    + +
    Perform the shufflevector + operation on constants.
    + +
    OPCODE ( LHS, RHS )
    + +
    Perform the specified operation of the LHS and RHS constants. OPCODE may + be any of the binary or bitwise + binary operations. The constraints on operands are the same as those for + the corresponding instruction (e.g. no bitwise operations on floating point + values are allowed).
    +
    +
    + + +
    Other Values
    + + + +
    + Inline Assembler Expressions +
    + +
    + +

    + LLVM supports inline assembler expressions (as opposed to + Module-Level Inline Assembly) through the use of a special value. This + value represents the inline assembler as a string (containing the instructions + to emit), a list of operand constraints (stored as a string), and a flag that + indicates whether or not the inline asm expression has side effects. An example + inline assembler expression is: +

    + +
    + 
    + i32 (i32) asm "bswap $0", "=r,r"
+
    +
    + +

    + Inline assembler expressions may only be used as the callee operand of + a call instruction. Thus, typically we have: +

    + +
    + 
    + %X = call i32 asm "bswap $0", "=r,r"(i32 %Y)
+
    +
    + +

    + Inline asms with side effects not visible in the constraint list must be marked + as having side effects. This is done through the use of the + 'sideeffect' keyword, like so: +

    + +
    + 
    + call void asm sideeffect "eieio", ""()
+
    +
    + +

    TODO: The format of the asm and constraints string still need to be + documented here. Constraints on what can be done (e.g. duplication, moving, etc + need to be documented). +

    + +
    + + +
    Instruction Reference
    + + +
    + +

    The LLVM instruction set consists of several different + classifications of instructions: terminator + instructions, binary instructions, + bitwise binary instructions, memory instructions, and other + instructions.

    + +
    + + +
    Terminator + Instructions
    + +
    + +

    As mentioned previously, every + basic block in a program ends with a "Terminator" instruction, which + indicates which block should be executed after the current block is + finished. These terminator instructions typically yield a 'void' + value: they produce control flow, not values (the one exception being + the 'invoke' instruction).

    +

    There are six different terminator instructions: the 'ret' instruction, the 'br' + instruction, the 'switch' instruction, + the 'invoke' instruction, the 'unwind' instruction, and the 'unreachable' instruction.

    + +
    + + +
    'ret' + Instruction
    +
    +
    Syntax:
    + 
      ret <type> <value>       ; Return a value from a non-void function
+   ret void                 ; Return from void function
+
    +
    Overview:
    +

    The 'ret' instruction is used to return control flow (and a + value) from a function back to the caller.

    +

    There are two forms of the 'ret' instruction: one that + returns a value and then causes control flow, and one that just causes + control flow to occur.

    +
    Arguments:
    +

    The 'ret' instruction may return any 'first class' type. Notice that a function is + not well formed if there exists a 'ret' + instruction inside of the function that returns a value that does not + match the return type of the function.

    +
    Semantics:
    +

    When the 'ret' instruction is executed, control flow + returns back to the calling function's context. If the caller is a "call" instruction, execution continues at + the instruction after the call. If the caller was an "invoke" instruction, execution continues + at the beginning of the "normal" destination block. If the instruction + returns a value, that value shall set the call or invoke instruction's + return value.

    +
    Example:
    + 
      ret i32 5                       ; Return an integer value of 5
+   ret void                        ; Return from a void function
+
    +
    + +
    'br' Instruction
    +
    +
    Syntax:
    + 
      br i1 <cond>, label <iftrue>, label <iffalse>
      br label <dest>          ; Unconditional branch
+
    +
    Overview:
    +

    The 'br' instruction is used to cause control flow to + transfer to a different basic block in the current function. There are + two forms of this instruction, corresponding to a conditional branch + and an unconditional branch.

    +
    Arguments:
    +

    The conditional branch form of the 'br' instruction takes a + single 'i1' value and two 'label' values. The + unconditional form of the 'br' instruction takes a single + 'label' value as a target.

    +
    Semantics:
    +

    Upon execution of a conditional 'br' instruction, the 'i1' + argument is evaluated. If the value is true, control flows + to the 'iftrue' label argument. If "cond" is false, + control flows to the 'iffalse' label argument.

    +
    Example:
    + 
    Test:
      %cond = icmp eq, i32 %a, %b
      br i1 %cond, label %IfEqual, label %IfUnequal
    IfEqual:
      ret i32 1
    IfUnequal:
      ret i32 0
    +
    + +
    + 'switch' Instruction +
    + +
    +
    Syntax:
    + + 
    +   switch <intty> <value>, label <defaultdest> [ <intty> <val>, label <dest> ... ]
+
    + +
    Overview:
    + +

    The 'switch' instruction is used to transfer control flow to one of + several different places. It is a generalization of the 'br' + instruction, allowing a branch to occur to one of many possible + destinations.

    + + +
    Arguments:
    + +

    The 'switch' instruction uses three parameters: an integer + comparison value 'value', a default 'label' destination, and + an array of pairs of comparison value constants and 'label's. The + table is not allowed to contain duplicate constant entries.

    + +
    Semantics:
    + +

    The switch instruction specifies a table of values and + destinations. When the 'switch' instruction is executed, this + table is searched for the given value. If the value is found, control flow is + transfered to the corresponding destination; otherwise, control flow is + transfered to the default destination.

    + +
    Implementation:
    + +

    Depending on properties of the target machine and the particular + switch instruction, this instruction may be code generated in different + ways. For example, it could be generated as a series of chained conditional + branches or with a lookup table.

    + +
    Example:
    + + 
    +  ; Emulate a conditional br instruction
+  %Val = zext i1 %value to i32
+  switch i32 %Val, label %truedest [i32 0, label %falsedest ]
+ 
+  ; Emulate an unconditional br instruction
+  switch i32 0, label %dest [ ]
+ 
+  ; Implement a jump table:
+  switch i32 %val, label %otherwise [ i32 0, label %onzero 
+                                       i32 1, label %onone 
+                                       i32 2, label %ontwo ]
+
    +
    + + +
    + 'invoke' Instruction +
    + +
    + +
    Syntax:
    + + 
    +   <result> = invoke [cconv] <ptr to function ty> %<function ptr val>(<function args>) 
+                 to label <normal label> unwind label <exception label>
+
    + +
    Overview:
    + +

    The 'invoke' instruction causes control to transfer to a specified + function, with the possibility of control flow transfer to either the + 'normal' label or the + 'exception' label. If the callee function returns with the + "ret" instruction, control flow will return to the + "normal" label. If the callee (or any indirect callees) returns with the "unwind" instruction, control is interrupted and + continued at the dynamically nearest "exception" label.

    + +
    Arguments:
    + +

    This instruction requires several arguments:

    + +
      +
    1. + The optional "cconv" marker indicates which calling + convention the call should use. If none is specified, the call defaults + to using C calling conventions. +
      2. +
    2. 'ptr to function ty': shall be the signature of the pointer to + function value being invoked. In most cases, this is a direct function + invocation, but indirect invokes are just as possible, branching off + an arbitrary pointer to function value. +
      3. + +
    3. 'function ptr val': An LLVM value containing a pointer to a + function to be invoked.
      4. + +
    4. 'function args': argument list whose types match the function + signature argument types. If the function signature indicates the function + accepts a variable number of arguments, the extra arguments can be + specified.
      5. + +
    5. 'normal label': the label reached when the called function + executes a 'ret' instruction.
      6. + +
    6. 'exception label': the label reached when a callee returns with + the unwind instruction.
      7. + +
    + +
    Semantics:
    + +

    This instruction is designed to operate as a standard 'call' instruction in most regards. The primary + difference is that it establishes an association with a label, which is used by + the runtime library to unwind the stack.

    + +

    This instruction is used in languages with destructors to ensure that proper + cleanup is performed in the case of either a longjmp or a thrown + exception. Additionally, this is important for implementation of + 'catch' clauses in high-level languages that support them.

    + +
    Example:
    + 
    +   %retval = invoke i32 %Test(i32 15) to label %Continue
+               unwind label %TestCleanup              ; {i32}:retval set
+   %retval = invoke coldcc i32 %Test(i32 15) to label %Continue
+               unwind label %TestCleanup              ; {i32}:retval set
+
    +
    + + + + +
    'unwind' + Instruction
    + +
    + +
    Syntax:
    + 
    +   unwind
+
    + +
    Overview:
    + +

    The 'unwind' instruction unwinds the stack, continuing control flow + at the first callee in the dynamic call stack which used an invoke instruction to perform the call. This is + primarily used to implement exception handling.

    + +
    Semantics:
    + +

    The 'unwind' intrinsic causes execution of the current function to + immediately halt. The dynamic call stack is then searched for the first invoke instruction on the call stack. Once found, + execution continues at the "exceptional" destination block specified by the + invoke instruction. If there is no invoke instruction in the + dynamic call chain, undefined behavior results.

    +
    + + + +
    'unreachable' + Instruction
    + +
    + +
    Syntax:
    + 
    +   unreachable
+
    + +
    Overview:
    + +

    The 'unreachable' instruction has no defined semantics. This + instruction is used to inform the optimizer that a particular portion of the + code is not reachable. This can be used to indicate that the code after a + no-return function cannot be reached, and other facts.

    + +
    Semantics:
    + +

    The 'unreachable' instruction has no defined semantics.

    +
    + + + + +
    Binary Operations
    +
    +

    Binary operators are used to do most of the computation in a + program. They require two operands, execute an operation on them, and + produce a single value. The operands might represent + multiple data, as is the case with the vector data type. + The result value of a binary operator is not + necessarily the same type as its operands.

    +

    There are several different binary operators:

    +
    + +
    'add' + Instruction
    +
    +
    Syntax:
    + 
      <result> = add <ty> <var1>, <var2>   ; yields {ty}:result
+
    +
    Overview:
    +

    The 'add' instruction returns the sum of its two operands.

    +
    Arguments:
    +

    The two arguments to the 'add' instruction must be either integer or floating point values. + This instruction can also take vector versions of the values. + Both arguments must have identical types.

    +
    Semantics:
    +

    The value produced is the integer or floating point sum of the two + operands.

    +
    Example:
    + 
      <result> = add i32 4, %var          ; yields {i32}:result = 4 + %var
+
    +
    + +
    'sub' + Instruction
    +
    +
    Syntax:
    + 
      <result> = sub <ty> <var1>, <var2>   ; yields {ty}:result
+
    +
    Overview:
    +

    The 'sub' instruction returns the difference of its two + operands.

    +

    Note that the 'sub' instruction is used to represent the 'neg' + instruction present in most other intermediate representations.

    +
    Arguments:
    +

    The two arguments to the 'sub' instruction must be either integer or floating point + values. + This instruction can also take vector versions of the values. + Both arguments must have identical types.

    +
    Semantics:
    +

    The value produced is the integer or floating point difference of + the two operands.

    +
    Example:
    + 
    +   <result> = sub i32 4, %var          ; yields {i32}:result = 4 - %var
+   <result> = sub i32 0, %val          ; yields {i32}:result = -%var
+
    +
    + +
    'mul' + Instruction
    +
    +
    Syntax:
    + 
      <result> = mul <ty> <var1>, <var2>   ; yields {ty}:result
+
    +
    Overview:
    +

    The 'mul' instruction returns the product of its two + operands.

    +
    Arguments:
    +

    The two arguments to the 'mul' instruction must be either integer or floating point + values. + This instruction can also take vector versions of the values. + Both arguments must have identical types.

    +
    Semantics:
    +

    The value produced is the integer or floating point product of the + two operands.

    +

    Because the operands are the same width, the result of an integer + multiplication is the same whether the operands should be deemed unsigned or + signed.

    +
    Example:
    + 
      <result> = mul i32 4, %var          ; yields {i32}:result = 4 * %var
+
    +
    + +
    'udiv' Instruction +
    +
    +
    Syntax:
    + 
      <result> = udiv <ty> <var1>, <var2>   ; yields {ty}:result
+
    +
    Overview:
    +

    The 'udiv' instruction returns the quotient of its two + operands.

    +
    Arguments:
    +

    The two arguments to the 'udiv' instruction must be + integer values. Both arguments must have identical + types. This instruction can also take vector versions + of the values in which case the elements must be integers.

    +
    Semantics:
    +

    The value produced is the unsigned integer quotient of the two operands. This + instruction always performs an unsigned division operation, regardless of + whether the arguments are unsigned or not.

    +
    Example:
    + 
      <result> = udiv i32 4, %var          ; yields {i32}:result = 4 / %var
+
    +
    + +
    'sdiv' Instruction +
    +
    +
    Syntax:
    + 
      <result> = sdiv <ty> <var1>, <var2>   ; yields {ty}:result
+
    +
    Overview:
    +

    The 'sdiv' instruction returns the quotient of its two + operands.

    +
    Arguments:
    +

    The two arguments to the 'sdiv' instruction must be + integer values. Both arguments must have identical + types. This instruction can also take vector versions + of the values in which case the elements must be integers.

    +
    Semantics:
    +

    The value produced is the signed integer quotient of the two operands. This + instruction always performs a signed division operation, regardless of whether + the arguments are signed or not.

    +
    Example:
    + 
      <result> = sdiv i32 4, %var          ; yields {i32}:result = 4 / %var
+
    +
    + +
    'fdiv' + Instruction
    +
    +
    Syntax:
    + 
      <result> = fdiv <ty> <var1>, <var2>   ; yields {ty}:result
+
    +
    Overview:
    +

    The 'fdiv' instruction returns the quotient of its two + operands.

    +
    Arguments:
    +

    The two arguments to the 'fdiv' instruction must be + floating point values. Both arguments must have + identical types. This instruction can also take vector + versions of floating point values.

    +
    Semantics:
    +

    The value produced is the floating point quotient of the two operands.

    +
    Example:
    + 
      <result> = fdiv float 4.0, %var          ; yields {float}:result = 4.0 / %var
+
    +
    + +
    'urem' Instruction +
    +
    +
    Syntax:
    + 
      <result> = urem <ty> <var1>, <var2>   ; yields {ty}:result
+
    +
    Overview:
    +

    The 'urem' instruction returns the remainder from the + unsigned division of its two arguments.

    +
    Arguments:
    +

    The two arguments to the 'urem' instruction must be + integer values. Both arguments must have identical + types. This instruction can also take vector versions + of the values in which case the elements must be integers.

    +
    Semantics:
    +

    This instruction returns the unsigned integer remainder of a division. + This instruction always performs an unsigned division to get the remainder, + regardless of whether the arguments are unsigned or not.

    +
    Example:
    + 
      <result> = urem i32 4, %var          ; yields {i32}:result = 4 % %var
+
    + +
    + +
    'srem' + Instruction
    +
    +
    Syntax:
    + 
      <result> = srem <ty> <var1>, <var2>   ; yields {ty}:result
+
    +
    Overview:
    +

    The 'srem' instruction returns the remainder from the + signed division of its two operands. This instruction can also take + vector versions of the values in which case + the elements must be integers.

    + +
    Arguments:
    +

    The two arguments to the 'srem' instruction must be + integer values. Both arguments must have identical + types.

    +
    Semantics:
    +

    This instruction returns the remainder of a division (where the result + has the same sign as the dividend, var1), not the modulo + operator (where the result has the same sign as the divisor, var2) of + a value. For more information about the difference, see The + Math Forum. For a table of how this is implemented in various languages, + please see + Wikipedia: modulo operation.

    +
    Example:
    + 
      <result> = srem i32 4, %var          ; yields {i32}:result = 4 % %var
+
    + +
    + +
    'frem' + Instruction
    +
    +
    Syntax:
    + 
      <result> = frem <ty> <var1>, <var2>   ; yields {ty}:result
+
    +
    Overview:
    +

    The 'frem' instruction returns the remainder from the + division of its two operands.

    +
    Arguments:
    +

    The two arguments to the 'frem' instruction must be + floating point values. Both arguments must have + identical types. This instruction can also take vector + versions of floating point values.

    +
    Semantics:
    +

    This instruction returns the remainder of a division.

    +
    Example:
    + 
      <result> = frem float 4.0, %var          ; yields {float}:result = 4.0 % %var
+
    +
    + + +
    Bitwise Binary + Operations
    +
    +

    Bitwise binary operators are used to do various forms of + bit-twiddling in a program. They are generally very efficient + instructions and can commonly be strength reduced from other + instructions. They require two operands, execute an operation on them, + and produce a single value. The resulting value of the bitwise binary + operators is always the same type as its first operand.

    +
    + + +
    'shl' + Instruction
    +
    +
    Syntax:
    + 
      <result> = shl <ty> <var1>, <var2>   ; yields {ty}:result
+
    + +
    Overview:
    + +

    The 'shl' instruction returns the first operand shifted to + the left a specified number of bits.

    + +
    Arguments:
    + +

    Both arguments to the 'shl' instruction must be the same integer type.

    + +
    Semantics:
    + +

    The value produced is var1 * 2var2. If + var2 is (statically or dynamically) equal to or larger than the number + of bits in var1, the result is undefined.

    + +
    Example:
    +   <result> = shl i32 4, %var   ; yields {i32}: 4 << %var
+   <result> = shl i32 4, 2      ; yields {i32}: 16
+   <result> = shl i32 1, 10     ; yields {i32}: 1024
+   <result> = shl i32 1, 32     ; undefined
+
    +
    + +
    'lshr' + Instruction
    +
    +
    Syntax:
    + 
      <result> = lshr <ty> <var1>, <var2>   ; yields {ty}:result
+
    + +
    Overview:
    +

    The 'lshr' instruction (logical shift right) returns the first + operand shifted to the right a specified number of bits with zero fill.

    + +
    Arguments:
    +

    Both arguments to the 'lshr' instruction must be the same + integer type.

    + +
    Semantics:
    + +

    This instruction always performs a logical shift right operation. The most + significant bits of the result will be filled with zero bits after the + shift. If var2 is (statically or dynamically) equal to or larger than + the number of bits in var1, the result is undefined.

    + +
    Example:
    + 
    +   <result> = lshr i32 4, 1   ; yields {i32}:result = 2
+   <result> = lshr i32 4, 2   ; yields {i32}:result = 1
+   <result> = lshr i8  4, 3   ; yields {i8}:result = 0
+   <result> = lshr i8 -2, 1   ; yields {i8}:result = 0x7FFFFFFF 
+   <result> = lshr i32 1, 32  ; undefined
+
    +
    + + +
    'ashr' + Instruction
    +
    + +
    Syntax:
    + 
      <result> = ashr <ty> <var1>, <var2>   ; yields {ty}:result
+
    + +
    Overview:
    +

    The 'ashr' instruction (arithmetic shift right) returns the first + operand shifted to the right a specified number of bits with sign extension.

    + +
    Arguments:
    +

    Both arguments to the 'ashr' instruction must be the same + integer type.

    + +
    Semantics:
    +

    This instruction always performs an arithmetic shift right operation, + The most significant bits of the result will be filled with the sign bit + of var1. If var2 is (statically or dynamically) equal to or + larger than the number of bits in var1, the result is undefined. +

    + +
    Example:
    + 
    +   <result> = ashr i32 4, 1   ; yields {i32}:result = 2
+   <result> = ashr i32 4, 2   ; yields {i32}:result = 1
+   <result> = ashr i8  4, 3   ; yields {i8}:result = 0
+   <result> = ashr i8 -2, 1   ; yields {i8}:result = -1
+   <result> = ashr i32 1, 32  ; undefined
+
    +
    + + +
    'and' + Instruction
    +
    +
    Syntax:
    + 
      <result> = and <ty> <var1>, <var2>   ; yields {ty}:result
+
    +
    Overview:
    +

    The 'and' instruction returns the bitwise logical and of + its two operands.

    +
    Arguments:
    +

    The two arguments to the 'and' instruction must be integer values. Both arguments must have + identical types.

    +
    Semantics:
    +

    The truth table used for the 'and' instruction is:

    +

    +
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    In0In1Out
    000
    010
    100
    111
    +
    +
    Example:
    + 
      <result> = and i32 4, %var         ; yields {i32}:result = 4 & %var
+   <result> = and i32 15, 40          ; yields {i32}:result = 8
+   <result> = and i32 4, 8            ; yields {i32}:result = 0
+
    +
    + +
    'or' Instruction
    +
    +
    Syntax:
    + 
      <result> = or <ty> <var1>, <var2>   ; yields {ty}:result
+
    +
    Overview:
    +

    The 'or' instruction returns the bitwise logical inclusive + or of its two operands.

    +
    Arguments:
    +

    The two arguments to the 'or' instruction must be integer values. Both arguments must have + identical types.

    +
    Semantics:
    +

    The truth table used for the 'or' instruction is:

    +

    +
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    In0In1Out
    000
    011
    101
    111
    +
    +
    Example:
    + 
      <result> = or i32 4, %var         ; yields {i32}:result = 4 | %var
+   <result> = or i32 15, 40          ; yields {i32}:result = 47
+   <result> = or i32 4, 8            ; yields {i32}:result = 12
+
    +
    + +
    'xor' + Instruction
    +
    +
    Syntax:
    + 
      <result> = xor <ty> <var1>, <var2>   ; yields {ty}:result
+
    +
    Overview:
    +

    The 'xor' instruction returns the bitwise logical exclusive + or of its two operands. The xor is used to implement the + "one's complement" operation, which is the "~" operator in C.

    +
    Arguments:
    +

    The two arguments to the 'xor' instruction must be integer values. Both arguments must have + identical types.

    +
    Semantics:
    +

    The truth table used for the 'xor' instruction is:

    +

    +
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    In0In1Out
    000
    011
    101
    110
    +
    +

    +
    Example:
    + 
      <result> = xor i32 4, %var         ; yields {i32}:result = 4 ^ %var
+   <result> = xor i32 15, 40          ; yields {i32}:result = 39
+   <result> = xor i32 4, 8            ; yields {i32}:result = 12
+   <result> = xor i32 %V, -1          ; yields {i32}:result = ~%V
+
    +
    + + +
    + Vector Operations +
    + +
    + +

    LLVM supports several instructions to represent vector operations in a + target-independent manner. These instructions cover the element-access and + vector-specific operations needed to process vectors effectively. While LLVM + does directly support these vector operations, many sophisticated algorithms + will want to use target-specific intrinsics to take full advantage of a specific + target.

    + +
    + + +
    + 'extractelement' Instruction +
    + +
    + +
    Syntax:
    + + 
    +   <result> = extractelement <n x <ty>> <val>, i32 <idx>    ; yields <ty>
+
    + +
    Overview:
    + +

    + The 'extractelement' instruction extracts a single scalar + element from a vector at a specified index. +

    + + +
    Arguments:
    + +

    + The first operand of an 'extractelement' instruction is a + value of vector type. The second operand is + an index indicating the position from which to extract the element. + The index may be a variable.

    + +
    Semantics:
    + +

    + The result is a scalar of the same type as the element type of + val. Its value is the value at position idx of + val. If idx exceeds the length of val, the + results are undefined. +

    + +
    Example:
    + + 
    +   %result = extractelement <4 x i32> %vec, i32 0    ; yields i32
+
    +
    + + + +
    + 'insertelement' Instruction +
    + +
    + +
    Syntax:
    + + 
    +   <result> = insertelement <n x <ty>> <val>, <ty> <elt>, i32 <idx>    ; yields <n x <ty>>
+
    + +
    Overview:
    + +

    + The 'insertelement' instruction inserts a scalar + element into a vector at a specified index. +

    + + +
    Arguments:
    + +

    + The first operand of an 'insertelement' instruction is a + value of vector type. The second operand is a + scalar value whose type must equal the element type of the first + operand. The third operand is an index indicating the position at + which to insert the value. The index may be a variable.

    + +
    Semantics:
    + +

    + The result is a vector of the same type as val. Its + element values are those of val except at position + idx, where it gets the value elt. If idx + exceeds the length of val, the results are undefined. +

    + +
    Example:
    + + 
    +   %result = insertelement <4 x i32> %vec, i32 1, i32 0    ; yields <4 x i32>
+
    +
    + + +
    + 'shufflevector' Instruction +
    + +
    + +
    Syntax:
    + + 
    +   <result> = shufflevector <n x <ty>> <v1>, <n x <ty>> <v2>, <n x i32> <mask>    ; yields <n x <ty>>
+
    + +
    Overview:
    + +

    + The 'shufflevector' instruction constructs a permutation of elements + from two input vectors, returning a vector of the same type. +

    + +
    Arguments:
    + +

    + The first two operands of a 'shufflevector' instruction are vectors + with types that match each other and types that match the result of the + instruction. The third argument is a shuffle mask, which has the same number + of elements as the other vector type, but whose element type is always 'i32'. +

    + +

    + The shuffle mask operand is required to be a constant vector with either + constant integer or undef values. +

    + +
    Semantics:
    + +

    + The elements of the two input vectors are numbered from left to right across + both of the vectors. The shuffle mask operand specifies, for each element of + the result vector, which element of the two input registers the result element + gets. The element selector may be undef (meaning "don't care") and the second + operand may be undef if performing a shuffle from only one vector. +

    + +
    Example:
    + + 
    +   %result = shufflevector <4 x i32> %v1, <4 x i32> %v2, 
+                           <4 x i32> <i32 0, i32 4, i32 1, i32 5>  ; yields <4 x i32>
+   %result = shufflevector <4 x i32> %v1, <4 x i32> undef, 
+                           <4 x i32> <i32 0, i32 1, i32 2, i32 3>  ; yields <4 x i32> - Identity shuffle.
+
    +
    + + + +
    + Memory Access and Addressing Operations +
    + +
    + +

    A key design point of an SSA-based representation is how it + represents memory. In LLVM, no memory locations are in SSA form, which + makes things very simple. This section describes how to read, write, + allocate, and free memory in LLVM.

    + +
    + + +
    + 'malloc' Instruction +
    + +
    + +
    Syntax:
    + + 
    +   <result> = malloc <type>[, i32 <NumElements>][, align <alignment>]     ; yields {type*}:result
+
    + +
    Overview:
    + +

    The 'malloc' instruction allocates memory from the system + heap and returns a pointer to it. The object is always allocated in the generic + address space (address space zero).

    + +
    Arguments:
    + +

    The 'malloc' instruction allocates + sizeof(<type>)*NumElements + bytes of memory from the operating system and returns a pointer of the + appropriate type to the program. If "NumElements" is specified, it is the + number of elements allocated. If an alignment is specified, the value result + of the allocation is guaranteed to be aligned to at least that boundary. If + not specified, or if zero, the target can choose to align the allocation on any + convenient boundary.

    + +

    'type' must be a sized type.

    + +
    Semantics:
    + +

    Memory is allocated using the system "malloc" function, and + a pointer is returned.

    + +
    Example:
    + + 
    +   %array  = malloc [4 x i8 ]                    ; yields {[%4 x i8]*}:array
+ 
+   %size   = add i32 2, 2                        ; yields {i32}:size = i32 4
+   %array1 = malloc i8, i32 4                    ; yields {i8*}:array1
+   %array2 = malloc [12 x i8], i32 %size         ; yields {[12 x i8]*}:array2
+   %array3 = malloc i32, i32 4, align 1024       ; yields {i32*}:array3
+   %array4 = malloc i32, align 1024              ; yields {i32*}:array4
+
    +
    + + +
    + 'free' Instruction +
    + +
    + +
    Syntax:
    + + 
    +   free <type> <value>                              ; yields {void}
+
    + +
    Overview:
    + +

    The 'free' instruction returns memory back to the unused + memory heap to be reallocated in the future.

    + +
    Arguments:
    + +

    'value' shall be a pointer value that points to a value + that was allocated with the 'malloc' + instruction.

    + +
    Semantics:
    + +

    Access to the memory pointed to by the pointer is no longer defined + after this instruction executes.

    + +
    Example:
    + + 
    +   %array  = malloc [4 x i8]                    ; yields {[4 x i8]*}:array
+             free   [4 x i8]* %array
+
    +
    + + +
    + 'alloca' Instruction +
    + +
    + +
    Syntax:
    + + 
    +   <result> = alloca <type>[, i32 <NumElements>][, align <alignment>]     ; yields {type*}:result
+
    + +
    Overview:
    + +

    The 'alloca' instruction allocates memory on the stack frame of the + currently executing function, to be automatically released when this function + returns to its caller. The object is always allocated in the generic address + space (address space zero).

    + +
    Arguments:
    + +

    The 'alloca' instruction allocates sizeof(<type>)*NumElements + bytes of memory on the runtime stack, returning a pointer of the + appropriate type to the program. If "NumElements" is specified, it is the + number of elements allocated. If an alignment is specified, the value result + of the allocation is guaranteed to be aligned to at least that boundary. If + not specified, or if zero, the target can choose to align the allocation on any + convenient boundary.

    + +

    'type' may be any sized type.

    + +
    Semantics:
    + +

    Memory is allocated; a pointer is returned. 'alloca'd + memory is automatically released when the function returns. The 'alloca' + instruction is commonly used to represent automatic variables that must + have an address available. When the function returns (either with the ret or unwind + instructions), the memory is reclaimed.

    + +
    Example:
    + + 
    +   %ptr = alloca i32                              ; yields {i32*}:ptr
+   %ptr = alloca i32, i32 4                       ; yields {i32*}:ptr
+   %ptr = alloca i32, i32 4, align 1024           ; yields {i32*}:ptr
+   %ptr = alloca i32, align 1024                  ; yields {i32*}:ptr
+
    +
    + + +
    'load' + Instruction
    +
    +
    Syntax:
    + 
      <result> = load <ty>* <pointer>[, align <alignment>]
      <result> = volatile load <ty>* <pointer>[, align <alignment>]
    +
    Overview:
    +

    The 'load' instruction is used to read from memory.

    +
    Arguments:
    +

    The argument to the 'load' instruction specifies the memory + address from which to load. The pointer must point to a first class type. If the load is + marked as volatile, then the optimizer is not allowed to modify + the number or order of execution of this load with other + volatile load and store + instructions.

    +

    + The optional "align" argument specifies the alignment of the operation + (that is, the alignment of the memory address). A value of 0 or an + omitted "align" argument means that the operation has the preferential + alignment for the target. It is the responsibility of the code emitter + to ensure that the alignment information is correct. Overestimating + the alignment results in an undefined behavior. Underestimating the + alignment may produce less efficient code. An alignment of 1 is always + safe. +

    +
    Semantics:
    +

    The location of memory pointed to is loaded.

    +
    Examples:
    + 
      %ptr = alloca i32                               ; yields {i32*}:ptr
+   store i32 3, i32* %ptr                          ; yields {void}
+   %val = load i32* %ptr                           ; yields {i32}:val = i32 3
+
    +
    + +
    'store' + Instruction
    +
    +
    Syntax:
    + 
      store <ty> <value>, <ty>* <pointer>[, align <alignment>]                   ; yields {void}
+   volatile store <ty> <value>, <ty>* <pointer>[, align <alignment>]          ; yields {void}
+
    +
    Overview:
    +

    The 'store' instruction is used to write to memory.

    +
    Arguments:
    +

    There are two arguments to the 'store' instruction: a value + to store and an address at which to store it. The type of the '<pointer>' + operand must be a pointer to the type of the '<value>' + operand. If the store is marked as volatile, then the + optimizer is not allowed to modify the number or order of execution of + this store with other volatile load and store instructions.

    +

    + The optional "align" argument specifies the alignment of the operation + (that is, the alignment of the memory address). A value of 0 or an + omitted "align" argument means that the operation has the preferential + alignment for the target. It is the responsibility of the code emitter + to ensure that the alignment information is correct. Overestimating + the alignment results in an undefined behavior. Underestimating the + alignment may produce less efficient code. An alignment of 1 is always + safe. +

    +
    Semantics:
    +

    The contents of memory are updated to contain '<value>' + at the location specified by the '<pointer>' operand.

    +
    Example:
    + 
      %ptr = alloca i32                               ; yields {i32*}:ptr
+   store i32 3, i32* %ptr                          ; yields {void}
+   %val = load i32* %ptr                           ; yields {i32}:val = i32 3
+
    +
    + + +
    + 'getelementptr' Instruction +
    + +
    +
    Syntax:
    + 
    +   <result> = getelementptr <ty>* <ptrval>{, <ty> <idx>}*
+
    + +
    Overview:
    + +

    + The 'getelementptr' instruction is used to get the address of a + subelement of an aggregate data structure.

    + +
    Arguments:
    + +

    This instruction takes a list of integer operands that indicate what + elements of the aggregate object to index to. The actual types of the arguments + provided depend on the type of the first pointer argument. The + 'getelementptr' instruction is used to index down through the type + levels of a structure or to a specific index in an array. When indexing into a + structure, only i32 integer constants are allowed. When indexing + into an array or pointer, only integers of 32 or 64 bits are allowed, and will + be sign extended to 64-bit values.

    + +

    For example, let's consider a C code fragment and how it gets + compiled to LLVM:

    + +
    + 
    + struct RT {
+   char A;
+   int B[10][20];
+   char C;
+ };
+ struct ST {
+   int X;
+   double Y;
+   struct RT Z;
+ };
+ 
+ int *foo(struct ST *s) {
+   return &s[1].Z.B[5][13];
+ }
+
    +
    + +

    The LLVM code generated by the GCC frontend is:

    + +
    + 
    + %RT = type { i8 , [10 x [20 x i32]], i8  }
+ %ST = type { i32, double, %RT }
+ 
+ define i32* %foo(%ST* %s) {
+ entry:
+   %reg = getelementptr %ST* %s, i32 1, i32 2, i32 1, i32 5, i32 13
+   ret i32* %reg
+ }
+
    +
    + +
    Semantics:
    + +

    The index types specified for the 'getelementptr' instruction depend + on the pointer type that is being indexed into. Pointer + and array types can use a 32-bit or 64-bit + integer type but the value will always be sign extended + to 64-bits. Structure types require i32 + constants.

    + +

    In the example above, the first index is indexing into the '%ST*' + type, which is a pointer, yielding a '%ST' = '{ i32, double, %RT + }' type, a structure. The second index indexes into the third element of + the structure, yielding a '%RT' = '{ i8 , [10 x [20 x i32]], + i8 }' type, another structure. The third index indexes into the second + element of the structure, yielding a '[10 x [20 x i32]]' type, an + array. The two dimensions of the array are subscripted into, yielding an + 'i32' type. The 'getelementptr' instruction returns a pointer + to this element, thus computing a value of 'i32*' type.

    + +

    Note that it is perfectly legal to index partially through a + structure, returning a pointer to an inner element. Because of this, + the LLVM code for the given testcase is equivalent to:

    + + 
    +   define i32* %foo(%ST* %s) {
+     %t1 = getelementptr %ST* %s, i32 1                        ; yields %ST*:%t1
+     %t2 = getelementptr %ST* %t1, i32 0, i32 2                ; yields %RT*:%t2
+     %t3 = getelementptr %RT* %t2, i32 0, i32 1                ; yields [10 x [20 x i32]]*:%t3
+     %t4 = getelementptr [10 x [20 x i32]]* %t3, i32 0, i32 5  ; yields [20 x i32]*:%t4
+     %t5 = getelementptr [20 x i32]* %t4, i32 0, i32 13        ; yields i32*:%t5
+     ret i32* %t5
+   }
+
    + +

    Note that it is undefined to access an array out of bounds: array and + pointer indexes must always be within the defined bounds of the array type. + The one exception for this rules is zero length arrays. These arrays are + defined to be accessible as variable length arrays, which requires access + beyond the zero'th element.

    + +

    The getelementptr instruction is often confusing. For some more insight + into how it works, see the getelementptr + FAQ.

    + +
    Example:
    + + 
    +     ; yields [12 x i8]*:aptr
+     %aptr = getelementptr {i32, [12 x i8]}* %sptr, i64 0, i32 1
+
    +
    + + +
    Conversion Operations +
    +
    +

    The instructions in this category are the conversion instructions (casting) + which all take a single operand and a type. They perform various bit conversions + on the operand.

    +
    + + +
    + 'trunc .. to' Instruction +
    +
    + +
    Syntax:
    + 
    +   <result> = trunc <ty> <value> to <ty2>             ; yields ty2
+
    + +
    Overview:
    +

    + The 'trunc' instruction truncates its operand to the type ty2. +

    + +
    Arguments:
    +

    + The 'trunc' instruction takes a value to trunc, which must + be an integer type, and a type that specifies the size + and type of the result, which must be an integer + type. The bit size of value must be larger than the bit size of + ty2. Equal sized types are not allowed.

    + +
    Semantics:
    +

    + The 'trunc' instruction truncates the high order bits in value + and converts the remaining bits to ty2. Since the source size must be + larger than the destination size, trunc cannot be a no-op cast. + It will always truncate bits.

    + +
    Example:
    + 
    +   %X = trunc i32 257 to i8              ; yields i8:1
+   %Y = trunc i32 123 to i1              ; yields i1:true
+   %Y = trunc i32 122 to i1              ; yields i1:false
+
    +
    + + +
    + 'zext .. to' Instruction +
    +
    + +
    Syntax:
    + 
    +   <result> = zext <ty> <value> to <ty2>             ; yields ty2
+
    + +
    Overview:
    +

    The 'zext' instruction zero extends its operand to type + ty2.

    + + +
    Arguments:
    +

    The 'zext' instruction takes a value to cast, which must be of + integer type, and a type to cast it to, which must + also be of integer type. The bit size of the + value must be smaller than the bit size of the destination type, + ty2.

    + +
    Semantics:
    +

    The zext fills the high order bits of the value with zero + bits until it reaches the size of the destination type, ty2.

    + +

    When zero extending from i1, the result will always be either 0 or 1.

    + +
    Example:
    + 
    +   %X = zext i32 257 to i64              ; yields i64:257
+   %Y = zext i1 true to i32              ; yields i32:1
+
    +
    + + +
    + 'sext .. to' Instruction +
    +
    + +
    Syntax:
    + 
    +   <result> = sext <ty> <value> to <ty2>             ; yields ty2
+
    + +
    Overview:
    +

    The 'sext' sign extends value to the type ty2.

    + +
    Arguments:
    +

    + The 'sext' instruction takes a value to cast, which must be of + integer type, and a type to cast it to, which must + also be of integer type. The bit size of the + value must be smaller than the bit size of the destination type, + ty2.

    + +
    Semantics:
    +

    + The 'sext' instruction performs a sign extension by copying the sign + bit (highest order bit) of the value until it reaches the bit size of + the type ty2.

    + +

    When sign extending from i1, the extension always results in -1 or 0.

    + +
    Example:
    + 
    +   %X = sext i8  -1 to i16              ; yields i16   :65535
+   %Y = sext i1 true to i32             ; yields i32:-1
+
    +
    + + +
    + 'fptrunc .. to' Instruction +
    + +
    + +
    Syntax:
    + + 
    +   <result> = fptrunc <ty> <value> to <ty2>             ; yields ty2
+
    + +
    Overview:
    +

    The 'fptrunc' instruction truncates value to type + ty2.

    + + +
    Arguments:
    +

    The 'fptrunc' instruction takes a floating + point value to cast and a floating point type to + cast it to. The size of value must be larger than the size of + ty2. This implies that fptrunc cannot be used to make a + no-op cast.

    + +
    Semantics:
    +

    The 'fptrunc' instruction truncates a value from a larger + floating point type to a smaller + floating point type. If the value cannot fit within + the destination type, ty2, then the results are undefined.

    + +
    Example:
    + 
    +   %X = fptrunc double 123.0 to float         ; yields float:123.0
+   %Y = fptrunc double 1.0E+300 to float      ; yields undefined
+
    +
    + + +
    + 'fpext .. to' Instruction +
    +
    + +
    Syntax:
    + 
    +   <result> = fpext <ty> <value> to <ty2>             ; yields ty2
+
    + +
    Overview:
    +

    The 'fpext' extends a floating point value to a larger + floating point value.

    + +
    Arguments:
    +

    The 'fpext' instruction takes a + floating point value to cast, + and a floating point type to cast it to. The source + type must be smaller than the destination type.

    + +
    Semantics:
    +

    The 'fpext' instruction extends the value from a smaller + floating point type to a larger + floating point type. The fpext cannot be + used to make a no-op cast because it always changes bits. Use + bitcast to make a no-op cast for a floating point cast.

    + +
    Example:
    + 
    +   %X = fpext float 3.1415 to double        ; yields double:3.1415
+   %Y = fpext float 1.0 to float            ; yields float:1.0 (no-op)
+
    +
    + + +
    + 'fptoui .. to' Instruction +
    +
    + +
    Syntax:
    + 
    +   <result> = fptoui <ty> <value> to <ty2>             ; yields ty2
+
    + +
    Overview:
    +

    The 'fptoui' converts a floating point value to its + unsigned integer equivalent of type ty2. +

    + +
    Arguments:
    +

    The 'fptoui' instruction takes a value to cast, which must be a + scalar or vector floating point value, and a type + to cast it to ty2, which must be an integer + type. If ty is a vector floating point type, ty2 must be a + vector integer type with the same number of elements as ty

    + +
    Semantics:
    +

    The 'fptoui' instruction converts its + floating point operand into the nearest (rounding + towards zero) unsigned integer value. If the value cannot fit in ty2, + the results are undefined.

    + +
    Example:
    + 
    +   %X = fptoui double 123.0 to i32      ; yields i32:123
+   %Y = fptoui float 1.0E+300 to i1     ; yields undefined:1
+   %X = fptoui float 1.04E+17 to i8     ; yields undefined:1
+
    +
    + + +
    + 'fptosi .. to' Instruction +
    +
    + +
    Syntax:
    + 
    +   <result> = fptosi <ty> <value> to <ty2>             ; yields ty2
+
    + +
    Overview:
    +

    The 'fptosi' instruction converts + floating point value to type ty2. +

    + +
    Arguments:
    +

    The 'fptosi' instruction takes a value to cast, which must be a + scalar or vector floating point value, and a type + to cast it to ty2, which must be an integer + type. If ty is a vector floating point type, ty2 must be a + vector integer type with the same number of elements as ty

    + +
    Semantics:
    +

    The 'fptosi' instruction converts its + floating point operand into the nearest (rounding + towards zero) signed integer value. If the value cannot fit in ty2, + the results are undefined.

    + +
    Example:
    + 
    +   %X = fptosi double -123.0 to i32      ; yields i32:-123
+   %Y = fptosi float 1.0E-247 to i1      ; yields undefined:1
+   %X = fptosi float 1.04E+17 to i8      ; yields undefined:1
+
    +
    + + +
    + 'uitofp .. to' Instruction +
    +
    + +
    Syntax:
    + 
    +   <result> = uitofp <ty> <value> to <ty2>             ; yields ty2
+
    + +
    Overview:
    +

    The 'uitofp' instruction regards value as an unsigned + integer and converts that value to the ty2 type.

    + +
    Arguments:
    +

    The 'uitofp' instruction takes a value to cast, which must be a + scalar or vector integer value, and a type to cast it + to ty2, which must be an floating point + type. If ty is a vector integer type, ty2 must be a vector + floating point type with the same number of elements as ty

    + +
    Semantics:
    +

    The 'uitofp' instruction interprets its operand as an unsigned + integer quantity and converts it to the corresponding floating point value. If + the value cannot fit in the floating point value, the results are undefined.

    + +
    Example:
    + 
    +   %X = uitofp i32 257 to float         ; yields float:257.0
+   %Y = uitofp i8  -1 to double         ; yields double:255.0
+
    +
    + + +
    + 'sitofp .. to' Instruction +
    +
    + +
    Syntax:
    + 
    +   <result> = sitofp <ty> <value> to <ty2>             ; yields ty2
+
    + +
    Overview:
    +

    The 'sitofp' instruction regards value as a signed + integer and converts that value to the ty2 type.

    + +
    Arguments:
    +

    The 'sitofp' instruction takes a value to cast, which must be a + scalar or vector integer value, and a type to cast it + to ty2, which must be an floating point + type. If ty is a vector integer type, ty2 must be a vector + floating point type with the same number of elements as ty

    + +
    Semantics:
    +

    The 'sitofp' instruction interprets its operand as a signed + integer quantity and converts it to the corresponding floating point value. If + the value cannot fit in the floating point value, the results are undefined.

    + +
    Example:
    + 
    +   %X = sitofp i32 257 to float         ; yields float:257.0
+   %Y = sitofp i8  -1 to double         ; yields double:-1.0
+
    +
    + + +
    + 'ptrtoint .. to' Instruction +
    +
    + +
    Syntax:
    + 
    +   <result> = ptrtoint <ty> <value> to <ty2>             ; yields ty2
+
    + +
    Overview:
    +

    The 'ptrtoint' instruction converts the pointer value to + the integer type ty2.

    + +
    Arguments:
    +

    The 'ptrtoint' instruction takes a value to cast, which + must be a pointer value, and a type to cast it to + ty2, which must be an integer type. + +

    Semantics:
    +

    The 'ptrtoint' instruction converts value to integer type + ty2 by interpreting the pointer value as an integer and either + truncating or zero extending that value to the size of the integer type. If + value is smaller than ty2 then a zero extension is done. If + value is larger than ty2 then a truncation is done. If they + are the same size, then nothing is done (no-op cast) other than a type + change.

    + +
    Example:
    + 
    +   %X = ptrtoint i32* %X to i8           ; yields truncation on 32-bit architecture
+   %Y = ptrtoint i32* %x to i64          ; yields zero extension on 32-bit architecture
+
    +
    + + +
    + 'inttoptr .. to' Instruction +
    +
    + +
    Syntax:
    + 
    +   <result> = inttoptr <ty> <value> to <ty2>             ; yields ty2
+
    + +
    Overview:
    +

    The 'inttoptr' instruction converts an integer value to + a pointer type, ty2.

    + +
    Arguments:
    +

    The 'inttoptr' instruction takes an integer + value to cast, and a type to cast it to, which must be a + pointer type. + +

    Semantics:
    +

    The 'inttoptr' instruction converts value to type + ty2 by applying either a zero extension or a truncation depending on + the size of the integer value. If value is larger than the + size of a pointer then a truncation is done. If value is smaller than + the size of a pointer then a zero extension is done. If they are the same size, + nothing is done (no-op cast).

    + +
    Example:
    + 
    +   %X = inttoptr i32 255 to i32*          ; yields zero extension on 64-bit architecture
+   %X = inttoptr i32 255 to i32*          ; yields no-op on 32-bit architecture
+   %Y = inttoptr i64 0 to i32*            ; yields truncation on 32-bit architecture
+
    +
    + + +
    + 'bitcast .. to' Instruction +
    +
    + +
    Syntax:
    + 
    +   <result> = bitcast <ty> <value> to <ty2>             ; yields ty2
+
    + +
    Overview:
    +

    The 'bitcast' instruction converts value to type + ty2 without changing any bits.

    + +
    Arguments:
    +

    The 'bitcast' instruction takes a value to cast, which must be + a first class value, and a type to cast it to, which must also be a first class type. The bit sizes of value + and the destination type, ty2, must be identical. If the source + type is a pointer, the destination type must also be a pointer.

    + +
    Semantics:
    +

    The 'bitcast' instruction converts value to type + ty2. It is always a no-op cast because no bits change with + this conversion. The conversion is done as if the value had been + stored to memory and read back as type ty2. Pointer types may only be + converted to other pointer types with this instruction. To convert pointers to + other types, use the inttoptr or + ptrtoint instructions first.

    + +
    Example:
    + 
    +   %X = bitcast i8 255 to i8              ; yields i8 :-1
+   %Y = bitcast i32* %x to sint*          ; yields sint*:%x
+   %Z = bitcast <2xint> %V to i64;        ; yields i64: %V   
+
    +
    + + +
    Other Operations
    +
    +

    The instructions in this category are the "miscellaneous" + instructions, which defy better classification.

    +
    + + +
    'icmp' Instruction +
    +
    +
    Syntax:
    + 
      <result> = icmp <cond> <ty> <var1>, <var2>   ; yields {i1}:result
+
    +
    Overview:
    +

    The 'icmp' instruction returns a boolean value based on comparison + of its two integer operands.

    +
    Arguments:
    +

    The 'icmp' instruction takes three operands. The first operand is + the condition code indicating the kind of comparison to perform. It is not + a value, just a keyword. The possible condition code are: +

      +
    1. eq: equal
      2. +
    2. ne: not equal
      3. +
    3. ugt: unsigned greater than
      4. +
    4. uge: unsigned greater or equal
      5. +
    5. ult: unsigned less than
      6. +
    6. ule: unsigned less or equal
      7. +
    7. sgt: signed greater than
      8. +
    8. sge: signed greater or equal
      9. +
    9. slt: signed less than
      10. +
    10. sle: signed less or equal
      11. +
    +

    The remaining two arguments must be integer or + pointer typed. They must also be identical types.

    +
    Semantics:
    +

    The 'icmp' compares var1 and var2 according to + the condition code given as cond. The comparison performed always + yields a i1 result, as follows: +

      +
    1. eq: yields true if the operands are equal, + false otherwise. No sign interpretation is necessary or performed. +
      2. +
    2. ne: yields true if the operands are unequal, + false otherwise. No sign interpretation is necessary or performed. +
    3. ugt: interprets the operands as unsigned values and yields + true if var1 is greater than var2.
      4. +
    4. uge: interprets the operands as unsigned values and yields + true if var1 is greater than or equal to var2.
      5. +
    5. ult: interprets the operands as unsigned values and yields + true if var1 is less than var2.
      6. +
    6. ule: interprets the operands as unsigned values and yields + true if var1 is less than or equal to var2.
      7. +
    7. sgt: interprets the operands as signed values and yields + true if var1 is greater than var2.
      8. +
    8. sge: interprets the operands as signed values and yields + true if var1 is greater than or equal to var2.
      9. +
    9. slt: interprets the operands as signed values and yields + true if var1 is less than var2.
      10. +
    10. sle: interprets the operands as signed values and yields + true if var1 is less than or equal to var2.
      11. +
    +

    If the operands are pointer typed, the pointer + values are compared as if they were integers.

    + +
    Example:
    + 
      <result> = icmp eq i32 4, 5          ; yields: result=false
+   <result> = icmp ne float* %X, %X     ; yields: result=false
+   <result> = icmp ult i16  4, 5        ; yields: result=true
+   <result> = icmp sgt i16  4, 5        ; yields: result=false
+   <result> = icmp ule i16 -4, 5        ; yields: result=false
+   <result> = icmp sge i16  4, 5        ; yields: result=false
+
    +
    + + +
    'fcmp' Instruction +
    +
    +
    Syntax:
    + 
      <result> = fcmp <cond> <ty> <var1>, <var2>     ; yields {i1}:result
+
    +
    Overview:
    +

    The 'fcmp' instruction returns a boolean value based on comparison + of its floating point operands.

    +
    Arguments:
    +

    The 'fcmp' instruction takes three operands. The first operand is + the condition code indicating the kind of comparison to perform. It is not + a value, just a keyword. The possible condition code are: +

      +
    1. false: no comparison, always returns false
      2. +
    2. oeq: ordered and equal
      3. +
    3. ogt: ordered and greater than
      4. +
    4. oge: ordered and greater than or equal
      5. +
    5. olt: ordered and less than
      6. +
    6. ole: ordered and less than or equal
      7. +
    7. one: ordered and not equal
      8. +
    8. ord: ordered (no nans)
      9. +
    9. ueq: unordered or equal
      10. +
    10. ugt: unordered or greater than
      11. +
    11. uge: unordered or greater than or equal
      12. +
    12. ult: unordered or less than
      13. +
    13. ule: unordered or less than or equal
      14. +
    14. une: unordered or not equal
      15. +
    15. uno: unordered (either nans)
      16. +
    16. true: no comparison, always returns true
      17. +
    +

    Ordered means that neither operand is a QNAN while + unordered means that either operand may be a QNAN.

    +

    The val1 and val2 arguments must be + floating point typed. They must have identical + types.

    +
    Semantics:
    +

    The 'fcmp' compares var1 and var2 according to + the condition code given as cond. The comparison performed always + yields a i1 result, as follows: +

      +
    1. false: always yields false, regardless of operands.
      2. +
    2. oeq: yields true if both operands are not a QNAN and + var1 is equal to var2.
      3. +
    3. ogt: yields true if both operands are not a QNAN and + var1 is greather than var2.
      4. +
    4. oge: yields true if both operands are not a QNAN and + var1 is greater than or equal to var2.
      5. +
    5. olt: yields true if both operands are not a QNAN and + var1 is less than var2.
      6. +
    6. ole: yields true if both operands are not a QNAN and + var1 is less than or equal to var2.
      7. +
    7. one: yields true if both operands are not a QNAN and + var1 is not equal to var2.
      8. +
    8. ord: yields true if both operands are not a QNAN.
      9. +
    9. ueq: yields true if either operand is a QNAN or + var1 is equal to var2.
      10. +
    10. ugt: yields true if either operand is a QNAN or + var1 is greater than var2.
      11. +
    11. uge: yields true if either operand is a QNAN or + var1 is greater than or equal to var2.
      12. +
    12. ult: yields true if either operand is a QNAN or + var1 is less than var2.
      13. +
    13. ule: yields true if either operand is a QNAN or + var1 is less than or equal to var2.
      14. +
    14. une: yields true if either operand is a QNAN or + var1 is not equal to var2.
      15. +
    15. uno: yields true if either operand is a QNAN.
      16. +
    16. true: always yields true, regardless of operands.
      17. +
    + +
    Example:
    + 
      <result> = fcmp oeq float 4.0, 5.0    ; yields: result=false
+   <result> = icmp one float 4.0, 5.0    ; yields: result=true
+   <result> = icmp olt float 4.0, 5.0    ; yields: result=true
+   <result> = icmp ueq double 1.0, 2.0   ; yields: result=false
+
    +
    + + +
    'phi' + Instruction
    +
    +
    Syntax:
    + 
      <result> = phi <ty> [ <val0>, <label0>], ...
    +
    Overview:
    +

    The 'phi' instruction is used to implement the φ node in + the SSA graph representing the function.

    +
    Arguments:
    +

    The type of the incoming values is specified with the first type + field. After this, the 'phi' instruction takes a list of pairs + as arguments, with one pair for each predecessor basic block of the + current block. Only values of first class + type may be used as the value arguments to the PHI node. Only labels + may be used as the label arguments.

    +

    There must be no non-phi instructions between the start of a basic + block and the PHI instructions: i.e. PHI instructions must be first in + a basic block.

    +
    Semantics:
    +

    At runtime, the 'phi' instruction logically takes on the value + specified by the pair corresponding to the predecessor basic block that executed + just prior to the current block.

    +
    Example:
    + 
    Loop:       ; Infinite loop that counts from 0 on up...
      %indvar = phi i32 [ 0, %LoopHeader ], [ %nextindvar, %Loop ]
      %nextindvar = add i32 %indvar, 1
      br label %Loop
    +
    + + +
    + 'select' Instruction +
    + +
    + +
    Syntax:
    + + 
    +   <result> = select i1 <cond>, <ty> <val1>, <ty> <val2>             ; yields ty
+
    + +
    Overview:
    + +

    + The 'select' instruction is used to choose one value based on a + condition, without branching. +

    + + +
    Arguments:
    + +

    + The 'select' instruction requires a boolean value indicating the condition, and two values of the same first class type. +

    + +
    Semantics:
    + +

    + If the boolean condition evaluates to true, the instruction returns the first + value argument; otherwise, it returns the second value argument. +

    + +
    Example:
    + + 
    +   %X = select i1 true, i8 17, i8 42          ; yields i8:17
+
    +
    + + + +
    + 'call' Instruction +
    + +
    + +
    Syntax:
    + 
    +   <result> = [tail] call [cconv] <ty> [<fnty>*] <fnptrval>(<param list>)
+
    + +
    Overview:
    + +

    The 'call' instruction represents a simple function call.

    + +
    Arguments:
    + +

    This instruction requires several arguments:

    + +
      +
    1. +

      The optional "tail" marker indicates whether the callee function accesses + any allocas or varargs in the caller. If the "tail" marker is present, the + function call is eligible for tail call optimization. Note that calls may + be marked "tail" even if they do not occur before a ret instruction. +

      2. +
    2. +

      The optional "cconv" marker indicates which calling + convention the call should use. If none is specified, the call defaults + to using C calling conventions. +

      3. +
    3. +

      'ty': the type of the call instruction itself which is also + the type of the return value. Functions that return no value are marked + void.

      +
      4. +
    4. +

      'fnty': shall be the signature of the pointer to function + value being invoked. The argument types must match the types implied by + this signature. This type can be omitted if the function is not varargs + and if the function type does not return a pointer to a function.

      +
      5. +
    5. +

      'fnptrval': An LLVM value containing a pointer to a function to + be invoked. In most cases, this is a direct function invocation, but + indirect calls are just as possible, calling an arbitrary pointer + to function value.

      +
      6. +
    6. +

      'function args': argument list whose types match the + function signature argument types. All arguments must be of + first class type. If the function signature + indicates the function accepts a variable number of arguments, the extra + arguments can be specified.

      +
      7. +
    + +
    Semantics:
    + +

    The 'call' instruction is used to cause control flow to + transfer to a specified function, with its incoming arguments bound to + the specified values. Upon a 'ret' + instruction in the called function, control flow continues with the + instruction after the function call, and the return value of the + function is bound to the result argument. This is a simpler case of + the invoke instruction.

    + +
    Example:
    + + 
    +   %retval = call i32 @test(i32 %argc)
+   call i32 (i8 *, ...)* @printf(i8 * %msg, i32 12, i8 42);
+   %X = tail call i32 @foo()
+   %Y = tail call fastcc i32 @foo()
+   %Z = call void %foo(i8 97 signext)
+
    + +
    + + +
    + 'va_arg' Instruction +
    + +
    + +
    Syntax:
    + + 
    +   <resultval> = va_arg <va_list*> <arglist>, <argty>
+
    + +
    Overview:
    + +

    The 'va_arg' instruction is used to access arguments passed through + the "variable argument" area of a function call. It is used to implement the + va_arg macro in C.

    + +
    Arguments:
    + +

    This instruction takes a va_list* value and the type of + the argument. It returns a value of the specified argument type and + increments the va_list to point to the next argument. The + actual type of va_list is target specific.

    + +
    Semantics:
    + +

    The 'va_arg' instruction loads an argument of the specified + type from the specified va_list and causes the + va_list to point to the next argument. For more information, + see the variable argument handling Intrinsic + Functions.

    + +

    It is legal for this instruction to be called in a function which does not + take a variable number of arguments, for example, the vfprintf + function.

    + +

    va_arg is an LLVM instruction instead of an intrinsic function because it takes a type as an + argument.

    + +
    Example:
    + +

    See the variable argument processing section.

    + +
    + + +
    Intrinsic Functions
    + + +
    + +

    LLVM supports the notion of an "intrinsic function". These functions have + well known names and semantics and are required to follow certain restrictions. + Overall, these intrinsics represent an extension mechanism for the LLVM + language that does not require changing all of the transformations in LLVM when + adding to the language (or the bitcode reader/writer, the parser, etc...).

    + +

    Intrinsic function names must all start with an "llvm." prefix. This + prefix is reserved in LLVM for intrinsic names; thus, function names may not + begin with this prefix. Intrinsic functions must always be external functions: + you cannot define the body of intrinsic functions. Intrinsic functions may + only be used in call or invoke instructions: it is illegal to take the address + of an intrinsic function. Additionally, because intrinsic functions are part + of the LLVM language, it is required if any are added that they be documented + here.

    + +

    Some intrinsic functions can be overloaded, i.e., the intrinsic represents + a family of functions that perform the same operation but on different data + types. Because LLVM can represent over 8 million different integer types, + overloading is used commonly to allow an intrinsic function to operate on any + integer type. One or more of the argument types or the result type can be + overloaded to accept any integer type. Argument types may also be defined as + exactly matching a previous argument's type or the result type. This allows an + intrinsic function which accepts multiple arguments, but needs all of them to + be of the same type, to only be overloaded with respect to a single argument or + the result.

    + +

    Overloaded intrinsics will have the names of its overloaded argument types + encoded into its function name, each preceded by a period. Only those types + which are overloaded result in a name suffix. Arguments whose type is matched + against another type do not. For example, the llvm.ctpop function can + take an integer of any width and returns an integer of exactly the same integer + width. This leads to a family of functions such as + i8 @llvm.ctpop.i8(i8 %val) and i29 @llvm.ctpop.i29(i29 %val). + Only one type, the return type, is overloaded, and only one type suffix is + required. Because the argument's type is matched against the return type, it + does not require its own name suffix.

    + +

    To learn how to add an intrinsic function, please see the + Extending LLVM Guide. +

    + +
    + + +
    + Variable Argument Handling Intrinsics +
    + +
    + +

    Variable argument support is defined in LLVM with the va_arg instruction and these three + intrinsic functions. These functions are related to the similarly + named macros defined in the <stdarg.h> header file.

    + +

    All of these functions operate on arguments that use a + target-specific value type "va_list". The LLVM assembly + language reference manual does not define what this type is, so all + transformations should be prepared to handle these functions regardless of + the type used.

    + +

    This example shows how the va_arg + instruction and the variable argument handling intrinsic functions are + used.

    + +
    + 
    + define i32 @test(i32 %X, ...) {
+   ; Initialize variable argument processing
+   %ap = alloca i8*
+   %ap2 = bitcast i8** %ap to i8*
+   call void @llvm.va_start(i8* %ap2)
+ 
+   ; Read a single integer argument
+   %tmp = va_arg i8** %ap, i32
+ 
+   ; Demonstrate usage of llvm.va_copy and llvm.va_end
+   %aq = alloca i8*
+   %aq2 = bitcast i8** %aq to i8*
+   call void @llvm.va_copy(i8* %aq2, i8* %ap2)
+   call void @llvm.va_end(i8* %aq2)
+ 
+   ; Stop processing of arguments.
+   call void @llvm.va_end(i8* %ap2)
+   ret i32 %tmp
+ }
+ 
+ declare void @llvm.va_start(i8*)
+ declare void @llvm.va_copy(i8*, i8*)
+ declare void @llvm.va_end(i8*)
+
    +
    + +
    + + +
    + 'llvm.va_start' Intrinsic +
    + + +
    +
    Syntax:
    + 
      declare void %llvm.va_start(i8* <arglist>)
    +
    Overview:
    +

    The 'llvm.va_start' intrinsic initializes + *<arglist> for subsequent use by va_arg.

    + +
    Arguments:
    + +

    The argument is a pointer to a va_list element to initialize.

    + +
    Semantics:
    + +

    The 'llvm.va_start' intrinsic works just like the va_start + macro available in C. In a target-dependent way, it initializes the + va_list element to which the argument points, so that the next call to + va_arg will produce the first variable argument passed to the function. + Unlike the C va_start macro, this intrinsic does not need to know the + last argument of the function as the compiler can figure that out.

    + +
    + + +
    + 'llvm.va_end' Intrinsic +
    + +
    +
    Syntax:
    + 
      declare void @llvm.va_end(i8* <arglist>)
    +
    Overview:
    + +

    The 'llvm.va_end' intrinsic destroys *<arglist>, + which has been initialized previously with llvm.va_start + or llvm.va_copy.

    + +
    Arguments:
    + +

    The argument is a pointer to a va_list to destroy.

    + +
    Semantics:
    + +

    The 'llvm.va_end' intrinsic works just like the va_end + macro available in C. In a target-dependent way, it destroys the + va_list element to which the argument points. Calls to llvm.va_start and + llvm.va_copy must be matched exactly with calls to + llvm.va_end.

    + +
    + + +
    + 'llvm.va_copy' Intrinsic +
    + +
    + +
    Syntax:
    + + 
    +   declare void @llvm.va_copy(i8* <destarglist>, i8* <srcarglist>)
+
    + +
    Overview:
    + +

    The 'llvm.va_copy' intrinsic copies the current argument position + from the source argument list to the destination argument list.

    + +
    Arguments:
    + +

    The first argument is a pointer to a va_list element to initialize. + The second argument is a pointer to a va_list element to copy from.

    + + +
    Semantics:
    + +

    The 'llvm.va_copy' intrinsic works just like the va_copy + macro available in C. In a target-dependent way, it copies the source + va_list element into the destination va_list element. This + intrinsic is necessary because the + llvm.va_start intrinsic may be arbitrarily complex and require, for + example, memory allocation.

    + +
    + + +
    + Accurate Garbage Collection Intrinsics +
    + +
    + +

    + LLVM support for Accurate Garbage + Collection requires the implementation and generation of these intrinsics. + These intrinsics allow identification of GC roots on the + stack, as well as garbage collector implementations that require read and write barriers. + Front-ends for type-safe garbage collected languages should generate these + intrinsics to make use of the LLVM garbage collectors. For more details, see Accurate Garbage Collection with LLVM. +

    + +

    The garbage collection intrinsics only operate on objects in the generic + address space (address space zero).

    + +
    + + +
    + 'llvm.gcroot' Intrinsic +
    + +
    + +
    Syntax:
    + + 
    +   declare void @llvm.gcroot(i8** %ptrloc, i8* %metadata)
+
    + +
    Overview:
    + +

    The 'llvm.gcroot' intrinsic declares the existence of a GC root to + the code generator, and allows some metadata to be associated with it.

    + +
    Arguments:
    + +

    The first argument specifies the address of a stack object that contains the + root pointer. The second pointer (which must be either a constant or a global + value address) contains the meta-data to be associated with the root.

    + +
    Semantics:
    + +

    At runtime, a call to this intrinsics stores a null pointer into the "ptrloc" + location. At compile-time, the code generator generates information to allow + the runtime to find the pointer at GC safe points. The 'llvm.gcroot' + intrinsic may only be used in a function which specifies a GC + algorithm.

    + +
    + + + +
    + 'llvm.gcread' Intrinsic +
    + +
    + +
    Syntax:
    + + 
    +   declare i8* @llvm.gcread(i8* %ObjPtr, i8** %Ptr)
+
    + +
    Overview:
    + +

    The 'llvm.gcread' intrinsic identifies reads of references from heap + locations, allowing garbage collector implementations that require read + barriers.

    + +
    Arguments:
    + +

    The second argument is the address to read from, which should be an address + allocated from the garbage collector. The first object is a pointer to the + start of the referenced object, if needed by the language runtime (otherwise + null).

    + +
    Semantics:
    + +

    The 'llvm.gcread' intrinsic has the same semantics as a load + instruction, but may be replaced with substantially more complex code by the + garbage collector runtime, as needed. The 'llvm.gcread' intrinsic + may only be used in a function which specifies a GC + algorithm.

    + +
    + + + +
    + 'llvm.gcwrite' Intrinsic +
    + +
    + +
    Syntax:
    + + 
    +   declare void @llvm.gcwrite(i8* %P1, i8* %Obj, i8** %P2)
+
    + +
    Overview:
    + +

    The 'llvm.gcwrite' intrinsic identifies writes of references to heap + locations, allowing garbage collector implementations that require write + barriers (such as generational or reference counting collectors).

    + +
    Arguments:
    + +

    The first argument is the reference to store, the second is the start of the + object to store it to, and the third is the address of the field of Obj to + store to. If the runtime does not require a pointer to the object, Obj may be + null.

    + +
    Semantics:
    + +

    The 'llvm.gcwrite' intrinsic has the same semantics as a store + instruction, but may be replaced with substantially more complex code by the + garbage collector runtime, as needed. The 'llvm.gcwrite' intrinsic + may only be used in a function which specifies a GC + algorithm.

    + +
    + + + + +
    + Code Generator Intrinsics +
    + +
    +

    + These intrinsics are provided by LLVM to expose special features that may only + be implemented with code generator support. +

    + +
    + + +
    + 'llvm.returnaddress' Intrinsic +
    + +
    + +
    Syntax:
    + 
    +   declare i8  *@llvm.returnaddress(i32 <level>)
+
    + +
    Overview:
    + +

    + The 'llvm.returnaddress' intrinsic attempts to compute a + target-specific value indicating the return address of the current function + or one of its callers. +

    + +
    Arguments:
    + +

    + The argument to this intrinsic indicates which function to return the address + for. Zero indicates the calling function, one indicates its caller, etc. The + argument is required to be a constant integer value. +

    + +
    Semantics:
    + +

    + The 'llvm.returnaddress' intrinsic either returns a pointer indicating + the return address of the specified call frame, or zero if it cannot be + identified. The value returned by this intrinsic is likely to be incorrect or 0 + for arguments other than zero, so it should only be used for debugging purposes. +

    + +

    + Note that calling this intrinsic does not prevent function inlining or other + aggressive transformations, so the value returned may not be that of the obvious + source-language caller. +

    +
    + + + +
    + 'llvm.frameaddress' Intrinsic +
    + +
    + +
    Syntax:
    + 
    +   declare i8 *@llvm.frameaddress(i32 <level>)
+
    + +
    Overview:
    + +

    + The 'llvm.frameaddress' intrinsic attempts to return the + target-specific frame pointer value for the specified stack frame. +

    + +
    Arguments:
    + +

    + The argument to this intrinsic indicates which function to return the frame + pointer for. Zero indicates the calling function, one indicates its caller, + etc. The argument is required to be a constant integer value. +

    + +
    Semantics:
    + +

    + The 'llvm.frameaddress' intrinsic either returns a pointer indicating + the frame address of the specified call frame, or zero if it cannot be + identified. The value returned by this intrinsic is likely to be incorrect or 0 + for arguments other than zero, so it should only be used for debugging purposes. +

    + +

    + Note that calling this intrinsic does not prevent function inlining or other + aggressive transformations, so the value returned may not be that of the obvious + source-language caller. +

    +
    + + +
    + 'llvm.stacksave' Intrinsic +
    + +
    + +
    Syntax:
    + 
    +   declare i8 *@llvm.stacksave()
+
    + +
    Overview:
    + +

    + The 'llvm.stacksave' intrinsic is used to remember the current state of + the function stack, for use with + llvm.stackrestore. This is useful for implementing language + features like scoped automatic variable sized arrays in C99. +

    + +
    Semantics:
    + +

    + This intrinsic returns a opaque pointer value that can be passed to llvm.stackrestore. When an + llvm.stackrestore intrinsic is executed with a value saved from + llvm.stacksave, it effectively restores the state of the stack to the + state it was in when the llvm.stacksave intrinsic executed. In + practice, this pops any alloca blocks from the stack + that were allocated after the llvm.stacksave was executed. +

    + +
    + + +
    + 'llvm.stackrestore' Intrinsic +
    + +
    + +
    Syntax:
    + 
    +   declare void @llvm.stackrestore(i8 * %ptr)
+
    + +
    Overview:
    + +

    + The 'llvm.stackrestore' intrinsic is used to restore the state of + the function stack to the state it was in when the corresponding llvm.stacksave intrinsic executed. This is + useful for implementing language features like scoped automatic variable sized + arrays in C99. +

    + +
    Semantics:
    + +

    + See the description for llvm.stacksave. +

    + +
    + + + +
    + 'llvm.prefetch' Intrinsic +
    + +
    + +
    Syntax:
    + 
    +   declare void @llvm.prefetch(i8* <address>, i32 <rw>, i32 <locality>)
+
    + +
    Overview:
    + + +

    + The 'llvm.prefetch' intrinsic is a hint to the code generator to insert + a prefetch instruction if supported; otherwise, it is a noop. Prefetches have + no + effect on the behavior of the program but can change its performance + characteristics. +

    + +
    Arguments:
    + +

    + address is the address to be prefetched, rw is the specifier + determining if the fetch should be for a read (0) or write (1), and + locality is a temporal locality specifier ranging from (0) - no + locality, to (3) - extremely local keep in cache. The rw and + locality arguments must be constant integers. +

    + +
    Semantics:
    + +

    + This intrinsic does not modify the behavior of the program. In particular, + prefetches cannot trap and do not produce a value. On targets that support this + intrinsic, the prefetch can provide hints to the processor cache for better + performance. +

    + +
    + + +
    + 'llvm.pcmarker' Intrinsic +
    + +
    + +
    Syntax:
    + 
    +   declare void @llvm.pcmarker(i32 <id>)
+
    + +
    Overview:
    + + +

    + The 'llvm.pcmarker' intrinsic is a method to export a Program Counter + (PC) in a region of + code to simulators and other tools. The method is target specific, but it is + expected that the marker will use exported symbols to transmit the PC of the marker. + The marker makes no guarantees that it will remain with any specific instruction + after optimizations. It is possible that the presence of a marker will inhibit + optimizations. The intended use is to be inserted after optimizations to allow + correlations of simulation runs. +

    + +
    Arguments:
    + +

    + id is a numerical id identifying the marker. +

    + +
    Semantics:
    + +

    + This intrinsic does not modify the behavior of the program. Backends that do not + support this intrinisic may ignore it. +

    + +
    + + +
    + 'llvm.readcyclecounter' Intrinsic +
    + +
    + +
    Syntax:
    + 
    +   declare i64 @llvm.readcyclecounter( )
+
    + +
    Overview:
    + + +

    + The 'llvm.readcyclecounter' intrinsic provides access to the cycle + counter register (or similar low latency, high accuracy clocks) on those targets + that support it. On X86, it should map to RDTSC. On Alpha, it should map to RPCC. + As the backing counters overflow quickly (on the order of 9 seconds on alpha), this + should only be used for small timings. +

    + +
    Semantics:
    + +

    + When directly supported, reading the cycle counter should not modify any memory. + Implementations are allowed to either return a application specific value or a + system wide value. On backends without support, this is lowered to a constant 0. +

    + +
    + + +
    + Standard C Library Intrinsics +
    + +
    +

    + LLVM provides intrinsics for a few important standard C library functions. + These intrinsics allow source-language front-ends to pass information about the + alignment of the pointer arguments to the code generator, providing opportunity + for more efficient code generation. +

    + +
    + + +
    + 'llvm.memcpy' Intrinsic +
    + +
    + +
    Syntax:
    + 
    +   declare void @llvm.memcpy.i32(i8 * <dest>, i8 * <src>,
+                                 i32 <len>, i32 <align>)
+   declare void @llvm.memcpy.i64(i8 * <dest>, i8 * <src>,
+                                 i64 <len>, i32 <align>)
+
    + +
    Overview:
    + +

    + The 'llvm.memcpy.*' intrinsics copy a block of memory from the source + location to the destination location. +

    + +

    + Note that, unlike the standard libc function, the llvm.memcpy.* + intrinsics do not return a value, and takes an extra alignment argument. +

    + +
    Arguments:
    + +

    + The first argument is a pointer to the destination, the second is a pointer to + the source. The third argument is an integer argument + specifying the number of bytes to copy, and the fourth argument is the alignment + of the source and destination locations. +

    + +

    + If the call to this intrinisic has an alignment value that is not 0 or 1, then + the caller guarantees that both the source and destination pointers are aligned + to that boundary. +

    + +
    Semantics:
    + +

    + The 'llvm.memcpy.*' intrinsics copy a block of memory from the source + location to the destination location, which are not allowed to overlap. It + copies "len" bytes of memory over. If the argument is known to be aligned to + some boundary, this can be specified as the fourth argument, otherwise it should + be set to 0 or 1. +

    +
    + + + +
    + 'llvm.memmove' Intrinsic +
    + +
    + +
    Syntax:
    + 
    +   declare void @llvm.memmove.i32(i8 * <dest>, i8 * <src>,
+                                  i32 <len>, i32 <align>)
+   declare void @llvm.memmove.i64(i8 * <dest>, i8 * <src>,
+                                  i64 <len>, i32 <align>)
+
    + +
    Overview:
    + +

    + The 'llvm.memmove.*' intrinsics move a block of memory from the source + location to the destination location. It is similar to the + 'llvm.memcpy' intrinsic but allows the two memory locations to overlap. +

    + +

    + Note that, unlike the standard libc function, the llvm.memmove.* + intrinsics do not return a value, and takes an extra alignment argument. +

    + +
    Arguments:
    + +

    + The first argument is a pointer to the destination, the second is a pointer to + the source. The third argument is an integer argument + specifying the number of bytes to copy, and the fourth argument is the alignment + of the source and destination locations. +

    + +

    + If the call to this intrinisic has an alignment value that is not 0 or 1, then + the caller guarantees that the source and destination pointers are aligned to + that boundary. +

    + +
    Semantics:
    + +

    + The 'llvm.memmove.*' intrinsics copy a block of memory from the source + location to the destination location, which may overlap. It + copies "len" bytes of memory over. If the argument is known to be aligned to + some boundary, this can be specified as the fourth argument, otherwise it should + be set to 0 or 1. +

    +
    + + + +
    + 'llvm.memset.*' Intrinsics +
    + +
    + +
    Syntax:
    + 
    +   declare void @llvm.memset.i32(i8 * <dest>, i8 <val>,
+                                 i32 <len>, i32 <align>)
+   declare void @llvm.memset.i64(i8 * <dest>, i8 <val>,
+                                 i64 <len>, i32 <align>)
+
    + +
    Overview:
    + +

    + The 'llvm.memset.*' intrinsics fill a block of memory with a particular + byte value. +

    + +

    + Note that, unlike the standard libc function, the llvm.memset intrinsic + does not return a value, and takes an extra alignment argument. +

    + +
    Arguments:
    + +

    + The first argument is a pointer to the destination to fill, the second is the + byte value to fill it with, the third argument is an integer + argument specifying the number of bytes to fill, and the fourth argument is the + known alignment of destination location. +

    + +

    + If the call to this intrinisic has an alignment value that is not 0 or 1, then + the caller guarantees that the destination pointer is aligned to that boundary. +

    + +
    Semantics:
    + +

    + The 'llvm.memset.*' intrinsics fill "len" bytes of memory starting at + the + destination location. If the argument is known to be aligned to some boundary, + this can be specified as the fourth argument, otherwise it should be set to 0 or + 1. +

    +
    + + + +
    + 'llvm.sqrt.*' Intrinsic +
    + +
    + +
    Syntax:
    +

    This is an overloaded intrinsic. You can use llvm.sqrt on any + floating point or vector of floating point type. Not all targets support all + types however. + 

    +   declare float     @llvm.sqrt.f32(float %Val)
+   declare double    @llvm.sqrt.f64(double %Val)
+   declare x86_fp80  @llvm.sqrt.f80(x86_fp80 %Val)
+   declare fp128     @llvm.sqrt.f128(fp128 %Val)
+   declare ppc_fp128 @llvm.sqrt.ppcf128(ppc_fp128 %Val)
+
    + +
    Overview:
    + +

    + The 'llvm.sqrt' intrinsics return the sqrt of the specified operand, + returning the same value as the libm 'sqrt' functions would. Unlike + sqrt in libm, however, llvm.sqrt has undefined behavior for + negative numbers (which allows for better optimization). +

    + +
    Arguments:
    + +

    + The argument and return value are floating point numbers of the same type. +

    + +
    Semantics:
    + +

    + This function returns the sqrt of the specified operand if it is a nonnegative + floating point number. +

    +
    + + +
    + 'llvm.powi.*' Intrinsic +
    + +
    + +
    Syntax:
    +

    This is an overloaded intrinsic. You can use llvm.powi on any + floating point or vector of floating point type. Not all targets support all + types however. + 

    +   declare float     @llvm.powi.f32(float  %Val, i32 %power)
+   declare double    @llvm.powi.f64(double %Val, i32 %power)
+   declare x86_fp80  @llvm.powi.f80(x86_fp80  %Val, i32 %power)
+   declare fp128     @llvm.powi.f128(fp128 %Val, i32 %power)
+   declare ppc_fp128 @llvm.powi.ppcf128(ppc_fp128  %Val, i32 %power)
+
    + +
    Overview:
    + +

    + The 'llvm.powi.*' intrinsics return the first operand raised to the + specified (positive or negative) power. The order of evaluation of + multiplications is not defined. When a vector of floating point type is + used, the second argument remains a scalar integer value. +

    + +
    Arguments:
    + +

    + The second argument is an integer power, and the first is a value to raise to + that power. +

    + +
    Semantics:
    + +

    + This function returns the first value raised to the second power with an + unspecified sequence of rounding operations.

    +
    + + +
    + 'llvm.sin.*' Intrinsic +
    + +
    + +
    Syntax:
    +

    This is an overloaded intrinsic. You can use llvm.sin on any + floating point or vector of floating point type. Not all targets support all + types however. + 

    +   declare float     @llvm.sin.f32(float  %Val)
+   declare double    @llvm.sin.f64(double %Val)
+   declare x86_fp80  @llvm.sin.f80(x86_fp80  %Val)
+   declare fp128     @llvm.sin.f128(fp128 %Val)
+   declare ppc_fp128 @llvm.sin.ppcf128(ppc_fp128  %Val)
+
    + +
    Overview:
    + +

    + The 'llvm.sin.*' intrinsics return the sine of the operand. +

    + +
    Arguments:
    + +

    + The argument and return value are floating point numbers of the same type. +

    + +
    Semantics:
    + +

    + This function returns the sine of the specified operand, returning the + same values as the libm sin functions would, and handles error + conditions in the same way.

    +
    + + +
    + 'llvm.cos.*' Intrinsic +
    + +
    + +
    Syntax:
    +

    This is an overloaded intrinsic. You can use llvm.cos on any + floating point or vector of floating point type. Not all targets support all + types however. + 

    +   declare float     @llvm.cos.f32(float  %Val)
+   declare double    @llvm.cos.f64(double %Val)
+   declare x86_fp80  @llvm.cos.f80(x86_fp80  %Val)
+   declare fp128     @llvm.cos.f128(fp128 %Val)
+   declare ppc_fp128 @llvm.cos.ppcf128(ppc_fp128  %Val)
+
    + +
    Overview:
    + +

    + The 'llvm.cos.*' intrinsics return the cosine of the operand. +

    + +
    Arguments:
    + +

    + The argument and return value are floating point numbers of the same type. +

    + +
    Semantics:
    + +

    + This function returns the cosine of the specified operand, returning the + same values as the libm cos functions would, and handles error + conditions in the same way.

    +
    + + +
    + 'llvm.pow.*' Intrinsic +
    + +
    + +
    Syntax:
    +

    This is an overloaded intrinsic. You can use llvm.pow on any + floating point or vector of floating point type. Not all targets support all + types however. + 

    +   declare float     @llvm.pow.f32(float  %Val, float %Power)
+   declare double    @llvm.pow.f64(double %Val, double %Power)
+   declare x86_fp80  @llvm.pow.f80(x86_fp80  %Val, x86_fp80 %Power)
+   declare fp128     @llvm.pow.f128(fp128 %Val, fp128 %Power)
+   declare ppc_fp128 @llvm.pow.ppcf128(ppc_fp128  %Val, ppc_fp128 Power)
+
    + +
    Overview:
    + +

    + The 'llvm.pow.*' intrinsics return the first operand raised to the + specified (positive or negative) power. +

    + +
    Arguments:
    + +

    + The second argument is a floating point power, and the first is a value to + raise to that power. +

    + +
    Semantics:
    + +

    + This function returns the first value raised to the second power, + returning the + same values as the libm pow functions would, and handles error + conditions in the same way.

    +
    + + + +
    + Bit Manipulation Intrinsics +
    + +
    +

    + LLVM provides intrinsics for a few important bit manipulation operations. + These allow efficient code generation for some algorithms. +

    + +
    + + +
    + 'llvm.bswap.*' Intrinsics +
    + +
    + +
    Syntax:
    +

    This is an overloaded intrinsic function. You can use bswap on any integer + type that is an even number of bytes (i.e. BitWidth % 16 == 0). + 

    +   declare i16 @llvm.bswap.i16(i16 <id>)
+   declare i32 @llvm.bswap.i32(i32 <id>)
+   declare i64 @llvm.bswap.i64(i64 <id>)
+
    + +
    Overview:
    + +

    + The 'llvm.bswap' family of intrinsics is used to byte swap integer + values with an even number of bytes (positive multiple of 16 bits). These are + useful for performing operations on data that is not in the target's native + byte order. +

    + +
    Semantics:
    + +

    + The llvm.bswap.i16 intrinsic returns an i16 value that has the high + and low byte of the input i16 swapped. Similarly, the llvm.bswap.i32 + intrinsic returns an i32 value that has the four bytes of the input i32 + swapped, so that if the input bytes are numbered 0, 1, 2, 3 then the returned + i32 will have its bytes in 3, 2, 1, 0 order. The llvm.bswap.i48, + llvm.bswap.i64 and other intrinsics extend this concept to + additional even-byte lengths (6 bytes, 8 bytes and more, respectively). +

    + +
    + + +
    + 'llvm.ctpop.*' Intrinsic +
    + +
    + +
    Syntax:
    +

    This is an overloaded intrinsic. You can use llvm.ctpop on any integer bit + width. Not all targets support all bit widths however. + 

    +   declare i8 @llvm.ctpop.i8 (i8  <src>)
+   declare i16 @llvm.ctpop.i16(i16 <src>)
+   declare i32 @llvm.ctpop.i32(i32 <src>)
+   declare i64 @llvm.ctpop.i64(i64 <src>)
+   declare i256 @llvm.ctpop.i256(i256 <src>)
+
    + +
    Overview:
    + +

    + The 'llvm.ctpop' family of intrinsics counts the number of bits set in a + value. +

    + +
    Arguments:
    + +

    + The only argument is the value to be counted. The argument may be of any + integer type. The return type must match the argument type. +

    + +
    Semantics:
    + +

    + The 'llvm.ctpop' intrinsic counts the 1's in a variable. +

    +
    + + +
    + 'llvm.ctlz.*' Intrinsic +
    + +
    + +
    Syntax:
    +

    This is an overloaded intrinsic. You can use llvm.ctlz on any + integer bit width. Not all targets support all bit widths however. + 

    +   declare i8 @llvm.ctlz.i8 (i8  <src>)
+   declare i16 @llvm.ctlz.i16(i16 <src>)
+   declare i32 @llvm.ctlz.i32(i32 <src>)
+   declare i64 @llvm.ctlz.i64(i64 <src>)
+   declare i256 @llvm.ctlz.i256(i256 <src>)
+
    + +
    Overview:
    + +

    + The 'llvm.ctlz' family of intrinsic functions counts the number of + leading zeros in a variable. +

    + +
    Arguments:
    + +

    + The only argument is the value to be counted. The argument may be of any + integer type. The return type must match the argument type. +

    + +
    Semantics:
    + +

    + The 'llvm.ctlz' intrinsic counts the leading (most significant) zeros + in a variable. If the src == 0 then the result is the size in bits of the type + of src. For example, llvm.ctlz(i32 2) = 30. +

    +
    + + + + +
    + 'llvm.cttz.*' Intrinsic +
    + +
    + +
    Syntax:
    +

    This is an overloaded intrinsic. You can use llvm.cttz on any + integer bit width. Not all targets support all bit widths however. + 

    +   declare i8 @llvm.cttz.i8 (i8  <src>)
+   declare i16 @llvm.cttz.i16(i16 <src>)
+   declare i32 @llvm.cttz.i32(i32 <src>)
+   declare i64 @llvm.cttz.i64(i64 <src>)
+   declare i256 @llvm.cttz.i256(i256 <src>)
+
    + +
    Overview:
    + +

    + The 'llvm.cttz' family of intrinsic functions counts the number of + trailing zeros. +

    + +
    Arguments:
    + +

    + The only argument is the value to be counted. The argument may be of any + integer type. The return type must match the argument type. +

    + +
    Semantics:
    + +

    + The 'llvm.cttz' intrinsic counts the trailing (least significant) zeros + in a variable. If the src == 0 then the result is the size in bits of the type + of src. For example, llvm.cttz(2) = 1. +

    +
    + + +
    + 'llvm.part.select.*' Intrinsic +
    + +
    + +
    Syntax:
    +

    This is an overloaded intrinsic. You can use llvm.part.select + on any integer bit width. + 

    +   declare i17 @llvm.part.select.i17 (i17 %val, i32 %loBit, i32 %hiBit)
+   declare i29 @llvm.part.select.i29 (i29 %val, i32 %loBit, i32 %hiBit)
+
    + +
    Overview:
    +

    The 'llvm.part.select' family of intrinsic functions selects a + range of bits from an integer value and returns them in the same bit width as + the original value.

    + +
    Arguments:
    +

    The first argument, %val and the result may be integer types of + any bit width but they must have the same bit width. The second and third + arguments must be i32 type since they specify only a bit index.

    + +
    Semantics:
    +

    The operation of the 'llvm.part.select' intrinsic has two modes + of operation: forwards and reverse. If %loBit is greater than + %hiBits then the intrinsic operates in reverse mode. Otherwise it + operates in forward mode.

    +

    In forward mode, this intrinsic is the equivalent of shifting %val + right by %loBit bits and then ANDing it with a mask with + only the %hiBit - %loBit bits set, as follows:

    +
      +
    1. The %val is shifted right (LSHR) by the number of bits specified + by %loBits. This normalizes the value to the low order bits.
      2. +
    2. The %loBits value is subtracted from the %hiBits value + to determine the number of bits to retain.
      3. +
    3. A mask of the retained bits is created by shifting a -1 value.
      4. +
    4. The mask is ANDed with %val to produce the result. +
    +

    In reverse mode, a similar computation is made except that the bits are + returned in the reverse order. So, for example, if X has the value + i16 0x0ACF (101011001111) and we apply + part.select(i16 X, 8, 3) to it, we get back the value + i16 0x0026 (000000100110).

    +
    + +
    + 'llvm.part.set.*' Intrinsic +
    + +
    + +
    Syntax:
    +

    This is an overloaded intrinsic. You can use llvm.part.set + on any integer bit width. + 

    +   declare i17 @llvm.part.set.i17.i9 (i17 %val, i9 %repl, i32 %lo, i32 %hi)
+   declare i29 @llvm.part.set.i29.i9 (i29 %val, i9 %repl, i32 %lo, i32 %hi)
+
    + +
    Overview:
    +

    The 'llvm.part.set' family of intrinsic functions replaces a range + of bits in an integer value with another integer value. It returns the integer + with the replaced bits.

    + +
    Arguments:
    +

    The first argument, %val and the result may be integer types of + any bit width but they must have the same bit width. %val is the value + whose bits will be replaced. The second argument, %repl may be an + integer of any bit width. The third and fourth arguments must be i32 + type since they specify only a bit index.

    + +
    Semantics:
    +

    The operation of the 'llvm.part.set' intrinsic has two modes + of operation: forwards and reverse. If %lo is greater than + %hi then the intrinsic operates in reverse mode. Otherwise it + operates in forward mode.

    +

    For both modes, the %repl value is prepared for use by either + truncating it down to the size of the replacement area or zero extending it + up to that size.

    +

    In forward mode, the bits between %lo and %hi (inclusive) + are replaced with corresponding bits from %repl. That is the 0th bit + in %repl replaces the %loth bit in %val and etc. up + to the %hith bit. +

    In reverse mode, a similar computation is made except that the bits are + reversed. That is, the 0th bit in %repl replaces the + %hi bit in %val and etc. down to the %loth bit. +

    Examples:
    + 
    +   llvm.part.set(0xFFFF, 0, 4, 7) -> 0xFF0F
+   llvm.part.set(0xFFFF, 0, 7, 4) -> 0xFF0F
+   llvm.part.set(0xFFFF, 1, 7, 4) -> 0xFF8F
+   llvm.part.set(0xFFFF, F, 8, 3) -> 0xFFE7
+   llvm.part.set(0xFFFF, 0, 3, 8) -> 0xFE07
+
    +
    + + +
    + Debugger Intrinsics +
    + +
    +

    + The LLVM debugger intrinsics (which all start with llvm.dbg. prefix), + are described in the LLVM Source Level + Debugging document. +

    +
    + + + +
    + Exception Handling Intrinsics +
    + +
    +

    The LLVM exception handling intrinsics (which all start with + llvm.eh. prefix), are described in the LLVM Exception + Handling document.

    +
    + + +
    + Trampoline Intrinsic +
    + +
    +

    + This intrinsic makes it possible to excise one parameter, marked with + the nest attribute, from a function. The result is a callable + function pointer lacking the nest parameter - the caller does not need + to provide a value for it. Instead, the value to use is stored in + advance in a "trampoline", a block of memory usually allocated + on the stack, which also contains code to splice the nest value into the + argument list. This is used to implement the GCC nested function address + extension. +

    +

    + For example, if the function is + i32 f(i8* nest %c, i32 %x, i32 %y) then the resulting function + pointer has signature i32 (i32, i32)*. It can be created as follows:

    + 
    +   %tramp = alloca [10 x i8], align 4 ; size and alignment only correct for X86
+   %tramp1 = getelementptr [10 x i8]* %tramp, i32 0, i32 0
+   %p = call i8* @llvm.init.trampoline( i8* %tramp1, i8* bitcast (i32 (i8* nest , i32, i32)* @f to i8*), i8* %nval )
+   %fp = bitcast i8* %p to i32 (i32, i32)*
+
    +

    The call %val = call i32 %fp( i32 %x, i32 %y ) is then equivalent + to %val = call i32 %f( i8* %nval, i32 %x, i32 %y ).

    +
    + + +
    + 'llvm.init.trampoline' Intrinsic +
    +
    +
    Syntax:
    + 
    + declare i8* @llvm.init.trampoline(i8* <tramp>, i8* <func>, i8* <nval>)
+
    +
    Overview:
    +

    + This fills the memory pointed to by tramp with code + and returns a function pointer suitable for executing it. +

    +
    Arguments:
    +

    + The llvm.init.trampoline intrinsic takes three arguments, all + pointers. The tramp argument must point to a sufficiently large + and sufficiently aligned block of memory; this memory is written to by the + intrinsic. Note that the size and the alignment are target-specific - LLVM + currently provides no portable way of determining them, so a front-end that + generates this intrinsic needs to have some target-specific knowledge. + The func argument must hold a function bitcast to an i8*. +

    +
    Semantics:
    +

    + The block of memory pointed to by tramp is filled with target + dependent code, turning it into a function. A pointer to this function is + returned, but needs to be bitcast to an + appropriate function pointer type + before being called. The new function's signature is the same as that of + func with any arguments marked with the nest attribute + removed. At most one such nest argument is allowed, and it must be + of pointer type. Calling the new function is equivalent to calling + func with the same argument list, but with nval used for the + missing nest argument. If, after calling + llvm.init.trampoline, the memory pointed to by tramp is + modified, then the effect of any later call to the returned function pointer is + undefined. +

    +
    + + +
    + General Intrinsics +
    + +
    +

    This class of intrinsics is designed to be generic and has + no specific purpose.

    +
    + + +
    + 'llvm.var.annotation' Intrinsic +
    + +
    + +
    Syntax:
    + 
    +   declare void @llvm.var.annotation(i8* <val>, i8* <str>, i8* <str>, i32  <int> )
+
    + +
    Overview:
    + +

    + The 'llvm.var.annotation' intrinsic +

    + +
    Arguments:
    + +

    + The first argument is a pointer to a value, the second is a pointer to a + global string, the third is a pointer to a global string which is the source + file name, and the last argument is the line number. +

    + +
    Semantics:
    + +

    + This intrinsic allows annotation of local variables with arbitrary strings. + This can be useful for special purpose optimizations that want to look for these + annotations. These have no other defined use, they are ignored by code + generation and optimization. +

    +
    + + +
    + 'llvm.annotation.*' Intrinsic +
    + +
    + +
    Syntax:
    +

    This is an overloaded intrinsic. You can use 'llvm.annotation' on + any integer bit width. +

    + 
    +   declare i8 @llvm.annotation.i8(i8 <val>, i8* <str>, i8* <str>, i32  <int> )
+   declare i16 @llvm.annotation.i16(i16 <val>, i8* <str>, i8* <str>, i32  <int> )
+   declare i32 @llvm.annotation.i32(i32 <val>, i8* <str>, i8* <str>, i32  <int> )
+   declare i64 @llvm.annotation.i64(i64 <val>, i8* <str>, i8* <str>, i32  <int> )
+   declare i256 @llvm.annotation.i256(i256 <val>, i8* <str>, i8* <str>, i32  <int> )
+
    + +
    Overview:
    + +

    + The 'llvm.annotation' intrinsic. +

    + +
    Arguments:
    + +

    + The first argument is an integer value (result of some expression), + the second is a pointer to a global string, the third is a pointer to a global + string which is the source file name, and the last argument is the line number. + It returns the value of the first argument. +

    + +
    Semantics:
    + +

    + This intrinsic allows annotations to be put on arbitrary expressions + with arbitrary strings. This can be useful for special purpose optimizations + that want to look for these annotations. These have no other defined use, they + are ignored by code generation and optimization. +

    + + +
    + 'llvm.trap' Intrinsic +
    + +
    + +
    Syntax:
    + 
    +   declare void @llvm.trap()
+
    + +
    Overview:
    + +

    + The 'llvm.trap' intrinsic +

    + +
    Arguments:
    + +

    + None +

    + +
    Semantics:
    + +

    + This intrinsics is lowered to the target dependent trap instruction. If the + target does not have a trap instruction, this intrinsic will be lowered to the + call of the abort() function. +

    +
    + + +
    +
    + Valid CSS! + Valid HTML 4.01! + + Chris Lattner
    + The LLVM Compiler Infrastructure
    + Last modified: $Date: 2008/02/12 06:05:03 $ +
    + + + Index: llvm-www/releases/2.2/docs/Lexicon.html diff -c /dev/null llvm-www/releases/2.2/docs/Lexicon.html:1.1 *** /dev/null Tue Feb 12 00:07:04 2008 --- llvm-www/releases/2.2/docs/Lexicon.html Tue Feb 12 00:05:03 2008 *************** *** 0 **** --- 1,254 ---- + + + + + The LLVM Lexicon + + + + + +
    The LLVM Lexicon
    +

    NOTE: This document is a work in progress!

    + +
    Table Of Contents
    + +
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    - A -
    ADCE
    - B -
    BURS
    - C -
    CSE
    - D -
    DAGDerived PointerDSADSE
    - G -
    GC
    - I -
    IPAIPOISel
    - L -
    LCSSALICMLoad-VN
    - O -
    Object Pointer
    - P -
    PRE
    - R -
    ReassociationRoot
    - S -
    Safe PointSCCSCCPSDISelSRoAStack Map
    +
    + + +
    Definitions
    + + +
    - A -
    +
    +
    +
    ADCE
    +
    Aggressive Dead Code Elimination
    +
    +
    + +
    - B -
    +
    +
    +
    BURS
    +
    Bottom Up Rewriting System - A method of instruction selection for + code generation. An example is the BURG tool.
    +
    +
    + +
    - C -
    +
    +
    +
    CSE
    +
    Common Subexpression Elimination. An optimization that removes common + subexpression compuation. For example (a+b)*(a+b) has two + subexpressions that are the same: (a+b). This optimization would + perform the addition only once and then perform the multiply (but only if + it's compulationally correct/safe). +
    +
    + +
    - D -
    +
    +
    +
    DAG
    +
    Directed Acyclic Graph
    +
    Derived Pointer
    +
    A pointer to the interior of an object, such that a garbage collector + is unable to use the pointer for reachability analysis. While a derived + pointer is live, the corresponding object pointer must be kept in a root, + otherwise the collector might free the referenced object. With copying + collectors, derived pointers pose an additional hazard that they may be + invalidated at any safe point. This term is used in + opposition to object pointer.
    +
    DSA
    +
    Data Structure Analysis
    +
    DSE
    +
    Dead Store Elimination
    +
    +
    + +
    - G -
    +
    +
    +
    GC
    +
    Garbage Collection. The practice of using reachability analysis instead + of explicit memory management to reclaim unused memory.
    +
    +
    + +
    - H -
    +
    +
    +
    Heap
    +
    In garbage collection, the region of memory which is managed using + reachability analysis.
    +
    +
    + +
    - I -
    +
    +
    +
    IPA
    +
    Inter-Procedural Analysis. Refers to any variety of code analysis that + occurs between procedures, functions or compilation units (modules).
    +
    IPO
    +
    Inter-Procedural Optimization. Refers to any variety of code + optimization that occurs between procedures, functions or compilation units + (modules).
    +
    ISel
    +
    Instruction Selection.
    +
    +
    + +
    - L -
    +
    +
    +
    LCSSA
    +
    Loop-Closed Static Single Assignment Form
    +
    LICM
    +
    Loop Invariant Code Motion
    +
    Load-VN
    +
    Load Value Numbering
    +
    +
    + + +
    - O -
    +
    +
    +
    Object Pointer
    +
    A pointer to an object such that the garbage collector is able to trace + references contained within the object. This term is used in opposition to + derived pointer.
    +
    +
    + + +
    - P -
    +
    +
    +
    PRE
    +
    Partial Redundancy Elimination
    +
    +
    + + +
    - R -
    +
    +
    +
    Reassociation
    Rearranging + associative expressions to promote better redundancy elimination and other + optimization. For example, changing (A+B-A) into (B+A-A), permitting it to + be optimized into (B+0) then (B).
    +
    Root
    In garbage collection, a + pointer variable lying outside of the heap from which + the collector begins its reachability analysis. In the context of code + generation, "root" almost always refers to a "stack root"—a local or + temporary variable within an executing function.
    +
    +
    + + +
    - S -
    +
    +
    +
    Safe Point
    +
    In garbage collection, it is necessary to identify stack + roots so that reachability analysis may proceed. It may be infeasible to + provide this information for every instruction, so instead the information + may is calculated only at designated safe points. With a copying collector, + derived pointers must not be retained across + safe points and object pointers must be + reloaded from stack roots.
    +
    SDISel
    +
    Selection DAG Instruction Selection.
    +
    SCC
    +
    Strongly Connected Component
    +
    SCCP
    +
    Sparse Conditional Constant Propagation
    +
    SRoA
    +
    Scalar Replacement of Aggregates
    +
    SSA
    +
    Static Single Assignment
    +
    Stack Map
    +
    In garbage collection, metadata emitted by the code generator which + identifies roots within the stack frame of an executing + function.
    +
    +
    + +
    +
    Valid CSS!Valid HTML 4.01!The LLVM Team
    + The LLVM Compiler Infrastructure
    + Last modified: $Date: 2008/02/12 06:05:03 $ +
    + + + Index: llvm-www/releases/2.2/docs/LinkTimeOptimization.html diff -c /dev/null llvm-www/releases/2.2/docs/LinkTimeOptimization.html:1.1 *** /dev/null Tue Feb 12 00:07:04 2008 --- llvm-www/releases/2.2/docs/LinkTimeOptimization.html Tue Feb 12 00:05:03 2008 *************** *** 0 **** --- 1,392 ---- + + + + LLVM Link Time Optimization: Design and Implementation + + + +
    + LLVM Link Time Optimization: Design and Implementation +
    + + + +
    +

    Written by Devang Patel

    +
    + + +
    + Description +
    + + +
    +

    + LLVM features powerful intermodular optimizations which can be used at link + time. Link Time Optimization is another name for intermodular optimization + when performed during the link stage. This document describes the interface + and design between the LLVM intermodular optimizer and the linker.

    +
    + + +
    + Design Philosophy +
    + + +
    +

    + The LLVM Link Time Optimizer provides complete transparency, while doing + intermodular optimization, in the compiler tool chain. Its main goal is to let + the developer take advantage of intermodular optimizations without making any + significant changes to the developer's makefiles or build system. This is + achieved through tight integration with the linker. In this model, the linker + treates LLVM bitcode files like native object files and allows mixing and + matching among them. The linker uses LLVMlto, a dynamically + loaded library, to handle LLVM bitcode files. This tight integration between + the linker and LLVM optimizer helps to do optimizations that are not possible + in other models. The linker input allows the optimizer to avoid relying on + conservative escape analysis. +

    +
    + + +
    + Example of link time optimization +
    + +
    +

    The following example illustrates the advantages of LTO's integrated + approach and clean interface. This example requires a system linker which + supports LTO through the interface described in this document. Here, + llvm-gcc transparently invokes system linker.

    +
      +
    • Input source file a.c is compiled into LLVM bitcode form. +
    • Input source file main.c is compiled into native object code. +
    + 
    + --- a.h ---
+ extern int foo1(void);
+ extern void foo2(void);
+ extern void foo4(void);
+ --- a.c ---
+ #include "a.h"
+ 
+ static signed int i = 0;
+ 
+ void foo2(void) {
+  i = -1;
+ }
+ 
+ static int foo3() {
+ foo4();
+ return 10;
+ }
+ 
+ int foo1(void) {
+ int data = 0;
+ 
+ if (i < 0) { data = foo3(); }
+ 
+ data = data + 42;
+ return data;
+ }
+ 
+ --- main.c ---
+ #include <stdio.h>
+ #include "a.h"
+ 
+ void foo4(void) {
+  printf ("Hi\n");
+ }
+ 
+ int main() {
+  return foo1();
+ }
+ 
+ --- command lines ---
+ $ llvm-gcc --emit-llvm -c a.c -o a.o  # <-- a.o is LLVM bitcode file
+ $ llvm-gcc -c main.c -o main.o # <-- main.o is native object file
+ $ llvm-gcc a.o main.o -o main # <-- standard link command without any modifications
+
    +

    In this example, the linker recognizes that foo2() is an + externally visible symbol defined in LLVM bitcode file. This information + is collected using readLLVMObjectFile(). + Based on this information, the linker completes its usual symbol resolution + pass and finds that foo2() is not used anywhere. This information + is used by the LLVM optimizer and it removes foo2(). As soon as + foo2() is removed, the optimizer recognizes that condition + i < 0 is always false, which means foo3() is never + used. Hence, the optimizer removes foo3(), also. And this in turn, + enables linker to remove foo4(). This example illustrates the + advantage of tight integration with the linker. Here, the optimizer can not + remove foo3() without the linker's input. +

    +
    + + +
    + Alternative Approaches +
    + +
    +
    +
    Compiler driver invokes link time optimizer separately.
    +
    In this model the link time optimizer is not able to take advantage of + information collected during the linker's normal symbol resolution phase. + In the above example, the optimizer can not remove foo2() without + the linker's input because it is externally visible. This in turn prohibits + the optimizer from removing foo3().
    +
    Use separate tool to collect symbol information from all object + files.
    +
    In this model, a new, separate, tool or library replicates the linker's + capability to collect information for link time optimization. Not only is + this code duplication difficult to justify, but it also has several other + disadvantages. For example, the linking semantics and the features + provided by the linker on various platform are not unique. This means, + this new tool needs to support all such features and platforms in one + super tool or a separate tool per platform is required. This increases + maintance cost for link time optimizer significantly, which is not + necessary. This approach also requires staying synchronized with linker + developements on various platforms, which is not the main focus of the link + time optimizer. Finally, this approach increases end user's build time due + to the duplication of work done by this separate tool and the linker itself. +
    +
    +
    + + +
    + Multi-phase communication between LLVM and linker +
    + +
    +

    The linker collects information about symbol defininitions and uses in + various link objects which is more accurate than any information collected + by other tools during typical build cycles. The linker collects this + information by looking at the definitions and uses of symbols in native .o + files and using symbol visibility information. The linker also uses + user-supplied information, such as a list of exported symbols. LLVM + optimizer collects control flow information, data flow information and knows + much more about program structure from the optimizer's point of view. + Our goal is to take advantage of tight intergration between the linker and + the optimizer by sharing this information during various linking phases. +

    +
    + + +
    + Phase 1 : Read LLVM Bitcode Files +
    + +
    +

    The linker first reads all object files in natural order and collects + symbol information. This includes native object files as well as LLVM bitcode + files. In this phase, the linker uses + readLLVMObjectFile() to collect symbol + information from each LLVM bitcode files and updates its internal global + symbol table accordingly. The intent of this interface is to avoid overhead + in the non LLVM case, where all input object files are native object files, + by putting this code in the error path of the linker. When the linker sees + the first llvm .o file, it dlopen()s the dynamic library. This is + to allow changes to the LLVM LTO code without relinking the linker. +

    +
    + + +
    + Phase 2 : Symbol Resolution +
    + +
    +

    In this stage, the linker resolves symbols using global symbol table + information to report undefined symbol errors, read archive members, resolve + weak symbols, etc. The linker is able to do this seamlessly even though it + does not know the exact content of input LLVM bitcode files because it uses + symbol information provided by + readLLVMObjectFile(). If dead code + stripping is enabled then the linker collects the list of live symbols. +

    +
    + + +
    + Phase 3 : Optimize Bitcode Files +
    +
    +

    After symbol resolution, the linker updates symbol information supplied + by LLVM bitcode files appropriately. For example, whether certain LLVM + bitcode supplied symbols are used or not. In the example above, the linker + reports that foo2() is not used anywhere in the program, including + native .o files. This information is used by the LLVM interprocedural + optimizer. The linker uses optimizeModules() + and requests an optimized native object file of the LLVM portion of the + program. +

    +
    + + +
    + Phase 4 : Symbol Resolution after optimization +
    + +
    +

    In this phase, the linker reads optimized a native object file and + updates the internal global symbol table to reflect any changes. The linker + also collects information about any changes in use of external symbols by + LLVM bitcode files. In the examle above, the linker notes that + foo4() is not used any more. If dead code stripping is enabled then + the linker refreshes the live symbol information appropriately and performs + dead code stripping.

    +

    After this phase, the linker continues linking as if it never saw LLVM + bitcode files.

    +
    + + +
    + LLVMlto +
    + +
    +

    LLVMlto is a dynamic library that is part of the LLVM tools, and + is intended for use by a linker. LLVMlto provides an abstract C++ + interface to use the LLVM interprocedural optimizer without exposing details + of LLVM's internals. The intention is to keep the interface as stable as + possible even when the LLVM optimizer continues to evolve.

    +
    + + +
    + LLVMSymbol +
    + +
    +

    The LLVMSymbol class is used to describe the externally visible + functions and global variables, defined in LLVM bitcode files, to the linker. + This includes symbol visibility information. This information is used by + the linker to do symbol resolution. For example: function foo2() is + defined inside an LLVM bitcode module and it is an externally visible symbol. + This helps the linker connect the use of foo2() in native object + files with a future definition of the symbol foo2(). The linker + will see the actual definition of foo2() when it receives the + optimized native object file in + Symbol Resolution after optimization phase. If the + linker does not find any uses of foo2(), it updates LLVMSymbol + visibility information to notify LLVM intermodular optimizer that it is dead. + The LLVM intermodular optimizer takes advantage of such information to + generate better code.

    +
    + + +
    + readLLVMObjectFile() +
    + +
    +

    The readLLVMObjectFile() function is used by the linker to read + LLVM bitcode files and collect LLVMSymbol information. This routine also + supplies a list of externally defined symbols that are used by LLVM bitcode + files. The linker uses this symbol information to do symbol resolution. + Internally, LLVMlto maintains LLVM bitcode modules in + memory. This function also provides a list of external references used by + bitcode files.

    +
    + + +
    + optimizeModules() +
    + +
    +

    The linker invokes optimizeModules to optimize already read + LLVM bitcode files by applying LLVM intermodular optimization techniques. + This function runs the LLVM intermodular optimizer and generates native + object code as .o files at the name and location provided by the + linker.

    +
    + + +
    + getTargetTriple() +
    + +
    +

    The linker may use getTargetTriple() to query target architecture + while validating LLVM bitcode file.

    +
    + + +
    + removeModule() +
    + +
    +

    Internally, LLVMlto maintains LLVM bitcode modules in + memory. The linker may use removeModule() method to remove desired + modules from memory.

    +
    + + +
    + getAlignment() +
    + +
    +

    The linker may use LLVMSymbol method + getAlignment() to query symbol alignment information.

    +
    + + +
    + Debugging Information +
    + + +
    + +

    ... To be completed ...

    + +
    + + + +
    +
    + Valid CSS! + Valid HTML 4.01! + + Devang Patel
    + LLVM Compiler Infrastructure
    + Last modified: $Date: 2008/02/12 06:05:03 $ +
    + + + Index: llvm-www/releases/2.2/docs/Makefile diff -c /dev/null llvm-www/releases/2.2/docs/Makefile:1.1 *** /dev/null Tue Feb 12 00:07:04 2008 --- llvm-www/releases/2.2/docs/Makefile Tue Feb 12 00:05:03 2008 *************** *** 0 **** --- 1,91 ---- + ##===- docs/Makefile ---------------------------------------*- Makefile -*-===## + # + # The LLVM Compiler Infrastructure + # + # This file is distributed under the University of Illinois Open Source + # License. See LICENSE.TXT for details. + # + ##===----------------------------------------------------------------------===## + + LEVEL := .. + DIRS := CommandGuide + + ifdef BUILD_FOR_WEBSITE + PROJ_OBJ_DIR = . + DOXYGEN = doxygen + # Extract version number from the AC_INT line in configure.ac + # AC_INIT([[llvm]],[[2.1svn]],[llvmbugs at cs.uiuc.edu]) + PACKAGE_VERSION = $(shell grep AC_INIT ../autoconf/configure.ac | sed -e 's/^[^0-9]*\([0-9_.a-zA-Z-]*\).*/\1/' ) + + $(PROJ_OBJ_DIR)/doxygen.cfg: doxygen.cfg.in + cat $< | sed \ + -e 's/@abs_top_srcdir@/../g' \ + -e 's/@DOT@/dot/g' \ + -e 's/@PACKAGE_VERSION@/$(PACKAGE_VERSION)/' \ + -e 's/@abs_top_builddir@/../g' > $@ + endif + + include $(LEVEL)/Makefile.common + + HTML := $(wildcard $(PROJ_SRC_DIR)/*.html) \ + $(wildcard $(PROJ_SRC_DIR)/*.css) + IMAGES := $(wildcard $(PROJ_SRC_DIR)/img/*.*) + DOXYFILES := doxygen.cfg.in doxygen.css doxygen.footer doxygen.header \ + doxygen.intro + EXTRA_DIST := $(HTML) $(DOXYFILES) llvm.css CommandGuide img + + .PHONY: install-html install-doxygen doxygen + + ifeq ($(ENABLE_DOXYGEN),1) + install-local:: install-html install-doxygen + else + install-local:: install-html + endif + + install-html: $(PROJ_OBJ_DIR)/html.tar.gz + $(Echo) Installing HTML documentation + $(Verb) $(MKDIR) $(PROJ_docsdir)/html + $(Verb) $(MKDIR) $(PROJ_docsdir)/html/img + $(Verb) $(DataInstall) $(HTML) $(PROJ_docsdir)/html + $(Verb) $(DataInstall) $(IMAGES) $(PROJ_docsdir)/html/img + $(Verb) $(DataInstall) $(PROJ_OBJ_DIR)/html.tar.gz $(PROJ_docsdir) + + $(PROJ_OBJ_DIR)/html.tar.gz: $(HTML) + $(Echo) Packaging HTML documentation + $(Verb) $(RM) -rf $@ $(PROJ_OBJ_DIR)/html.tar + $(Verb) cd $(PROJ_SRC_DIR) && \ + $(TAR) cf $(PROJ_OBJ_DIR)/html.tar *.html + $(Verb) $(GZIP) $(PROJ_OBJ_DIR)/html.tar + + install-doxygen: doxygen + $(Echo) Installing doxygen documentation + $(Echo) Installing doxygen documentation + $(Verb) $(MKDIR) $(PROJ_docsdir)/html/doxygen + $(Verb) $(DataInstall) $(PROJ_OBJ_DIR)/doxygen.tar.gz $(PROJ_docsdir) + $(Verb) cd $(PROJ_OBJ_DIR)/doxygen && \ + $(FIND) . -type f -exec \ + $(DataInstall) {} $(PROJ_docsdir)/html/doxygen \; + + doxygen: regendoc $(PROJ_OBJ_DIR)/doxygen.tar.gz + + regendoc: + $(Echo) Building doxygen documentation + $(Verb) if test -e $(PROJ_OBJ_DIR)/doxygen ; then \ + $(RM) -rf $(PROJ_OBJ_DIR)/doxygen ; \ + fi + $(Verb) $(DOXYGEN) $(PROJ_OBJ_DIR)/doxygen.cfg + + $(PROJ_OBJ_DIR)/doxygen.tar.gz: $(DOXYFILES) $(PROJ_OBJ_DIR)/doxygen.cfg + $(Echo) Packaging doxygen documentation + $(Verb) $(RM) -rf $@ $(PROJ_OBJ_DIR)/doxygen.tar + $(Verb) $(TAR) cf $(PROJ_OBJ_DIR)/doxygen.tar doxygen + $(Verb) $(GZIP) $(PROJ_OBJ_DIR)/doxygen.tar + $(Verb) $(CP) $(PROJ_OBJ_DIR)/doxygen.tar.gz $(PROJ_OBJ_DIR)/doxygen/html/ + + userloc: $(LLVM_SRC_ROOT)/docs/userloc.html + + $(LLVM_SRC_ROOT)/docs/userloc.html: + $(Echo) Making User LOC Table + $(Verb) cd $(LLVM_SRC_ROOT) ; ./utils/userloc.pl -details -recurse \ + -html lib include tools runtime utils examples autoconf test > docs/userloc.html + Index: llvm-www/releases/2.2/docs/MakefileGuide.html diff -c /dev/null llvm-www/releases/2.2/docs/MakefileGuide.html:1.1 *** /dev/null Tue Feb 12 00:07:04 2008 --- llvm-www/releases/2.2/docs/MakefileGuide.html Tue Feb 12 00:05:03 2008 *************** *** 0 **** --- 1,1041 ---- + + + + + LLVM Makefile Guide + + + + +
    LLVM Makefile Guide
    + +
      +
    1. Introduction
      2. +
    2. General Concepts +
        +
      1. Projects
        2. +
      2. Variable Values
        3. +
      3. Including Makefiles +
          +
        1. Makefile
          2. +
        2. Makefile.common
          3. +
        3. Makefile.config
          4. +
        4. Makefile.rules
          5. +
        +
        4. +
      4. Comments
        5. +
      +
      3. +
    3. Tutorial +
        +
      1. Libraries +
          +
        1. Bitcode Modules
          2. +
        2. Loadable Modules
          3. +
        +
        2. +
      2. Tools +
          +
        1. JIT Tools
          2. +
        +
        3. +
      3. Projects
        4. +
      +
      4. +
    4. Targets Supported +
        +
      1. all
        2. +
      2. all-local
        3. +
      3. check
        4. +
      4. check-local
        5. +
      5. clean
        6. +
      6. clean-local
        7. +
      7. dist
        8. +
      8. dist-check
        9. +
      9. dist-clean
        10. +
      10. install
        11. +
      11. preconditions
        12. +
      12. printvars
        13. +
      13. reconfigure
        14. +
      14. spotless
        15. +
      15. tags
        16. +
      16. uninstall
        17. +
      +
      5. +
    5. Using Variables +
        +
      1. Control Variables
        2. +
      2. Override Variables
        3. +
      3. Readable Variables
        4. +
      4. Internal Variables
        5. +
      +
      6. +
    + +
    +

    Written by Reid Spencer

    +
    + + +
    Introduction
    + + +
    +

    This document provides usage information about the LLVM makefile + system. While loosely patterned after the BSD makefile system, LLVM has taken + a departure from BSD in order to implement additional features needed by LLVM. + Although makefile systems such as automake were attempted at one point, it + has become clear that the features needed by LLVM and the Makefile norm are + too great to use a more limited tool. Consequently, LLVM requires simply GNU + Make 3.79, a widely portable makefile processor. LLVM unabashedly makes heavy + use of the features of GNU Make so the dependency on GNU Make is firm. If + you're not familiar with make, it is recommended that you read the + GNU Makefile + Manual.

    +

    While this document is rightly part of the + LLVM Programmer's Manual, it is treated + separately here because of the volume of content and because it is often an + early source of bewilderment for new developers.

    +
    + + +
    General Concepts
    + + +
    +

    The LLVM Makefile System is the component of LLVM that is responsible for + building the software, testing it, generating distributions, checking those + distributions, installing and uninstalling, etc. It consists of a several + files throughout the source tree. These files and other general concepts are + described in this section.

    +
    + + +
    Projects
    +
    +

    The LLVM Makefile System is quite generous. It not only builds its own + software, but it can build yours too. Built into the system is knowledge of + the llvm/projects directory. Any directory under projects + that has both a configure script and a Makefile is assumed + to be a project that uses the LLVM Makefile system. Building software that + uses LLVM does not require the LLVM Makefile System nor even placement in the + llvm/projects directory. However, doing so will allow your project + to get up and running quickly by utilizing the built-in features that are used + to compile LLVM. LLVM compiles itself using the same features of the makefile + system as used for projects.

    +

    For complete details on setting up your projects configuration, simply + mimic the llvm/projects/sample project or for further details, + consult the Projects.html page.

    +
    + + +
    Variable Values
    +
    +

    To use the makefile system, you simply create a file named + Makefile in your directory and declare values for certain variables. + The variables and values that you select determine what the makefile system + will do. These variables enable rules and processing in the makefile system + that automatically Do The Right Thing™. +

    + + +
    Including Makefiles
    +
    +

    Setting variables alone is not enough. You must include into your Makefile + additional files that provide the rules of the LLVM Makefile system. The + various files involved are described in the sections that follow.

    +
    + + +
    Makefile
    +
    +

    Each directory to participate in the build needs to have a file named + Makefile. This is the file first read by make. It has three + sections:

    +
      +
    1. Settable Variables - Required that must be set + first.
      2. +
    2. include $(LEVEL)/Makefile.common + - include the LLVM Makefile system. +
    3. Override Variables - Override variables set by + the LLVM Makefile system. +
    +
    + + +
    Makefile.common +
    +
    +

    Every project must have a Makefile.common file at its top source + directory. This file serves three purposes:

    +
      +
    1. It includes the project's configuration makefile to obtain values + determined by the configure script. This is done by including the + $(LEVEL)/Makefile.config file.
      2. +
    2. It specifies any other (static) values that are needed throughout the + project. Only values that are used in all or a large proportion of the + project's directories should be placed here.
      3. +
    3. It includes the standard rules for the LLVM Makefile system, + $(LLVM_SRC_ROOT)/Makefile.rules. + This file is the "guts" of the LLVM Makefile system.
      4. +
    +
    + + +
    Makefile.config +
    +
    +

    Every project must have a Makefile.config at the top of its + build directory. This file is generated by the + configure script from the pattern provided by the + Makefile.config.in file located at the top of the project's + source directory. The contents of this file depend largely on what + configuration items the project uses, however most projects can get what they + need by just relying on LLVM's configuration found in + $(LLVM_OBJ_ROOT)/Makefile.config. +

    + + +
    Makefile.rules
    +
    +

    This file, located at $(LLVM_SRC_ROOT)/Makefile.rules is the heart + of the LLVM Makefile System. It provides all the logic, dependencies, and + rules for building the targets supported by the system. What it does largely + depends on the values of make variables that + have been set before Makefile.rules is included. +

    + + +
    Comments
    +
    +

    User Makefiles need not have comments in them unless the construction is + unusual or it does not strictly follow the rules and patterns of the LLVM + makefile system. Makefile comments are invoked with the pound (#) character. + The # character and any text following it, to the end of the line, are ignored + by make.

    +
    + + +
    Tutorial
    + +
    +

    This section provides some examples of the different kinds of modules you + can build with the LLVM makefile system. In general, each directory you + provide will build a single object although that object may be composed of + additionally compiled components.

    +
    + + +
    Libraries
    +
    +

    Only a few variable definitions are needed to build a regular library. + Normally, the makefile system will build all the software into a single + libname.o (pre-linked) object. This means the library is not + searchable and that the distinction between compilation units has been + dissolved. Optionally, you can ask for a shared library (.so), archive library + (.a) or to not have the default (relinked) library built. For example:

    + 
    
+       LIBRARYNAME = mylib
+       SHARED_LIBRARY = 1
+       ARCHIVE_LIBRARY = 1
+       DONT_BUILD_RELINKED = 1
+
    +

    says to build a library named "mylib" with both a shared library + (mylib.so) and an archive library (mylib.a) version but + not to build the relinked object (mylib.o). The contents of all the + libraries produced will be the same, they are just constructed differently. + Note that you normally do not need to specify the sources involved. The LLVM + Makefile system will infer the source files from the contents of the source + directory.

    +

    The LOADABLE_MODULE=1 directive can be used in conjunction with + SHARED_LIBRARY=1 to indicate that the resulting shared library should + be openable with the dlopen function and searchable with the + dlsym function (or your operating system's equivalents). While this + isn't strictly necessary on Linux and a few other platforms, it is required + on systems like HP-UX and Darwin. You should use LOADABLE_MODULE for + any shared library that you intend to be loaded into an tool via the + -load option. See the + WritingAnLLVMPass.html document + for an example of why you might want to do this. +

    + + +
    Bitcode Modules
    +
    +

    In some situations, it is desireable to build a single bitcode module from + a variety of sources, instead of an archive, shared library, or bitcode + library. Bitcode modules can be specified in addition to any of the other + types of libraries by defining the MODULE_NAME + variable. For example:

    + 
    
+       LIBRARYNAME = mylib
+       BYTECODE_LIBRARY = 1
+       MODULE_NAME = mymod
+
    +

    will build a module named mymod.bc from the sources in the + directory. This module will be an aggregation of all the bitcode modules + derived from the sources. The example will also build a bitcode archive + containing a bitcode module for each compiled source file. The difference is + subtle, but important depending on how the module or library is to be linked. +

    +
    + + +
    + Loadable Modules +
    +
    +

    In some situations, you need to create a loadable module. Loadable modules + can be loaded into programs like opt or llc to specify + additional passes to run or targets to support. Loadable modules are also + useful for debugging a pass or providing a pass with another package if that + pass can't be included in LLVM.

    +

    LLVM provides complete support for building such a module. All you need to + do is use the LOADABLE_MODULE variable in your Makefile. For example, to + build a loadable module named MyMod that uses the LLVM libraries + LLVMSupport.a and LLVMSystem.a, you would specify:

    + 
    
+      LIBRARYNAME := MyMod
+      LOADABLE_MODULE := 1
+      LINK_COMPONENTS := support system
+
    +

    Use of the LOADABLE_MODULE facility implies several things:

    +
      +
    1. There will be no "lib" prefix on the module. This differentiates it from + a standard shared library of the same name.
      2. +
    2. The SHARED_LIBRARY variable is turned + on.
      3. +
    3. The LINK_LIBS_IN_SHARED variable + is turned on.
      4. +
    4. The DONT_BUILD_RELINKED variable + is turned on.
      5. +
    +

    A loadable module is loaded by LLVM via the facilities of libtool's libltdl + library which is part of lib/System implementation.

    +
    + + +
    Tools
    +
    +

    For building executable programs (tools), you must provide the name of the + tool and the names of the libraries you wish to link with the tool. For + example:

    + 
    
+       TOOLNAME = mytool
+       USEDLIBS = mylib
+       LINK_COMPONENTS = support system
+
    +

    says that we are to build a tool name mytool and that it requires + three libraries: mylib, LLVMSupport.a and + LLVMSystem.a.

    +

    Note that two different variables are use to indicate which libraries are + linked: USEDLIBS and LLVMLIBS. This distinction is necessary + to support projects. LLVMLIBS refers to the LLVM libraries found in + the LLVM object directory. USEDLIBS refers to the libraries built by + your project. In the case of building LLVM tools, USEDLIBS and + LLVMLIBS can be used interchangeably since the "project" is LLVM + itself and USEDLIBS refers to the same place as LLVMLIBS. +

    +

    Also note that there are two different ways of specifying a library: with a + .a suffix and without. Without the suffix, the entry refers to the + re-linked (.o) file which will include all symbols of the library. + This is useful, for example, to include all passes from a library of passes. + If the .a suffix is used then the library is linked as a searchable + library (with the -l option). In this case, only the symbols that are + unresolved at that point will be resolved from the library, if they + exist. Other (unreferenced) symbols will not be included when the .a + syntax is used. Note that in order to use the .a suffix, the library + in question must have been built with the ARCHIVE_LIBRARY option set. +

    +
    + + +
    JIT Tools
    +
    +

    Many tools will want to use the JIT features of LLVM. To do this, you + simply specify that you want an execution 'engine', and the makefiles will + automatically link in the appropriate JIT for the host or an interpreter + if none is available:

    + 
    
+       TOOLNAME = my_jit_tool
+       USEDLIBS = mylib
+       LINK_COMPONENTS = engine
+
    +

    Of course, any additional libraries may be listed as other components. To + get a full understanding of how this changes the linker command, it is + recommended that you:

    + 
    
+       cd examples/Fibonacci
+       make VERBOSE=1
+
    +
    + + +
    Targets Supported
    + + +
    +

    This section describes each of the targets that can be built using the LLVM + Makefile system. Any target can be invoked from any directory but not all are + applicable to a given directory (e.g. "check", "dist" and "install" will + always operate as if invoked from the top level directory).

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    Target NameImplied TargetsTarget Description
    allCompile the software recursively. Default target. +
    all-localCompile the software in the local directory only. +
    checkChange to the test directory in a project and run the + test suite there. +
    check-localRun a local test suite. Generally this is only defined in the + Makefile of the project's test directory. +
    cleanRemove built objects recursively. +
    clean-localRemove built objects from the local directory only. +
    distallPrepare a source distribution tarball. +
    dist-checkallPrepare a source distribution tarball and check that it builds. +
    dist-cleancleanClean source distribution tarball temporary files. +
    installallCopy built objects to installation directory. +
    preconditionsallCheck to make sure configuration and makefiles are up to date. +
    printvarsallPrints variables defined by the makefile system (for debugging). +
    tagsMake C and C++ tags files for emacs and vi. +
    uninstallRemove built objects from installation directory. +
    +
    + + +
    all (default)
    +
    +

    When you invoke make with no arguments, you are implicitly + instructing it to seek the "all" target (goal). This target is used for + building the software recursively and will do different things in different + directories. For example, in a lib directory, the "all" target will + compile source files and generate libraries. But, in a tools + directory, it will link libraries and generate executables.

    +
    + + +
    all-local
    +
    +

    This target is the same as all but it operates only on + the current directory instead of recursively.

    +
    + + +
    check
    +
    +

    This target can be invoked from anywhere within a project's directories + but always invokes the check-local target + in the project's test directory, if it exists and has a + Makefile. A warning is produced otherwise. If + TESTSUITE is defined on the make + command line, it will be passed down to the invocation of + make check-local in the test directory. The intended usage + for this is to assist in running specific suites of tests. If + TESTSUITE is not set, the implementation of check-local + should run all normal tests. It is up to the project to define what + different values for TESTSUTE will do. See the + TestingGuide for further details.

    +
    + + +
    check-local
    +
    +

    This target should be implemented by the Makefile in the project's + test directory. It is invoked by the check target elsewhere. + Each project is free to define the actions of check-local as + appropriate for that project. The LLVM project itself uses dejagnu to run a + suite of feature and regresson tests. Other projects may choose to use + dejagnu or any other testing mechanism.

    +
    + + +
    clean
    +
    +

    This target cleans the build directory, recursively removing all things + that the Makefile builds. The cleaning rules have been made guarded so they + shouldn't go awry (via rm -f $(UNSET_VARIABLE)/* which will attempt + to erase the entire directory structure.

    +
    + + +
    clean-local
    +
    +

    This target does the same thing as clean but only for the current + (local) directory.

    +
    + + +
    dist
    +
    +

    This target builds a distribution tarball. It first builds the entire + project using the all target and then tars up the necessary files and + compresses it. The generated tarball is sufficient for a casual source + distribution, but probably not for a release (see dist-check).

    +
    + + +
    dist-check
    +
    +

    This target does the same thing as the dist target but also checks + the distribution tarball. The check is made by unpacking the tarball to a new + directory, configuring it, building it, installing it, and then verifying that + the installation results are correct (by comparing to the original build). + This target can take a long time to run but should be done before a release + goes out to make sure that the distributed tarball can actually be built into + a working release.

    +
    + + +
    dist-clean
    +
    +

    This is a special form of the clean clean target. It performs a + normal clean but also removes things pertaining to building the + distribution.

    +
    + + +
    install
    +
    +

    This target finalizes shared objects and executables and copies all + libraries, headers, executables and documentation to the directory given + with the --prefix option to configure. When completed, + the prefix directory will have everything needed to use LLVM.

    +

    The LLVM makefiles can generate complete internal documentation + for all the classes by using doxygen. By default, this feature is + not enabled because it takes a long time and generates a massive + amount of data (>100MB). If you want this feature, you must configure LLVM + with the --enable-doxygen switch and ensure that a modern version of doxygen + (1.3.7 or later) is available in your PATH. You can download + doxygen from + + here. +

    + + +
    preconditions
    +
    +

    This utility target checks to see if the Makefile in the object + directory is older than the Makefile in the source directory and + copies it if so. It also reruns the configure script if that needs to + be done and rebuilds the Makefile.config file similarly. Users may + overload this target to ensure that sanity checks are run before any + building of targets as all the targets depend on preconditions.

    +
    + + +
    printvars
    +
    +

    This utility target just causes the LLVM makefiles to print out some of + the makefile variables so that you can double check how things are set.

    +
    + + +
    reconfigure
    +
    +

    This utility target will force a reconfigure of LLVM or your project. It + simply runs $(PROJ_OBJ_ROOT)/config.status --recheck to rerun the + configuration tests and rebuild the configured files. This isn't generally + useful as the makefiles will reconfigure themselves whenever its necessary. +

    +
    + + +
    spotless
    +
    +

    This utility target, only available when $(PROJ_OBJ_ROOT) is not + the same as $(PROJ_SRC_ROOT), will completely clean the + $(PROJ_OBJ_ROOT) directory by removing its content entirely and + reconfiguring the directory. This returns the $(PROJ_OBJ_ROOT) + directory to a completely fresh state. All content in the directory except + configured files and top-level makefiles will be lost.

    +

    Use with caution.

    +
    + + +
    tags
    +
    +

    This target will generate a TAGS file in the top-level source + directory. It is meant for use with emacs, XEmacs, or ViM. The TAGS file + provides an index of symbol definitions so that the editor can jump you to the + definition quickly.

    +
    + + +
    uninstall
    +
    +

    This target is the opposite of the install target. It removes the + header, library and executable files from the installation directories. Note + that the directories themselves are not removed because it is not guaranteed + that LLVM is the only thing installing there (e.g. --prefix=/usr).

    +
    + + +
    Variables
    + +
    +

    Variables are used to tell the LLVM Makefile System what to do and to + obtain information from it. Variables are also used internally by the LLVM + Makefile System. Variable names that contain only the upper case alphabetic + letters and underscore are intended for use by the end user. All other + variables are internal to the LLVM Makefile System and should not be relied + upon nor modified. The sections below describe how to use the LLVM Makefile + variables.

    +
    + + +
    Control Variables
    +
    +

    Variables listed in the table below should be set before the + inclusion of $(LEVEL)/Makefile.common. + These variables provide input to the LLVM make system that tell it what to do + for the current directory.

    +
    +
    BUILD_ARCHIVE
    +
    If set to any value, causes an archive (.a) library to be built.
    +
    BUILT_SOURCES
    +
    Specifies a set of source files that are generated from other source + files. These sources will be built before any other target processing to + ensure they are present.
    +
    BYTECODE_LIBRARY
    +
    If set to any value, causes a bitcode library (.bc) to be built.
    +
    CONFIG_FILES
    +
    Specifies a set of configuration files to be installed.
    +
    DIRS
    +
    Specifies a set of directories, usually children of the current + directory, that should also be made using the same goal. These directories + will be built serially.
    +
    DISABLE_AUTO_DEPENDENCIES
    +
    If set to any value, causes the makefiles to not automatically + generate dependencies when running the compiler. Use of this feature is + discouraged and it may be removed at a later date.
    +
    DONT_BUILD_RELINKED
    +
    If set to any value, causes a relinked library (.o) not to be built. By + default, libraries are built as re-linked since most LLVM libraries are + needed in their entirety and re-linked libraries will be linked more quickly + than equivalent archive libraries.
    +
    ENABLE_OPTIMIZED
    +
    If set to any value, causes the build to generate optimized objects, + libraries and executables. This alters the flags specified to the compilers + and linkers. Generally debugging won't be a fun experience with an optimized + build.
    +
    ENABLE_PROFILING
    +
    If set to any value, causes the build to generate both optimized and + profiled objects, libraries and executables. This alters the flags specified + to the compilers and linkers to ensure that profile data can be collected + from the tools built. Use the gprof tool to analyze the output from + the profiled tools (gmon.out).
    +
    DISABLE_ASSERTIONS
    +
    If set to any value, causes the build to disable assertions, even if + building a release or profile build. This will exclude all assertion check + code from the build. LLVM will execute faster, but with little help when + things go wrong.
    +
    EXPERIMENTAL_DIRS
    +
    Specify a set of directories that should be built, but if they fail, it + should not cause the build to fail. Note that this should only be used + temporarily while code is being written.
    +
    EXPORTED_SYMBOL_FILE
    +
    Specifies the name of a single file that contains a list of the + symbols to be exported by the linker. One symbol per line.
    +
    EXPORTED_SYMBOL_LIST
    +
    Specifies a set of symbols to be exported by the linker.
    +
    EXTRA_DIST
    +
    Specifies additional files that should be distributed with LLVM. All + source files, all built sources, all Makefiles, and most documentation files + will be automatically distributed. Use this variable to distribute any + files that are not automatically distributed.
    +
    KEEP_SYMBOLS
    +
    If set to any value, specifies that when linking executables the + makefiles should retain debug symbols in the executable. Normally, symbols + are stripped from the executable.
    +
    LEVEL(required)
    +
    Specify the level of nesting from the top level. This variable must be + set in each makefile as it is used to find the top level and thus the other + makefiles.
    +
    LIBRARYNAME
    +
    Specify the name of the library to be built. (Required For + Libraries)
    +
    LINK_COMPONENTS
    +
    When specified for building a tool, the value of this variable will be + passed to the llvm-config tool to generate a link line for the + tool. Unlike USEDLIBS and LLVMLIBS, not all libraries need + to be specified. The llvm-config tool will figure out the library + dependencies and add any libraries that are needed. The USEDLIBS + variable can still be used in conjunction with LINK_COMPONENTS so + that additional project-specific libraries can be linked with the LLVM + libraries specified by LINK_COMPONENTS
    +
    LINK_LIBS_IN_SHARED
    +
    By default, shared library linking will ignore any libraries specified + with the LLVMLIBS or USEDLIBS. + This prevents shared libs from including things that will be in the LLVM + tool the shared library will be loaded into. However, sometimes it is useful + to link certain libraries into your shared library and this option enables + that feature.
    +
    LLVMLIBS
    +
    Specifies the set of libraries from the LLVM $(ObjDir) that will be + linked into the tool or library.
    +
    LOADABLE_MODULE
    +
    If set to any value, causes the shared library being built to also be + a loadable module. Loadable modules can be opened with the dlopen() function + and searched with dlsym (or the operating system's equivalent). Note that + setting this variable without also setting SHARED_LIBRARY will have + no effect.
    +
    MODULE_NAME
    +
    Specifies the name of a bitcode module to be created. A bitcode + module can be specified in conjunction with other kinds of library builds + or by itself. It constructs from the sources a single linked bitcode + file.
    +
    NO_INSTALL
    +
    Specifies that the build products of the directory should not be + installed but should be built even if the install target is given. + This is handy for directories that build libraries or tools that are only + used as part of the build process, such as code generators (e.g. + tblgen).
    +
    OPTIONAL_DIRS
    +
    Specify a set of directories that may be built, if they exist, but its + not an error for them not to exist.
    +
    PARALLEL_DIRS
    +
    Specify a set of directories to build recursively and in parallel if + the -j option was used with make.
    +
    SHARED_LIBRARY
    +
    If set to any value, causes a shared library (.so) to be built in + addition to any other kinds of libraries. Note that this option will cause + all source files to be built twice: once with options for position + independent code and once without. Use it only where you really need a + shared library.
    +
    SOURCES(optional)
    +
    Specifies the list of source files in the current directory to be + built. Source files of any type may be specified (programs, documentation, + config files, etc.). If not specified, the makefile system will infer the + set of source files from the files present in the current directory.
    +
    SUFFIXES
    +
    Specifies a set of filename suffixes that occur in suffix match rules. + Only set this if your local Makefile specifies additional suffix + match rules.
    +
    TARGET
    +
    Specifies the name of the LLVM code generation target that the + current directory builds. Setting this variable enables additional rules to + build .inc files from .td files.
    +
    TESTSUITE
    +
    Specifies the directory of tests to run in llvm/test.
    +
    TOOLNAME
    +
    Specifies the name of the tool that the current directory should + build.
    +
    TOOL_VERBOSE
    +
    Implies VERBOSE and also tells each tool invoked to be verbose. This is + handy when you're trying to see the sub-tools invoked by each tool invoked + by the makefile. For example, this will pass -v to the GCC + compilers which causes it to print out the command lines it uses to invoke + sub-tools (compiler, assembler, linker).
    +
    USEDLIBS
    +
    Specifies the list of project libraries that will be linked into the + tool or library.
    +
    VERBOSE
    +
    Tells the Makefile system to produce detailed output of what it is doing + instead of just summary comments. This will generate a LOT of output.
    +
    +
    + + +
    Override Variables
    +
    +

    Override variables can be used to override the default + values provided by the LLVM makefile system. These variables can be set in + several ways:

    +
      +
    • In the environment (e.g. setenv, export) -- not recommended.
      • +
    • On the make command line -- recommended.
      • +
    • On the configure command line
      • +
    • In the Makefile (only after the inclusion of $(LEVEL)/Makefile.common).
      • +
    +

    The override variables are given below:

    +
    +
    AR (defaulted)
    +
    Specifies the path to the ar tool.
    +
    BISON(configured)
    +
    Specifies the path to the bison tool.
    +
    PROJ_OBJ_DIR
    +
    The directory into which the products of build rules will be placed. + This might be the same as + PROJ_SRC_DIR but typically is + not.
    +
    PROJ_SRC_DIR
    +
    The directory which contains the source files to be built.
    +
    BZIP2(configured)
    +
    The path to the bzip2 tool.
    +
    CC(configured)
    +
    The path to the 'C' compiler.
    +
    CFLAGS
    +
    Additional flags to be passed to the 'C' compiler.
    +
    CXX
    +
    Specifies the path to the C++ compiler.
    +
    CXXFLAGS
    +
    Additional flags to be passed to the C++ compiler.
    +
    DATE(configured)
    +
    Specifies the path to the date program or any program that can + generate the current date and time on its standard output
    +
    DOT(configured)
    +
    Specifies the path to the dot tool or false if there + isn't one.
    +
    ECHO(configured)
    +
    Specifies the path to the echo tool for printing output.
    +
    EXEEXT(configured)
    +
    Provides the extension to be used on executables built by the makefiles. + The value may be empty on platforms that do not use file extensions for + executables (e.g. Unix).
    +
    FLEX(configured)
    +
    Specifies the path to the flex tool.
    +
    INSTALL(configured)
    +
    Specifies the path to the install tool.
    +
    LDFLAGS(configured)
    +
    Allows users to specify additional flags to pass to the linker.
    +
    LIBS(configured)
    +
    The list of libraries that should be linked with each tool.
    +
    LIBTOOL(configured)
    +
    Specifies the path to the libtool tool. This tool is renamed + mklib by the configure script and always located in the +
    LLVMAS(defaulted)
    +
    Specifies the path to the llvm-as tool.
    +
    LLVMGCC(defaulted)
    +
    Specifies the path to the LLVM version of the GCC 'C' Compiler
    +
    LLVMGXX(defaulted)
    +
    Specifies the path to the LLVM version of the GCC C++ Compiler
    +
    LLVMLD(defaulted)
    +
    Specifies the path to the LLVM bitcode linker tool
    +
    LLVM_OBJ_ROOT(configured) +
    +
    Specifies the top directory into which the output of the build is + placed.
    +
    LLVM_SRC_ROOT(configured) +
    +
    Specifies the top directory in which the sources are found.
    +
    LLVM_TARBALL_NAME + (configured)
    +
    Specifies the name of the distribution tarball to create. This is + configured from the name of the project and its version number.
    +
    MKDIR(defaulted)
    +
    Specifies the path to the mkdir tool that creates + directories.
    +
    PLATFORMSTRIPOPTS
    +
    The options to provide to the linker to specify that a stripped (no + symbols) executable should be built.
    +
    RANLIB(defaulted)
    +
    Specifies the path to the ranlib tool.
    +
    RM(defaulted)
    +
    Specifies the path to the rm tool.
    +
    SED(defaulted)
    +
    Specifies the path to the sed tool.
    +
    SHLIBEXT(configured)
    +
    Provides the filename extension to use for shared libraries.
    +
    TBLGEN(defaulted)
    +
    Specifies the path to the tblgen tool.
    +
    TAR(defaulted)
    +
    Specifies the path to the tar tool.
    +
    ZIP(defaulted)
    +
    Specifies the path to the zip tool.
    +
    +
    + + +
    Readable Variables
    +
    +

    Variables listed in the table below can be used by the user's Makefile but + should not be changed. Changing the value will generally cause the build to go + wrong, so don't do it.

    +
    +
    bindir
    +
    The directory into which executables will ultimately be installed. This + value is derived from the --prefix option given to + configure.
    +
    BuildMode
    +
    The name of the type of build being performed: Debug, Release, or + Profile
    +
    bytecode_libdir
    +
    The directory into which bitcode libraries will ultimately be + installed. This value is derived from the --prefix option given to + configure.
    +
    ConfigureScriptFLAGS
    +
    Additional flags given to the configure script when + reconfiguring.
    +
    DistDir
    +
    The current directory for which a distribution copy is being + made.
    +
    Echo
    +
    The LLVM Makefile System output command. This provides the + llvm[n] prefix and starts with @ so the command itself is not + printed by make.
    +
    EchoCmd
    +
    Same as Echo but without the leading @. +
    +
    includedir
    +
    The directory into which include files will ultimately be installed. + This value is derived from the --prefix option given to + configure.
    +
    libdir
    +
    The directory into which native libraries will ultimately be installed. + This value is derived from the --prefix option given to + configure.
    +
    LibDir
    +
    The configuration specific directory into which libraries are placed + before installation.
    +
    MakefileConfig
    +
    Full path of the Makefile.config file.
    +
    MakefileConfigIn
    +
    Full path of the Makefile.config.in file.
    +
    ObjDir
    +
    The configuration and directory specific directory where build objects + (compilation results) are placed.
    +
    SubDirs
    +
    The complete list of sub-directories of the current directory as + specified by other variables.
    +
    Sources
    +
    The complete list of source files.
    +
    sysconfdir
    +
    The directory into which configuration files will ultimately be + installed. This value is derived from the --prefix option given to + configure.
    +
    ToolDir
    +
    The configuration specific directory into which executables are placed + before they are installed.
    +
    TopDistDir
    +
    The top most directory into which the distribution files are copied. +
    +
    Verb
    +
    Use this as the first thing on your build script lines to enable or + disable verbose mode. It expands to either an @ (quiet mode) or nothing + (verbose mode).
    +
    +
    + + +
    Internal Variables
    +
    +

    Variables listed below are used by the LLVM Makefile System + and considered internal. You should not use these variables under any + circumstances.

    +

    + Archive + AR.Flags + BaseNameSources + BCCompile.C + BCCompile.CXX + BCLinkLib + C.Flags + Compile.C + CompileCommonOpts + Compile.CXX + ConfigStatusScript + ConfigureScript + CPP.Flags + CPP.Flags + CXX.Flags + DependFiles + DestArchiveLib + DestBitcodeLib + DestModule + DestRelinkedLib + DestSharedLib + DestTool + DistAlways + DistCheckDir + DistCheckTop + DistFiles + DistName + DistOther + DistSources + DistSubDirs + DistTarBZ2 + DistTarGZip + DistZip + ExtraLibs + FakeSources + INCFiles + InternalTargets + LD.Flags + LexFiles + LexOutput + LibName.A + LibName.BC + LibName.LA + LibName.O + LibTool.Flags + Link + LinkModule + LLVMLibDir + LLVMLibsOptions + LLVMLibsPaths + LLVMToolDir + LLVMUsedLibs + LocalTargets + LTCompile.C + LTCompile.CXX + LTInstall + Module + ObjectsBC + ObjectsLO + ObjectsO + ObjMakefiles + ParallelTargets + PreConditions + ProjLibsOptions + ProjLibsPaths + ProjUsedLibs + Ranlib + RecursiveTargets + Relink + SrcMakefiles + Strip + StripWarnMsg + TableGen + TDFiles + ToolBuildPath + TopLevelTargets + UserTargets + YaccFiles + YaccOutput +

    +
    + + +
    +
    + Valid CSS! + Valid HTML 4.01! + + Reid Spencer
    + The LLVM Compiler Infrastructure
    + Last modified: $Date: 2008/02/12 06:05:03 $ +
    + + Index: llvm-www/releases/2.2/docs/Passes.html diff -c /dev/null llvm-www/releases/2.2/docs/Passes.html:1.1 *** /dev/null Tue Feb 12 00:07:04 2008 --- llvm-www/releases/2.2/docs/Passes.html Tue Feb 12 00:05:03 2008 *************** *** 0 **** --- 1,1930 ---- + + + + LLVM's Analysis and Transform Passes + + + + + + + +
    LLVM's Analysis and Transform Passes
    + +
      +
    1. Introduction
      2. +
    2. Analysis Passes +
    3. Transform Passes
      4. +
    4. Utility Passes
      5. +
    + +
    +

    Written by Reid Spencer + and Gordon Henriksen

    +
    + + +
    Introduction
    +
    +

    This document serves as a high level summary of the optimization features + that LLVM provides. Optimizations are implemented as Passes that traverse some + portion of a program to either collect information or transform the program. + The table below divides the passes that LLVM provides into three categories. + Analysis passes compute information that other passes can use or for debugging + or program visualization purposes. Transform passes can use (or invalidate) + the analysis passes. Transform passes all mutate the program in some way. + Utility passes provides some utility but don't otherwise fit categorization. + For example passes to extract functions to bitcode or write a module to + bitcode are neither analysis nor transform passes. +

    The table below provides a quick summary of each pass and links to the more + complete pass description later in the document.

    +
    +
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    ANALYSIS PASSES
    OptionName
    -aa-evalExhaustive Alias Analysis Precision Evaluator
    -anders-aaAndersen's Interprocedural Alias Analysis
    -basicaaBasic Alias Analysis (default AA impl)
    -basiccgBasic CallGraph Construction
    -basicvnBasic Value Numbering (default GVN impl)
    -callgraphPrint a call graph
    -callsccPrint SCCs of the Call Graph
    -cfgsccPrint SCCs of each function CFG
    -codegenprepareOptimize for code generation
    -count-aaCount Alias Analysis Query Responses
    -debug-aaAA use debugger
    -domfrontierDominance Frontier Construction
    -domtreeDominator Tree Construction
    -externalfnconstantsPrint external fn callsites passed constants
    -globalsmodref-aaSimple mod/ref analysis for globals
    -instcountCounts the various types of Instructions
    -intervalsInterval Partition Construction
    -load-vnLoad Value Numbering
    -loopsNatural Loop Construction
    -memdepMemory Dependence Analysis
    -no-aaNo Alias Analysis (always returns 'may' alias)
    -no-profileNo Profile Information
    -postdomfrontierPost-Dominance Frontier Construction
    -postdomtreePost-Dominator Tree Construction
    -printPrint function to stderr
    -print-alias-setsAlias Set Printer
    -print-callgraphPrint Call Graph to 'dot' file
    -print-cfgPrint CFG of function to 'dot' file
    -print-cfg-onlyPrint CFG of function to 'dot' file (with no function bodies)
    -printmPrint module to stderr
    -printusedtypesFind Used Types
    -profile-loaderLoad profile information from llvmprof.out
    -scalar-evolutionScalar Evolution Analysis
    -targetdataTarget Data Layout
    TRANSFORM PASSES
    OptionName
    -adceAggressive Dead Code Elimination
    -argpromotionPromote 'by reference' arguments to scalars
    -block-placementProfile Guided Basic Block Placement
    -break-crit-edgesBreak critical edges in CFG
    -ceeCorrelated Expression Elimination
    -condpropConditional Propagation
    -constmergeMerge Duplicate Global Constants
    -constpropSimple constant propagation
    -dceDead Code Elimination
    -deadargelimDead Argument Elimination
    -deadtypeelimDead Type Elimination
    -dieDead Instruction Elimination
    -dseDead Store Elimination
    -gcseGlobal Common Subexpression Elimination
    -globaldceDead Global Elimination
    -globaloptGlobal Variable Optimizer
    -gvnGlobal Value Numbering
    -gvnpreGlobal Value Numbering/Partial Redundancy Elimination
    -indmemremIndirect Malloc and Free Removal
    -indvarsCanonicalize Induction Variables
    -inlineFunction Integration/Inlining
    -insert-block-profilingInsert instrumentation for block profiling
    -insert-edge-profilingInsert instrumentation for edge profiling
    -insert-function-profilingInsert instrumentation for function profiling
    -insert-null-profiling-rsMeasure profiling framework overhead
    -insert-rs-profiling-frameworkInsert random sampling instrumentation framework
    -instcombineCombine redundant instructions
    -internalizeInternalize Global Symbols
    -ipconstpropInterprocedural constant propagation
    -ipsccpInterprocedural Sparse Conditional Constant Propagation
    -lcssaLoop-Closed SSA Form Pass
    -licmLoop Invariant Code Motion
    -loop-extractExtract loops into new functions
    -loop-extract-singleExtract at most one loop into a new function
    -loop-index-splitIndex Split Loops
    -loop-reduceLoop Strength Reduction
    -loop-rotateRotate Loops
    -loop-unrollUnroll loops
    -loop-unswitchUnswitch loops
    -loopsimplifyCanonicalize natural loops
    -lower-packedlowers packed operations to operations on smaller packed datatypes
    -lowerallocsLower allocations from instructions to calls
    -lowergcLower GC intrinsics, for GCless code generators
    -lowerinvokeLower invoke and unwind, for unwindless code generators
    -lowerselectLower select instructions to branches
    -lowersetjmpLower Set Jump
    -lowerswitchLower SwitchInst's to branches
    -mem2regPromote Memory to Register
    -mergereturnUnify function exit nodes
    -predsimplifyPredicate Simplifier
    -prune-ehRemove unused exception handling info
    -raiseallocsRaise allocations from calls to instructions
    -reassociateReassociate expressions
    -reg2memDemote all values to stack slots
    -scalarreplScalar Replacement of Aggregates
    -sccpSparse Conditional Constant Propagation
    -simplify-libcallsSimplify well-known library calls
    -simplifycfgSimplify the CFG
    -stripStrip all symbols from a module
    -tailcallelimTail Call Elimination
    -tailduplicateTail Duplication
    UTILITY PASSES
    OptionName
    -deadarghaX0rDead Argument Hacking (BUGPOINT USE ONLY; DO NOT USE)
    -extract-blocksExtract Basic Blocks From Module (for bugpoint use)
    -preverifyPreliminary module verification
    -verifyModule Verifier
    -view-cfgView CFG of function
    -view-cfg-onlyView CFG of function (with no function bodies)
    +
    + + +
    Analysis Passes
    +
    +

    This section describes the LLVM Analysis Passes.

    +
    + + +
    + Exhaustive Alias Analysis Precision Evaluator +
    +
    +

    This is a simple N^2 alias analysis accuracy evaluator. + Basically, for each function in the program, it simply queries to see how the + alias analysis implementation answers alias queries between each pair of + pointers in the function.

    + +

    This is inspired and adapted from code by: Naveen Neelakantam, Francesco + Spadini, and Wojciech Stryjewski.

    +
    + + +
    + Andersen's Interprocedural Alias Analysis +
    +
    +

    + This is an implementation of Andersen's interprocedural alias + analysis +

    + +

    + In pointer analysis terms, this is a subset-based, flow-insensitive, + field-sensitive, and context-insensitive algorithm pointer algorithm. +

    + +

    + This algorithm is implemented as three stages: +

    + +
      +
    1. Object identification.
      2. +
    2. Inclusion constraint identification.
      3. +
    3. Offline constraint graph optimization.
      4. +
    4. Inclusion constraint solving.
      5. +
    + +

    + The object identification stage identifies all of the memory objects in the + program, which includes globals, heap allocated objects, and stack allocated + objects. +

    + +

    + The inclusion constraint identification stage finds all inclusion constraints + in the program by scanning the program, looking for pointer assignments and + other statements that effect the points-to graph. For a statement like + A = B, this statement is processed to + indicate that A can point to anything that B can point + to. Constraints can handle copies, loads, and stores, and address taking. +

    + +

    + The offline constraint graph optimization portion includes offline variable + substitution algorithms intended to computer pointer and location + equivalences. Pointer equivalences are those pointers that will have the + same points-to sets, and location equivalences are those variables that + always appear together in points-to sets. +

    + +

    + The inclusion constraint solving phase iteratively propagates the inclusion + constraints until a fixed point is reached. This is an O(n??) + algorithm. +

    + +

    + Function constraints are handled as if they were structs with X + fields. Thus, an access to argument X of function Y is + an access to node index getNode(Y) + X. + This representation allows handling of indirect calls without any issues. To + wit, an indirect call Y(a,b) is + equivalent to *(Y + 1) = a, *(Y + 2) = + b. The return node for a function F is always + located at getNode(F) + CallReturnPos. The arguments + start at getNode(F) + CallArgPos. +

    +
    + + +
    + Basic Alias Analysis (default AA impl) +
    +
    +

    + This is the default implementation of the Alias Analysis interface + that simply implements a few identities (two different globals cannot alias, + etc), but otherwise does no analysis. +

    +
    + + +
    + Basic CallGraph Construction +
    +
    +

    Yet to be written.

    +
    + + +
    + Basic Value Numbering (default GVN impl) +
    +
    +

    + This is the default implementation of the ValueNumbering + interface. It walks the SSA def-use chains to trivially identify + lexically identical expressions. This does not require any ahead of time + analysis, so it is a very fast default implementation. +

    +
    + + +
    + Print a call graph +
    +
    +

    + This pass, only available in opt, prints the call graph to + standard output in a human-readable form. +

    +
    + + +
    + Print SCCs of the Call Graph +
    +
    +

    + This pass, only available in opt, prints the SCCs of the call + graph to standard output in a human-readable form. +

    +
    + + +
    + Print SCCs of each function CFG +
    +
    +

    + This pass, only available in opt, prints the SCCs of each + function CFG to standard output in a human-readable form. +

    +
    + + +
    + Optimize for code generation +
    +
    +

    + This pass munges the code in the input function to better prepare it for + SelectionDAG-based code generation. This works around limitations in it's + basic-block-at-a-time approach. It should eventually be removed. +

    +
    + + +
    + Count Alias Analysis Query Responses +
    +
    +

    + A pass which can be used to count how many alias queries + are being made and how the alias analysis implementation being used responds. +

    +
    + + +
    + AA use debugger +
    +
    +

    + This simple pass checks alias analysis users to ensure that if they + create a new value, they do not query AA without informing it of the value. + It acts as a shim over any other AA pass you want. +

    + +

    + Yes keeping track of every value in the program is expensive, but this is + a debugging pass. +

    +
    + + +
    + Dominance Frontier Construction +
    +
    +

    + This pass is a simple dominator construction algorithm for finding forward + dominator frontiers. +

    +
    + + +
    + Dominator Tree Construction +
    +
    +

    + This pass is a simple dominator construction algorithm for finding forward + dominators. +

    +
    + + +
    + Print external fn callsites passed constants +
    +
    +

    + This pass, only available in opt, prints out call sites to + external functions that are called with constant arguments. This can be + useful when looking for standard library functions we should constant fold + or handle in alias analyses. +

    +
    + + +
    + Simple mod/ref analysis for globals +
    +
    +

    + This simple pass provides alias and mod/ref information for global values + that do not have their address taken, and keeps track of whether functions + read or write memory (are "pure"). For this simple (but very common) case, + we can provide pretty accurate and useful information. +

    +
    + + +
    + Counts the various types of Instructions +
    +
    +

    + This pass collects the count of all instructions and reports them +

    +
    + + +
    + Interval Partition Construction +
    +
    +

    + This analysis calculates and represents the interval partition of a function, + or a preexisting interval partition. +

    + +

    + In this way, the interval partition may be used to reduce a flow graph down + to its degenerate single node interval partition (unless it is irreducible). +

    +
    + + +
    + Load Value Numbering +
    +
    +

    + This pass value numbers load and call instructions. To do this, it finds + lexically identical load instructions, and uses alias analysis to determine + which loads are guaranteed to produce the same value. To value number call + instructions, it looks for calls to functions that do not write to memory + which do not have intervening instructions that clobber the memory that is + read from. +

    + +

    + This pass builds off of another value numbering pass to implement value + numbering for non-load and non-call instructions. It uses Alias Analysis so + that it can disambiguate the load instructions. The more powerful these base + analyses are, the more powerful the resultant value numbering will be. +

    +
    + + +
    + Natural Loop Construction +
    +
    +

    + This analysis is used to identify natural loops and determine the loop depth + of various nodes of the CFG. Note that the loops identified may actually be + several natural loops that share the same header node... not just a single + natural loop. +

    +
    + + +
    + Memory Dependence Analysis +
    +
    +

    + An analysis that determines, for a given memory operation, what preceding + memory operations it depends on. It builds on alias analysis information, and + tries to provide a lazy, caching interface to a common kind of alias + information query. +

    +
    + + +
    + No Alias Analysis (always returns 'may' alias) +
    +
    +

    + Always returns "I don't know" for alias queries. NoAA is unlike other alias + analysis implementations, in that it does not chain to a previous analysis. As + such it doesn't follow many of the rules that other alias analyses must. +

    +
    + + +
    + No Profile Information +
    +
    +

    + The default "no profile" implementation of the abstract + ProfileInfo interface. +

    +
    + + +
    + Post-Dominance Frontier Construction +
    +
    +

    + This pass is a simple post-dominator construction algorithm for finding + post-dominator frontiers. +

    +
    + + +
    + Post-Dominator Tree Construction +
    +
    +

    + This pass is a simple post-dominator construction algorithm for finding + post-dominators. +

    +
    + + +
    + Print function to stderr +
    +
    +

    + The PrintFunctionPass class is designed to be pipelined with + other FunctionPasses, and prints out the functions of the module + as they are processed. +

    +
    + + +
    + Alias Set Printer +
    +
    +

    Yet to be written.

    +
    + + +
    + Print Call Graph to 'dot' file +
    +
    +

    + This pass, only available in opt, prints the call graph into a + .dot graph. This graph can then be processed with the "dot" tool + to convert it to postscript or some other suitable format. +

    +
    + + +
    + Print CFG of function to 'dot' file +
    +
    +

    + This pass, only available in opt, prints the control flow graph + into a .dot graph. This graph can then be processed with the + "dot" tool to convert it to postscript or some other suitable format. +

    +
    + + +
    + Print CFG of function to 'dot' file (with no function bodies) +
    +
    +

    + This pass, only available in opt, prints the control flow graph + into a .dot graph, omitting the function bodies. This graph can + then be processed with the "dot" tool to convert it to postscript or some + other suitable format. +

    +
    + + +
    + Print module to stderr +
    +
    +

    + This pass simply prints out the entire module when it is executed. +

    +
    + + +
    + Find Used Types +
    +
    +

    + This pass is used to seek out all of the types in use by the program. Note + that this analysis explicitly does not include types only used by the symbol + table. +

    + + +
    + Load profile information from llvmprof.out +
    +
    +

    + A concrete implementation of profiling information that loads the information + from a profile dump file. +

    +
    + + +
    + Scalar Evolution Analysis +
    +
    +

    + The ScalarEvolution analysis can be used to analyze and + catagorize scalar expressions in loops. It specializes in recognizing general + induction variables, representing them with the abstract and opaque + SCEV class. Given this analysis, trip counts of loops and other + important properties can be obtained. +

    + +

    + This analysis is primarily useful for induction variable substitution and + strength reduction. +

    +
    + + +
    + Target Data Layout +
    +
    +

    Provides other passes access to information on how the size and alignment + required by the the target ABI for various data types.

    +
    + + +
    Transform Passes
    +
    +

    This section describes the LLVM Transform Passes.

    +
    + + +
    + Aggressive Dead Code Elimination +
    +
    +

    ADCE aggressively tries to eliminate code. This pass is similar to + DCE but it assumes that values are dead until proven + otherwise. This is similar to SCCP, except applied to + the liveness of values.

    +
    + + +
    + Promote 'by reference' arguments to scalars +
    +
    +

    + This pass promotes "by reference" arguments to be "by value" arguments. In + practice, this means looking for internal functions that have pointer + arguments. If it can prove, through the use of alias analysis, that an + argument is *only* loaded, then it can pass the value into the function + instead of the address of the value. This can cause recursive simplification + of code and lead to the elimination of allocas (especially in C++ template + code like the STL). +

    + +

    + This pass also handles aggregate arguments that are passed into a function, + scalarizing them if the elements of the aggregate are only loaded. Note that + it refuses to scalarize aggregates which would require passing in more than + three operands to the function, because passing thousands of operands for a + large array or structure is unprofitable! +

    + +

    + Note that this transformation could also be done for arguments that are only + stored to (returning the value instead), but does not currently. This case + would be best handled when and if LLVM starts supporting multiple return + values from functions. +

    +
    + + +
    + Profile Guided Basic Block Placement +
    +
    +

    This pass is a very simple profile guided basic block placement algorithm. + The idea is to put frequently executed blocks together at the start of the + function and hopefully increase the number of fall-through conditional + branches. If there is no profile information for a particular function, this + pass basically orders blocks in depth-first order.

    +
    + + +
    + Break critical edges in CFG +
    +
    +

    + Break all of the critical edges in the CFG by inserting a dummy basic block. + It may be "required" by passes that cannot deal with critical edges. This + transformation obviously invalidates the CFG, but can update forward dominator + (set, immediate dominators, tree, and frontier) information. +

    +
    + + +
    + Correlated Expression Elimination +
    +
    +

    Correlated Expression Elimination propagates information from conditional + branches to blocks dominated by destinations of the branch. It propagates + information from the condition check itself into the body of the branch, + allowing transformations like these for example:

    + + 
    + if (i == 7)
+   ... 4*i;  // constant propagation
+ 
+ M = i+1; N = j+1;
+ if (i == j)
+   X = M-N;  // = M-M == 0;
+
    + +

    This is called Correlated Expression Elimination because we eliminate or + simplify expressions that are correlated with the direction of a branch. In + this way we use static information to give us some information about the + dynamic value of a variable.

    +
    + + +
    + Conditional Propagation +
    +
    +

    This pass propagates information about conditional expressions through the + program, allowing it to eliminate conditional branches in some cases.

    +
    + + +
    + Merge Duplicate Global Constants +
    +
    +

    + Merges duplicate global constants together into a single constant that is + shared. This is useful because some passes (ie TraceValues) insert a lot of + string constants into the program, regardless of whether or not an existing + string is available. +

    +
    + + +
    + Simple constant propagation +
    +
    +

    This file implements constant propagation and merging. It looks for + instructions involving only constant operands and replaces them with a + constant value instead of an instruction. For example:

    + 
    add i32 1, 2
    +

    becomes

    + 
    i32 3
    +

    NOTE: this pass has a habit of making definitions be dead. It is a good + idea to to run a DIE (Dead Instruction Elimination) pass + sometime after running this pass.

    +
    + + +
    + Dead Code Elimination +
    +
    +

    + Dead code elimination is similar to dead instruction + elimination, but it rechecks instructions that were used by removed + instructions to see if they are newly dead. +

    +
    + + +
    + Dead Argument Elimination +
    +
    +

    + This pass deletes dead arguments from internal functions. Dead argument + elimination removes arguments which are directly dead, as well as arguments + only passed into function calls as dead arguments of other functions. This + pass also deletes dead arguments in a similar way. +

    + +

    + This pass is often useful as a cleanup pass to run after aggressive + interprocedural passes, which add possibly-dead arguments. +

    +
    + + +
    + Dead Type Elimination +
    +
    +

    + This pass is used to cleanup the output of GCC. It eliminate names for types + that are unused in the entire translation unit, using the find used types pass. +

    +
    + + +
    + Dead Instruction Elimination +
    +
    +

    + Dead instruction elimination performs a single pass over the function, + removing instructions that are obviously dead. +

    +
    + + +
    + Dead Store Elimination +
    +
    +

    + A trivial dead store elimination that only considers basic-block local + redundant stores. +

    +
    + + +
    + Global Common Subexpression Elimination +
    +
    +

    + This pass is designed to be a very quick global transformation that + eliminates global common subexpressions from a function. It does this by + using an existing value numbering implementation to identify the common + subexpressions, eliminating them when possible. +

    +
    + + +
    + Dead Global Elimination +
    +
    +

    + This transform is designed to eliminate unreachable internal globals from the + program. It uses an aggressive algorithm, searching out globals that are + known to be alive. After it finds all of the globals which are needed, it + deletes whatever is left over. This allows it to delete recursive chunks of + the program which are unreachable. +

    +
    + + +
    + Global Variable Optimizer +
    +
    +

    + This pass transforms simple global variables that never have their address + taken. If obviously true, it marks read/write globals as constant, deletes + variables only stored to, etc. +

    +
    + + +
    + Global Value Numbering +
    +
    +

    + This pass performs global value numbering to eliminate fully redundant + instructions. It also performs simple dead load elimination. +

    +
    + + +
    + Global Value Numbering/Partial Redundancy Elimination +
    +
    +

    + This pass performs a hybrid of global value numbering and partial redundancy + elimination, known as GVN-PRE. It performs partial redundancy elimination on + values, rather than lexical expressions, allowing a more comprehensive view + the optimization. It replaces redundant values with uses of earlier + occurences of the same value. While this is beneficial in that it eliminates + unneeded computation, it also increases register pressure by creating large + live ranges, and should be used with caution on platforms that are very + sensitive to register pressure. +

    +
    + + +
    + Indirect Malloc and Free Removal +
    +
    +

    + This pass finds places where memory allocation functions may escape into + indirect land. Some transforms are much easier (aka possible) only if free + or malloc are not called indirectly. +

    + +

    + Thus find places where the address of memory functions are taken and construct + bounce functions with direct calls of those functions. +

    +
    + + +
    + Canonicalize Induction Variables +
    +
    +

    + This transformation analyzes and transforms the induction variables (and + computations derived from them) into simpler forms suitable for subsequent + analysis and transformation. +

    + +

    + This transformation makes the following changes to each loop with an + identifiable induction variable: +

    + +
      +
    1. All loops are transformed to have a single canonical + induction variable which starts at zero and steps by one.
      2. +
    2. The canonical induction variable is guaranteed to be the first PHI node + in the loop header block.
      3. +
    3. Any pointer arithmetic recurrences are raised to use array + subscripts.
      4. +
    + +

    + If the trip count of a loop is computable, this pass also makes the following + changes: +

    + +
      +
    1. The exit condition for the loop is canonicalized to compare the + induction value against the exit value. This turns loops like: + 
      for (i = 7; i*i < 1000; ++i)
      + into + 
      for (i = 0; i != 25; ++i)
      2. +
    2. Any use outside of the loop of an expression derived from the indvar + is changed to compute the derived value outside of the loop, eliminating + the dependence on the exit value of the induction variable. If the only + purpose of the loop is to compute the exit value of some derived + expression, this transformation will make the loop dead.
      3. +
    + +

    + This transformation should be followed by strength reduction after all of the + desired loop transformations have been performed. Additionally, on targets + where it is profitable, the loop could be transformed to count down to zero + (the "do loop" optimization). +

    +
    + + +
    + Function Integration/Inlining +
    +
    +

    + Bottom-up inlining of functions into callees. +

    +
    + + +
    + Insert instrumentation for block profiling +
    +
    +

    + This pass instruments the specified program with counters for basic block + profiling, which counts the number of times each basic block executes. This + is the most basic form of profiling, which can tell which blocks are hot, but + cannot reliably detect hot paths through the CFG. +

    + +

    + Note that this implementation is very na??ve. Control equivalent regions of + the CFG should not require duplicate counters, but it does put duplicate + counters in. +

    +
    + + +
    + Insert instrumentation for edge profiling +
    +
    +

    + This pass instruments the specified program with counters for edge profiling. + Edge profiling can give a reasonable approximation of the hot paths through a + program, and is used for a wide variety of program transformations. +

    + +

    + Note that this implementation is very na??ve. It inserts a counter for + every edge in the program, instead of using control flow information + to prune the number of counters inserted. +

    +
    + + +
    + Insert instrumentation for function profiling +
    +
    +

    + This pass instruments the specified program with counters for function + profiling, which counts the number of times each function is called. +

    +
    + + +
    + Measure profiling framework overhead +
    +
    +

    + The basic profiler that does nothing. It is the default profiler and thus + terminates RSProfiler chains. It is useful for measuring + framework overhead. +

    +
    + + +
    + Insert random sampling instrumentation framework +
    +
    +

    + The second stage of the random-sampling instrumentation framework, duplicates + all instructions in a function, ignoring the profiling code, then connects the + two versions together at the entry and at backedges. At each connection point + a choice is made as to whether to jump to the profiled code (take a sample) or + execute the unprofiled code. +

    + +

    + After this pass, it is highly recommended to runmem2reg + and adce. instcombine, + load-vn, gdce, and + dse also are good to run afterwards. +

    +
    + + +
    + Combine redundant instructions +
    +
    +

    + Combine instructions to form fewer, simple + instructions. This pass does not modify the CFG This pass is where algebraic + simplification happens. +

    + +

    + This pass combines things like: +

    + + 
    %Y = add i32 %X, 1
+ %Z = add i32 %Y, 1
    + +

    + into: +

    + + 
    %Z = add i32 %X, 2
    + +

    + This is a simple worklist driven algorithm. +

    + +

    + This pass guarantees that the following canonicalizations are performed on + the program: +

    + +
      +
    • If a binary operator has a constant operand, it is moved to the right- + hand side.
      • +
    • Bitwise operators with constant operands are always grouped so that + shifts are performed first, then ors, then + ands, then xors.
      • +
    • Compare instructions are converted from <, + >, ???, or ??? to + = or ??? if possible.
      • +
    • All cmp instructions on boolean values are replaced with + logical operations.
      • +
    • add X, X is represented as + mul X, 2 ??? shl X, 1
      • +
    • Multiplies with a constant power-of-two argument are transformed into + shifts.
      • +
    • ??? etc.
      • +
    +
    + + +
    + Internalize Global Symbols +
    +
    +

    + This pass loops over all of the functions in the input module, looking for a + main function. If a main function is found, all other functions and all + global variables with initializers are marked as internal. +

    +
    + + +
    + Interprocedural constant propagation +
    +
    +

    + This pass implements an extremely simple interprocedural constant + propagation pass. It could certainly be improved in many different ways, + like using a worklist. This pass makes arguments dead, but does not remove + them. The existing dead argument elimination pass should be run after this + to clean up the mess. +

    +
    + + +
    + Interprocedural Sparse Conditional Constant Propagation +
    +
    +

    + An interprocedural variant of Sparse Conditional Constant + Propagation. +

    +
    + + +
    + Loop-Closed SSA Form Pass +
    +
    +

    + This pass transforms loops by placing phi nodes at the end of the loops for + all values that are live across the loop boundary. For example, it turns + the left into the right code: +

    + + 
    for (...)                for (...)
+   if (c)                   if (c)
+     X1 = ...                 X1 = ...
+   else                     else
+     X2 = ...                 X2 = ...
+   X3 = phi(X1, X2)         X3 = phi(X1, X2)
+ ... = X3 + 4              X4 = phi(X3)
+                           ... = X4 + 4
    + +

    + This is still valid LLVM; the extra phi nodes are purely redundant, and will + be trivially eliminated by InstCombine. The major benefit of + this transformation is that it makes many other loop optimizations, such as + LoopUnswitching, simpler. +

    +
    + + +
    + Loop Invariant Code Motion +
    +
    +

    + This pass performs loop invariant code motion, attempting to remove as much + code from the body of a loop as possible. It does this by either hoisting + code into the preheader block, or by sinking code to the exit blocks if it is + safe. This pass also promotes must-aliased memory locations in the loop to + live in registers, thus hoisting and sinking "invariant" loads and stores. +

    + +

    + This pass uses alias analysis for two purposes: +

    + +
      +
    • Moving loop invariant loads and calls out of loops. If we can determine + that a load or call inside of a loop never aliases anything stored to, + we can hoist it or sink it like any other instruction.
      • +
    • Scalar Promotion of Memory - If there is a store instruction inside of + the loop, we try to move the store to happen AFTER the loop instead of + inside of the loop. This can only happen if a few conditions are true: +
        +
      • The pointer stored through is loop invariant.
        • +
      • There are no stores or loads in the loop which may alias + the pointer. There are no calls in the loop which mod/ref the + pointer.
        • +
      + If these conditions are true, we can promote the loads and stores in the + loop of the pointer to use a temporary alloca'd variable. We then use + the mem2reg functionality to construct the appropriate SSA form for the + variable.
      • +
    +
    + + +
    + Extract loops into new functions +
    +
    +

    + A pass wrapper around the ExtractLoop() scalar transformation to + extract each top-level loop into its own new function. If the loop is the + only loop in a given function, it is not touched. This is a pass most + useful for debugging via bugpoint. +

    +
    + + +
    + Extract at most one loop into a new function +
    +
    +

    + Similar to Extract loops into new functions, + this pass extracts one natural loop from the program into a function if it + can. This is used by bugpoint. +

    +
    + + +
    + Index Split Loops +
    +
    +

    + This pass divides loop's iteration range by spliting loop such that each + individual loop is executed efficiently. +

    +
    + + +
    + Loop Strength Reduction +
    +
    +

    + This pass performs a strength reduction on array references inside loops that + have as one or more of their components the loop induction variable. This is + accomplished by creating a new value to hold the initial value of the array + access for the first iteration, and then creating a new GEP instruction in + the loop to increment the value by the appropriate amount. +

    +
    + + +
    + Rotate Loops +
    +
    +

    A simple loop rotation transformation.

    +
    + + +
    + Unroll loops +
    +
    +

    + This pass implements a simple loop unroller. It works best when loops have + been canonicalized by the -indvars pass, + allowing it to determine the trip counts of loops easily. +

    +
    + + +
    + Unswitch loops +
    +
    +

    + This pass transforms loops that contain branches on loop-invariant conditions + to have multiple loops. For example, it turns the left into the right code: +

    + + 
    for (...)                  if (lic)
+   A                          for (...)
+   if (lic)                     A; B; C
+     B                      else
+   C                          for (...)
+                                A; C
    + +

    + This can increase the size of the code exponentially (doubling it every time + a loop is unswitched) so we only unswitch if the resultant code will be + smaller than a threshold. +

    + +

    + This pass expects LICM to be run before it to hoist invariant conditions out + of the loop, to make the unswitching opportunity obvious. +

    +
    + + +
    + Canonicalize natural loops +
    +
    +

    + This pass performs several transformations to transform natural loops into a + simpler form, which makes subsequent analyses and transformations simpler and + more effective. +

    + +

    + Loop pre-header insertion guarantees that there is a single, non-critical + entry edge from outside of the loop to the loop header. This simplifies a + number of analyses and transformations, such as LICM. +

    + +

    + Loop exit-block insertion guarantees that all exit blocks from the loop + (blocks which are outside of the loop that have predecessors inside of the + loop) only have predecessors from inside of the loop (and are thus dominated + by the loop header). This simplifies transformations such as store-sinking + that are built into LICM. +

    + +

    + This pass also guarantees that loops will have exactly one backedge. +

    + +

    + Note that the simplifycfg pass will clean up blocks which are split out but + end up being unnecessary, so usage of this pass should not pessimize + generated code. +

    + +

    + This pass obviously modifies the CFG, but updates loop information and + dominator information. +

    +
    + + +
    + lowers packed operations to operations on smaller packed datatypes +
    +
    +

    + Lowers operations on vector datatypes into operations on more primitive vector + datatypes, and finally to scalar operations. +

    +
    + + +
    + Lower allocations from instructions to calls +
    +
    +

    + Turn malloc and free instructions into @malloc and + @free calls. +

    + +

    + This is a target-dependent tranformation because it depends on the size of + data types and alignment constraints. +

    +
    + + +
    + Lower GC intrinsics, for GCless code generators +
    +
    +

    + This file implements lowering for the llvm.gc* intrinsics for targets + that do not natively support them (which includes the C backend). Note that + the code generated is not as efficient as it would be for targets that + natively support the GC intrinsics, but it is useful for getting new targets + up-and-running quickly. +

    + +

    + This pass implements the code transformation described in this paper: +

    + +

    + "Accurate Garbage Collection in an Uncooperative Environment" + Fergus Henderson, ISMM, 2002 +

    +
    + + +
    + Lower invoke and unwind, for unwindless code generators +
    +
    +

    + This transformation is designed for use by code generators which do not yet + support stack unwinding. This pass supports two models of exception handling + lowering, the 'cheap' support and the 'expensive' support. +

    + +

    + 'Cheap' exception handling support gives the program the ability to execute + any program which does not "throw an exception", by turning 'invoke' + instructions into calls and by turning 'unwind' instructions into calls to + abort(). If the program does dynamically use the unwind instruction, the + program will print a message then abort. +

    + +

    + 'Expensive' exception handling support gives the full exception handling + support to the program at the cost of making the 'invoke' instruction + really expensive. It basically inserts setjmp/longjmp calls to emulate the + exception handling as necessary. +

    + +

    + Because the 'expensive' support slows down programs a lot, and EH is only + used for a subset of the programs, it must be specifically enabled by the + -enable-correct-eh-support option. +

    + +

    + Note that after this pass runs the CFG is not entirely accurate (exceptional + control flow edges are not correct anymore) so only very simple things should + be done after the lowerinvoke pass has run (like generation of native code). + This should not be used as a general purpose "my LLVM-to-LLVM pass doesn't + support the invoke instruction yet" lowering pass. +

    +
    + + +
    + Lower select instructions to branches +
    +
    +

    + Lowers select instructions into conditional branches for targets that do not + have conditional moves or that have not implemented the select instruction + yet. +

    + +

    + Note that this pass could be improved. In particular it turns every select + instruction into a new conditional branch, even though some common cases have + select instructions on the same predicate next to each other. It would be + better to use the same branch for the whole group of selects. +

    +
    + + +
    + Lower Set Jump +
    +
    +

    + Lowers setjmp and longjmp to use the LLVM invoke and unwind + instructions as necessary. +

    + +

    + Lowering of longjmp is fairly trivial. We replace the call with a + call to the LLVM library function __llvm_sjljeh_throw_longjmp(). + This unwinds the stack for us calling all of the destructors for + objects allocated on the stack. +

    + +

    + At a setjmp call, the basic block is split and the setjmp + removed. The calls in a function that have a setjmp are converted to + invoke where the except part checks to see if it's a longjmp + exception and, if so, if it's handled in the function. If it is, then it gets + the value returned by the longjmp and goes to where the basic block + was split. invoke instructions are handled in a similar fashion with + the original except block being executed if it isn't a longjmp + except that is handled by that function. +

    +
    + + +
    + Lower SwitchInst's to branches +
    +
    +

    + Rewrites switch instructions with a sequence of branches, which + allows targets to get away with not implementing the switch instruction until + it is convenient. +

    +
    + + +
    + Promote Memory to Register +
    +
    +

    + This file promotes memory references to be register references. It promotes + alloca instructions which only have loads and + stores as uses. An alloca is transformed by using dominator + frontiers to place phi nodes, then traversing the function in + depth-first order to rewrite loads and stores as + appropriate. This is just the standard SSA construction algorithm to construct + "pruned" SSA form. +

    +
    + + +
    + Unify function exit nodes +
    +
    +

    + Ensure that functions have at most one ret instruction in them. + Additionally, it keeps track of which node is the new exit node of the CFG. +

    +
    + + +
    + Predicate Simplifier +
    +
    +

    + Path-sensitive optimizer. In a branch where x == y, replace uses of + x with y. Permits further optimization, such as the + elimination of the unreachable call: +

    + + 
    void test(int *p, int *q)
+ {
+   if (p != q)
+     return;
+ 
+   if (*p != *q)
+     foo(); // unreachable
+ }
    +
    + + +
    + Remove unused exception handling info +
    +
    +

    + This file implements a simple interprocedural pass which walks the call-graph, + turning invoke instructions into call instructions if and + only if the callee cannot throw an exception. It implements this as a + bottom-up traversal of the call-graph. +

    +
    + + +
    + Raise allocations from calls to instructions +
    +
    +

    + Converts @malloc and @free calls to malloc and + free instructions. +

    +
    + + +
    + Reassociate expressions +
    +
    +

    + This pass reassociates commutative expressions in an order that is designed + to promote better constant propagation, GCSE, LICM, PRE, etc. +

    + +

    + For example: 4 + (x + 5) ??? x + (4 + 5) +

    + +

    + In the implementation of this algorithm, constants are assigned rank = 0, + function arguments are rank = 1, and other values are assigned ranks + corresponding to the reverse post order traversal of current function + (starting at 2), which effectively gives values in deep loops higher rank + than values not in loops. +

    +
    + + +
    + Demote all values to stack slots +
    +
    +

    + This file demotes all registers to memory references. It is intented to be + the inverse of -mem2reg. By converting to + load instructions, the only values live accross basic blocks are + alloca instructions and load instructions before + phi nodes. It is intended that this should make CFG hacking much + easier. To make later hacking easier, the entry block is split into two, such + that all introduced alloca instructions (and nothing else) are in the + entry block. +

    +
    + + +
    + Scalar Replacement of Aggregates +
    +
    +

    + The well-known scalar replacement of aggregates transformation. This + transform breaks up alloca instructions of aggregate type (structure + or array) into individual alloca instructions for each member if + possible. Then, if possible, it transforms the individual alloca + instructions into nice clean scalar SSA form. +

    + +

    + This combines a simple scalar replacement of aggregates algorithm with the mem2reg algorithm because often interact, + especially for C++ programs. As such, iterating between scalarrepl, + then mem2reg until we run out of things to + promote works well. +

    +
    + + +
    + Sparse Conditional Constant Propagation +
    +
    +

    + Sparse conditional constant propagation and merging, which can be summarized + as: +

    + +
      +
    1. Assumes values are constant unless proven otherwise
      2. +
    2. Assumes BasicBlocks are dead unless proven otherwise
      3. +
    3. Proves values to be constant, and replaces them with constants
      4. +
    4. Proves conditional branches to be unconditional
      5. +
    + +

    + Note that this pass has a habit of making definitions be dead. It is a good + idea to to run a DCE pass sometime after running this pass. +

    +
    + + +
    + Simplify well-known library calls +
    +
    +

    + Applies a variety of small optimizations for calls to specific well-known + function calls (e.g. runtime library functions). For example, a call + exit(3) that occurs within the main() function can be + transformed into simply return 3. +

    +
    + + +
    + Simplify the CFG +
    +
    +

    + Performs dead code elimination and basic block merging. Specifically: +

    + +
      +
    1. Removes basic blocks with no predecessors.
      2. +
    2. Merges a basic block into its predecessor if there is only one and the + predecessor only has one successor.
      3. +
    3. Eliminates PHI nodes for basic blocks with a single predecessor.
      4. +
    4. Eliminates a basic block that only contains an unconditional + branch.
      5. +
    +
    + + +
    + Strip all symbols from a module +
    +
    +

    + Performs code stripping. This transformation can delete: +

    + +
      +
    1. names for virtual registers
      2. +
    2. symbols for internal globals and functions
      3. +
    3. debug information
      4. +
    + +

    + Note that this transformation makes code much less readable, so it should + only be used in situations where the strip utility would be used, + such as reducing code size or making it harder to reverse engineer code. +

    +
    + + +
    + Tail Call Elimination +
    +
    +

    + This file transforms calls of the current function (self recursion) followed + by a return instruction with a branch to the entry of the function, creating + a loop. This pass also implements the following extensions to the basic + algorithm: +

    + +
      +
    • Trivial instructions between the call and return do not prevent the + transformation from taking place, though currently the analysis cannot + support moving any really useful instructions (only dead ones). +
    • This pass transforms functions that are prevented from being tail + recursive by an associative expression to use an accumulator variable, + thus compiling the typical naive factorial or fib implementation + into efficient code. +
    • TRE is performed if the function returns void, if the return + returns the result returned by the call, or if the function returns a + run-time constant on all exits from the function. It is possible, though + unlikely, that the return returns something else (like constant 0), and + can still be TRE'd. It can be TRE'd if all other return + instructions in the function return the exact same value. +
    • If it can prove that callees do not access theier caller stack frame, + they are marked as eligible for tail call elimination (by the code + generator). +
    +
    + + +
    + Tail Duplication +
    +
    +

    + This pass performs a limited form of tail duplication, intended to simplify + CFGs by removing some unconditional branches. This pass is necessary to + straighten out loops created by the C front-end, but also is capable of + making other code nicer. After this pass is run, the CFG simplify pass + should be run to clean up the mess. +

    +
    + + +
    Utility Passes
    +
    +

    This section describes the LLVM Utility Passes.

    +
    + + +
    + Dead Argument Hacking (BUGPOINT USE ONLY; DO NOT USE) +
    +
    +

    + Same as dead argument elimination, but deletes arguments to functions which + are external. This is only for use by bugpoint.

    +
    + + +
    + Extract Basic Blocks From Module (for bugpoint use) +
    +
    +

    + This pass is used by bugpoint to extract all blocks from the module into their + own functions.

    +
    + + +
    + Preliminary module verification +
    +
    +

    + Ensures that the module is in the form required by the Module Verifier pass. +

    + +

    + Running the verifier runs this pass automatically, so there should be no need + to use it directly. +

    +
    + + +
    + Module Verifier +
    +
    +

    + Verifies an LLVM IR code. This is useful to run after an optimization which is + undergoing testing. Note that llvm-as verifies its input before + emitting bitcode, and also that malformed bitcode is likely to make LLVM + crash. All language front-ends are therefore encouraged to verify their output + before performing optimizing transformations. +

    + +
      +
    • Both of a binary operator's parameters are of the same type.
      • +
    • Verify that the indices of mem access instructions match other + operands.
      • +
    • Verify that arithmetic and other things are only performed on + first-class types. Verify that shifts and logicals only happen on + integrals f.e.
      • +
    • All of the constants in a switch statement are of the correct type.
      • +
    • The code is in valid SSA form.
      • +
    • It should be illegal to put a label into any other type (like a + structure) or to return one. [except constant arrays!]
      • +
    • Only phi nodes can be self referential: %x = add int %x, %x is + invalid.
      • +
    • PHI nodes must have an entry for each predecessor, with no extras.
      • +
    • PHI nodes must be the first thing in a basic block, all grouped + together.
      • +
    • PHI nodes must have at least one entry.
      • +
    • All basic blocks should only end with terminator insts, not contain + them.
      • +
    • The entry node to a function must not have predecessors.
      • +
    • All Instructions must be embedded into a basic block.
      • +
    • Functions cannot take a void-typed parameter.
      • +
    • Verify that a function's argument list agrees with its declared + type.
      • +
    • It is illegal to specify a name for a void value.
      • +
    • It is illegal to have a internal global value with no initializer.
      • +
    • It is illegal to have a ret instruction that returns a value that does + not agree with the function return value type.
      • +
    • Function call argument types match the function prototype.
      • +
    • All other things that are tested by asserts spread about the code.
      • +
    + +

    + Note that this does not provide full security verification (like Java), but + instead just tries to ensure that code is well-formed. +

    +
    + + +
    + View CFG of function +
    +
    +

    + Displays the control flow graph using the GraphViz tool. +

    +
    + + +
    + View CFG of function (with no function bodies) +
    +
    +

    + Displays the control flow graph using the GraphViz tool, but omitting function + bodies. +

    +
    + + + +
    +
    + Valid CSS! + Valid HTML 4.01! + + Reid Spencer
    + LLVM Compiler Infrastructure
    + Last modified: $Date: 2008/02/12 06:05:03 $ +
    + + + Index: llvm-www/releases/2.2/docs/ProgrammersManual.html diff -c /dev/null llvm-www/releases/2.2/docs/ProgrammersManual.html:1.1 *** /dev/null Tue Feb 12 00:07:04 2008 --- llvm-www/releases/2.2/docs/ProgrammersManual.html Tue Feb 12 00:05:03 2008 *************** *** 0 **** --- 1,3197 ---- + + + + LLVM Programmer's Manual + + + + +
    + LLVM Programmer's Manual +
    + +
      +
    1. Introduction
      2. +
    2. General Information + +
      3. +
    3. Important and useful LLVM APIs + +
      4. +
    4. Picking the Right Data Structure for a Task + +
      5. +
    5. Helpful Hints for Common Operations + +
      6. + +
    6. Advanced Topics +
      7. + +
    7. The Core LLVM Class Hierarchy Reference + +
      8. +
    + +
    +

    Written by Chris Lattner, + Dinakar Dhurjati, + Joel Stanley, and + Reid Spencer

    +
    + + +
    + Introduction +
    + + +
    + +

    This document is meant to highlight some of the important classes and + interfaces available in the LLVM source-base. This manual is not + intended to explain what LLVM is, how it works, and what LLVM code looks + like. It assumes that you know the basics of LLVM and are interested + in writing transformations or otherwise analyzing or manipulating the + code.

    + +

    This document should get you oriented so that you can find your + way in the continuously growing source code that makes up the LLVM + infrastructure. Note that this manual is not intended to serve as a + replacement for reading the source code, so if you think there should be + a method in one of these classes to do something, but it's not listed, + check the source. Links to the doxygen sources + are provided to make this as easy as possible.

    + +

    The first section of this document describes general information that is + useful to know when working in the LLVM infrastructure, and the second describes + the Core LLVM classes. In the future this manual will be extended with + information describing how to use extension libraries, such as dominator + information, CFG traversal routines, and useful utilities like the InstVisitor template.

    + +
    + + +
    + General Information +
    + + +
    + +

    This section contains general information that is useful if you are working + in the LLVM source-base, but that isn't specific to any particular API.

    + +
    + + +
    + The C++ Standard Template Library +
    + +
    + +

    LLVM makes heavy use of the C++ Standard Template Library (STL), + perhaps much more than you are used to, or have seen before. Because of + this, you might want to do a little background reading in the + techniques used and capabilities of the library. There are many good + pages that discuss the STL, and several books on the subject that you + can get, so it will not be discussed in this document.

    + +

    Here are some useful links:

    + +
      + +
    1. Dinkumware C++ Library + reference - an excellent reference for the STL and other parts of the + standard C++ library.
      2. + +
    2. C++ In a Nutshell - This is an + O'Reilly book in the making. It has a decent + Standard Library + Reference that rivals Dinkumware's, and is unfortunately no longer free since the book has been + published.
      3. + +
    3. C++ Frequently Asked + Questions
      4. + +
    4. SGI's STL Programmer's Guide - + Contains a useful Introduction to the + STL.
      5. + +
    5. Bjarne Stroustrup's C++ + Page
      6. + +
    6. + Bruce Eckel's Thinking in C++, 2nd ed. Volume 2 Revision 4.0 (even better, get + the book).
      7. + +
    + +

    You are also encouraged to take a look at the LLVM Coding Standards guide which focuses on how + to write maintainable code more than where to put your curly braces.

    + +
    + + +
    + Other useful references +
    + +
    + +
      +
    1. CVS + Branch and Tag Primer
      2. +
    2. Using + static and shared libraries across platforms
      3. +
    + +
    + + +
    + Important and useful LLVM APIs +
    + + +
    + +

    Here we highlight some LLVM APIs that are generally useful and good to + know about when writing transformations.

    + +
    + + +
    + The isa<>, cast<> and + dyn_cast<> templates +
    + +
    + +

    The LLVM source-base makes extensive use of a custom form of RTTI. + These templates have many similarities to the C++ dynamic_cast<> + operator, but they don't have some drawbacks (primarily stemming from + the fact that dynamic_cast<> only works on classes that + have a v-table). Because they are used so often, you must know what they + do and how they work. All of these templates are defined in the llvm/Support/Casting.h + file (note that you very rarely have to include this file directly).

    + +
    +
    isa<>:
    + +

    The isa<> operator works exactly like the Java + "instanceof" operator. It returns true or false depending on whether + a reference or pointer points to an instance of the specified class. This can + be very useful for constraint checking of various sorts (example below).

    +
    + +
    cast<>:
    + +

    The cast<> operator is a "checked cast" operation. It + converts a pointer or reference from a base class to a derived cast, causing + an assertion failure if it is not really an instance of the right type. This + should be used in cases where you have some information that makes you believe + that something is of the right type. An example of the isa<> + and cast<> template is:

    + +
    + 
    + static bool isLoopInvariant(const Value *V, const Loop *L) {
+   if (isa<Constant>(V) || isa<Argument>(V) || isa<GlobalValue>(V))
+     return true;
+ 
+   // Otherwise, it must be an instruction...
+   return !L->contains(cast<Instruction>(V)->getParent());
+ }
+
    +
    + +

    Note that you should not use an isa<> test followed + by a cast<>, for that use the dyn_cast<> + operator.

    + +
    + +
    dyn_cast<>:
    + +

    The dyn_cast<> operator is a "checking cast" operation. + It checks to see if the operand is of the specified type, and if so, returns a + pointer to it (this operator does not work with references). If the operand is + not of the correct type, a null pointer is returned. Thus, this works very + much like the dynamic_cast<> operator in C++, and should be + used in the same circumstances. Typically, the dyn_cast<> + operator is used in an if statement or some other flow control + statement like this:

    + +
    + 
    + if (AllocationInst *AI = dyn_cast<AllocationInst>(Val)) {
+   // ...
+ }
+
    +
    + +

    This form of the if statement effectively combines together a call + to isa<> and a call to cast<> into one + statement, which is very convenient.

    + +

    Note that the dyn_cast<> operator, like C++'s + dynamic_cast<> or Java's instanceof operator, can be + abused. In particular, you should not use big chained if/then/else + blocks to check for lots of different variants of classes. If you find + yourself wanting to do this, it is much cleaner and more efficient to use the + InstVisitor class to dispatch over the instruction type directly.

    + +
    + +
    cast_or_null<>:
    + +

    The cast_or_null<> operator works just like the + cast<> operator, except that it allows for a null pointer as an + argument (which it then propagates). This can sometimes be useful, allowing + you to combine several null checks into one.

    + +
    dyn_cast_or_null<>:
    + +

    The dyn_cast_or_null<> operator works just like the + dyn_cast<> operator, except that it allows for a null pointer + as an argument (which it then propagates). This can sometimes be useful, + allowing you to combine several null checks into one.

    + +
    + +

    These five templates can be used with any classes, whether they have a + v-table or not. To add support for these templates, you simply need to add + classof static methods to the class you are interested casting + to. Describing this is currently outside the scope of this document, but there + are lots of examples in the LLVM source base.

    + +
    + + +
    + The DEBUG() macro and -debug option +
    + +
    + +

    Often when working on your pass you will put a bunch of debugging printouts + and other code into your pass. After you get it working, you want to remove + it, but you may need it again in the future (to work out new bugs that you run + across).

    + +

    Naturally, because of this, you don't want to delete the debug printouts, + but you don't want them to always be noisy. A standard compromise is to comment + them out, allowing you to enable them if you need them in the future.

    + +

    The "llvm/Support/Debug.h" + file provides a macro named DEBUG() that is a much nicer solution to + this problem. Basically, you can put arbitrary code into the argument of the + DEBUG macro, and it is only executed if 'opt' (or any other + tool) is run with the '-debug' command line argument:

    + +
    + 
    + DOUT << "I am here!\n";
+
    +
    + +

    Then you can run your pass like this:

    + +
    + 
    + $ opt < a.bc > /dev/null -mypass
+ <no output>
+ $ opt < a.bc > /dev/null -mypass -debug
+ I am here!
+
    +
    + +

    Using the DEBUG() macro instead of a home-brewed solution allows you + to not have to create "yet another" command line option for the debug output for + your pass. Note that DEBUG() macros are disabled for optimized builds, + so they do not cause a performance impact at all (for the same reason, they + should also not contain side-effects!).

    + +

    One additional nice thing about the DEBUG() macro is that you can + enable or disable it directly in gdb. Just use "set DebugFlag=0" or + "set DebugFlag=1" from the gdb if the program is running. If the + program hasn't been started yet, you can always just run it with + -debug.

    + +
    + + +
    + Fine grained debug info with DEBUG_TYPE and + the -debug-only option +
    + +
    + +

    Sometimes you may find yourself in a situation where enabling -debug + just turns on too much information (such as when working on the code + generator). If you want to enable debug information with more fine-grained + control, you define the DEBUG_TYPE macro and the -debug only + option as follows:

    + +
    + 
    + DOUT << "No debug type\n";
+ #undef  DEBUG_TYPE
+ #define DEBUG_TYPE "foo"
+ DOUT << "'foo' debug type\n";
+ #undef  DEBUG_TYPE
+ #define DEBUG_TYPE "bar"
+ DOUT << "'bar' debug type\n";
+ #undef  DEBUG_TYPE
+ #define DEBUG_TYPE ""
+ DOUT << "No debug type (2)\n";
+
    +
    + +

    Then you can run your pass like this:

    + +
    + 
    + $ opt < a.bc > /dev/null -mypass
+ <no output>
+ $ opt < a.bc > /dev/null -mypass -debug
+ No debug type
+ 'foo' debug type
+ 'bar' debug type
+ No debug type (2)
+ $ opt < a.bc > /dev/null -mypass -debug-only=foo
+ 'foo' debug type
+ $ opt < a.bc > /dev/null -mypass -debug-only=bar
+ 'bar' debug type
+
    +
    + +

    Of course, in practice, you should only set DEBUG_TYPE at the top of + a file, to specify the debug type for the entire module (if you do this before + you #include "llvm/Support/Debug.h", you don't have to insert the ugly + #undef's). Also, you should use names more meaningful than "foo" and + "bar", because there is no system in place to ensure that names do not + conflict. If two different modules use the same string, they will all be turned + on when the name is specified. This allows, for example, all debug information + for instruction scheduling to be enabled with -debug-type=InstrSched, + even if the source lives in multiple files.

    + +
    + + +
    + The Statistic class & -stats + option +
    + +
    + +

    The "llvm/ADT/Statistic.h" file + provides a class named Statistic that is used as a unified way to + keep track of what the LLVM compiler is doing and how effective various + optimizations are. It is useful to see what optimizations are contributing to + making a particular program run faster.

    + +

    Often you may run your pass on some big program, and you're interested to see + how many times it makes a certain transformation. Although you can do this with + hand inspection, or some ad-hoc method, this is a real pain and not very useful + for big programs. Using the Statistic class makes it very easy to + keep track of this information, and the calculated information is presented in a + uniform manner with the rest of the passes being executed.

    + +

    There are many examples of Statistic uses, but the basics of using + it are as follows:

    + +
      +

    1. Define your statistic like this:

      + +
      + 
      + #define DEBUG_TYPE "mypassname"   // This goes before any #includes.
+ STATISTIC(NumXForms, "The # of times I did stuff");
+
      +
      + +

      The STATISTIC macro defines a static variable, whose name is + specified by the first argument. The pass name is taken from the DEBUG_TYPE + macro, and the description is taken from the second argument. The variable + defined ("NumXForms" in this case) acts like an unsigned integer.

      2. + +

    2. Whenever you make a transformation, bump the counter:

      + +
      + 
      + ++NumXForms;   // I did stuff!
+
      +
      + +
      3. +
    + +

    That's all you have to do. To get 'opt' to print out the + statistics gathered, use the '-stats' option:

    + +
    + 
    + $ opt -stats -mypassname < program.bc > /dev/null
+ ... statistics output ...
+
    +
    + +

    When running opt on a C file from the SPEC benchmark + suite, it gives a report that looks like this:

    + +
    + 
    +    7646 bitcodewriter   - Number of normal instructions
+     725 bitcodewriter   - Number of oversized instructions
+  129996 bitcodewriter   - Number of bitcode bytes written
+    2817 raise           - Number of insts DCEd or constprop'd
+    3213 raise           - Number of cast-of-self removed
+    5046 raise           - Number of expression trees converted
+      75 raise           - Number of other getelementptr's formed
+     138 raise           - Number of load/store peepholes
+      42 deadtypeelim    - Number of unused typenames removed from symtab
+     392 funcresolve     - Number of varargs functions resolved
+      27 globaldce       - Number of global variables removed
+       2 adce            - Number of basic blocks removed
+     134 cee             - Number of branches revectored
+      49 cee             - Number of setcc instruction eliminated
+     532 gcse            - Number of loads removed
+    2919 gcse            - Number of instructions removed
+      86 indvars         - Number of canonical indvars added
+      87 indvars         - Number of aux indvars removed
+      25 instcombine     - Number of dead inst eliminate
+     434 instcombine     - Number of insts combined
+     248 licm            - Number of load insts hoisted
+    1298 licm            - Number of insts hoisted to a loop pre-header
+       3 licm            - Number of insts hoisted to multiple loop preds (bad, no loop pre-header)
+      75 mem2reg         - Number of alloca's promoted
+    1444 cfgsimplify     - Number of blocks simplified
+
    +
    + +

    Obviously, with so many optimizations, having a unified framework for this + stuff is very nice. Making your pass fit well into the framework makes it more + maintainable and useful.

    + +
    + + +
    + Viewing graphs while debugging code +
    + +
    + +

    Several of the important data structures in LLVM are graphs: for example + CFGs made out of LLVM BasicBlocks, CFGs made out of + LLVM MachineBasicBlocks, and + Instruction Selection + DAGs. In many cases, while debugging various parts of the compiler, it is + nice to instantly visualize these graphs.

    + +

    LLVM provides several callbacks that are available in a debug build to do + exactly that. If you call the Function::viewCFG() method, for example, + the current LLVM tool will pop up a window containing the CFG for the function + where each basic block is a node in the graph, and each node contains the + instructions in the block. Similarly, there also exists + Function::viewCFGOnly() (does not include the instructions), the + MachineFunction::viewCFG() and MachineFunction::viewCFGOnly(), + and the SelectionDAG::viewGraph() methods. Within GDB, for example, + you can usually use something like call DAG.viewGraph() to pop + up a window. Alternatively, you can sprinkle calls to these functions in your + code in places you want to debug.

    + +

    Getting this to work requires a small amount of configuration. On Unix + systems with X11, install the graphviz + toolkit, and make sure 'dot' and 'gv' are in your path. If you are running on + Mac OS/X, download and install the Mac OS/X Graphviz program, and add + /Applications/Graphviz.app/Contents/MacOS/ (or wherever you install + it) to your path. Once in your system and path are set up, rerun the LLVM + configure script and rebuild LLVM to enable this functionality.

    + +

    SelectionDAG has been extended to make it easier to locate + interesting nodes in large complex graphs. From gdb, if you + call DAG.setGraphColor(node, "color"), then the + next call DAG.viewGraph() would highlight the node in the + specified color (choices of colors can be found at colors.) More + complex node attributes can be provided with call + DAG.setGraphAttrs(node, "attributes") (choices can be + found at Graph + Attributes.) If you want to restart and clear all the current graph + attributes, then you can call DAG.clearGraphAttrs().

    + +
    + + +
    + Picking the Right Data Structure for a Task +
    + + +
    + +

    LLVM has a plethora of data structures in the llvm/ADT/ directory, + and we commonly use STL data structures. This section describes the trade-offs + you should consider when you pick one.

    + +

    + The first step is a choose your own adventure: do you want a sequential + container, a set-like container, or a map-like container? The most important + thing when choosing a container is the algorithmic properties of how you plan to + access the container. Based on that, you should use:

    + +
      +
    • a map-like container if you need efficient look-up + of an value based on another value. Map-like containers also support + efficient queries for containment (whether a key is in the map). Map-like + containers generally do not support efficient reverse mapping (values to + keys). If you need that, use two maps. Some map-like containers also + support efficient iteration through the keys in sorted order. Map-like + containers are the most expensive sort, only use them if you need one of + these capabilities.
      • + +
    • a set-like container if you need to put a bunch of + stuff into a container that automatically eliminates duplicates. Some + set-like containers support efficient iteration through the elements in + sorted order. Set-like containers are more expensive than sequential + containers. +
      • + +
    • a sequential container provides + the most efficient way to add elements and keeps track of the order they are + added to the collection. They permit duplicates and support efficient + iteration, but do not support efficient look-up based on a key. +
      • + +
    • a bit container provides an efficient way to store and + perform set operations on sets of numeric id's, while automatically + eliminating duplicates. Bit containers require a maximum of 1 bit for each + identifier you want to store. +
      • +
    + +

    + Once the proper category of container is determined, you can fine tune the + memory use, constant factors, and cache behaviors of access by intelligently + picking a member of the category. Note that constant factors and cache behavior + can be a big deal. If you have a vector that usually only contains a few + elements (but could contain many), for example, it's much better to use + SmallVector than vector + . Doing so avoids (relatively) expensive malloc/free calls, which dwarf the + cost of adding the elements to the container.

    + +
    + + +
    + Sequential Containers (std::vector, std::list, etc) +
    + +
    + There are a variety of sequential containers available for you, based on your + needs. Pick the first in this section that will do what you want. +
    + + +
    + Fixed Size Arrays +
    + +
    +

    Fixed size arrays are very simple and very fast. They are good if you know + exactly how many elements you have, or you have a (low) upper bound on how many + you have.

    +
    + + +
    + Heap Allocated Arrays +
    + +
    +

    Heap allocated arrays (new[] + delete[]) are also simple. They are good if + the number of elements is variable, if you know how many elements you will need + before the array is allocated, and if the array is usually large (if not, + consider a SmallVector). The cost of a heap + allocated array is the cost of the new/delete (aka malloc/free). Also note that + if you are allocating an array of a type with a constructor, the constructor and + destructors will be run for every element in the array (re-sizable vectors only + construct those elements actually used).

    +
    + + +
    + "llvm/ADT/SmallVector.h" +
    + +
    +

    SmallVector<Type, N> is a simple class that looks and smells + just like vector<Type>: + it supports efficient iteration, lays out elements in memory order (so you can + do pointer arithmetic between elements), supports efficient push_back/pop_back + operations, supports efficient random access to its elements, etc.

    + +

    The advantage of SmallVector is that it allocates space for + some number of elements (N) in the object itself. Because of this, if + the SmallVector is dynamically smaller than N, no malloc is performed. This can + be a big win in cases where the malloc/free call is far more expensive than the + code that fiddles around with the elements.

    + +

    This is good for vectors that are "usually small" (e.g. the number of + predecessors/successors of a block is usually less than 8). On the other hand, + this makes the size of the SmallVector itself large, so you don't want to + allocate lots of them (doing so will waste a lot of space). As such, + SmallVectors are most useful when on the stack.

    + +

    SmallVector also provides a nice portable and efficient replacement for + alloca.

    + +
    + + +
    + <vector> +
    + +
    +

    + std::vector is well loved and respected. It is useful when SmallVector isn't: + when the size of the vector is often large (thus the small optimization will + rarely be a benefit) or if you will be allocating many instances of the vector + itself (which would waste space for elements that aren't in the container). + vector is also useful when interfacing with code that expects vectors :). +

    + +

    One worthwhile note about std::vector: avoid code like this:

    + +
    + 
    + for ( ... ) {
+    std::vector<foo> V;
+    use V;
+ }
+
    +
    + +

    Instead, write this as:

    + +
    + 
    + std::vector<foo> V;
+ for ( ... ) {
+    use V;
+    V.clear();
+ }
+
    +
    + +

    Doing so will save (at least) one heap allocation and free per iteration of + the loop.

    + +
    + + +
    + <deque> +
    + +
    +

    std::deque is, in some senses, a generalized version of std::vector. Like + std::vector, it provides constant time random access and other similar + properties, but it also provides efficient access to the front of the list. It + does not guarantee continuity of elements within memory.

    + +

    In exchange for this extra flexibility, std::deque has significantly higher + constant factor costs than std::vector. If possible, use std::vector or + something cheaper.

    +
    + + +
    + <list> +
    + +
    +

    std::list is an extremely inefficient class that is rarely useful. + It performs a heap allocation for every element inserted into it, thus having an + extremely high constant factor, particularly for small data types. std::list + also only supports bidirectional iteration, not random access iteration.

    + +

    In exchange for this high cost, std::list supports efficient access to both + ends of the list (like std::deque, but unlike std::vector or SmallVector). In + addition, the iterator invalidation characteristics of std::list are stronger + than that of a vector class: inserting or removing an element into the list does + not invalidate iterator or pointers to other elements in the list.

    +
    + + +
    + llvm/ADT/ilist +
    + +
    +

    ilist<T> implements an 'intrusive' doubly-linked list. It is + intrusive, because it requires the element to store and provide access to the + prev/next pointers for the list.

    + +

    ilist has the same drawbacks as std::list, and additionally requires an + ilist_traits implementation for the element type, but it provides some novel + characteristics. In particular, it can efficiently store polymorphic objects, + the traits class is informed when an element is inserted or removed from the + list, and ilists are guaranteed to support a constant-time splice operation. +

    + +

    These properties are exactly what we want for things like Instructions and + basic blocks, which is why these are implemented with ilists.

    +
    + + +
    + Other Sequential Container options +
    + +
    +

    Other STL containers are available, such as std::string.

    + +

    There are also various STL adapter classes such as std::queue, + std::priority_queue, std::stack, etc. These provide simplified access to an + underlying container but don't affect the cost of the container itself.

    + +
    + + + +
    + Set-Like Containers (std::set, SmallSet, SetVector, etc) +
    + +
    + +

    Set-like containers are useful when you need to canonicalize multiple values + into a single representation. There are several different choices for how to do + this, providing various trade-offs.

    + +
    + + + +
    + A sorted 'vector' +
    + +
    + +

    If you intend to insert a lot of elements, then do a lot of queries, a + great approach is to use a vector (or other sequential container) with + std::sort+std::unique to remove duplicates. This approach works really well if + your usage pattern has these two distinct phases (insert then query), and can be + coupled with a good choice of sequential container. +

    + +

    + This combination provides the several nice properties: the result data is + contiguous in memory (good for cache locality), has few allocations, is easy to + address (iterators in the final vector are just indices or pointers), and can be + efficiently queried with a standard binary or radix search.

    + +
    + + +
    + "llvm/ADT/SmallSet.h" +
    + +
    + +

    If you have a set-like data structure that is usually small and whose elements + are reasonably small, a SmallSet<Type, N> is a good choice. This set + has space for N elements in place (thus, if the set is dynamically smaller than + N, no malloc traffic is required) and accesses them with a simple linear search. + When the set grows beyond 'N' elements, it allocates a more expensive representation that + guarantees efficient access (for most types, it falls back to std::set, but for + pointers it uses something far better, SmallPtrSet).

    + +

    The magic of this class is that it handles small sets extremely efficiently, + but gracefully handles extremely large sets without loss of efficiency. The + drawback is that the interface is quite small: it supports insertion, queries + and erasing, but does not support iteration.

    + +
    + + +
    + "llvm/ADT/SmallPtrSet.h" +
    + +
    + +

    SmallPtrSet has all the advantages of SmallSet (and a SmallSet of pointers is + transparently implemented with a SmallPtrSet), but also supports iterators. If + more than 'N' insertions are performed, a single quadratically + probed hash table is allocated and grows as needed, providing extremely + efficient access (constant time insertion/deleting/queries with low constant + factors) and is very stingy with malloc traffic.

    + +

    Note that, unlike std::set, the iterators of SmallPtrSet are invalidated + whenever an insertion occurs. Also, the values visited by the iterators are not + visited in sorted order.

    + +
    + + +
    + "llvm/ADT/DenseSet.h" +
    + +
    + +

    + DenseSet is a simple quadratically probed hash table. It excels at supporting + small values: it uses a single allocation to hold all of the pairs that + are currently inserted in the set. DenseSet is a great way to unique small + values that are not simple pointers (use SmallPtrSet for pointers). Note that DenseSet has + the same requirements for the value type that DenseMap has. +

    + +
    + + +
    + "llvm/ADT/FoldingSet.h" +
    + +
    + +

    + FoldingSet is an aggregate class that is really good at uniquing + expensive-to-create or polymorphic objects. It is a combination of a chained + hash table with intrusive links (uniqued objects are required to inherit from + FoldingSetNode) that uses SmallVector as part of + its ID process.

    + +

    Consider a case where you want to implement a "getOrCreateFoo" method for + a complex object (for example, a node in the code generator). The client has a + description of *what* it wants to generate (it knows the opcode and all the + operands), but we don't want to 'new' a node, then try inserting it into a set + only to find out it already exists, at which point we would have to delete it + and return the node that already exists. +

    + +

    To support this style of client, FoldingSet perform a query with a + FoldingSetNodeID (which wraps SmallVector) that can be used to describe the + element that we want to query for. The query either returns the element + matching the ID or it returns an opaque ID that indicates where insertion should + take place. Construction of the ID usually does not require heap traffic.

    + +

    Because FoldingSet uses intrusive links, it can support polymorphic objects + in the set (for example, you can have SDNode instances mixed with LoadSDNodes). + Because the elements are individually allocated, pointers to the elements are + stable: inserting or removing elements does not invalidate any pointers to other + elements. +

    + +
    + + +
    + <set> +
    + +
    + +

    std::set is a reasonable all-around set class, which is decent at + many things but great at nothing. std::set allocates memory for each element + inserted (thus it is very malloc intensive) and typically stores three pointers + per element in the set (thus adding a large amount of per-element space + overhead). It offers guaranteed log(n) performance, which is not particularly + fast from a complexity standpoint (particularly if the elements of the set are + expensive to compare, like strings), and has extremely high constant factors for + lookup, insertion and removal.

    + +

    The advantages of std::set are that its iterators are stable (deleting or + inserting an element from the set does not affect iterators or pointers to other + elements) and that iteration over the set is guaranteed to be in sorted order. + If the elements in the set are large, then the relative overhead of the pointers + and malloc traffic is not a big deal, but if the elements of the set are small, + std::set is almost never a good choice.

    + +
    + + +
    + "llvm/ADT/SetVector.h" +
    + +
    +

    LLVM's SetVector<Type> is an adapter class that combines your choice of + a set-like container along with a Sequential + Container. The important property + that this provides is efficient insertion with uniquing (duplicate elements are + ignored) with iteration support. It implements this by inserting elements into + both a set-like container and the sequential container, using the set-like + container for uniquing and the sequential container for iteration. +

    + +

    The difference between SetVector and other sets is that the order of + iteration is guaranteed to match the order of insertion into the SetVector. + This property is really important for things like sets of pointers. Because + pointer values are non-deterministic (e.g. vary across runs of the program on + different machines), iterating over the pointers in the set will + not be in a well-defined order.

    + +

    + The drawback of SetVector is that it requires twice as much space as a normal + set and has the sum of constant factors from the set-like container and the + sequential container that it uses. Use it *only* if you need to iterate over + the elements in a deterministic order. SetVector is also expensive to delete + elements out of (linear time), unless you use it's "pop_back" method, which is + faster. +

    + +

    SetVector is an adapter class that defaults to using std::vector and std::set + for the underlying containers, so it is quite expensive. However, + "llvm/ADT/SetVector.h" also provides a SmallSetVector class, which + defaults to using a SmallVector and SmallSet of a specified size. If you use + this, and if your sets are dynamically smaller than N, you will save a lot of + heap traffic.

    + +
    + + +
    + "llvm/ADT/UniqueVector.h" +
    + +
    + +

    + UniqueVector is similar to SetVector, but it + retains a unique ID for each element inserted into the set. It internally + contains a map and a vector, and it assigns a unique ID for each value inserted + into the set.

    + +

    UniqueVector is very expensive: its cost is the sum of the cost of + maintaining both the map and vector, it has high complexity, high constant + factors, and produces a lot of malloc traffic. It should be avoided.

    + +
    + + + +
    + Other Set-Like Container Options +
    + +
    + +

    + The STL provides several other options, such as std::multiset and the various + "hash_set" like containers (whether from C++ TR1 or from the SGI library).

    + +

    std::multiset is useful if you're not interested in elimination of + duplicates, but has all the drawbacks of std::set. A sorted vector (where you + don't delete duplicate entries) or some other approach is almost always + better.

    + +

    The various hash_set implementations (exposed portably by + "llvm/ADT/hash_set") is a simple chained hashtable. This algorithm is as malloc + intensive as std::set (performing an allocation for each element inserted, + thus having really high constant factors) but (usually) provides O(1) + insertion/deletion of elements. This can be useful if your elements are large + (thus making the constant-factor cost relatively low) or if comparisons are + expensive. Element iteration does not visit elements in a useful order.

    + +
    + + +
    + Map-Like Containers (std::map, DenseMap, etc) +
    + +
    + Map-like containers are useful when you want to associate data to a key. As + usual, there are a lot of different ways to do this. :) +
    + + +
    + A sorted 'vector' +
    + +
    + +

    + If your usage pattern follows a strict insert-then-query approach, you can + trivially use the same approach as sorted vectors + for set-like containers. The only difference is that your query function + (which uses std::lower_bound to get efficient log(n) lookup) should only compare + the key, not both the key and value. This yields the same advantages as sorted + vectors for sets. +

    +
    + + +
    + "llvm/ADT/StringMap.h" +
    + +
    + +

    + Strings are commonly used as keys in maps, and they are difficult to support + efficiently: they are variable length, inefficient to hash and compare when + long, expensive to copy, etc. StringMap is a specialized container designed to + cope with these issues. It supports mapping an arbitrary range of bytes to an + arbitrary other object.

    + +

    The StringMap implementation uses a quadratically-probed hash table, where + the buckets store a pointer to the heap allocated entries (and some other + stuff). The entries in the map must be heap allocated because the strings are + variable length. The string data (key) and the element object (value) are + stored in the same allocation with the string data immediately after the element + object. This container guarantees the "(char*)(&Value+1)" points + to the key string for a value.

    + +

    The StringMap is very fast for several reasons: quadratic probing is very + cache efficient for lookups, the hash value of strings in buckets is not + recomputed when lookup up an element, StringMap rarely has to touch the + memory for unrelated objects when looking up a value (even when hash collisions + happen), hash table growth does not recompute the hash values for strings + already in the table, and each pair in the map is store in a single allocation + (the string data is stored in the same allocation as the Value of a pair).

    + +

    StringMap also provides query methods that take byte ranges, so it only ever + copies a string if a value is inserted into the table.

    +
    + + +
    + "llvm/ADT/IndexedMap.h" +
    + +
    +

    + IndexedMap is a specialized container for mapping small dense integers (or + values that can be mapped to small dense integers) to some other type. It is + internally implemented as a vector with a mapping function that maps the keys to + the dense integer range. +

    + +

    + This is useful for cases like virtual registers in the LLVM code generator: they + have a dense mapping that is offset by a compile-time constant (the first + virtual register ID).

    + +
    + + +
    + "llvm/ADT/DenseMap.h" +
    + +
    + +

    + DenseMap is a simple quadratically probed hash table. It excels at supporting + small keys and values: it uses a single allocation to hold all of the pairs that + are currently inserted in the map. DenseMap is a great way to map pointers to + pointers, or map other small types to each other. +

    + +

    + There are several aspects of DenseMap that you should be aware of, however. The + iterators in a densemap are invalidated whenever an insertion occurs, unlike + map. Also, because DenseMap allocates space for a large number of key/value + pairs (it starts with 64 by default), it will waste a lot of space if your keys + or values are large. Finally, you must implement a partial specialization of + DenseMapInfo for the key that you want, if it isn't already supported. This + is required to tell DenseMap about two special marker values (which can never be + inserted into the map) that it needs internally.

    + +
    + + +
    + <map> +
    + +
    + +

    + std::map has similar characteristics to std::set: it uses + a single allocation per pair inserted into the map, it offers log(n) lookup with + an extremely large constant factor, imposes a space penalty of 3 pointers per + pair in the map, etc.

    + +

    std::map is most useful when your keys or values are very large, if you need + to iterate over the collection in sorted order, or if you need stable iterators + into the map (i.e. they don't get invalidated if an insertion or deletion of + another element takes place).

    + +
    + + +
    + Other Map-Like Container Options +
    + +
    + +

    + The STL provides several other options, such as std::multimap and the various + "hash_map" like containers (whether from C++ TR1 or from the SGI library).

    + +

    std::multimap is useful if you want to map a key to multiple values, but has + all the drawbacks of std::map. A sorted vector or some other approach is almost + always better.

    + +

    The various hash_map implementations (exposed portably by + "llvm/ADT/hash_map") are simple chained hash tables. This algorithm is as + malloc intensive as std::map (performing an allocation for each element + inserted, thus having really high constant factors) but (usually) provides O(1) + insertion/deletion of elements. This can be useful if your elements are large + (thus making the constant-factor cost relatively low) or if comparisons are + expensive. Element iteration does not visit elements in a useful order.

    + +
    + + +
    + Bit storage containers (BitVector, SparseBitVector) +
    + +
    +

    Unlike the other containers, there are only two bit storage containers, and + choosing when to use each is relatively straightforward.

    + +

    One additional option is + std::vector<bool>: we discourage its use for two reasons 1) the + implementation in many common compilers (e.g. commonly available versions of + GCC) is extremely inefficient and 2) the C++ standards committee is likely to + deprecate this container and/or change it significantly somehow. In any case, + please don't use it.

    +
    + + +
    + BitVector +
    + +
    +

    The BitVector container provides a fixed size set of bits for manipulation. + It supports individual bit setting/testing, as well as set operations. The set + operations take time O(size of bitvector), but operations are performed one word + at a time, instead of one bit at a time. This makes the BitVector very fast for + set operations compared to other containers. Use the BitVector when you expect + the number of set bits to be high (IE a dense set). +

    +
    + + +
    + SparseBitVector +
    + +
    +

    The SparseBitVector container is much like BitVector, with one major + difference: Only the bits that are set, are stored. This makes the + SparseBitVector much more space efficient than BitVector when the set is sparse, + as well as making set operations O(number of set bits) instead of O(size of + universe). The downside to the SparseBitVector is that setting and testing of random bits is O(N), and on large SparseBitVectors, this can be slower than BitVector. In our implementation, setting or testing bits in sorted order + (either forwards or reverse) is O(1) worst case. Testing and setting bits within 128 bits (depends on size) of the current bit is also O(1). As a general statement, testing/setting bits in a SparseBitVector is O(distance away from last set bit). +

    +
    + + +
    + Helpful Hints for Common Operations +
    + + +
    + +

    This section describes how to perform some very simple transformations of + LLVM code. This is meant to give examples of common idioms used, showing the + practical side of LLVM transformations.

    Because this is a "how-to" section, + you should also read about the main classes that you will be working with. The + Core LLVM Class Hierarchy Reference contains details + and descriptions of the main classes that you should know about.

    + +
    + + + +
    + Basic Inspection and Traversal Routines +
    + +
    + +

    The LLVM compiler infrastructure have many different data structures that may + be traversed. Following the example of the C++ standard template library, the + techniques used to traverse these various data structures are all basically the + same. For a enumerable sequence of values, the XXXbegin() function (or + method) returns an iterator to the start of the sequence, the XXXend() + function returns an iterator pointing to one past the last valid element of the + sequence, and there is some XXXiterator data type that is common + between the two operations.

    + +

    Because the pattern for iteration is common across many different aspects of + the program representation, the standard template library algorithms may be used + on them, and it is easier to remember how to iterate. First we show a few common + examples of the data structures that need to be traversed. Other data + structures are traversed in very similar ways.

    + +
    + + +
    + Iterating over the BasicBlocks in a Function +
    + +
    + +

    It's quite common to have a Function instance that you'd like to + transform in some way; in particular, you'd like to manipulate its + BasicBlocks. To facilitate this, you'll need to iterate over all of + the BasicBlocks that constitute the Function. The following is + an example that prints the name of a BasicBlock and the number of + Instructions it contains:

    + +
    + 
    + // func is a pointer to a Function instance
+ for (Function::iterator i = func->begin(), e = func->end(); i != e; ++i)
+   // Print out the name of the basic block if it has one, and then the
+   // number of instructions that it contains
+   llvm::cerr << "Basic block (name=" << i->getName() << ") has "
+              << i->size() << " instructions.\n";
+
    +
    + +

    Note that i can be used as if it were a pointer for the purposes of + invoking member functions of the Instruction class. This is + because the indirection operator is overloaded for the iterator + classes. In the above code, the expression i->size() is + exactly equivalent to (*i).size() just like you'd expect.

    + +
    + + +
    + Iterating over the Instructions in a BasicBlock +
    + +
    + +

    Just like when dealing with BasicBlocks in Functions, it's + easy to iterate over the individual instructions that make up + BasicBlocks. Here's a code snippet that prints out each instruction in + a BasicBlock:

    + +
    + 
    + // blk is a pointer to a BasicBlock instance
+ for (BasicBlock::iterator i = blk->begin(), e = blk->end(); i != e; ++i)
+    // The next statement works since operator<<(ostream&,...)
+    // is overloaded for Instruction&
+    llvm::cerr << *i << "\n";
+
    +
    + +

    However, this isn't really the best way to print out the contents of a + BasicBlock! Since the ostream operators are overloaded for virtually + anything you'll care about, you could have just invoked the print routine on the + basic block itself: llvm::cerr << *blk << "\n";.

    + +
    + + +
    + Iterating over the Instructions in a Function +
    + +
    + +

    If you're finding that you commonly iterate over a Function's + BasicBlocks and then that BasicBlock's Instructions, + InstIterator should be used instead. You'll need to include llvm/Support/InstIterator.h, + and then instantiate InstIterators explicitly in your code. Here's a + small example that shows how to dump all instructions in a function to the standard error stream:

    + +

    + 
    + #include "llvm/Support/InstIterator.h"
+ 
+ // F is a pointer to a Function instance
+ for (inst_iterator i = inst_begin(F), e = inst_end(F); i != e; ++i)
+   llvm::cerr << *i << "\n";
+
    +
    + +

    Easy, isn't it? You can also use InstIterators to fill a + work list with its initial contents. For example, if you wanted to + initialize a work list to contain all instructions in a Function + F, all you would need to do is something like:

    + +
    + 
    + std::set<Instruction*> worklist;
+ worklist.insert(inst_begin(F), inst_end(F));
+
    +
    + +

    The STL set worklist would now contain all instructions in the + Function pointed to by F.

    + +
    + + +
    + Turning an iterator into a class pointer (and + vice-versa) +
    + +
    + +

    Sometimes, it'll be useful to grab a reference (or pointer) to a class + instance when all you've got at hand is an iterator. Well, extracting + a reference or a pointer from an iterator is very straight-forward. + Assuming that i is a BasicBlock::iterator and j + is a BasicBlock::const_iterator:

    + +
    + 
    + Instruction& inst = *i;   // Grab reference to instruction reference
+ Instruction* pinst = &*i; // Grab pointer to instruction reference
+ const Instruction& inst = *j;
+
    +
    + +

    However, the iterators you'll be working with in the LLVM framework are + special: they will automatically convert to a ptr-to-instance type whenever they + need to. Instead of dereferencing the iterator and then taking the address of + the result, you can simply assign the iterator to the proper pointer type and + you get the dereference and address-of operation as a result of the assignment + (behind the scenes, this is a result of overloading casting mechanisms). Thus + the last line of the last example,

    + +
    + 
    + Instruction *pinst = &*i;
+
    +
    + +

    is semantically equivalent to

    + +
    + 
    + Instruction *pinst = i;
+
    +
    + +

    It's also possible to turn a class pointer into the corresponding iterator, + and this is a constant time operation (very efficient). The following code + snippet illustrates use of the conversion constructors provided by LLVM + iterators. By using these, you can explicitly grab the iterator of something + without actually obtaining it via iteration over some structure:

    + +
    + 
    + void printNextInstruction(Instruction* inst) {
+   BasicBlock::iterator it(inst);
+   ++it; // After this line, it refers to the instruction after *inst
+   if (it != inst->getParent()->end()) llvm::cerr << *it << "\n";
+ }
+
    +
    + +
    + + +
    + Finding call sites: a slightly more complex + example +
    + +
    + +

    Say that you're writing a FunctionPass and would like to count all the + locations in the entire module (that is, across every Function) where a + certain function (i.e., some Function*) is already in scope. As you'll + learn later, you may want to use an InstVisitor to accomplish this in a + much more straight-forward manner, but this example will allow us to explore how + you'd do it if you didn't have InstVisitor around. In pseudo-code, this + is what we want to do:

    + +
    + 
    + initialize callCounter to zero
+ for each Function f in the Module
+   for each BasicBlock b in f
+     for each Instruction i in b
+       if (i is a CallInst and calls the given function)
+         increment callCounter
+
    +
    + +

    And the actual code is (remember, because we're writing a + FunctionPass, our FunctionPass-derived class simply has to + override the runOnFunction method):

    + +
    + 
    + Function* targetFunc = ...;
+ 
+ class OurFunctionPass : public FunctionPass {
+   public:
+     OurFunctionPass(): callCounter(0) { }
+ 
+     virtual runOnFunction(Function& F) {
+       for (Function::iterator b = F.begin(), be = F.end(); b != be; ++b) {
+         for (BasicBlock::iterator i = b->begin(); ie = b->end(); i != ie; ++i) {
+           if (CallInst* callInst = dyn_cast<CallInst>(&*i)) {
+             // We know we've encountered a call instruction, so we
+             // need to determine if it's a call to the
+             // function pointed to by m_func or not.
+             if (callInst->getCalledFunction() == targetFunc)
+               ++callCounter;
+           }
+         }
+       }
+     }
+ 
+   private:
+     unsigned callCounter;
+ };
+
    +
    + +
    + + +
    + Treating calls and invokes the same way +
    + +
    + +

    You may have noticed that the previous example was a bit oversimplified in + that it did not deal with call sites generated by 'invoke' instructions. In + this, and in other situations, you may find that you want to treat + CallInsts and InvokeInsts the same way, even though their + most-specific common base class is Instruction, which includes lots of + less closely-related things. For these cases, LLVM provides a handy wrapper + class called CallSite. + It is essentially a wrapper around an Instruction pointer, with some + methods that provide functionality common to CallInsts and + InvokeInsts.

    + +

    This class has "value semantics": it should be passed by value, not by + reference and it should not be dynamically allocated or deallocated using + operator new or operator delete. It is efficiently copyable, + assignable and constructable, with costs equivalents to that of a bare pointer. + If you look at its definition, it has only a single pointer member.

    + +
    + + +
    + Iterating over def-use & use-def chains +
    + +
    + +

    Frequently, we might have an instance of the Value Class and we want to + determine which Users use the Value. The list of all + Users of a particular Value is called a def-use chain. + For example, let's say we have a Function* named F to a + particular function foo. Finding all of the instructions that + use foo is as simple as iterating over the def-use chain + of F:

    + +
    + 
    + Function *F = ...;
+ 
+ for (Value::use_iterator i = F->use_begin(), e = F->use_end(); i != e; ++i)
+   if (Instruction *Inst = dyn_cast<Instruction>(*i)) {
+     llvm::cerr << "F is used in instruction:\n";
+     llvm::cerr << *Inst << "\n";
+   }
+
    +
    + +

    Alternately, it's common to have an instance of the User Class and need to know what + Values are used by it. The list of all Values used by a + User is known as a use-def chain. Instances of class + Instruction are common Users, so we might want to iterate over + all of the values that a particular instruction uses (that is, the operands of + the particular Instruction):

    + +
    + 
    + Instruction *pi = ...;
+ 
+ for (User::op_iterator i = pi->op_begin(), e = pi->op_end(); i != e; ++i) {
+   Value *v = *i;
+   // ...
+ }
+
    +
    + + + +
    + + +
    + Iterating over predecessors & + successors of blocks +
    + +
    + +

    Iterating over the predecessors and successors of a block is quite easy + with the routines defined in "llvm/Support/CFG.h". Just use code like + this to iterate over all predecessors of BB:

    + +
    + 
    + #include "llvm/Support/CFG.h"
+ BasicBlock *BB = ...;
+ 
+ for (pred_iterator PI = pred_begin(BB), E = pred_end(BB); PI != E; ++PI) {
+   BasicBlock *Pred = *PI;
+   // ...
+ }
+
    +
    + +

    Similarly, to iterate over successors use + succ_iterator/succ_begin/succ_end.

    + +
    + + + +
    + Making simple changes +
    + +
    + +

    There are some primitive transformation operations present in the LLVM + infrastructure that are worth knowing about. When performing + transformations, it's fairly common to manipulate the contents of basic + blocks. This section describes some of the common methods for doing so + and gives example code.

    + +
    + + +
    + Creating and inserting new + Instructions +
    + +
    + +

    Instantiating Instructions

    + +

    Creation of Instructions is straight-forward: simply call the + constructor for the kind of instruction to instantiate and provide the necessary + parameters. For example, an AllocaInst only requires a + (const-ptr-to) Type. Thus:

    + +
    + 
    + AllocaInst* ai = new AllocaInst(Type::Int32Ty);
+
    +
    + +

    will create an AllocaInst instance that represents the allocation of + one integer in the current stack frame, at run time. Each Instruction + subclass is likely to have varying default parameters which change the semantics + of the instruction, so refer to the doxygen documentation for the subclass of + Instruction that you're interested in instantiating.

    + +

    Naming values

    + +

    It is very useful to name the values of instructions when you're able to, as + this facilitates the debugging of your transformations. If you end up looking + at generated LLVM machine code, you definitely want to have logical names + associated with the results of instructions! By supplying a value for the + Name (default) parameter of the Instruction constructor, you + associate a logical name with the result of the instruction's execution at + run time. For example, say that I'm writing a transformation that dynamically + allocates space for an integer on the stack, and that integer is going to be + used as some kind of index by some other code. To accomplish this, I place an + AllocaInst at the first point in the first BasicBlock of some + Function, and I'm intending to use it within the same + Function. I might do:

    + +
    + 
    + AllocaInst* pa = new AllocaInst(Type::Int32Ty, 0, "indexLoc");
+
    +
    + +

    where indexLoc is now the logical name of the instruction's + execution value, which is a pointer to an integer on the run time stack.

    + +

    Inserting instructions

    + +

    There are essentially two ways to insert an Instruction + into an existing sequence of instructions that form a BasicBlock:

    + +
      +
    • Insertion into an explicit instruction list + +

      Given a BasicBlock* pb, an Instruction* pi within that + BasicBlock, and a newly-created instruction we wish to insert + before *pi, we do the following:

      + +
      + 
      + BasicBlock *pb = ...;
+ Instruction *pi = ...;
+ Instruction *newInst = new Instruction(...);
+ 
+ pb->getInstList().insert(pi, newInst); // Inserts newInst before pi in pb
+
      +
      + +

      Appending to the end of a BasicBlock is so common that + the Instruction class and Instruction-derived + classes provide constructors which take a pointer to a + BasicBlock to be appended to. For example code that + looked like:

      + +
      + 
      + BasicBlock *pb = ...;
+ Instruction *newInst = new Instruction(...);
+ 
+ pb->getInstList().push_back(newInst); // Appends newInst to pb
+
      +
      + +

      becomes:

      + +
      + 
      + BasicBlock *pb = ...;
+ Instruction *newInst = new Instruction(..., pb);
+
      +
      + +

      which is much cleaner, especially if you are creating + long instruction streams.

      • + +
    • Insertion into an implicit instruction list + +

      Instruction instances that are already in BasicBlocks + are implicitly associated with an existing instruction list: the instruction + list of the enclosing basic block. Thus, we could have accomplished the same + thing as the above code without being given a BasicBlock by doing: +

      + +
      + 
      + Instruction *pi = ...;
+ Instruction *newInst = new Instruction(...);
+ 
+ pi->getParent()->getInstList().insert(pi, newInst);
+
      +
      + +

      In fact, this sequence of steps occurs so frequently that the + Instruction class and Instruction-derived classes provide + constructors which take (as a default parameter) a pointer to an + Instruction which the newly-created Instruction should + precede. That is, Instruction constructors are capable of + inserting the newly-created instance into the BasicBlock of a + provided instruction, immediately before that instruction. Using an + Instruction constructor with a insertBefore (default) + parameter, the above code becomes:

      + +
      + 
      + Instruction* pi = ...;
+ Instruction* newInst = new Instruction(..., pi);
+
      +
      + +

      which is much cleaner, especially if you're creating a lot of + instructions and adding them to BasicBlocks.

      • +
    + +
    + + +
    + Deleting Instructions +
    + +
    + +

    Deleting an instruction from an existing sequence of instructions that form a + BasicBlock is very straight-forward. First, + you must have a pointer to the instruction that you wish to delete. Second, you + need to obtain the pointer to that instruction's basic block. You use the + pointer to the basic block to get its list of instructions and then use the + erase function to remove your instruction. For example:

    + +
    + 
    + Instruction *I = .. ;
+ BasicBlock *BB = I->getParent();
+ 
+ BB->getInstList().erase(I);
+
    +
    + +
    + + +
    + Replacing an Instruction with another + Value +
    + +
    + +

    Replacing individual instructions

    + +

    Including "llvm/Transforms/Utils/BasicBlockUtils.h" + permits use of two very useful replace functions: ReplaceInstWithValue + and ReplaceInstWithInst.

    + +

    Deleting Instructions

    + +
      +
    • ReplaceInstWithValue + +

      This function replaces all uses (within a basic block) of a given + instruction with a value, and then removes the original instruction. The + following example illustrates the replacement of the result of a particular + AllocaInst that allocates memory for a single integer with a null + pointer to an integer.

      + +
      + 
      + AllocaInst* instToReplace = ...;
+ BasicBlock::iterator ii(instToReplace);
+ 
+ ReplaceInstWithValue(instToReplace->getParent()->getInstList(), ii,
+                      Constant::getNullValue(PointerType::get(Type::Int32Ty)));
+
      • + +
    • ReplaceInstWithInst + +

      This function replaces a particular instruction with another + instruction. The following example illustrates the replacement of one + AllocaInst with another.

      + +
      + 
      + AllocaInst* instToReplace = ...;
+ BasicBlock::iterator ii(instToReplace);
+ 
+ ReplaceInstWithInst(instToReplace->getParent()->getInstList(), ii,
+                     new AllocaInst(Type::Int32Ty, 0, "ptrToReplacedInt"));
+
      • +
    + +

    Replacing multiple uses of Users and Values

    + +

    You can use Value::replaceAllUsesWith and + User::replaceUsesOfWith to change more than one use at a time. See the + doxygen documentation for the Value Class + and User Class, respectively, for more + information.

    + + + +
    + + +
    + Deleting GlobalVariables +
    + +
    + +

    Deleting a global variable from a module is just as easy as deleting an + Instruction. First, you must have a pointer to the global variable that you wish + to delete. You use this pointer to erase it from its parent, the module. + For example:

    + +
    + 
    + GlobalVariable *GV = .. ;
+ 
+ GV->eraseFromParent();
+
    +
    + +
    + + +
    + Advanced Topics +
    + + +
    +

    + This section describes some of the advanced or obscure API's that most clients + do not need to be aware of. These API's tend manage the inner workings of the + LLVM system, and only need to be accessed in unusual circumstances. +

    +
    + + +
    + LLVM Type Resolution +
    + +
    + +

    + The LLVM type system has a very simple goal: allow clients to compare types for + structural equality with a simple pointer comparison (aka a shallow compare). + This goal makes clients much simpler and faster, and is used throughout the LLVM + system. +

    + +

    + Unfortunately achieving this goal is not a simple matter. In particular, + recursive types and late resolution of opaque types makes the situation very + difficult to handle. Fortunately, for the most part, our implementation makes + most clients able to be completely unaware of the nasty internal details. The + primary case where clients are exposed to the inner workings of it are when + building a recursive type. In addition to this case, the LLVM bitcode reader, + assembly parser, and linker also have to be aware of the inner workings of this + system. +

    + +

    + For our purposes below, we need three concepts. First, an "Opaque Type" is + exactly as defined in the language + reference. Second an "Abstract Type" is any type which includes an + opaque type as part of its type graph (for example "{ opaque, i32 }"). + Third, a concrete type is a type that is not an abstract type (e.g. "{ i32, + float }"). +

    + +
    + + +
    + Basic Recursive Type Construction +
    + +
    + +

    + Because the most common question is "how do I build a recursive type with LLVM", + we answer it now and explain it as we go. Here we include enough to cause this + to be emitted to an output .ll file: +

    + +
    + 
    + %mylist = type { %mylist*, i32 }
+
    +
    + +

    + To build this, use the following LLVM APIs: +

    + +
    + 
    + // Create the initial outer struct
+ PATypeHolder StructTy = OpaqueType::get();
+ std::vector<const Type*> Elts;
+ Elts.push_back(PointerType::get(StructTy));
+ Elts.push_back(Type::Int32Ty);
+ StructType *NewSTy = StructType::get(Elts);
+ 
+ // At this point, NewSTy = "{ opaque*, i32 }". Tell VMCore that
+ // the struct and the opaque type are actually the same.
+ cast<OpaqueType>(StructTy.get())->refineAbstractTypeTo(NewSTy);
+ 
+ // NewSTy is potentially invalidated, but StructTy (a PATypeHolder) is
+ // kept up-to-date
+ NewSTy = cast<StructType>(StructTy.get());
+ 
+ // Add a name for the type to the module symbol table (optional)
+ MyModule->addTypeName("mylist", NewSTy);
+
    +
    + +

    + This code shows the basic approach used to build recursive types: build a + non-recursive type using 'opaque', then use type unification to close the cycle. + The type unification step is performed by the refineAbstractTypeTo method, which is + described next. After that, we describe the PATypeHolder class. +

    + +
    + + +
    + The refineAbstractTypeTo method +
    + +
    +

    + The refineAbstractTypeTo method starts the type unification process. + While this method is actually a member of the DerivedType class, it is most + often used on OpaqueType instances. Type unification is actually a recursive + process. After unification, types can become structurally isomorphic to + existing types, and all duplicates are deleted (to preserve pointer equality). +

    + +

    + In the example above, the OpaqueType object is definitely deleted. + Additionally, if there is an "{ \2*, i32}" type already created in the system, + the pointer and struct type created are also deleted. Obviously whenever + a type is deleted, any "Type*" pointers in the program are invalidated. As + such, it is safest to avoid having any "Type*" pointers to abstract types + live across a call to refineAbstractTypeTo (note that non-abstract + types can never move or be deleted). To deal with this, the PATypeHolder class is used to maintain a stable + reference to a possibly refined type, and the AbstractTypeUser class is used to update more + complex datastructures. +

    + +
    + + +
    + The PATypeHolder Class +
    + +
    +

    + PATypeHolder is a form of a "smart pointer" for Type objects. When VMCore + happily goes about nuking types that become isomorphic to existing types, it + automatically updates all PATypeHolder objects to point to the new type. In the + example above, this allows the code to maintain a pointer to the resultant + resolved recursive type, even though the Type*'s are potentially invalidated. +

    + +

    + PATypeHolder is an extremely light-weight object that uses a lazy union-find + implementation to update pointers. For example the pointer from a Value to its + Type is maintained by PATypeHolder objects. +

    + +
    + + +
    + The AbstractTypeUser Class +
    + +
    + +

    + Some data structures need more to perform more complex updates when types get + resolved. To support this, a class can derive from the AbstractTypeUser class. + This class + allows it to get callbacks when certain types are resolved. To register to get + callbacks for a particular type, the DerivedType::{add/remove}AbstractTypeUser + methods can be called on a type. Note that these methods only work for + abstract types. Concrete types (those that do not include any opaque + objects) can never be refined. +

    +
    + + + +
    + The ValueSymbolTable and + TypeSymbolTable classes +
    + +
    +

    The + ValueSymbolTable class provides a symbol table that the Function and + Module classes use for naming value definitions. The symbol table + can provide a name for any Value. + The + TypeSymbolTable class is used by the Module class to store + names for types.

    + +

    Note that the SymbolTable class should not be directly accessed + by most clients. It should only be used when iteration over the symbol table + names themselves are required, which is very special purpose. Note that not + all LLVM + Values have names, and those without names (i.e. they have + an empty name) do not exist in the symbol table. +

    + +

    These symbol tables support iteration over the values/types in the symbol + table with begin/end/iterator and supports querying to see if a + specific name is in the symbol table (with lookup). The + ValueSymbolTable class exposes no public mutator methods, instead, + simply call setName on a value, which will autoinsert it into the + appropriate symbol table. For types, use the Module::addTypeName method to + insert entries into the symbol table.

    + +
    + + + + +
    + The Core LLVM Class Hierarchy Reference +
    + + +
    +

    #include "llvm/Type.h" +
    doxygen info: Type Class

    + +

    The Core LLVM classes are the primary means of representing the program + being inspected or transformed. The core LLVM classes are defined in + header files in the include/llvm/ directory, and implemented in + the lib/VMCore directory.

    + +
    + + +
    + The Type class and Derived Types +
    + +
    + +

    Type is a superclass of all type classes. Every Value has + a Type. Type cannot be instantiated directly but only + through its subclasses. Certain primitive types (VoidType, + LabelType, FloatType and DoubleType) have hidden + subclasses. They are hidden because they offer no useful functionality beyond + what the Type class offers except to distinguish themselves from + other subclasses of Type.

    +

    All other types are subclasses of DerivedType. Types can be + named, but this is not a requirement. There exists exactly + one instance of a given shape at any one time. This allows type equality to + be performed with address equality of the Type Instance. That is, given two + Type* values, the types are identical if the pointers are identical. +

    +
    + + +
    + Important Public Methods +
    + +
    + +
      +
    • bool isInteger() const: Returns true for any integer type.
      • + +
    • bool isFloatingPoint(): Return true if this is one of the two + floating point types.
      • + +
    • bool isAbstract(): Return true if the type is abstract (contains + an OpaqueType anywhere in its definition).
      • + +
    • bool isSized(): Return true if the type has known size. Things + that don't have a size are abstract types, labels and void.
      • + +
    +
    + + +
    + Important Derived Types +
    +
    +
    +
    IntegerType
    +
    Subclass of DerivedType that represents integer types of any bit width. + Any bit width between IntegerType::MIN_INT_BITS (1) and + IntegerType::MAX_INT_BITS (~8 million) can be represented. +
      +
    • static const IntegerType* get(unsigned NumBits): get an integer + type of a specific bit width.
      • +
    • unsigned getBitWidth() const: Get the bit width of an integer + type.
      • +
    +
    +
    SequentialType
    +
    This is subclassed by ArrayType and PointerType +
      +
    • const Type * getElementType() const: Returns the type of each + of the elements in the sequential type.
      • +
    +
    +
    ArrayType
    +
    This is a subclass of SequentialType and defines the interface for array + types. +
      +
    • unsigned getNumElements() const: Returns the number of + elements in the array.
      • +
    +
    +
    PointerType
    +
    Subclass of SequentialType for pointer types.
    +
    VectorType
    +
    Subclass of SequentialType for vector types. A + vector type is similar to an ArrayType but is distinguished because it is + a first class type wherease ArrayType is not. Vector types are used for + vector operations and are usually small vectors of of an integer or floating + point type.
    +
    StructType
    +
    Subclass of DerivedTypes for struct types.
    +
    FunctionType
    +
    Subclass of DerivedTypes for function types. +
      +
    • bool isVarArg() const: Returns true if its a vararg + function
      • +
    • const Type * getReturnType() const: Returns the + return type of the function.
      • +
    • const Type * getParamType (unsigned i): Returns + the type of the ith parameter.
      • +
    • const unsigned getNumParams() const: Returns the + number of formal parameters.
      • +
    +
    +
    OpaqueType
    +
    Sublcass of DerivedType for abstract types. This class + defines no content and is used as a placeholder for some other type. Note + that OpaqueType is used (temporarily) during type resolution for forward + references of types. Once the referenced type is resolved, the OpaqueType + is replaced with the actual type. OpaqueType can also be used for data + abstraction. At link time opaque types can be resolved to actual types + of the same name.
    +
    +
    + + + + +
    + The Module class +
    + +
    + +

    #include "llvm/Module.h"
    doxygen info: + Module Class

    + +

    The Module class represents the top level structure present in LLVM + programs. An LLVM module is effectively either a translation unit of the + original program or a combination of several translation units merged by the + linker. The Module class keeps track of a list of Functions, a list of GlobalVariables, and a SymbolTable. Additionally, it contains a few + helpful member functions that try to make common operations easy.

    + +
    + + +
    + Important Public Members of the Module class +
    + +
    + +
      +
    • Module::Module(std::string name = "")
      • +
    + +

    Constructing a Module is easy. You can optionally + provide a name for it (probably based on the name of the translation unit).

    + +
      +
    • Module::iterator - Typedef for function list iterator
      + Module::const_iterator - Typedef for const_iterator.
      + + begin(), end() + size(), empty() + +

      These are forwarding methods that make it easy to access the contents of + a Module object's Function + list.

      • + +
    • Module::FunctionListType &getFunctionList() + +

      Returns the list of Functions. This is + necessary to use when you need to update the list or perform a complex + action that doesn't have a forwarding method.

      + +

      • +
    + +
    + +
      +
    • Module::global_iterator - Typedef for global variable list iterator
      + + Module::const_global_iterator - Typedef for const_iterator.
      + + global_begin(), global_end() + global_size(), global_empty() + +

      These are forwarding methods that make it easy to access the contents of + a Module object's GlobalVariable list.

      • + +
    • Module::GlobalListType &getGlobalList() + +

      Returns the list of GlobalVariables. This is necessary to + use when you need to update the list or perform a complex action that + doesn't have a forwarding method.

      + +

      • +
    + +
    + + + +
    + +
      +
    • Function *getFunction(const std::string + &Name, const FunctionType *Ty) + +

      Look up the specified function in the Module SymbolTable. If it does not exist, return + null.

      • + +
    • Function *getOrInsertFunction(const + std::string &Name, const FunctionType *T) + +

      Look up the specified function in the Module SymbolTable. If it does not exist, add an + external declaration for the function and return it.

      • + +
    • std::string getTypeName(const Type *Ty) + +

      If there is at least one entry in the SymbolTable for the specified Type, return it. Otherwise return the empty + string.

      • + +
    • bool addTypeName(const std::string &Name, const Type *Ty) + +

      Insert an entry in the SymbolTable + mapping Name to Ty. If there is already an entry for this + name, true is returned and the SymbolTable is not modified.

      • +
    + +
    + + + +
    + The Value class +
    + +
    + +

    #include "llvm/Value.h" +
    + doxygen info: Value Class

    + +

    The Value class is the most important class in the LLVM Source + base. It represents a typed value that may be used (among other things) as an + operand to an instruction. There are many different types of Values, + such as Constants,Arguments. Even Instructions and Functions are Values.

    + +

    A particular Value may be used many times in the LLVM representation + for a program. For example, an incoming argument to a function (represented + with an instance of the Argument class) is "used" by + every instruction in the function that references the argument. To keep track + of this relationship, the Value class keeps a list of all of the Users that is using it (the User class is a base class for all nodes in the LLVM + graph that can refer to Values). This use list is how LLVM represents + def-use information in the program, and is accessible through the use_* + methods, shown below.

    + +

    Because LLVM is a typed representation, every LLVM Value is typed, + and this Type is available through the getType() + method. In addition, all LLVM values can be named. The "name" of the + Value is a symbolic string printed in the LLVM code:

    + +
    + 
    + %foo = add i32 1, 2
+
    +
    + +

    The name of this instruction is "foo". NOTE + that the name of any value may be missing (an empty string), so names should + ONLY be used for debugging (making the source code easier to read, + debugging printouts), they should not be used to keep track of values or map + between them. For this purpose, use a std::map of pointers to the + Value itself instead.

    + +

    One important aspect of LLVM is that there is no distinction between an SSA + variable and the operation that produces it. Because of this, any reference to + the value produced by an instruction (or the value available as an incoming + argument, for example) is represented as a direct pointer to the instance of + the class that + represents this value. Although this may take some getting used to, it + simplifies the representation and makes it easier to manipulate.

    + +
    + + +
    + Important Public Members of the Value class +
    + +
    + +
      +
    • Value::use_iterator - Typedef for iterator over the + use-list
      + Value::use_const_iterator - Typedef for const_iterator over + the use-list
      + unsigned use_size() - Returns the number of users of the + value.
      + bool use_empty() - Returns true if there are no users.
      + use_iterator use_begin() - Get an iterator to the start of + the use-list.
      + use_iterator use_end() - Get an iterator to the end of the + use-list.
      + User *use_back() - Returns the last + element in the list. +

      These methods are the interface to access the def-use + information in LLVM. As with all other iterators in LLVM, the naming + conventions follow the conventions defined by the STL.

      +
      • +
    • Type *getType() const +

      This method returns the Type of the Value.

      +
      • +
    • bool hasName() const
      + std::string getName() const
      + void setName(const std::string &Name) +

      This family of methods is used to access and assign a name to a Value, + be aware of the precaution above.

      +
      • +
    • void replaceAllUsesWith(Value *V) + +

      This method traverses the use list of a Value changing all Users of the current value to refer to + "V" instead. For example, if you detect that an instruction always + produces a constant value (for example through constant folding), you can + replace all uses of the instruction with the constant like this:

      + +
      + 
      + Inst->replaceAllUsesWith(ConstVal);
+
      +
      + +
    + +
    + + +
    + The User class +
    + +
    + +

    + #include "llvm/User.h"
    + doxygen info: User Class
    + Superclass: Value

    + +

    The User class is the common base class of all LLVM nodes that may + refer to Values. It exposes a list of "Operands" + that are all of the Values that the User is + referring to. The User class itself is a subclass of + Value.

    + +

    The operands of a User point directly to the LLVM Value that it refers to. Because LLVM uses Static + Single Assignment (SSA) form, there can only be one definition referred to, + allowing this direct connection. This connection provides the use-def + information in LLVM.

    + +
    + + +
    + Important Public Members of the User class +
    + +
    + +

    The User class exposes the operand list in two ways: through + an index access interface and through an iterator based interface.

    + +
      +
    • Value *getOperand(unsigned i)
      + unsigned getNumOperands() +

      These two methods expose the operands of the User in a + convenient form for direct access.

      • + +
    • User::op_iterator - Typedef for iterator over the operand + list
      + op_iterator op_begin() - Get an iterator to the start of + the operand list.
      + op_iterator op_end() - Get an iterator to the end of the + operand list. +

      Together, these methods make up the iterator based interface to + the operands of a User.

      • +
    + +
    + + +
    + The Instruction class +
    + +
    + +

    #include "llvm/Instruction.h"
    + doxygen info: Instruction Class
    + Superclasses: User, Value

    + +

    The Instruction class is the common base class for all LLVM + instructions. It provides only a few methods, but is a very commonly used + class. The primary data tracked by the Instruction class itself is the + opcode (instruction type) and the parent BasicBlock the Instruction is embedded + into. To represent a specific type of instruction, one of many subclasses of + Instruction are used.

    + +

    Because the Instruction class subclasses the User class, its operands can be accessed in the same + way as for other Users (with the + getOperand()/getNumOperands() and + op_begin()/op_end() methods).

    An important file for + the Instruction class is the llvm/Instruction.def file. This + file contains some meta-data about the various different types of instructions + in LLVM. It describes the enum values that are used as opcodes (for example + Instruction::Add and Instruction::ICmp), as well as the + concrete sub-classes of Instruction that implement the instruction (for + example BinaryOperator and CmpInst). Unfortunately, the use of macros in + this file confuses doxygen, so these enum values don't show up correctly in the + doxygen output.

    + +
    + + +
    + Important Subclasses of the Instruction + class +
    +
    +
      +
    • BinaryOperator +

      This subclasses represents all two operand instructions whose operands + must be the same type, except for the comparison instructions.

      • +
    • CastInst +

      This subclass is the parent of the 12 casting instructions. It provides + common operations on cast instructions.

      +
    • CmpInst +

      This subclass respresents the two comparison instructions, + ICmpInst (integer opreands), and + FCmpInst (floating point operands).

      +
    • TerminatorInst +

      This subclass is the parent of all terminator instructions (those which + can terminate a block).

      +
    +
    + + +
    + Important Public Members of the Instruction + class +
    + +
    + +
      +
    • BasicBlock *getParent() +

      Returns the BasicBlock that + this Instruction is embedded into.

      • +
    • bool mayWriteToMemory() +

      Returns true if the instruction writes to memory, i.e. it is a + call,free,invoke, or store.

      • +
    • unsigned getOpcode() +

      Returns the opcode for the Instruction.

      • +
    • Instruction *clone() const +

      Returns another instance of the specified instruction, identical + in all ways to the original except that the instruction has no parent + (ie it's not embedded into a BasicBlock), + and it has no name

      • +
    + +
    + + +
    + The Constant class and subclasses +
    + +
    + +

    Constant represents a base class for different types of constants. It + is subclassed by ConstantInt, ConstantArray, etc. for representing + the various types of Constants. GlobalValue is also + a subclass, which represents the address of a global variable or function. +

    + +
    + + +
    Important Subclasses of Constant
    +
    +
      +
    • ConstantInt : This subclass of Constant represents an integer constant of + any width. +
        +
      • const APInt& getValue() const: Returns the underlying + value of this constant, an APInt value.
        • +
      • int64_t getSExtValue() const: Converts the underlying APInt + value to an int64_t via sign extension. If the value (not the bit width) + of the APInt is too large to fit in an int64_t, an assertion will result. + For this reason, use of this method is discouraged.
        • +
      • uint64_t getZExtValue() const: Converts the underlying APInt + value to a uint64_t via zero extension. IF the value (not the bit width) + of the APInt is too large to fit in a uint64_t, an assertion will result. + For this reason, use of this method is discouraged.
        • +
      • static ConstantInt* get(const APInt& Val): Returns the + ConstantInt object that represents the value provided by Val. + The type is implied as the IntegerType that corresponds to the bit width + of Val.
        • +
      • static ConstantInt* get(const Type *Ty, uint64_t Val): + Returns the ConstantInt object that represents the value provided by + Val for integer type Ty.
        • +
      +
      • +
    • ConstantFP : This class represents a floating point constant. +
        +
      • double getValue() const: Returns the underlying value of + this constant.
        • +
      +
      • +
    • ConstantArray : This represents a constant array. +
        +
      • const std::vector<Use> &getValues() const: Returns + a vector of component constants that makeup this array.
        • +
      +
      • +
    • ConstantStruct : This represents a constant struct. +
        +
      • const std::vector<Use> &getValues() const: Returns + a vector of component constants that makeup this array.
        • +
      +
      • +
    • GlobalValue : This represents either a global variable or a function. In + either case, the value is a constant fixed address (after linking). +
      • +
    +
    + + + +
    + The GlobalValue class +
    + +
    + +

    #include "llvm/GlobalValue.h"
    + doxygen info: GlobalValue + Class
    + Superclasses: Constant, + User, Value

    + +

    Global values (GlobalVariables or Functions) are the only LLVM values that are + visible in the bodies of all Functions. + Because they are visible at global scope, they are also subject to linking with + other globals defined in different translation units. To control the linking + process, GlobalValues know their linkage rules. Specifically, + GlobalValues know whether they have internal or external linkage, as + defined by the LinkageTypes enumeration.

    + +

    If a GlobalValue has internal linkage (equivalent to being + static in C), it is not visible to code outside the current translation + unit, and does not participate in linking. If it has external linkage, it is + visible to external code, and does participate in linking. In addition to + linkage information, GlobalValues keep track of which Module they are currently part of.

    + +

    Because GlobalValues are memory objects, they are always referred to + by their address. As such, the Type of a + global is always a pointer to its contents. It is important to remember this + when using the GetElementPtrInst instruction because this pointer must + be dereferenced first. For example, if you have a GlobalVariable (a + subclass of GlobalValue) that is an array of 24 ints, type [24 x + i32], then the GlobalVariable is a pointer to that array. Although + the address of the first element of this array and the value of the + GlobalVariable are the same, they have different types. The + GlobalVariable's type is [24 x i32]. The first element's type + is i32. Because of this, accessing a global value requires you to + dereference the pointer with GetElementPtrInst first, then its elements + can be accessed. This is explained in the LLVM + Language Reference Manual.

    + +
    + + +
    + Important Public Members of the GlobalValue + class +
    + +
    + +
      +
    • bool hasInternalLinkage() const
      + bool hasExternalLinkage() const
      + void setInternalLinkage(bool HasInternalLinkage) +

      These methods manipulate the linkage characteristics of the GlobalValue.

      +

      +
      • +
    • Module *getParent() +

      This returns the Module that the + GlobalValue is currently embedded into.

      • +
    + +
    + + +
    + The Function class +
    + +
    + +

    #include "llvm/Function.h"
    doxygen + info: Function Class
    + Superclasses: GlobalValue, + Constant, + User, + Value

    + +

    The Function class represents a single procedure in LLVM. It is + actually one of the more complex classes in the LLVM heirarchy because it must + keep track of a large amount of data. The Function class keeps track + of a list of BasicBlocks, a list of formal + Arguments, and a + SymbolTable.

    + +

    The list of BasicBlocks is the most + commonly used part of Function objects. The list imposes an implicit + ordering of the blocks in the function, which indicate how the code will be + layed out by the backend. Additionally, the first BasicBlock is the implicit entry node for the + Function. It is not legal in LLVM to explicitly branch to this initial + block. There are no implicit exit nodes, and in fact there may be multiple exit + nodes from a single Function. If the BasicBlock list is empty, this indicates that + the Function is actually a function declaration: the actual body of the + function hasn't been linked in yet.

    + +

    In addition to a list of BasicBlocks, the + Function class also keeps track of the list of formal Arguments that the function receives. This + container manages the lifetime of the Argument + nodes, just like the BasicBlock list does for + the BasicBlocks.

    + +

    The SymbolTable is a very rarely used + LLVM feature that is only used when you have to look up a value by name. Aside + from that, the SymbolTable is used + internally to make sure that there are not conflicts between the names of Instructions, BasicBlocks, or Arguments in the function body.

    + +

    Note that Function is a GlobalValue + and therefore also a Constant. The value of the function + is its address (after linking) which is guaranteed to be constant.

    +
    + + +
    + Important Public Members of the Function + class +
    + +
    + +
      +
    • Function(const FunctionType + *Ty, LinkageTypes Linkage, const std::string &N = "", Module* Parent = 0) + +

      Constructor used when you need to create new Functions to add + the the program. The constructor must specify the type of the function to + create and what type of linkage the function should have. The FunctionType argument + specifies the formal arguments and return value for the function. The same + FunctionType value can be used to + create multiple functions. The Parent argument specifies the Module + in which the function is defined. If this argument is provided, the function + will automatically be inserted into that module's list of + functions.

      • + +
    • bool isExternal() + +

      Return whether or not the Function has a body defined. If the + function is "external", it does not have a body, and thus must be resolved + by linking with a function defined in a different translation unit.

      • + +
    • Function::iterator - Typedef for basic block list iterator
      + Function::const_iterator - Typedef for const_iterator.
      + + begin(), end() + size(), empty() + +

      These are forwarding methods that make it easy to access the contents of + a Function object's BasicBlock + list.

      • + +
    • Function::BasicBlockListType &getBasicBlockList() + +

      Returns the list of BasicBlocks. This + is necessary to use when you need to update the list or perform a complex + action that doesn't have a forwarding method.

      • + +
    • Function::arg_iterator - Typedef for the argument list + iterator
      + Function::const_arg_iterator - Typedef for const_iterator.
      + + arg_begin(), arg_end() + arg_size(), arg_empty() + +

      These are forwarding methods that make it easy to access the contents of + a Function object's Argument + list.

      • + +
    • Function::ArgumentListType &getArgumentList() + +

      Returns the list of Arguments. This is + necessary to use when you need to update the list or perform a complex + action that doesn't have a forwarding method.

      • + +
    • BasicBlock &getEntryBlock() + +

      Returns the entry BasicBlock for the + function. Because the entry block for the function is always the first + block, this returns the first block of the Function.

      • + +
    • Type *getReturnType()
      + FunctionType *getFunctionType() + +

      This traverses the Type of the + Function and returns the return type of the function, or the FunctionType of the actual + function.

      • + +
    • SymbolTable *getSymbolTable() + +

      Return a pointer to the SymbolTable + for this Function.

      • +
    + +
    + + +
    + The GlobalVariable class +
    + +
    + +

    #include "llvm/GlobalVariable.h" +
    + doxygen info: GlobalVariable + Class
    + Superclasses: GlobalValue, + Constant, + User, + Value

    + +

    Global variables are represented with the (suprise suprise) + GlobalVariable class. Like functions, GlobalVariables are also + subclasses of GlobalValue, and as such are + always referenced by their address (global values must live in memory, so their + "name" refers to their constant address). See + GlobalValue for more on this. Global + variables may have an initial value (which must be a + Constant), and if they have an initializer, + they may be marked as "constant" themselves (indicating that their contents + never change at runtime).

    +
    + + +
    + Important Public Members of the + GlobalVariable class +
    + +
    + +
      +
    • GlobalVariable(const Type *Ty, bool + isConstant, LinkageTypes& Linkage, Constant + *Initializer = 0, const std::string &Name = "", Module* Parent = 0) + +

      Create a new global variable of the specified type. If + isConstant is true then the global variable will be marked as + unchanging for the program. The Linkage parameter specifies the type of + linkage (internal, external, weak, linkonce, appending) for the variable. If + the linkage is InternalLinkage, WeakLinkage, or LinkOnceLinkage,  then + the resultant global variable will have internal linkage. AppendingLinkage + concatenates together all instances (in different translation units) of the + variable into a single variable but is only applicable to arrays.  See + the LLVM Language Reference for + further details on linkage types. Optionally an initializer, a name, and the + module to put the variable into may be specified for the global variable as + well.

      • + +
    • bool isConstant() const + +

      Returns true if this is a global variable that is known not to + be modified at runtime.

      • + +
    • bool hasInitializer() + +

      Returns true if this GlobalVariable has an intializer.

      • + +
    • Constant *getInitializer() + +

      Returns the intial value for a GlobalVariable. It is not legal + to call this method if there is no initializer.

      • +
    + +
    + + + +
    + The BasicBlock class +
    + +
    + +

    #include "llvm/BasicBlock.h"
    + doxygen info: BasicBlock + Class
    + Superclass: Value

    + +

    This class represents a single entry multiple exit section of the code, + commonly known as a basic block by the compiler community. The + BasicBlock class maintains a list of Instructions, which form the body of the block. + Matching the language definition, the last element of this list of instructions + is always a terminator instruction (a subclass of the TerminatorInst class).

    + +

    In addition to tracking the list of instructions that make up the block, the + BasicBlock class also keeps track of the Function that it is embedded into.

    + +

    Note that BasicBlocks themselves are Values, because they are referenced by instructions + like branches and can go in the switch tables. BasicBlocks have type + label.

    + +
    + + +
    + Important Public Members of the BasicBlock + class +
    + +
    +
      + +
    • BasicBlock(const std::string &Name = "", Function *Parent = 0) + +

      The BasicBlock constructor is used to create new basic blocks for + insertion into a function. The constructor optionally takes a name for the new + block, and a Function to insert it into. If + the Parent parameter is specified, the new BasicBlock is + automatically inserted at the end of the specified Function, if not specified, the BasicBlock must be + manually inserted into the Function.

      • + +
    • BasicBlock::iterator - Typedef for instruction list iterator
      + BasicBlock::const_iterator - Typedef for const_iterator.
      + begin(), end(), front(), back(), + size(), empty() + STL-style functions for accessing the instruction list. + +

      These methods and typedefs are forwarding functions that have the same + semantics as the standard library methods of the same names. These methods + expose the underlying instruction list of a basic block in a way that is easy to + manipulate. To get the full complement of container operations (including + operations to update the list), you must use the getInstList() + method.

      • + +
    • BasicBlock::InstListType &getInstList() + +

      This method is used to get access to the underlying container that actually + holds the Instructions. This method must be used when there isn't a forwarding + function in the BasicBlock class for the operation that you would like + to perform. Because there are no forwarding functions for "updating" + operations, you need to use this if you want to update the contents of a + BasicBlock.

      • + +
    • Function *getParent() + +

      Returns a pointer to Function the block is + embedded into, or a null pointer if it is homeless.

      • + +
    • TerminatorInst *getTerminator() + +

      Returns a pointer to the terminator instruction that appears at the end of + the BasicBlock. If there is no terminator instruction, or if the last + instruction in the block is not a terminator, then a null pointer is + returned.

      • + +
    + +
    + + + +
    + The Argument class +
    + +
    + +

    This subclass of Value defines the interface for incoming formal + arguments to a function. A Function maintains a list of its formal + arguments. An argument has a pointer to the parent Function.

    + +
    + + +
    +
    + Valid CSS! + Valid HTML 4.01! + + Dinakar Dhurjati and + Chris Lattner
    + The LLVM Compiler Infrastructure
    + Last modified: $Date: 2008/02/12 06:05:03 $ +
    + + + Index: llvm-www/releases/2.2/docs/Projects.html diff -c /dev/null llvm-www/releases/2.2/docs/Projects.html:1.1 *** /dev/null Tue Feb 12 00:07:05 2008 --- llvm-www/releases/2.2/docs/Projects.html Tue Feb 12 00:05:03 2008 *************** *** 0 **** --- 1,460 ---- + + + + Creating an LLVM Project + + + + +
    Creating an LLVM Project
    + +
      +
    1. Overview
      2. +
    2. Create a project from the Sample Project
      3. +
    3. Source tree layout
      4. +
    4. Writing LLVM-style Makefiles +
        +
      1. Required Variables
        2. +
      2. Variables for Building Subdirectories
        3. +
      3. Variables for Building Libraries
        4. +
      4. Variables for Building Programs
        5. +
      5. Miscellaneous Variables
        6. +
      5. +
    5. Placement of object code
      6. +
    6. Further help
      7. +
    + +
    +

    Written by John Criswell

    +
    + + +
    Overview
    + + +
    + +

    The LLVM build system is designed to facilitate the building of third party + projects that use LLVM header files, libraries, and tools. In order to use + these facilities, a Makefile from a project must do the following things:

    + +
      +
    1. Set make variables. There are several variables that a Makefile + needs to set to use the LLVM build system: +
        +
      • PROJECT_NAME - The name by which your project is known.
        • +
      • LLVM_SRC_ROOT - The root of the LLVM source tree.
        • +
      • LLVM_OBJ_ROOT - The root of the LLVM object tree.
        • +
      • PROJ_SRC_ROOT - The root of the project's source tree.
        • +
      • PROJ_OBJ_ROOT - The root of the project's object tree.
        • +
      • PROJ_INSTALL_ROOT - The root installation directory.
        • +
      • LEVEL - The relative path from the current directory to the + project's root ($PROJ_OBJ_ROOT).
        • +
      2. +
    2. Include Makefile.config from $(LLVM_OBJ_ROOT).
      3. +
    3. Include Makefile.rules from $(LLVM_SRC_ROOT).
      4. +
    + +

    There are two ways that you can set all of these variables:

    +
      +
    1. You can write your own Makefiles which hard-code these values.
      2. +
    2. You can use the pre-made LLVM sample project. This sample project + includes Makefiles, a configure script that can be used to configure the + location of LLVM, and the ability to support multiple object directories + from a single source directory.
      3. +
    + +

    This document assumes that you will base your project on the LLVM sample + project found in llvm/projects/sample. If you want to devise your own + build system, studying the sample project and LLVM Makefiles will probably + provide enough information on how to write your own Makefiles.

    + +
    + + +
    + Create a Project from the Sample Project +
    + + +
    + +

    Follow these simple steps to start your project:

    + +
      +
    1. Copy the llvm/projects/sample directory to any place of your + choosing. You can place it anywhere you like. Rename the directory to match + the name of your project.
      2. + +
    2. + If you downloaded LLVM using Subversion, remove all the directories named .svn + (and all the files therein) from your project's new source tree. This will + keep Subversion from thinking that your project is inside + llvm/trunk/projects/sample.
      3. + +
    3. Add your source code and Makefiles to your source tree.
      4. + +
    4. If you want your project to be configured with the configure script + then you need to edit autoconf/configure.ac as follows: +
        +
      • AC_INIT. Place the name of your project, its version number and + a contact email address for your project as the arguments to this macro
        • +
      • AC_CONFIG_AUX_DIR. If your project isn't in the + llvm/projects directory then you might need to adjust this so that + it specifies a relative path to the llvm/autoconf directory.
        • +
      • LLVM_CONFIG_PROJECT. Just leave this alone.
        • +
      • AC_CONFIG_SRCDIR. Specify a path to a file name that identifies + your project; or just leave it at Makefile.common.in
        • +
      • AC_CONFIG_FILES. Do not change.
        • +
      • AC_CONFIG_MAKEFILE. Use one of these macros for each Makefile + that your project uses. This macro arranges for your makefiles to be copied + from the source directory, unmodified, to the build directory.
        • +
      +
      5. + +
    5. After updating autoconf/configure.ac, regenerate the + configure script with these commands: + +
      +

      % cd autoconf
      + % AutoRegen.sh

      +
      + +

      You must be using Autoconf version 2.59 or later and your aclocal version + should 1.9 or later.

      6. + +
    6. Run configure in the directory in which you want to place + object code. Use the following options to tell your project where it + can find LLVM: + +
      +
      --with-llvmsrc=<directory>
      +
      Tell your project where the LLVM source tree is located.
      +

      --with-llvmobj=<directory>
      +
      Tell your project where the LLVM object tree is located.
      +

      --prefix=<directory>
      +
      Tell your project where it should get installed.
      +
      +
    + +

    That's it! Now all you have to do is type gmake (or make + if your on a GNU/Linux system) in the root of your object directory, and your + project should build.

    + +
    + + +
    + Source Tree Layout +
    + + +
    + +

    In order to use the LLVM build system, you will want to organize your + source code so that it can benefit from the build system's features. + Mainly, you want your source tree layout to look similar to the LLVM + source tree layout. The best way to do this is to just copy the + project tree from llvm/projects/sample and modify it to meet + your needs, but you can certainly add to it if you want.

    + +

    Underneath your top level directory, you should have the following + directories:

    + +
    +
    lib +
    + This subdirectory should contain all of your library source + code. For each library that you build, you will have one + directory in lib that will contain that library's source + code. + +

    + Libraries can be object files, archives, or dynamic libraries. + The lib directory is just a convenient place for libraries + as it places them all in a directory from which they can be linked + later. + +

    include +
    + This subdirectory should contain any header files that are + global to your project. By global, we mean that they are used + by more than one library or executable of your project. +

    + By placing your header files in include, they will be + found automatically by the LLVM build system. For example, if + you have a file include/jazz/note.h, then your source + files can include it simply with #include "jazz/note.h". + +

    tools +
    + This subdirectory should contain all of your source + code for executables. For each program that you build, you + will have one directory in tools that will contain that + program's source code. +

    + +

    test +
    + This subdirectory should contain tests that verify that your code + works correctly. Automated tests are especially useful. +

    + Currently, the LLVM build system provides basic support for tests. + The LLVM system provides the following: +

      +
    • + LLVM provides a tcl procedure that is used by Dejagnu to run + tests. It can be found in llvm/lib/llvm-dg.exp. This + test procedure uses RUN lines in the actual test case to determine + how to run the test. See the TestingGuide for more details. You + can easily write Makefile support similar to the Makefiles in + llvm/test to use Dejagnu to run your project's tests.
      • +
    • + LLVM contains an optional package called llvm-test + which provides benchmarks and programs that are known to compile with the + LLVM GCC front ends. You can use these + programs to test your code, gather statistics information, and + compare it to the current LLVM performance statistics. +
      Currently, there is no way to hook your tests directly into the + llvm/test testing harness. You will simply + need to find a way to use the source provided within that directory + on your own. +
    +
    + +

    Typically, you will want to build your lib directory first followed by + your tools directory.

    + +
    + + +
    + Writing LLVM Style Makefiles +
    + + +
    + +

    The LLVM build system provides a convenient way to build libraries and + executables. Most of your project Makefiles will only need to define a few + variables. Below is a list of the variables one can set and what they can + do:

    + +
    + + +
    + Required Variables +
    + +
    + +
    +
    LEVEL +
    + This variable is the relative path from this Makefile to the + top directory of your project's source code. For example, if + your source code is in /tmp/src, then the Makefile in + /tmp/src/jump/high would set LEVEL to "../..". +
    + +
    + + +
    + Variables for Building Subdirectories +
    + +
    + +
    +
    DIRS +
    + This is a space separated list of subdirectories that should be + built. They will be built, one at a time, in the order + specified. +

    + +

    PARALLEL_DIRS +
    + This is a list of directories that can be built in parallel. + These will be built after the directories in DIRS have been + built. +

    + +

    OPTIONAL_DIRS +
    + This is a list of directories that can be built if they exist, + but will not cause an error if they do not exist. They are + built serially in the order in which they are listed. +
    + +
    + + +
    + Variables for Building Libraries +
    + +
    + +
    +
    LIBRARYNAME +
    + This variable contains the base name of the library that will + be built. For example, to build a library named + libsample.a, LIBRARYNAME should be set to + sample. +

    + +

    BUILD_ARCHIVE +
    + By default, a library is a .o file that is linked + directly into a program. To build an archive (also known as + a static library), set the BUILD_ARCHIVE variable. +

    + +

    SHARED_LIBRARY +
    + If SHARED_LIBRARY is defined in your Makefile, a shared + (or dynamic) library will be built. +
    + +
    + + +
    + Variables for Building Programs +
    + +
    + +
    +
    TOOLNAME +
    + This variable contains the name of the program that will + be built. For example, to build an executable named + sample, TOOLNAME should be set to sample. +

    + +

    USEDLIBS +
    + This variable holds a space separated list of libraries that + should be linked into the program. These libraries must either + be LLVM libraries or libraries that come from your lib + directory. The libraries must be specified by their base name. + For example, to link libsample.a, you would set USEDLIBS to + sample. +

    + Note that this works only for statically linked libraries. +

    + +

    LIBS +
    + To link dynamic libraries, add -l<library base name> to + the LIBS variable. The LLVM build system will look in the same places + for dynamic libraries as it does for static libraries. +

    + For example, to link libsample.so, you would have the + following line in your Makefile: +

    + + LIBS += -lsample + +

    + +
    + + +
    + Miscellaneous Variables +
    + +
    + +
    +
    ExtraSource +
    + This variable contains a space separated list of extra source + files that need to be built. It is useful for including the + output of Lex and Yacc programs. +

    + +

    CFLAGS +
    CPPFLAGS +
    + This variable can be used to add options to the C and C++ + compiler, respectively. It is typically used to add options + that tell the compiler the location of additional directories + to search for header files. +

    + It is highly suggested that you append to CFLAGS and CPPFLAGS as + opposed to overwriting them. The master Makefiles may already + have useful options in them that you may not want to overwrite. +

    +

    + +
    + + +
    + Placement of Object Code +
    + + +
    + +

    The final location of built libraries and executables will depend upon + whether you do a Debug, Release, or Profile build.

    + +
    +
    Libraries +
    + All libraries (static and dynamic) will be stored in + PROJ_OBJ_ROOT/<type>/lib, where type is Debug, + Release, or Profile for a debug, optimized, or + profiled build, respectively.

    + +

    Executables +
    All executables will be stored in + PROJ_OBJ_ROOT/<type>/bin, where type is Debug, + Release, or Profile for a debug, optimized, or profiled + build, respectively. +
    + +
    + + +
    + Further Help +
    + + +
    + +

    If you have any questions or need any help creating an LLVM project, + the LLVM team would be more than happy to help. You can always post your + questions to the LLVM Developers + Mailing List.

    + +
    + + +
    +
    + Valid CSS! + Valid HTML 4.01! + + John Criswell
    + The LLVM Compiler Infrastructure +
    + Last modified: $Date: 2008/02/12 06:05:03 $ +
    + + + Index: llvm-www/releases/2.2/docs/ReleaseNotes.html diff -c /dev/null llvm-www/releases/2.2/docs/ReleaseNotes.html:1.1 *** /dev/null Tue Feb 12 00:07:05 2008 --- llvm-www/releases/2.2/docs/ReleaseNotes.html Tue Feb 12 00:05:03 2008 *************** *** 0 **** --- 1,761 ---- + + + + + + LLVM 2.2 Release Notes + + + +
    LLVM 2.2 Release Notes
    + +
      +
    1. Introduction
      2. +
    2. What's New?
      3. +
    3. Installation Instructions
      4. +
    4. Portability and Supported Platforms
      5. +
    5. Known Problems +
    6. Additional Information
      7. +
    + +
    +

    Written by the LLVM Team

    +

    + + + +
    + Introduction +
    + + +
    + +

    This document contains the release notes for the LLVM compiler + infrastructure, release 2.2. Here we describe the status of LLVM, including + major improvements from the previous release and any known problems. All LLVM + releases may be downloaded from the LLVM + releases web site.

    + +

    For more information about LLVM, including information about the latest + release, please check out the main LLVM + web site. If you have questions or comments, the LLVM developer's mailing + list is a good place to send them.

    + +

    Note that if you are reading this file from a Subversion checkout or the + main LLVM web page, this document applies to the next release, not the + current one. To see the release notes for a specific releases, please see the + releases page.

    + +
    + + +
    + What's New? +
    + + +
    + +

    This is the thirteenth public release of the LLVM Compiler Infrastructure. + It includes many features and refinements from LLVM 2.1.

    + +
    + + + + +
    + Deprecated features in LLVM 2.2 +
    + +
    + +

    This is the last LLVM release to support llvm-gcc 4.0, llvm-upgrade, and + llvmc in its current form. llvm-gcc 4.0 has been replaced with llvm-gcc 4.2. + llvm-upgrade is useful for upgrading llvm 1.9 files to llvm 2.x syntax, but you + can always use an old release to do this. llvmc is currently mostly useless in + llvm 2.2, and will be redesigned or removed in llvm 2.3.

    + +
    + + +
    + llvm-gcc 4.0, llvm-gcc 4.2, and clang +
    + +
    + +

    LLVM 2.2 fully supports both the llvm-gcc 4.0 and llvm-gcc 4.2 front-ends (in + LLVM 2.1, llvm-gcc 4.2 was beta). Since LLVM 2.1, the llvm-gcc 4.2 front-end + has made leaps and bounds and is now at least as good as 4.0 in virtually every + area, and is better in several areas (for example, exception handling + correctness, support for Ada and Fortran, better ABI compatibility, etc). We + strongly recommend that you + migrate from llvm-gcc 4.0 to llvm-gcc 4.2 in this release cycle because + LLVM 2.2 is the last release that will support llvm-gcc 4.0: LLVM 2.3 + will only support the llvm-gcc 4.2 front-end.

    + +

    The clang project is an effort to build + a set of new 'llvm native' front-end technologies for the LLVM optimizer + and code generator. Currently, its C and Objective-C support is maturing + nicely, and it has advanced source-to-source analysis and transformation + capabilities. If you are interested in building source-level tools for C and + Objective-C (and eventually C++), you should take a look. However, note that + clang is not an official part of the LLVM 2.2 release. If you are interested in + this project, please see its web site.

    + +
    + + +
    + Major New Features +
    + +
    + +

    LLVM 2.2 includes several major new capabilities:

    + +
      +
    • A research team led by Scott Michel in the Computer Systems Research + Department at The Aerospace Corporation contributed the CellSPU backend, which + generates code for the vector coprocessors on the Sony/Toshiba/IBM Cell BE + processor. llvm-gcc 4.2 supports CellSPU as a 'configure' target and progress + is being made so that libgcc.a compiles cleanly. Notable pieces still in + development include full 64-bit integer and full double precision floating + point support.
      • + +
    • Anton and Duncan significantly improved llvm-gcc 4.2 support for the GCC Ada + (GNAT) and Fortran (gfortran) front-ends. These front-ends should still be considered + experimental however: see the list of known problems. + The release binaries do not contain either front-end: they need to be built from + source (the Ada front-end only builds on x86-32 linux).
      • + +
    • Dale contributed full support for long double on x86/x86-64 (where it is 80 + bits) and on Darwin PPC/PPC64 (where it is 128 bits). In previous LLVM + releases, llvm-gcc silently mapped long double to double.
      • + +
    • Gordon Henriksen rewrote most of the Accurate Garbage Collection code in the code generator, making the + generated code more efficient and adding support for the OCaml garbage collector + metadata format.
      • + +
    • Christopher Lamb contributed support for multiple address spaces in LLVM + IR. This is useful for supporting targets that have 'near' vs 'far' pointers, + 'RAM' vs 'ROM' pointers, or that have non-local memory that can be accessed with + special instructions.
      • + +
    • LLVM now includes a new set of detailed tutorials, which explain how to implement a + language with LLVM and shows how to use several important APIs.
      • + +
    + +
    + + +
    + LLVM Core Improvements +
    + +
    +

    New features include: +

    + +
      +
    • Gordon contributed support for C and OCaml Bindings for the basic LLVM IR + construction routines as well as several other auxiliary APIs.
      • + +
    • Anton added readnone/readonly attributes for modeling function side effects. + Duncan hooked up GCC's pure/const attributes to them and enhanced mod/ref + analysis to use them.
      • + +
    • Devang added LLVMFoldingBuilder, a version of LLVMBuilder that implicitly + simplifies the code as it is constructed.
      • + +
    • Ted Kremenek added a framework for generic object serialization to bitcode + files. This support is only used by clang right now for ASTs but is extensible + and could be used for serializing arbitrary other data into bitcode files.
      • + +
    • Duncan improved TargetData to distinguish between the size/alignment of a + type in a register, in memory according to the platform ABI, and in memory when + we have a choice.
      • + +
    • Reid moved parameter attributes off of FunctionType and onto functions + and calls. This makes it much easier to add attributes to a function in a + transformation pass.
      • + +
    • Dan Gohman added support for vector sin, cos, and pow intrinsics.
      • + +
    + +
    + + +
    + Code Generator Improvements +
    + +
    + +

    We put a significant amount of work into the code generator infrastructure, + which allows us to implement more aggressive algorithms and make it run + faster:

    + +
      + +
    • Owen refactored the existing LLVM dominator and loop information code to + allow it work on the machine code representation. He contributed support for + dominator and loop information on machine code and merged the code for forward + and backward dominator computation.
      • + +
    • Dan added support for emitting debug information with .file and .loc + directives on platforms that support it, instead of emitting large tables in the .s + file.
      • + +
    • Evan extended the DAG scheduler to model physical register dependencies + explicitly and have the BURR scheduler pick a correct schedule based on the + dependencies. This reduces our use of the 'flag' operand hack.
      • + +
    • Evan added initial support for register coalescing of subregister + references.
      • + +
    • Rafael Espindola implemented initial support for a new 'byval' attribute, + which allows more efficient by-value argument passing in the LLVM IR. Evan + finished support for it and enabled it in the X86 (32- and 64-bit) and C + backends.
      • + +
    • The LLVM TargetInstrInfo class can now answer queries about the mod/ref and + side-effect behavior of MachineInstr's. This information is inferred + automatically by TableGen from .td files for all instructions with + patterns.
      • + +
    • Evan implemented simple live interval splitting on basic block boundaries. + This allows the register allocator to be more successful at keeping values in + registers in some parts of a value's live range, even if they need to be spilled + in some other block.
      • + +
    • The new MachineRegisterInfo.h class provides support for efficiently + iterating over all defs/uses of a register, and this information is + automatically kept up-to-date. This support is similar to the use_iterator in + the LLVM IR level.
      • + +
    • The MachineInstr, MachineOperand and TargetInstrDesc classes are simpler, + more consistent, and better documented.
      • +
    + +
    + + +
    + Optimizer Improvements +
    + +
    + +

    In addition to a huge array of bug fixes and minor performance tweaks, the + LLVM 2.2 optimizers support a few major enhancements:

    + +
      + +
    • Daniel Berlin and Curtis Dunham rewrote Andersen's alias analysis to be + several orders of magnitude faster, and implemented Offline Variable + Substitution and Lazy Cycle Detection. Note that Andersen's is not enabled in + llvm-gcc by default, but can be accessed through 'opt'.
      • + +
    • Dan Gohman contributed several enhancements to Loop Strength Reduction (LSR) + to make it more aggressive with SSE intrinsics and when induction variables are + used by non-memory instructions.
      • + +
    • Evan added support for simple exit value substitution to LSR.
      • + +
    • Evan enhanced LSR to support induction variable reuse when the induction + variables have different widths.
      • + +
    + +
    + + + +
    + Target Specific Improvements +
    + +
    +

    New target-specific features include: +

    + +
      +
    • Evan contributed support to the X86 backend to model the mod/ref behavior + of the EFLAGS register explicitly in all instructions. This gives more freedom + to the scheduler, and is a more explicit way to model the instructions.
      • +
    • Dale contributed support for exception handling on Darwin/PPC and he and + Anton got x86-64 working.
      • +
    • Evan turned on if-conversion by default for ARM, allowing LLVM to take + advantage of its predication features.
      • +
    • Bruno added PIC support to the MIPS backend, fixed many bugs and improved + support for architecture variants.
      • +
    • Arnold Schwaighofer added initial support for X86 tail calls.
      • +
    • Evan contributed several enhancements to Darwin/x86 debug information.
      • +
    • Duncan added x86-64 support for trampolines (pointers to nested functions).
      • +
    + +
    + + +
    + Other Improvements +
    + +
    +

    New features include: +

    + +
      +
    • Gordon expanded and updated the LLVM Analysis and + Transformation Passes reference to include descriptions for each pass.
      • + +
    • We rewrote the lexer and parser used by TableGen to make them simpler + and cleaner. This gives tblgen support for 'caret diagnostics'. The .ll file + lexer was also rewritten to support caret diagnostics but doesn't use this + support yet.
      • + +
    • Dale has been grinding through the GCC testsuite, and marked many + LLVM-incompatible tests as not-to-be-run (for example, if they are grepping + through some GCC dump file that LLVM doesn't produce), he also found and fixed + many LLVM bugs exposed by the testsuite.
      • +
    + +
    + + +
    + Portability and Supported Platforms +
    + + +
    + +

    LLVM is known to work on the following platforms:

    + +
      +
    • Intel and AMD machines running Red Hat Linux, Fedora Core and FreeBSD + (and probably other unix-like systems).
      • +
    • PowerPC and X86-based Mac OS X systems, running 10.3 and above in 32-bit and + 64-bit modes.
      • +
    • Intel and AMD machines running on Win32 using MinGW libraries (native).
      • +
    • Intel and AMD machines running on Win32 with the Cygwin libraries (limited + support is available for native builds with Visual C++).
      • +
    • Sun UltraSPARC workstations running Solaris 8.
      • +
    • Alpha-based machines running Debian GNU/Linux.
      • +
    • Itanium-based machines running Linux and HP-UX.
      • +
    + +

    The core LLVM infrastructure uses + GNU autoconf to adapt itself + to the machine and operating system on which it is built. However, minor + porting may be required to get LLVM to work on new platforms. We welcome your + portability patches and reports of successful builds or error messages.

    + +
    + + +
    + Known Problems +
    + + +
    + +

    This section contains all known problems with the LLVM system, listed by + component. As new problems are discovered, they will be added to these + sections. If you run into a problem, please check the LLVM bug database and submit a bug if + there isn't already one.

    + +
    + + +
    + Experimental features included with this release +
    + +
    + +

    The following components of this LLVM release are either untested, known to + be broken or unreliable, or are in early development. These components should + not be relied on, and bugs should not be filed against them, but they may be + useful to some people. In particular, if you would like to work on one of these + components, please contact us on the LLVMdev list.

    + +
      +
    • The -cee pass is known to be buggy and will be removed in + LLVM 2.3.
      • +
    • The MSIL, IA64, Alpha, and MIPS backends are experimental.
      • +
    • The LLC "-filetype=asm" (the default) is the only supported + value for this option.
      • +
    • The llvmc tool is not supported.
      • +
    + +
    + + +
    + Known problems with the X86 back-end +
    + +
    + +
      +
    • The X86 backend does not yet support inline + assembly that uses the X86 floating point stack.
      • +
    • The X86 backend occasionally has alignment + problems on operating systems that don't require 16-byte stack alignment + (including most non-darwin OS's like linux).
      • +
    • The X86 backend generates inefficient floating point code when configured to + generate code for systems that don't have SSE2.
      • +
    + +
    + + +
    + Known problems with the PowerPC back-end +
    + +
    + +
      +
    • The Linux PPC32/ABI support needs testing for the interpreter and static + compilation, and lacks support for debug information.
      • +
    + +
    + + +
    + Known problems with the ARM back-end +
    + +
    + +
      +
    • Thumb mode works only on ARMv6 or higher processors. On sub-ARMv6 + processors, thumb programs can crash or produce wrong + results (PR1388).
      • +
    • Compilation for ARM Linux OABI (old ABI) is supported, but not fully tested. +
      • +
    • There is a bug in QEMU-ARM (<= 0.9.0) which causes it to incorrectly execute + programs compiled with LLVM. Please use more recent versions of QEMU.
      • +
    + +
    + + +
    + Known problems with the SPARC back-end +
    + +
    + +
      +
    • The SPARC backend only supports the 32-bit SPARC ABI (-m32), it does not + support the 64-bit SPARC ABI (-m64).
      • +
    + +
    + + +
    + Known problems with the Alpha back-end +
    + +
    + +
      + +
    • On 21164s, some rare FP arithmetic sequences which may trap do not have the + appropriate nops inserted to ensure restartability.
      • + +
    +
    + + +
    + Known problems with the IA64 back-end +
    + +
    + +
      + +
    • C++ programs are likely to fail on IA64, as calls to setjmp are + made where the argument is not 16-byte aligned, as required on IA64. (Strictly + speaking this is not a bug in the IA64 back-end; it will also be encountered + when building C++ programs using the C back-end.)
      • + +
    • The C++ front-end does not use IA64 + ABI compliant layout of v-tables. In particular, it just stores function + pointers instead of function descriptors in the vtable. This bug prevents + mixing C++ code compiled with LLVM with C++ objects compiled by other C++ + compilers.
      • + +
    • There are a few ABI violations which will lead to problems when mixing LLVM + output with code built with other compilers, particularly for floating-point + programs.
      • + +
    • Defining vararg functions is not supported (but calling them is ok).
      • + +
    • The Itanium backend has bitrotted somewhat.
      • +
    + +
    + + +
    + Known problems with the C back-end +
    + +
    + + + +
    + + + +
    + Known problems with the C front-end +
    + + +
    + Known problems with the Ada front-end +
    + +
    + The llvm-gcc 4.2 Ada compiler works fairly well, however this is not a mature + technology and problems should be expected. +
      +
    • The Ada front-end currently only builds on x86-32. This is mainly due + to lack of trampoline support (pointers to nested functions) on other platforms, + however it also fails to build on x86-64 + which does support trampolines.
      • +
    • The Ada front-end fails to bootstrap. + Workaround: configure with --disable-bootstrap.
      • +
    • The c380004 and c393010 ACATS tests + fail (c380004 also fails with gcc-4.2 mainline).
      • +
    • Many gcc specific Ada tests continue to crash the compiler.
      • +
    • The -E binder option (exception backtraces) + does not work and will result in programs + crashing if an exception is raised. Workaround: do not use -E.
      • +
    • Only discrete types are allowed to start + or finish at a non-byte offset in a record. Workaround: do not pack records + or use representation clauses that result in a field of a non-discrete type + starting or finishing in the middle of a byte.
      • +
    • The lli interpreter considers 'main' + as generated by the Ada binder to be invalid. + Workaround: hand edit the file to use pointers for argv and envp rather than + integers.
      • +
    • The -fstack-check option is ignored.
      • +
    +
    + + +
    + Known problems with the Fortran front-end +
    + +
    + + +
    + + +
    Bugs
    + +
    + +

    llvm-gcc does not currently support Link-Time + Optimization on most platforms "out-of-the-box". Please inquire on the + llvmdev mailing list if you are interested.

    + +
    + + +
    + Notes +
    + +
    +
      + +

    • llvm-gcc does not support __builtin_apply yet. + See Constructing Calls: Dispatching a call to another function.

      +
      • + +

    • llvm-gcc partially supports these GCC extensions:

      +
        +
      1. Nested Functions: + + As in Algol and Pascal, lexical scoping of functions. + Nested functions are supported, but llvm-gcc does not support + taking the address of a nested function (except on X86 targets) + or non-local gotos.
        2. + +
      2. Function Attributes: + + Declaring that functions have no side effects or that they can never + return.
        + + Supported: alias, always_inline, cdecl, + const, constructor, destructor, + deprecated, fastcall, format, + format_arg, non_null, noinline, + noreturn, nothrow, pure, regparm + section, stdcall, unused, used, + visibility, warn_unused_result, weak
        + + Ignored: malloc, + no_instrument_function
        3. +
      +
      • + +

    • llvm-gcc supports the vast majority of GCC extensions, including:

      + +
        +
      1. Pragmas: Pragmas accepted by GCC.
        2. +
      2. Local Labels: Labels local to a block.
        3. +
      3. Other Builtins: + Other built-in functions.
        4. +
      4. Variable Attributes: + Specifying attributes of variables.
        5. +
      5. Type Attributes: Specifying attributes of types.
        6. +
      6. Thread-Local: Per-thread variables.
        7. +
      7. Variable Length: + Arrays whose length is computed at run time.
        8. +
      8. Labels as Values: Getting pointers to labels and computed gotos.
        9. +
      9. Statement Exprs: Putting statements and declarations inside expressions.
        10. +
      10. Typeof: typeof: referring to the type of an expression.
        11. +
      11. Lvalues: Using ?:, "," and casts in lvalues.
        12. +
      12. Conditionals: Omitting the middle operand of a ?: expression.
        13. +
      13. Long Long: Double-word integers.
        14. +
      14. Complex: Data types for complex numbers.
        15. +
      15. Hex Floats:Hexadecimal floating-point constants.
        16. +
      16. Zero Length: Zero-length arrays.
        17. +
      17. Empty Structures: Structures with no members.
        18. +
      18. Variadic Macros: Macros with a variable number of arguments.
        19. +
      19. Escaped Newlines: Slightly looser rules for escaped newlines.
        20. +
      20. Extended Asm: Assembler instructions with C expressions as operands.
        21. +
      21. Constraints: Constraints for asm operands.
        22. +
      22. Asm Labels: Specifying the assembler name to use for a C symbol.
        23. +
      23. Explicit Reg Vars: Defining variables residing in specified registers.
        24. +
      24. Vector Extensions: Using vector instructions through built-in functions.
        25. +
      25. Target Builtins: Built-in functions specific to particular targets.
        26. +
      26. Subscripting: Any array can be subscripted, even if not an lvalue.
        27. +
      27. Pointer Arith: Arithmetic on void-pointers and function pointers.
        28. +
      28. Initializers: Non-constant initializers.
        29. +
      29. Compound Literals: Compound literals give structures, unions, + or arrays as values.
        30. +
      30. Designated Inits: Labeling elements of initializers.
        31. +
      31. Cast to Union: Casting to union type from any member of the union.
        32. +
      32. Case Ranges: `case 1 ... 9' and such.
        33. +
      33. Mixed Declarations: Mixing declarations and code.
        34. +
      34. Function Prototypes: Prototype declarations and old-style definitions.
        35. +
      35. C++ Comments: C++ comments are recognized.
        36. +
      36. Dollar Signs: Dollar sign is allowed in identifiers.
        37. +
      37. Character Escapes: \e stands for the character <ESC>.
        38. +
      38. Alignment: Inquiring about the alignment of a type or variable.
        39. +
      39. Inline: Defining inline functions (as fast as macros).
        40. +
      40. Alternate Keywords:__const__, __asm__, etc., for header files.
        41. +
      41. Incomplete Enums: enum foo;, with details to follow.
        42. +
      42. Function Names: Printable strings which are the name of the current function.
        43. +
      43. Return Address: Getting the return or frame address of a function.
        44. +
      44. Unnamed Fields: Unnamed struct/union fields within structs/unions.
        45. +
      45. Attribute Syntax: Formal syntax for attributes.
        46. +
      • + +
    + +

    If you run into GCC extensions which have not been included in any of these + lists, please let us know (also including whether or not they work).

    + +
    + + +
    + Known problems with the C++ front-end +
    + +
    + +

    The C++ front-end is considered to be fully + tested and works for a number of non-trivial programs, including LLVM + itself, Qt, Mozilla, etc.

    + +
      +
    • Exception handling only works well on the X86 and PowerPC targets. + It works well for x86-64 darwin but not x86-64 linux.
      • +
    + +
    + + + + +
    + Additional Information +
    + + +
    + +

    A wide variety of additional information is available on the LLVM web page, in particular in the documentation section. The web page also + contains versions of the API documentation which is up-to-date with the + Subversion version of the source code. + You can access versions of these documents specific to this release by going + into the "llvm/doc/" directory in the LLVM tree.

    + +

    If you have any questions or comments about LLVM, please feel free to contact + us via the mailing + lists.

    + +
    + + + +
    +
    + Valid CSS! + Valid HTML 4.01! + + LLVM Compiler Infrastructure
    + Last modified: $Date: 2008/02/12 06:05:03 $ +
    + + + Index: llvm-www/releases/2.2/docs/SourceLevelDebugging.html diff -c /dev/null llvm-www/releases/2.2/docs/SourceLevelDebugging.html:1.1 *** /dev/null Tue Feb 12 00:07:05 2008 --- llvm-www/releases/2.2/docs/SourceLevelDebugging.html Tue Feb 12 00:05:03 2008 *************** *** 0 **** --- 1,1782 ---- + + + + Source Level Debugging with LLVM + + + + +
    Source Level Debugging with LLVM
    + + + + + +
    + + + A leafy and green bug eater +
    + +
    +

    Written by Chris Lattner + and Jim Laskey

    +
    + + + +
    Introduction
    + + +
    + +

    This document is the central repository for all information pertaining to + debug information in LLVM. It describes the actual format + that the LLVM debug information takes, which is useful for those interested + in creating front-ends or dealing directly with the information. Further, this + document provides specifc examples of what debug information for C/C++.

    + +
    + + +
    + Philosophy behind LLVM debugging information +
    + +
    + +

    The idea of the LLVM debugging information is to capture how the important + pieces of the source-language's Abstract Syntax Tree map onto LLVM code. + Several design aspects have shaped the solution that appears here. The + important ones are:

    + +
      +
    • Debugging information should have very little impact on the rest of the + compiler. No transformations, analyses, or code generators should need to be + modified because of debugging information.
      • + +
    • LLVM optimizations should interact in well-defined and + easily described ways with the debugging information.
      • + +
    • Because LLVM is designed to support arbitrary programming languages, + LLVM-to-LLVM tools should not need to know anything about the semantics of the + source-level-language.
      • + +
    • Source-level languages are often widely different from one another. + LLVM should not put any restrictions of the flavor of the source-language, and + the debugging information should work with any language.
      • + +
    • With code generator support, it should be possible to use an LLVM compiler + to compile a program to native machine code and standard debugging formats. + This allows compatibility with traditional machine-code level debuggers, like + GDB or DBX.
      • + +
    + +

    The approach used by the LLVM implementation is to use a small set of intrinsic functions to define a mapping + between LLVM program objects and the source-level objects. The description of + the source-level program is maintained in LLVM global variables in an implementation-defined format (the C/C++ front-end + currently uses working draft 7 of the Dwarf 3 standard).

    + +

    When a program is being debugged, a debugger interacts with the user and + turns the stored debug information into source-language specific information. + As such, a debugger must be aware of the source-language, and is thus tied to + a specific language of family of languages.

    + +
    + + +
    + Debug information consumers +
    + +
    +

    The role of debug information is to provide meta information normally + stripped away during the compilation process. This meta information provides an + llvm user a relationship between generated code and the original program source + code.

    + +

    Currently, debug information is consumed by the DwarfWriter to produce dwarf + information used by the gdb debugger. Other targets could use the same + information to produce stabs or other debug forms.

    + +

    It would also be reasonable to use debug information to feed profiling tools + for analysis of generated code, or, tools for reconstructing the original source + from generated code.

    + +

    TODO - expound a bit more.

    + +
    + + +
    + Debugging optimized code +
    + +
    + +

    An extremely high priority of LLVM debugging information is to make it + interact well with optimizations and analysis. In particular, the LLVM debug + information provides the following guarantees:

    + +
      + +
    • LLVM debug information always provides information to accurately read the + source-level state of the program, regardless of which LLVM optimizations + have been run, and without any modification to the optimizations themselves. + However, some optimizations may impact the ability to modify the current state + of the program with a debugger, such as setting program variables, or calling + function that have been deleted.
      • + +
    • LLVM optimizations gracefully interact with debugging information. If they + are not aware of debug information, they are automatically disabled as necessary + in the cases that would invalidate the debug info. This retains the LLVM + features making it easy to write new transformations.
      • + +
    • As desired, LLVM optimizations can be upgraded to be aware of the LLVM + debugging information, allowing them to update the debugging information as they + perform aggressive optimizations. This means that, with effort, the LLVM + optimizers could optimize debug code just as well as non-debug code.
      • + +
    • LLVM debug information does not prevent many important optimizations from + happening (for example inlining, basic block reordering/merging/cleanup, tail + duplication, etc), further reducing the amount of the compiler that eventually + is "aware" of debugging information.
      • + +
    • LLVM debug information is automatically optimized along with the rest of the + program, using existing facilities. For example, duplicate information is + automatically merged by the linker, and unused information is automatically + removed.
      • + +
    + +

    Basically, the debug information allows you to compile a program with + "-O0 -g" and get full debug information, allowing you to arbitrarily + modify the program as it executes from a debugger. Compiling a program with + "-O3 -g" gives you full debug information that is always available and + accurate for reading (e.g., you get accurate stack traces despite tail call + elimination and inlining), but you might lose the ability to modify the program + and call functions where were optimized out of the program, or inlined away + completely.

    + +
    + + +
    + Debugging information format +
    + + +
    + +

    LLVM debugging information has been carefully designed to make it possible + for the optimizer to optimize the program and debugging information without + necessarily having to know anything about debugging information. In particular, + the global constant merging pass automatically eliminates duplicated debugging + information (often caused by header files), the global dead code elimination + pass automatically deletes debugging information for a function if it decides to + delete the function, and the linker eliminates debug information when it merges + linkonce functions.

    + +

    To do this, most of the debugging information (descriptors for types, + variables, functions, source files, etc) is inserted by the language front-end + in the form of LLVM global variables. These LLVM global variables are no + different from any other global variables, except that they have a web of LLVM + intrinsic functions that point to them. If the last references to a particular + piece of debugging information are deleted (for example, by the + -globaldce pass), the extraneous debug information will automatically + become dead and be removed by the optimizer.

    + +

    Debug information is designed to be agnostic about the target debugger and + debugging information representation (e.g. DWARF/Stabs/etc). It uses a generic + machine debug information pass to decode the information that represents + variables, types, functions, namespaces, etc: this allows for arbitrary + source-language semantics and type-systems to be used, as long as there is a + module written for the target debugger to interpret the information. In + addition, debug global variables are declared in the "llvm.metadata" + section. All values declared in this section are stripped away after target + debug information is constructed and before the program object is emitted.

    + +

    To provide basic functionality, the LLVM debugger does have to make some + assumptions about the source-level language being debugged, though it keeps + these to a minimum. The only common features that the LLVM debugger assumes + exist are source files, and program objects. These abstract objects are + used by a debugger to form stack traces, show information about local + variables, etc.

    + +

    This section of the documentation first describes the representation aspects + common to any source-language. The next section + describes the data layout conventions used by the C and C++ front-ends.

    + +
    + + +
    + Debug information descriptors +
    + +
    +

    In consideration of the complexity and volume of debug information, LLVM + provides a specification for well formed debug global variables. The constant + value of each of these globals is one of a limited set of structures, known as + debug descriptors.

    + +

    Consumers of LLVM debug information expect the descriptors for program + objects to start in a canonical format, but the descriptors can include + additional information appended at the end that is source-language specific. All + LLVM debugging information is versioned, allowing backwards compatibility in the + case that the core structures need to change in some way. Also, all debugging + information objects start with a tag to indicate what type of object it is. The + source-language is allowed to define its own objects, by using unreserved tag + numbers. We recommend using with tags in the range 0x1000 thru 0x2000 (there is + a defined enum DW_TAG_user_base = 0x1000.)

    + +

    The fields of debug descriptors used internally by LLVM (MachineModuleInfo) + are restricted to only the simple data types int, uint, + bool, float, double, sbyte* and { }* + . References to arbitrary values are handled using a { }* and a + cast to { }* expression; typically references to other field + descriptors, arrays of descriptors or global variables.

    + + 
    +   %llvm.dbg.object.type = type {
+     uint,   ;; A tag
+     ...
+   }
+
    + +

    The first field of a descriptor is always an + uint containing a tag value identifying the content of the descriptor. + The remaining fields are specific to the descriptor. The values of tags are + loosely bound to the tag values of Dwarf information entries. However, that + does not restrict the use of the information supplied to Dwarf targets. To + facilitate versioning of debug information, the tag is augmented with the + current debug version (LLVMDebugVersion = 4 << 16 or 0x40000 or 262144.)

    + +

    The details of the various descriptors follow.

    + +
    + + +
    + Anchor descriptors +
    + +
    + + 
    +   %llvm.dbg.anchor.type = type {
+     uint,   ;; Tag = 0 + LLVMDebugVersion
+     uint    ;; Tag of descriptors grouped by the anchor
+   }
+
    + +

    One important aspect of the LLVM debug representation is that it allows the + LLVM debugger to efficiently index all of the global objects without having the + scan the program. To do this, all of the global objects use "anchor" + descriptors with designated names. All of the global objects of a particular + type (e.g., compile units) contain a pointer to the anchor. This pointer allows + a debugger to use def-use chains to find all global objects of that type.

    + +

    The following names are recognized as anchors by LLVM:

    + + 
    +   %llvm.dbg.compile_units       = linkonce constant %llvm.dbg.anchor.type  { uint 0, uint 17 } ;; DW_TAG_compile_unit
+   %llvm.dbg.global_variables    = linkonce constant %llvm.dbg.anchor.type  { uint 0, uint 52 } ;; DW_TAG_variable
+   %llvm.dbg.subprograms         = linkonce constant %llvm.dbg.anchor.type  { uint 0, uint 46 } ;; DW_TAG_subprogram
+
    + +

    Using anchors in this way (where the compile unit descriptor points to the + anchors, as opposed to having a list of compile unit descriptors) allows for the + standard dead global elimination and merging passes to automatically remove + unused debugging information. If the globals were kept track of through lists, + there would always be an object pointing to the descriptors, thus would never be + deleted.

    + +
    + + +
    + Compile unit descriptors +
    + +
    + + 
    +   %llvm.dbg.compile_unit.type = type {
+     uint,   ;; Tag = 17 + LLVMDebugVersion (DW_TAG_compile_unit)
+     {  }*,  ;; Compile unit anchor = cast = (%llvm.dbg.anchor.type* %llvm.dbg.compile_units to {  }*)
+     uint,   ;; Dwarf language identifier (ex. DW_LANG_C89) 
+     sbyte*, ;; Source file name
+     sbyte*, ;; Source file directory (includes trailing slash)
+     sbyte*  ;; Producer (ex. "4.0.1 LLVM (LLVM research group)")
+   }
+
    + +

    These descriptors contain a source language ID for the file (we use the Dwarf + 3.0 ID numbers, such as DW_LANG_C89, DW_LANG_C_plus_plus, + DW_LANG_Cobol74, etc), three strings describing the filename, working + directory of the compiler, and an identifier string for the compiler that + produced it.

    + +

    Compile unit descriptors provide the root context for objects declared in a + specific source file. Global variables and top level functions would be defined + using this context. Compile unit descriptors also provide context for source + line correspondence.

    + +
    + + +
    + Global variable descriptors +
    + +
    + + 
    +   %llvm.dbg.global_variable.type = type {
+     uint,   ;; Tag = 52 + LLVMDebugVersion (DW_TAG_variable)
+     {  }*,  ;; Global variable anchor = cast (%llvm.dbg.anchor.type* %llvm.dbg.global_variables to {  }*),  
+     {  }*,  ;; Reference to context descriptor
+     sbyte*, ;; Name
+     sbyte*, ;; Display name (fully qualified C++ name)
+     sbyte*, ;; MIPS linkage name (for C++)
+     {  }*,  ;; Reference to compile unit where defined
+     uint,   ;; Line number where defined
+     {  }*,  ;; Reference to type descriptor
+     bool,   ;; True if the global is local to compile unit (static)
+     bool,   ;; True if the global is defined in the compile unit (not extern)
+     {  }*   ;; Reference to the global variable
+   }
+
    + +

    These descriptors provide debug information about globals variables. The + provide details such as name, type and where the variable is defined.

    + +
    + + +
    + Subprogram descriptors +
    + +
    + + 
    +   %llvm.dbg.subprogram.type = type {
+     uint,   ;; Tag = 46 + LLVMDebugVersion (DW_TAG_subprogram)
+     {  }*,  ;; Subprogram anchor = cast (%llvm.dbg.anchor.type* %llvm.dbg.subprograms to {  }*),  
+     {  }*,  ;; Reference to context descriptor
+     sbyte*, ;; Name
+     sbyte*, ;; Display name (fully qualified C++ name)
+     sbyte*, ;; MIPS linkage name (for C++)
+     {  }*,  ;; Reference to compile unit where defined
+     uint,   ;; Line number where defined
+     {  }*,  ;; Reference to type descriptor
+     bool,   ;; True if the global is local to compile unit (static)
+     bool    ;; True if the global is defined in the compile unit (not extern)
+   }
+
    + +

    These descriptors provide debug information about functions, methods and + subprograms. They provide details such as name, return types and the source + location where the subprogram is defined.

    + +
    + +
    + Block descriptors +
    + +
    + + 
    +   %llvm.dbg.block = type {
+     uint,   ;; Tag = 13 + LLVMDebugVersion (DW_TAG_lexical_block)
+     {  }*   ;; Reference to context descriptor
+   }
+
    + +

    These descriptors provide debug information about nested blocks within a + subprogram. The array of member descriptors is used to define local variables + and deeper nested blocks.

    + +
    + + +
    + Basic type descriptors +
    + +
    + + 
    +   %llvm.dbg.basictype.type = type {
+     uint,   ;; Tag = 36 + LLVMDebugVersion (DW_TAG_base_type)
+     {  }*,  ;; Reference to context (typically a compile unit)
+     sbyte*, ;; Name (may be "" for anonymous types)
+     {  }*,  ;; Reference to compile unit where defined (may be NULL)
+     uint,   ;; Line number where defined (may be 0)
+     uint,   ;; Size in bits
+     uint,   ;; Alignment in bits
+     uint,   ;; Offset in bits
+     uint    ;; Dwarf type encoding
+   }
+
    + +

    These descriptors define primitive types used in the code. Example int, bool + and float. The context provides the scope of the type, which is usually the top + level. Since basic types are not usually user defined the compile unit and line + number can be left as NULL and 0. The size, alignment and offset are expressed + in bits and can be 64 bit values. The alignment is used to round the offset + when embedded in a composite type + (example to keep float doubles on 64 bit boundaries.) The offset is the bit + offset if embedded in a composite + type.

    + +

    The type encoding provides the details of the type. The values are typically + one of the following;

    + + 
    +   DW_ATE_address = 1
+   DW_ATE_boolean = 2
+   DW_ATE_float = 4
+   DW_ATE_signed = 5
+   DW_ATE_signed_char = 6
+   DW_ATE_unsigned = 7
+   DW_ATE_unsigned_char = 8
+
    + +
    + + +
    + Derived type descriptors +
    + +
    + + 
    +   %llvm.dbg.derivedtype.type = type {
+     uint,   ;; Tag (see below)
+     {  }*,  ;; Reference to context
+     sbyte*, ;; Name (may be "" for anonymous types)
+     {  }*,  ;; Reference to compile unit where defined (may be NULL)
+     uint,   ;; Line number where defined (may be 0)
+     uint,   ;; Size in bits
+     uint,   ;; Alignment in bits
+     uint,   ;; Offset in bits
+     {  }*   ;; Reference to type derived from
+   }
+
    + +

    These descriptors are used to define types derived from other types. The + value of the tag varies depending on the meaning. The following are possible + tag values;

    + + 
    +   DW_TAG_formal_parameter = 5
+   DW_TAG_member = 13
+   DW_TAG_pointer_type = 15
+   DW_TAG_reference_type = 16
+   DW_TAG_typedef = 22
+   DW_TAG_const_type = 38
+   DW_TAG_volatile_type = 53
+   DW_TAG_restrict_type = 55
+
    + +

    DW_TAG_member is used to define a member of a composite type or subprogram. The type of the member is the derived type. DW_TAG_formal_parameter + is used to define a member which is a formal argument of a subprogram.

    + +

    DW_TAG_typedef is used to + provide a name for the derived type.

    + +

    DW_TAG_pointer_type, + DW_TAG_reference_type, DW_TAG_const_type, + DW_TAG_volatile_type and DW_TAG_restrict_type are used to + qualify the derived type.

    + +

    Derived type location can be determined + from the compile unit and line number. The size, alignment and offset are + expressed in bits and can be 64 bit values. The alignment is used to round the + offset when embedded in a composite type + (example to keep float doubles on 64 bit boundaries.) The offset is the bit + offset if embedded in a composite + type.

    + +

    Note that the void * type is expressed as a + llvm.dbg.derivedtype.type with tag of DW_TAG_pointer_type and + NULL derived type.

    + +
    + + +
    + Composite type descriptors +
    + +
    + + 
    +   %llvm.dbg.compositetype.type = type {
+     uint,   ;; Tag (see below)
+     {  }*,  ;; Reference to context
+     sbyte*, ;; Name (may be "" for anonymous types)
+     {  }*,  ;; Reference to compile unit where defined (may be NULL)
+     uint,   ;; Line number where defined (may be 0)
+     uint,   ;; Size in bits
+     uint,   ;; Alignment in bits
+     uint,   ;; Offset in bits
+     {  }*   ;; Reference to array of member descriptors
+   }
+
    + +

    These descriptors are used to define types that are composed of 0 or more + elements. The value of the tag varies depending on the meaning. The following + are possible tag values;

    + + 
    +   DW_TAG_array_type = 1
+   DW_TAG_enumeration_type = 4
+   DW_TAG_structure_type = 19
+   DW_TAG_union_type = 23
+   DW_TAG_vector_type = 259
+   DW_TAG_subroutine_type = 46
+   DW_TAG_inheritance = 26
+
    + +

    The vector flag indicates that an array type is a native packed vector.

    + +

    The members of array types (tag = DW_TAG_array_type) or vector types + (tag = DW_TAG_vector_type) are subrange + descriptors, each representing the range of subscripts at that level of + indexing.

    + +

    The members of enumeration types (tag = DW_TAG_enumeration_type) are + enumerator descriptors, each representing the + definition of enumeration value + for the set.

    + +

    The members of structure (tag = DW_TAG_structure_type) or union (tag + = DW_TAG_union_type) types are any one of the basic, derived + or composite type descriptors, each + representing a field member of the structure or union.

    + +

    For C++ classes (tag = DW_TAG_structure_type), member descriptors + provide information about base classes, static members and member functions. If + a member is a derived type descriptor and has + a tag of DW_TAG_inheritance, then the type represents a base class. If + the member of is a global variable + descriptor then it represents a static member. And, if the member is a subprogram descriptor then it represents a member + function. For static members and member functions, getName() returns + the members link or the C++ mangled name. getDisplayName() the + simplied version of the name.

    + +

    The first member of subroutine (tag = DW_TAG_subroutine_type) + type elements is the return type for the subroutine. The remaining + elements are the formal arguments to the subroutine.

    + +

    Composite type location can be + determined from the compile unit and line number. The size, alignment and + offset are expressed in bits and can be 64 bit values. The alignment is used to + round the offset when embedded in a composite + type (as an example, to keep float doubles on 64 bit boundaries.) The offset + is the bit offset if embedded in a composite + type.

    + +
    + + +
    + Subrange descriptors +
    + +
    + + 
    +   %llvm.dbg.subrange.type = type {
+     uint,   ;; Tag = 33 + LLVMDebugVersion (DW_TAG_subrange_type)
+     uint,   ;; Low value
+     uint    ;; High value
+   }
+
    + +

    These descriptors are used to define ranges of array subscripts for an array + composite type. The low value defines the + lower bounds typically zero for C/C++. The high value is the upper bounds. + Values are 64 bit. High - low + 1 is the size of the array. If + low == high the array will be unbounded.

    + +
    + + +
    + Enumerator descriptors +
    + +
    + + 
    +   %llvm.dbg.enumerator.type = type {
+     uint,   ;; Tag = 40 + LLVMDebugVersion (DW_TAG_enumerator)
+     sbyte*, ;; Name
+     uint    ;; Value
+   }
+
    + +

    These descriptors are used to define members of an enumeration composite type, it associates the name to the + value.

    + +
    + + +
    + Local variables +
    + +
    + 
    +   %llvm.dbg.variable.type = type {
+     uint,    ;; Tag (see below)
+     {  }*,   ;; Context
+     sbyte*,  ;; Name
+     {  }*,   ;; Reference to compile unit where defined
+     uint,    ;; Line number where defined
+     {  }*    ;; Type descriptor
+   }
+
    + +

    These descriptors are used to define variables local to a sub program. The + value of the tag depends on the usage of the variable;

    + + 
    +   DW_TAG_auto_variable = 256
+   DW_TAG_arg_variable = 257
+   DW_TAG_return_variable = 258
+
    + +

    An auto variable is any variable declared in the body of the function. An + argument variable is any variable that appears as a formal argument to the + function. A return variable is used to track the result of a function and has + no source correspondent.

    + +

    The context is either the subprogram or block where the variable is defined. + Name the source variable name. Compile unit and line indicate where the + variable was defined. Type descriptor defines the declared type of the + variable.

    + +
    + + +
    + Debugger intrinsic functions +
    + +
    + +

    LLVM uses several intrinsic functions (name prefixed with "llvm.dbg") to + provide debug information at various points in generated code.

    + +
    + + +
    + llvm.dbg.stoppoint +
    + +
    + 
    +   void %llvm.dbg.stoppoint( uint, uint, { }* )
+
    + +

    This intrinsic is used to provide correspondence between the source file and + the generated code. The first argument is the line number (base 1), second + argument is the column number (0 if unknown) and the third argument the source + %llvm.dbg.compile_unit* cast to a + { }*. Code following a call to this intrinsic will have been defined + in close proximity of the line, column and file. This information holds until + the next call to %lvm.dbg.stoppoint.

    + +
    + + +
    + llvm.dbg.func.start +
    + +
    + 
    +   void %llvm.dbg.func.start( { }* )
+
    + +

    This intrinsic is used to link the debug information in %llvm.dbg.subprogram to the function. It also + defines the beginning of the function's declarative region (scope.) The + intrinsic should be called early in the function after the all the alloca + instructions. It should be paired off with a closing %llvm.dbg.region.end. The function's + single argument is the %llvm.dbg.subprogram.type.

    + +
    + + +
    + llvm.dbg.region.start +
    + +
    + 
    +   void %llvm.dbg.region.start( { }* )
+
    + +

    This intrinsic is used to define the beginning of a declarative scope (ex. + block) for local language elements. It should be paired off with a closing + %llvm.dbg.region.end. The + function's single argument is the %llvm.dbg.block which is starting.

    + + +
    + + +
    + llvm.dbg.region.end +
    + +
    + 
    +   void %llvm.dbg.region.end( { }* )
+
    + +

    This intrinsic is used to define the end of a declarative scope (ex. block) + for local language elements. It should be paired off with an opening %llvm.dbg.region.start or %llvm.dbg.func.start. The function's + single argument is either the %llvm.dbg.block or the %llvm.dbg.subprogram.type which is + ending.

    + +
    + + +
    + llvm.dbg.declare +
    + +
    + 
    +   void %llvm.dbg.declare( { } *, { }* )
+
    + +

    This intrinsic provides information about a local element (ex. variable.) The + first argument is the alloca for the variable, cast to a { }*. The + second argument is the %llvm.dbg.variable containing the description + of the variable, also cast to a { }*.

    + +
    + + +
    + + Representing stopping points in the source program + +
    + +
    + +

    LLVM debugger "stop points" are a key part of the debugging representation + that allows the LLVM to maintain simple semantics for debugging optimized code. The basic idea is that the + front-end inserts calls to the %llvm.dbg.stoppoint intrinsic + function at every point in the program where a debugger should be able to + inspect the program (these correspond to places a debugger stops when you + "step" through it). The front-end can choose to place these as + fine-grained as it would like (for example, before every subexpression + evaluated), but it is recommended to only put them after every source statement + that includes executable code.

    + +

    Using calls to this intrinsic function to demark legal points for the + debugger to inspect the program automatically disables any optimizations that + could potentially confuse debugging information. To non-debug-information-aware + transformations, these calls simply look like calls to an external function, + which they must assume to do anything (including reading or writing to any part + of reachable memory). On the other hand, it does not impact many optimizations, + such as code motion of non-trapping instructions, nor does it impact + optimization of subexpressions, code duplication transformations, or basic-block + reordering transformations.

    + +
    + + + +
    + Object lifetimes and scoping +
    + +
    +

    In many languages, the local variables in functions can have their lifetime + or scope limited to a subset of a function. In the C family of languages, for + example, variables are only live (readable and writable) within the source block + that they are defined in. In functional languages, values are only readable + after they have been defined. Though this is a very obvious concept, it is also + non-trivial to model in LLVM, because it has no notion of scoping in this sense, + and does not want to be tied to a language's scoping rules.

    + +

    In order to handle this, the LLVM debug format uses the notion of "regions" + of a function, delineated by calls to intrinsic functions. These intrinsic + functions define new regions of the program and indicate when the region + lifetime expires. Consider the following C fragment, for example:

    + + 
    + 1.  void foo() {
+ 2.    int X = ...;
+ 3.    int Y = ...;
+ 4.    {
+ 5.      int Z = ...;
+ 6.      ...
+ 7.    }
+ 8.    ...
+ 9.  }
+
    + +

    Compiled to LLVM, this function would be represented like this:

    + + 
    + void %foo() {
+ entry:
+     %X = alloca int
+     %Y = alloca int
+     %Z = alloca int
+     
+     ...
+     
+     call void %llvm.dbg.func.start( %llvm.dbg.subprogram.type* %llvm.dbg.subprogram )
+     
+     call void %llvm.dbg.stoppoint( uint 2, uint 2, %llvm.dbg.compile_unit* %llvm.dbg.compile_unit )
+     
+     call void %llvm.dbg.declare({}* %X, ...)
+     call void %llvm.dbg.declare({}* %Y, ...)
+     
+     ;; Evaluate expression on line 2, assigning to X.
+     
+     call void %llvm.dbg.stoppoint( uint 3, uint 2, %llvm.dbg.compile_unit* %llvm.dbg.compile_unit )
+     
+     ;; Evaluate expression on line 3, assigning to Y.
+     
+     call void %llvm.region.start()
+     call void %llvm.dbg.stoppoint( uint 5, uint 4, %llvm.dbg.compile_unit* %llvm.dbg.compile_unit )
+     call void %llvm.dbg.declare({}* %X, ...)
+     
+     ;; Evaluate expression on line 5, assigning to Z.
+     
+     call void %llvm.dbg.stoppoint( uint 7, uint 2, %llvm.dbg.compile_unit* %llvm.dbg.compile_unit )
+     call void %llvm.region.end()
+     
+     call void %llvm.dbg.stoppoint( uint 9, uint 2, %llvm.dbg.compile_unit* %llvm.dbg.compile_unit )
+     
+     call void %llvm.region.end()
+     
+     ret void
+ }
+
    + +

    This example illustrates a few important details about the LLVM debugging + information. In particular, it shows how the various intrinsics are applied + together to allow a debugger to analyze the relationship between statements, + variable definitions, and the code used to implement the function.

    + +

    The first intrinsic %llvm.dbg.func.start provides + a link with the subprogram descriptor + containing the details of this function. This call also defines the beginning + of the function region, bounded by the %llvm.region.end at the end of + the function. This region is used to bracket the lifetime of variables declared + within. For a function, this outer region defines a new stack frame whose + lifetime ends when the region is ended.

    + +

    It is possible to define inner regions for short term variables by using the + %llvm.region.start and %llvm.region.end to bound a + region. The inner region in this example would be for the block containing the + declaration of Z.

    + +

    Using regions to represent the boundaries of source-level functions allow + LLVM interprocedural optimizations to arbitrarily modify LLVM functions without + having to worry about breaking mapping information between the LLVM code and the + and source-level program. In particular, the inliner requires no modification + to support inlining with debugging information: there is no explicit correlation + drawn between LLVM functions and their source-level counterparts (note however, + that if the inliner inlines all instances of a non-strong-linkage function into + its caller that it will not be possible for the user to manually invoke the + inlined function from a debugger).

    + +

    Once the function has been defined, the stopping point corresponding to + line #2 (column #2) of the function is encountered. At this point in the + function, no local variables are live. As lines 2 and 3 of the example + are executed, their variable definitions are introduced into the program using + %llvm.dbg.declare, without the + need to specify a new region. These variables do not require new regions to be + introduced because they go out of scope at the same point in the program: line + 9.

    + +

    In contrast, the Z variable goes out of scope at a different time, + on line 7. For this reason, it is defined within the inner region, which kills + the availability of Z before the code for line 8 is executed. In this + way, regions can support arbitrary source-language scoping rules, as long as + they can only be nested (ie, one scope cannot partially overlap with a part of + another scope).

    + +

    It is worth noting that this scoping mechanism is used to control scoping of + all declarations, not just variable declarations. For example, the scope of a + C++ using declaration is controlled with this and could change how name lookup is + performed.

    + +
    + + + + +
    + C/C++ front-end specific debug information +
    + + +
    + +

    The C and C++ front-ends represent information about the program in a format + that is effectively identical to Dwarf 3.0 in terms of + information content. This allows code generators to trivially support native + debuggers by generating standard dwarf information, and contains enough + information for non-dwarf targets to translate it as needed.

    + +

    This section describes the forms used to represent C and C++ programs. Other + languages could pattern themselves after this (which itself is tuned to + representing programs in the same way that Dwarf 3 does), or they could choose + to provide completely different forms if they don't fit into the Dwarf model. + As support for debugging information gets added to the various LLVM + source-language front-ends, the information used should be documented here.

    + +

    The following sections provide examples of various C/C++ constructs and the + debug information that would best describe those constructs.

    + +
    + + +
    + C/C++ source file information +
    + +
    + +

    Given the source files "MySource.cpp" and "MyHeader.h" located in the + directory "/Users/mine/sources", the following code;

    + + 
    + #include "MyHeader.h"
+ 
+ int main(int argc, char *argv[]) {
+   return 0;
+ }
+
    + +

    a C/C++ front-end would generate the following descriptors;

    + + 
    + ...
+ ;;
+ ;; Define types used.  In this case we need one for compile unit anchors and one
+ ;; for compile units.
+ ;;
+ %llvm.dbg.anchor.type = type { uint, uint }
+ %llvm.dbg.compile_unit.type = type { uint, {  }*, uint, uint, sbyte*, sbyte*, sbyte* }
+ ...
+ ;;
+ ;; Define the anchor for compile units.  Note that the second field of the
+ ;; anchor is 17, which is the same as the tag for compile units
+ ;; (17 = DW_TAG_compile_unit.)
+ ;;
+ %llvm.dbg.compile_units = linkonce constant %llvm.dbg.anchor.type { uint 0, uint 17 }, section "llvm.metadata"
+ 
+ ;;
+ ;; Define the compile unit for the source file "/Users/mine/sources/MySource.cpp".
+ ;;
+ %llvm.dbg.compile_unit1 = internal constant %llvm.dbg.compile_unit.type {
+     uint add(uint 17, uint 262144), 
+     {  }* cast (%llvm.dbg.anchor.type* %llvm.dbg.compile_units to {  }*), 
+     uint 1, 
+     uint 1, 
+     sbyte* getelementptr ([13 x sbyte]* %str1, int 0, int 0), 
+     sbyte* getelementptr ([21 x sbyte]* %str2, int 0, int 0), 
+     sbyte* getelementptr ([33 x sbyte]* %str3, int 0, int 0) }, section "llvm.metadata"
+     
+ ;;
+ ;; Define the compile unit for the header file "/Users/mine/sources/MyHeader.h".
+ ;;
+ %llvm.dbg.compile_unit2 = internal constant %llvm.dbg.compile_unit.type {
+     uint add(uint 17, uint 262144), 
+     {  }* cast (%llvm.dbg.anchor.type* %llvm.dbg.compile_units to {  }*), 
+     uint 1, 
+     uint 1, 
+     sbyte* getelementptr ([11 x sbyte]* %str4, int 0, int 0), 
+     sbyte* getelementptr ([21 x sbyte]* %str2, int 0, int 0), 
+     sbyte* getelementptr ([33 x sbyte]* %str3, int 0, int 0) }, section "llvm.metadata"
+ 
+ ;;
+ ;; Define each of the strings used in the compile units.
+ ;;
+ %str1 = internal constant [13 x sbyte] c"MySource.cpp\00", section "llvm.metadata";
+ %str2 = internal constant [21 x sbyte] c"/Users/mine/sources/\00", section "llvm.metadata";
+ %str3 = internal constant [33 x sbyte] c"4.0.1 LLVM (LLVM research group)\00", section "llvm.metadata";
+ %str4 = internal constant [11 x sbyte] c"MyHeader.h\00", section "llvm.metadata";
+ ...
+
    + +
    + + +
    + C/C++ global variable information +
    + +
    + +

    Given an integer global variable declared as follows;

    + + 
    + int MyGlobal = 100;
+
    + +

    a C/C++ front-end would generate the following descriptors;

    + + 
    + ;;
+ ;; Define types used. One for global variable anchors, one for the global
+ ;; variable descriptor, one for the global's basic type and one for the global's
+ ;; compile unit.
+ ;;
+ %llvm.dbg.anchor.type = type { uint, uint }
+ %llvm.dbg.global_variable.type = type { uint, {  }*, {  }*, sbyte*, {  }*, uint, {  }*, bool, bool, {  }*, uint }
+ %llvm.dbg.basictype.type = type { uint, {  }*, sbyte*, {  }*, int, uint, uint, uint, uint }
+ %llvm.dbg.compile_unit.type = ...
+ ...
+ ;;
+ ;; Define the global itself.
+ ;;
+ %MyGlobal = global int 100
+ ...
+ ;;
+ ;; Define the anchor for global variables.  Note that the second field of the
+ ;; anchor is 52, which is the same as the tag for global variables
+ ;; (52 = DW_TAG_variable.)
+ ;;
+ %llvm.dbg.global_variables = linkonce constant %llvm.dbg.anchor.type { uint 0, uint 52 }, section "llvm.metadata"
+ 
+ ;;
+ ;; Define the global variable descriptor.  Note the reference to the global
+ ;; variable anchor and the global variable itself.
+ ;;
+ %llvm.dbg.global_variable = internal constant %llvm.dbg.global_variable.type {
+     uint add(uint 52, uint 262144), 
+     {  }* cast (%llvm.dbg.anchor.type* %llvm.dbg.global_variables to {  }*), 
+     {  }* cast (%llvm.dbg.compile_unit.type* %llvm.dbg.compile_unit to {  }*), 
+     sbyte* getelementptr ([9 x sbyte]* %str1, int 0, int 0), 
+     sbyte* getelementptr ([1 x sbyte]* %str2, int 0, int 0), 
+     {  }* cast (%llvm.dbg.compile_unit.type* %llvm.dbg.compile_unit to {  }*), 
+     uint 1,
+     {  }* cast (%llvm.dbg.basictype.type* %llvm.dbg.basictype to {  }*), 
+     bool false, 
+     bool true, 
+     {  }* cast (int* %MyGlobal to {  }*) }, section "llvm.metadata"
+     
+ ;;
+ ;; Define the basic type of 32 bit signed integer.  Note that since int is an
+ ;; intrinsic type the source file is NULL and line 0.
+ ;;    
+ %llvm.dbg.basictype = internal constant %llvm.dbg.basictype.type {
+     uint add(uint 36, uint 262144), 
+     {  }* cast (%llvm.dbg.compile_unit.type* %llvm.dbg.compile_unit to {  }*), 
+     sbyte* getelementptr ([4 x sbyte]* %str3, int 0, int 0), 
+     {  }* null, 
+     int 0, 
+     uint 32, 
+     uint 32, 
+     uint 0, 
+     uint 5 }, section "llvm.metadata"
+ 
+ ;;
+ ;; Define the names of the global variable and basic type.
+ ;;
+ %str1 = internal constant [9 x sbyte] c"MyGlobal\00", section "llvm.metadata"
+ %str2 = internal constant [1 x sbyte] c"\00", section "llvm.metadata"
+ %str3 = internal constant [4 x sbyte] c"int\00", section "llvm.metadata"
+
    + +
    + + +
    + C/C++ function information +
    + +
    + +

    Given a function declared as follows;

    + + 
    + int main(int argc, char *argv[]) {
+   return 0;
+ }
+
    + +

    a C/C++ front-end would generate the following descriptors;

    + + 
    + ;;
+ ;; Define types used. One for subprogram anchors, one for the subprogram
+ ;; descriptor, one for the global's basic type and one for the subprogram's
+ ;; compile unit.
+ ;;
+ %llvm.dbg.subprogram.type = type { uint, {  }*, {  }*, sbyte*, {  }*, bool, bool }
+ %llvm.dbg.anchor.type = type { uint, uint }
+ %llvm.dbg.compile_unit.type = ...
+ 	
+ ;;
+ ;; Define the anchor for subprograms.  Note that the second field of the
+ ;; anchor is 46, which is the same as the tag for subprograms
+ ;; (46 = DW_TAG_subprogram.)
+ ;;
+ %llvm.dbg.subprograms = linkonce constant %llvm.dbg.anchor.type { uint 0, uint 46 }, section "llvm.metadata"
+ 
+ ;;
+ ;; Define the descriptor for the subprogram.  TODO - more details.
+ ;;
+ %llvm.dbg.subprogram = internal constant %llvm.dbg.subprogram.type {
+     uint add(uint 46, uint 262144), 
+     {  }* cast (%llvm.dbg.anchor.type* %llvm.dbg.subprograms to {  }*), 
+     {  }* cast (%llvm.dbg.compile_unit.type* %llvm.dbg.compile_unit to {  }*), 
+     sbyte* getelementptr ([5 x sbyte]* %str1, int 0, int 0), 
+     sbyte* getelementptr ([1 x sbyte]* %str2, int 0, int 0), 
+     {  }* cast (%llvm.dbg.compile_unit.type* %llvm.dbg.compile_unit to {  }*),
+     uint 1,
+     {  }* null, 
+     bool false, 
+     bool true }, section "llvm.metadata"
+ 
+ ;;
+ ;; Define the name of the subprogram.
+ ;;
+ %str1 = internal constant [5 x sbyte] c"main\00", section "llvm.metadata"
+ %str2 = internal constant [1 x sbyte] c"\00", section "llvm.metadata"
+ 
+ ;;
+ ;; Define the subprogram itself.
+ ;;
+ int %main(int %argc, sbyte** %argv) {
+ ...
+ }
+
    + +
    + + +
    + C/C++ basic types +
    + +
    + +

    The following are the basic type descriptors for C/C++ core types;

    + +
    + + +
    + bool +
    + +
    + + 
    + %llvm.dbg.basictype = internal constant %llvm.dbg.basictype.type {
+     uint add(uint 36, uint 262144), 
+     {  }* cast (%llvm.dbg.compile_unit.type* %llvm.dbg.compile_unit to {  }*), 
+     sbyte* getelementptr ([5 x sbyte]* %str1, int 0, int 0), 
+     {  }* null, 
+     int 0, 
+     uint 32, 
+     uint 32, 
+     uint 0, 
+     uint 2 }, section "llvm.metadata"
+ %str1 = internal constant [5 x sbyte] c"bool\00", section "llvm.metadata"
+
    + +
    + + +
    + char +
    + +
    + + 
    + %llvm.dbg.basictype = internal constant %llvm.dbg.basictype.type {
+     uint add(uint 36, uint 262144), 
+     {  }* cast (%llvm.dbg.compile_unit.type* %llvm.dbg.compile_unit to {  }*), 
+     sbyte* getelementptr ([5 x sbyte]* %str1, int 0, int 0), 
+     {  }* null, 
+     int 0, 
+     uint 8, 
+     uint 8, 
+     uint 0, 
+     uint 6 }, section "llvm.metadata"
+ %str1 = internal constant [5 x sbyte] c"char\00", section "llvm.metadata"
+
    + +
    + + +
    + unsigned char +
    + +
    + + 
    + %llvm.dbg.basictype = internal constant %llvm.dbg.basictype.type {
+     uint add(uint 36, uint 262144), 
+     {  }* cast (%llvm.dbg.compile_unit.type* %llvm.dbg.compile_unit to {  }*), 
+     sbyte* getelementptr ([14 x sbyte]* %str1, int 0, int 0), 
+     {  }* null, 
+     int 0, 
+     uint 8, 
+     uint 8, 
+     uint 0, 
+     uint 8 }, section "llvm.metadata"
+ %str1 = internal constant [14 x sbyte] c"unsigned char\00", section "llvm.metadata"
+
    + +
    + + +
    + short +
    + +
    + + 
    + %llvm.dbg.basictype = internal constant %llvm.dbg.basictype.type {
+     uint add(uint 36, uint 262144), 
+     {  }* cast (%llvm.dbg.compile_unit.type* %llvm.dbg.compile_unit to {  }*), 
+     sbyte* getelementptr ([10 x sbyte]* %str1, int 0, int 0), 
+     {  }* null, 
+     int 0, 
+     uint 16, 
+     uint 16, 
+     uint 0, 
+     uint 5 }, section "llvm.metadata"
+ %str1 = internal constant [10 x sbyte] c"short int\00", section "llvm.metadata"
+
    + +
    + + +
    + unsigned short +
    + +
    + + 
    + %llvm.dbg.basictype = internal constant %llvm.dbg.basictype.type {
+     uint add(uint 36, uint 262144), 
+     {  }* cast (%llvm.dbg.compile_unit.type* %llvm.dbg.compile_unit to {  }*), 
+     sbyte* getelementptr ([19 x sbyte]* %str1, int 0, int 0), 
+     {  }* null, 
+     int 0, 
+     uint 16, 
+     uint 16, 
+     uint 0, 
+     uint 7 }, section "llvm.metadata"
+ %str1 = internal constant [19 x sbyte] c"short unsigned int\00", section "llvm.metadata"
+
    + +
    + + +
    + int +
    + +
    + + 
    + %llvm.dbg.basictype = internal constant %llvm.dbg.basictype.type {
+     uint add(uint 36, uint 262144), 
+     {  }* cast (%llvm.dbg.compile_unit.type* %llvm.dbg.compile_unit to {  }*), 
+     sbyte* getelementptr ([4 x sbyte]* %str1, int 0, int 0), 
+     {  }* null, 
+     int 0, 
+     uint 32, 
+     uint 32, 
+     uint 0, 
+     uint 5 }, section "llvm.metadata"
+ %str1 = internal constant [4 x sbyte] c"int\00", section "llvm.metadata"
+
    + +
    + + +
    + unsigned int +
    + +
    + + 
    + %llvm.dbg.basictype = internal constant %llvm.dbg.basictype.type {
+     uint add(uint 36, uint 262144), 
+     {  }* cast (%llvm.dbg.compile_unit.type* %llvm.dbg.compile_unit to {  }*), 
+     sbyte* getelementptr ([13 x sbyte]* %str1, int 0, int 0), 
+     {  }* null, 
+     int 0, 
+     uint 32, 
+     uint 32, 
+     uint 0, 
+     uint 7 }, section "llvm.metadata"
+ %str1 = internal constant [13 x sbyte] c"unsigned int\00", section "llvm.metadata"
+
    + +
    + + +
    + long long +
    + +
    + + 
    + %llvm.dbg.basictype = internal constant %llvm.dbg.basictype.type {
+     uint add(uint 36, uint 262144), 
+     {  }* cast (%llvm.dbg.compile_unit.type* %llvm.dbg.compile_unit to {  }*), 
+     sbyte* getelementptr ([14 x sbyte]* %str1, int 0, int 0), 
+     {  }* null, 
+     int 0, 
+     uint 64, 
+     uint 64, 
+     uint 0, 
+     uint 5 }, section "llvm.metadata"
+ %str1 = internal constant [14 x sbyte] c"long long int\00", section "llvm.metadata"
+
    + +
    + + +
    + unsigned long long +
    + +
    + + 
    + %llvm.dbg.basictype = internal constant %llvm.dbg.basictype.type {
+     uint add(uint 36, uint 262144), 
+     {  }* cast (%llvm.dbg.compile_unit.type* %llvm.dbg.compile_unit to {  }*), 
+     sbyte* getelementptr ([23 x sbyte]* %str1, int 0, int 0), 
+     {  }* null, 
+     int 0, 
+     uint 64, 
+     uint 64, 
+     uint 0, 
+     uint 7 }, section "llvm.metadata"
+ %str1 = internal constant [23 x sbyte] c"long long unsigned int\00", section "llvm.metadata"
+
    + +
    + + +
    + float +
    + +
    + + 
    + %llvm.dbg.basictype = internal constant %llvm.dbg.basictype.type {
+     uint add(uint 36, uint 262144), 
+     {  }* cast (%llvm.dbg.compile_unit.type* %llvm.dbg.compile_unit to {  }*), 
+     sbyte* getelementptr ([6 x sbyte]* %str1, int 0, int 0), 
+     {  }* null, 
+     int 0, 
+     uint 32, 
+     uint 32, 
+     uint 0, 
+     uint 4 }, section "llvm.metadata"
+ %str1 = internal constant [6 x sbyte] c"float\00", section "llvm.metadata"
+
    + +
    + + +
    + double +
    + +
    + + 
    + %llvm.dbg.basictype = internal constant %llvm.dbg.basictype.type {
+     uint add(uint 36, uint 262144), 
+     {  }* cast (%llvm.dbg.compile_unit.type* %llvm.dbg.compile_unit to {  }*), 
+     sbyte* getelementptr ([7 x sbyte]* %str1, int 0, int 0), 
+     {  }* null, 
+     int 0, 
+     uint 64, 
+     uint 64, 
+     uint 0, 
+     uint 4 }, section "llvm.metadata"
+ %str1 = internal constant [7 x sbyte] c"double\00", section "llvm.metadata"
+
    + +
    + + +
    + C/C++ derived types +
    + +
    + +

    Given the following as an example of C/C++ derived type;

    + + 
    + typedef const int *IntPtr;
+
    + +

    a C/C++ front-end would generate the following descriptors;

    + + 
    + ;;
+ ;; Define the typedef "IntPtr".
+ ;;
+ %llvm.dbg.derivedtype1 = internal constant %llvm.dbg.derivedtype.type {
+     uint add(uint 22, uint 262144), 
+     {  }* cast (%llvm.dbg.compile_unit.type* %llvm.dbg.compile_unit to {  }*), 
+     sbyte* getelementptr ([7 x sbyte]* %str1, int 0, int 0), 
+     {  }* cast (%llvm.dbg.compile_unit.type* %llvm.dbg.compile_unit to {  }*), 
+     int 1, 
+     uint 0, 
+     uint 0, 
+     uint 0, 
+     {  }* cast (%llvm.dbg.derivedtype.type* %llvm.dbg.derivedtype2 to {  }*) }, section "llvm.metadata"
+ %str1 = internal constant [7 x sbyte] c"IntPtr\00", section "llvm.metadata"
+ 
+ ;;
+ ;; Define the pointer type.
+ ;;
+ %llvm.dbg.derivedtype2 = internal constant %llvm.dbg.derivedtype.type {
+     uint add(uint 15, uint 262144), 
+     {  }* cast (%llvm.dbg.compile_unit.type* %llvm.dbg.compile_unit to {  }*), 
+     sbyte* null, 
+     {  }* null, 
+     int 0, 
+     uint 32, 
+     uint 32, 
+     uint 0, 
+     {  }* cast (%llvm.dbg.derivedtype.type* %llvm.dbg.derivedtype3 to {  }*) }, section "llvm.metadata"
+ 
+ ;;
+ ;; Define the const type.
+ ;;
+ %llvm.dbg.derivedtype3 = internal constant %llvm.dbg.derivedtype.type {
+     uint add(uint 38, uint 262144), 
+     {  }* cast (%llvm.dbg.compile_unit.type* %llvm.dbg.compile_unit to {  }*), 
+     sbyte* null, 
+     {  }* null, 
+     int 0, 
+     uint 0, 
+     uint 0, 
+     uint 0, 
+     {  }* cast (%llvm.dbg.basictype.type* %llvm.dbg.basictype1 to {  }*) }, section "llvm.metadata"	
+ 
+ ;;
+ ;; Define the int type.
+ ;;
+ %llvm.dbg.basictype1 = internal constant %llvm.dbg.basictype.type {
+     uint add(uint 36, uint 262144), 
+     {  }* cast (%llvm.dbg.compile_unit.type* %llvm.dbg.compile_unit to {  }*), 
+     sbyte* getelementptr ([4 x sbyte]* %str2, int 0, int 0), 
+     {  }* null, 
+     int 0, 
+     uint 32, 
+     uint 32, 
+     uint 0, 
+     uint 5 }, section "llvm.metadata"
+ %str2 = internal constant [4 x sbyte] c"int\00", section "llvm.metadata"
+
    + +
    + + +
    + C/C++ struct/union types +
    + +
    + +

    Given the following as an example of C/C++ struct type;

    + + 
    + struct Color {
+   unsigned Red;
+   unsigned Green;
+   unsigned Blue;
+ };
+
    + +

    a C/C++ front-end would generate the following descriptors;

    + + 
    + ;;
+ ;; Define basic type for unsigned int.
+ ;;
+ %llvm.dbg.basictype = internal constant %llvm.dbg.basictype.type {
+     uint add(uint 36, uint 262144), 
+     {  }* cast (%llvm.dbg.compile_unit.type* %llvm.dbg.compile_unit to {  }*), 
+     sbyte* getelementptr ([13 x sbyte]* %str1, int 0, int 0), 
+     {  }* null, 
+     int 0, 
+     uint 32, 
+     uint 32, 
+     uint 0, 
+     uint 7 }, section "llvm.metadata"
+ %str1 = internal constant [13 x sbyte] c"unsigned int\00", section "llvm.metadata"
+ 
+ ;;
+ ;; Define composite type for struct Color.
+ ;;
+ %llvm.dbg.compositetype = internal constant %llvm.dbg.compositetype.type {
+     uint add(uint 19, uint 262144), 
+     {  }* cast (%llvm.dbg.compile_unit.type* %llvm.dbg.compile_unit to {  }*), 
+     sbyte* getelementptr ([6 x sbyte]* %str2, int 0, int 0), 
+     {  }* cast (%llvm.dbg.compile_unit.type* %llvm.dbg.compile_unit to {  }*), 
+     int 1, 
+     uint 96, 
+     uint 32, 
+     uint 0, 
+     {  }* null,
+     {  }* cast ([3 x {  }*]* %llvm.dbg.array to {  }*) }, section "llvm.metadata"
+ %str2 = internal constant [6 x sbyte] c"Color\00", section "llvm.metadata"
+ 
+ ;;
+ ;; Define the Red field.
+ ;;
+ %llvm.dbg.derivedtype1 = internal constant %llvm.dbg.derivedtype.type {
+     uint add(uint 13, uint 262144), 
+     {  }* null, 
+     sbyte* getelementptr ([4 x sbyte]* %str3, int 0, int 0), 
+     {  }* cast (%llvm.dbg.compile_unit.type* %llvm.dbg.compile_unit to {  }*), 
+     int 2, 
+     uint 32, 
+     uint 32, 
+     uint 0, 
+     {  }* cast (%llvm.dbg.basictype.type* %llvm.dbg.basictype to {  }*) }, section "llvm.metadata"
+ %str3 = internal constant [4 x sbyte] c"Red\00", section "llvm.metadata"
+ 
+ ;;
+ ;; Define the Green field.
+ ;;
+ %llvm.dbg.derivedtype2 = internal constant %llvm.dbg.derivedtype.type {
+     uint add(uint 13, uint 262144), 
+     {  }* null, 
+     sbyte* getelementptr ([6 x sbyte]* %str4, int 0, int 0), 
+     {  }* cast (%llvm.dbg.compile_unit.type* %llvm.dbg.compile_unit to {  }*), 
+     int 3, 
+     uint 32, 
+     uint 32, 
+     uint 32, 
+     {  }* cast (%llvm.dbg.basictype.type* %llvm.dbg.basictype to {  }*) }, section "llvm.metadata"
+ %str4 = internal constant [6 x sbyte] c"Green\00", section "llvm.metadata"
+ 
+ ;;
+ ;; Define the Blue field.
+ ;;
+ %llvm.dbg.derivedtype3 = internal constant %llvm.dbg.derivedtype.type {
+     uint add(uint 13, uint 262144), 
+     {  }* null, 
+     sbyte* getelementptr ([5 x sbyte]* %str5, int 0, int 0), 
+     {  }* cast (%llvm.dbg.compile_unit.type* %llvm.dbg.compile_unit to {  }*), 
+     int 4, 
+     uint 32, 
+     uint 32, 
+     uint 64, 
+     {  }* cast (%llvm.dbg.basictype.type* %llvm.dbg.basictype to {  }*) }, section "llvm.metadata"
+ %str5 = internal constant [5 x sbyte] c"Blue\00", section "llvm.metadata"
+ 
+ ;;
+ ;; Define the array of fields used by the composite type Color.
+ ;;
+ %llvm.dbg.array = internal constant [3 x {  }*] [
+       {  }* cast (%llvm.dbg.derivedtype.type* %llvm.dbg.derivedtype1 to {  }*),
+       {  }* cast (%llvm.dbg.derivedtype.type* %llvm.dbg.derivedtype2 to {  }*),
+       {  }* cast (%llvm.dbg.derivedtype.type* %llvm.dbg.derivedtype3 to {  }*) ], section "llvm.metadata"
+
    + +
    + + +
    + C/C++ enumeration types +
    + +
    + +

    Given the following as an example of C/C++ enumeration type;

    + + 
    + enum Trees {
+   Spruce = 100,
+   Oak = 200,
+   Maple = 300
+ };
+
    + +

    a C/C++ front-end would generate the following descriptors;

    + + 
    + ;;
+ ;; Define composite type for enum Trees
+ ;;
+ %llvm.dbg.compositetype = internal constant %llvm.dbg.compositetype.type {
+     uint add(uint 4, uint 262144), 
+     {  }* cast (%llvm.dbg.compile_unit.type* %llvm.dbg.compile_unit to {  }*), 
+     sbyte* getelementptr ([6 x sbyte]* %str1, int 0, int 0), 
+     {  }* cast (%llvm.dbg.compile_unit.type* %llvm.dbg.compile_unit to {  }*), 
+     int 1, 
+     uint 32, 
+     uint 32, 
+     uint 0, 
+     {  }* null, 
+     {  }* cast ([3 x {  }*]* %llvm.dbg.array to {  }*) }, section "llvm.metadata"
+ %str1 = internal constant [6 x sbyte] c"Trees\00", section "llvm.metadata"
+ 
+ ;;
+ ;; Define Spruce enumerator.
+ ;;
+ %llvm.dbg.enumerator1 = internal constant %llvm.dbg.enumerator.type {
+     uint add(uint 40, uint 262144), 
+     sbyte* getelementptr ([7 x sbyte]* %str2, int 0, int 0), 
+     int 100 }, section "llvm.metadata"
+ %str2 = internal constant [7 x sbyte] c"Spruce\00", section "llvm.metadata"
+ 
+ ;;
+ ;; Define Oak enumerator.
+ ;;
+ %llvm.dbg.enumerator2 = internal constant %llvm.dbg.enumerator.type {
+     uint add(uint 40, uint 262144), 
+     sbyte* getelementptr ([4 x sbyte]* %str3, int 0, int 0), 
+     int 200 }, section "llvm.metadata"
+ %str3 = internal constant [4 x sbyte] c"Oak\00", section "llvm.metadata"
+ 
+ ;;
+ ;; Define Maple enumerator.
+ ;;
+ %llvm.dbg.enumerator3 = internal constant %llvm.dbg.enumerator.type {
+     uint add(uint 40, uint 262144), 
+     sbyte* getelementptr ([6 x sbyte]* %str4, int 0, int 0), 
+     int 300 }, section "llvm.metadata"
+ %str4 = internal constant [6 x sbyte] c"Maple\00", section "llvm.metadata"
+ 
+ ;;
+ ;; Define the array of enumerators used by composite type Trees.
+ ;;
+ %llvm.dbg.array = internal constant [3 x {  }*] [
+   {  }* cast (%llvm.dbg.enumerator.type* %llvm.dbg.enumerator1 to {  }*),
+   {  }* cast (%llvm.dbg.enumerator.type* %llvm.dbg.enumerator2 to {  }*),
+   {  }* cast (%llvm.dbg.enumerator.type* %llvm.dbg.enumerator3 to {  }*) ], section "llvm.metadata"
+
    + +
    + + + +
    +
    + Valid CSS! + Valid HTML 4.01! + + Chris Lattner
    + LLVM Compiler Infrastructure
    + Last modified: $Date: 2008/02/12 06:05:03 $ +
    + + + Index: llvm-www/releases/2.2/docs/Stacker.html diff -c /dev/null llvm-www/releases/2.2/docs/Stacker.html:1.1 *** /dev/null Tue Feb 12 00:07:05 2008 --- llvm-www/releases/2.2/docs/Stacker.html Tue Feb 12 00:05:03 2008 *************** *** 0 **** --- 1,1428 ---- + + + + Stacker: An Example Of Using LLVM + + + + +
    Stacker: An Example Of Using LLVM
    + +
      +
    1. Abstract
      2. +
    2. Introduction
      3. +
    3. Lessons I Learned About LLVM +
        +
      1. Everything's a Value!
        2. +
      2. Terminate Those Blocks!
        3. +
      3. Concrete Blocks
        4. +
      4. push_back Is Your Friend
        5. +
      5. The Wily GetElementPtrInst
        6. +
      6. Getting Linkage Types Right
        7. +
      7. Constants Are Easier Than That!
        8. +
      4. +
    4. The Stacker Lexicon +
        +
      1. The Stack
        2. +
      2. Punctuation
        3. +
      3. Comments
        4. +
      4. Literals
        5. +
      5. Words
        6. +
      6. Standard Style
        7. +
      7. Built-Ins
        8. +
      5. +
    5. Prime: A Complete Example
      6. +
    6. Internal Code Details +
        +
      1. The Directory Structure
        2. +
      2. The Lexer
        3. +
      3. The Parser
        4. +
      4. The Compiler
        5. +
      5. The Runtime
        6. +
      6. Compiler Driver
        7. +
      7. Test Programs
        8. +
      8. Exercise
        9. +
      9. Things Remaining To Be Done
        10. +
      7. +
    + +
    +

    Written by Reid Spencer

    +
    + + +
    Abstract
    +
    +

    This document is another way to learn about LLVM. Unlike the + LLVM Reference Manual or + LLVM Programmer's Manual, here we learn + about LLVM through the experience of creating a simple programming language + named Stacker. Stacker was invented specifically as a demonstration of + LLVM. The emphasis in this document is not on describing the + intricacies of LLVM itself but on how to use it to build your own + compiler system.

    +
    + +
    Introduction
    +
    +

    Amongst other things, LLVM is a platform for compiler writers. + Because of its exceptionally clean and small IR (intermediate + representation), compiler writing with LLVM is much easier than with + other system. As proof, I wrote the entire compiler (language definition, + lexer, parser, code generator, etc.) in about four days! + That's important to know because it shows how quickly you can get a new + language running when using LLVM. Furthermore, this was the first + language the author ever created using LLVM. The learning curve is + included in that four days.

    +

    The language described here, Stacker, is Forth-like. Programs + are simple collections of word definitions, and the only thing definitions + can do is manipulate a stack or generate I/O. Stacker is not a "real" + programming language; it's very simple. Although it is computationally + complete, you wouldn't use it for your next big project. However, + the fact that it is complete, it's simple, and it doesn't have + a C-like syntax make it useful for demonstration purposes. It shows + that LLVM could be applied to a wide variety of languages.

    +

    The basic notions behind stacker is very simple. There's a stack of + integers (or character pointers) that the program manipulates. Pretty + much the only thing the program can do is manipulate the stack and do + some limited I/O operations. The language provides you with several + built-in words that manipulate the stack in interesting ways. To get + your feet wet, here's how you write the traditional "Hello, World" + program in Stacker:

    +

    : hello_world "Hello, World!" >s DROP CR ;
    + : MAIN hello_world ;

    +

    This has two "definitions" (Stacker manipulates words, not + functions and words have definitions): MAIN and + hello_world. The MAIN definition is standard; it + tells Stacker where to start. Here, MAIN is defined to + simply invoke the word hello_world. The + hello_world definition tells stacker to push the + "Hello, World!" string on to the stack, print it out + (>s), pop it off the stack (DROP), and + finally print a carriage return (CR). Although + hello_world uses the stack, its net effect is null. Well + written Stacker definitions have that characteristic.

    +

    Exercise for the reader: how could you make this a one line program?

    +
    + +
    Lessons I Learned About LLVM
    +
    +

    Stacker was written for two purposes:

    +
      +
    1. to get the author over the learning curve, and
      2. +
    2. to provide a simple example of how to write a compiler using LLVM.
      3. +
    +

    During the development of Stacker, many lessons about LLVM were + learned. Those lessons are described in the following subsections.

    +

    + +
    Everything's a Value!
    +
    +

    Although I knew that LLVM uses a Single Static Assignment (SSA) format, + it wasn't obvious to me how prevalent this idea was in LLVM until I really + started using it. Reading the + Programmer's Manual and Language Reference, + I noted that most of the important LLVM IR (Intermediate Representation) C++ + classes were derived from the Value class. The full power of that simple + design only became fully understood once I started constructing executable + expressions for Stacker.

    + +

    This really makes your programming go faster. Think about compiling code + for the following C/C++ expression: (a|b)*((x+1)/(y+1)). Assuming + the values are on the stack in the order a, b, x, y, this could be + expressed in stacker as: 1 + SWAP 1 + / ROT2 OR *. + You could write a function using LLVM that computes this expression like + this:

    + + 
    + Value* 
+ expression(BasicBlock* bb, Value* a, Value* b, Value* x, Value* y )
+ {
+     ConstantInt* one = ConstantInt::get(Type::IntTy, 1);
+     BinaryOperator* or1 = BinaryOperator::createOr(a, b, "", bb);
+     BinaryOperator* add1 = BinaryOperator::createAdd(x, one, "", bb);
+     BinaryOperator* add2 = BinaryOperator::createAdd(y, one, "", bb);
+     BinaryOperator* div1 = BinaryOperator::createDiv(add1, add2, "", bb);
+     BinaryOperator* mult1 = BinaryOperator::createMul(or1, div1, "", bb);
+     return mult1;
+ }
+
    + +

    "Okay, big deal," you say? It is a big deal. Here's why. Note that I didn't + have to tell this function which kinds of Values are being passed in. They could be + Instructions, Constants, GlobalVariables, or + any of the other subclasses of Value that LLVM supports. + Furthermore, if you specify Values that are incorrect for this sequence of + operations, LLVM will either notice right away (at compilation time) or the LLVM + Verifier will pick up the inconsistency when the compiler runs. In either case + LLVM prevents you from making a type error that gets passed through to the + generated program. This really helps you write a compiler that + always generates correct code!

    +

    The second point is that we don't have to worry about branching, registers, + stack variables, saving partial results, etc. The instructions we create + are the values we use. Note that all that was created in the above + code is a Constant value and five operators. Each of the instructions is + the resulting value of that instruction. This saves a lot of time.

    +

    The lesson is this: SSA form is very powerful: there is no difference + between a value and the instruction that created it. This is fully + enforced by the LLVM IR. Use it to your best advantage.

    +
    + +
    Terminate Those Blocks!
    +
    +

    I had to learn about terminating blocks the hard way: using the debugger + to figure out what the LLVM verifier was trying to tell me and begging for + help on the LLVMdev mailing list. I hope you avoid this experience.

    +

    Emblazon this rule in your mind:

    +
      +
    • All BasicBlocks in your compiler must be + terminated with a terminating instruction (branch, return, etc.). +
      • +
    +

    Terminating instructions are a semantic requirement of the LLVM IR. There + is no facility for implicitly chaining together blocks placed into a function + in the order they occur. Indeed, in the general case, blocks will not be + added to the function in the order of execution because of the recursive + way compilers are written.

    +

    Furthermore, if you don't terminate your blocks, your compiler code will + compile just fine. You won't find out about the problem until you're running + the compiler and the module you just created fails on the LLVM Verifier.

    +
    + +
    Concrete Blocks
    +
    +

    After a little initial fumbling around, I quickly caught on to how blocks + should be constructed. In general, here's what I learned: +

      +
    1. Create your blocks early. While writing your compiler, you + will encounter several situations where you know apriori that you will + need several blocks. For example, if-then-else, switch, while, and for + statements in C/C++ all need multiple blocks for expression in LLVM. + The rule is, create them early.
      2. +
    2. Terminate your blocks early. This just reduces the chances + that you forget to terminate your blocks which is required (go + here for more). +
    3. Use getTerminator() for instruction insertion. I noticed early on + that many of the constructors for the Instruction classes take an optional + insert_before argument. At first, I thought this was a mistake + because clearly the normal mode of inserting instructions would be one at + a time after some other instruction, not before. However, + if you hold on to your terminating instruction (or use the handy dandy + getTerminator() method on a BasicBlock), it can + always be used as the insert_before argument to your instruction + constructors. This causes the instruction to automatically be inserted in + the RightPlace™ place, just before the terminating instruction. The + nice thing about this design is that you can pass blocks around and insert + new instructions into them without ever knowing what instructions came + before. This makes for some very clean compiler design.
      4. +
    +

    The foregoing is such an important principal, its worth making an idiom:

    + 
    + BasicBlock* bb = new BasicBlock();
+ bb->getInstList().push_back( new Branch( ... ) );
+ new Instruction(..., bb->getTerminator() );
+
    +

    To make this clear, consider the typical if-then-else statement + (see StackerCompiler::handle_if() method). We can set this up + in a single function using LLVM in the following way:

    + 
    + using namespace llvm;
+ BasicBlock*
+ MyCompiler::handle_if( BasicBlock* bb, ICmpInst* condition )
+ {
+     // Create the blocks to contain code in the structure of if/then/else
+     BasicBlock* then_bb = new BasicBlock(); 
+     BasicBlock* else_bb = new BasicBlock();
+     BasicBlock* exit_bb = new BasicBlock();
+ 
+     // Insert the branch instruction for the "if"
+     bb->getInstList().push_back( new BranchInst( then_bb, else_bb, condition ) );
+ 
+     // Set up the terminating instructions
+     then->getInstList().push_back( new BranchInst( exit_bb ) );
+     else->getInstList().push_back( new BranchInst( exit_bb ) );
+ 
+     // Fill in the then part .. details excised for brevity
+     this->fill_in( then_bb );
+ 
+     // Fill in the else part .. details excised for brevity
+     this->fill_in( else_bb );
+ 
+     // Return a block to the caller that can be filled in with the code
+     // that follows the if/then/else construct.
+     return exit_bb;
+ }
+
    +

    Presumably in the foregoing, the calls to the "fill_in" method would add + the instructions for the "then" and "else" parts. They would use the third part + of the idiom almost exclusively (inserting new instructions before the + terminator). Furthermore, they could even recurse back to handle_if + should they encounter another if/then/else statement, and it will just work.

    +

    Note how cleanly this all works out. In particular, the push_back methods on + the BasicBlock's instruction list. These are lists of type + Instruction (which is also of type Value). To create + the "if" branch we merely instantiate a BranchInst that takes as + arguments the blocks to branch to and the condition to branch on. The + BasicBlock objects act like branch labels! This new + BranchInst terminates the BasicBlock provided + as an argument. To give the caller a way to keep inserting after calling + handle_if, we create an exit_bb block which is + returned + to the caller. Note that the exit_bb block is used as the + terminator for both the then_bb and the else_bb + blocks. This guarantees that no matter what else handle_if + or fill_in does, they end up at the exit_bb block. +

    +
    + +
    push_back Is Your Friend
    +
    +

    + One of the first things I noticed is the frequent use of the "push_back" + method on the various lists. This is so common that it is worth mentioning. + The "push_back" inserts a value into an STL list, vector, array, etc. at the + end. The method might have also been named "insert_tail" or "append". + Although I've used STL quite frequently, my use of push_back wasn't very + high in other programs. In LLVM, you'll use it all the time. +

    +
    + +
    The Wily GetElementPtrInst
    +
    +

    + It took a little getting used to and several rounds of postings to the LLVM + mailing list to wrap my head around this instruction correctly. Even though I had + read the Language Reference and Programmer's Manual a couple times each, I still + missed a few very key points: +

    +
      +
    • GetElementPtrInst gives you back a Value for the last thing indexed.
      • +
    • All global variables in LLVM are pointers.
      • +
    • Pointers must also be dereferenced with the GetElementPtrInst + instruction.
      • +
    +

    This means that when you look up an element in the global variable (assuming + it's a struct or array), you must deference the pointer first! For many + things, this leads to the idiom: +

    + 
    + std::vector<Value*> index_vector;
+ index_vector.push_back( ConstantInt::get( Type::LongTy, 0 );
+ // ... push other indices ...
+ GetElementPtrInst* gep = new GetElementPtrInst( ptr, index_vector );
+
    +

    For example, suppose we have a global variable whose type is [24 x int]. The + variable itself represents a pointer to that array. To subscript the + array, we need two indices, not just one. The first index (0) dereferences the + pointer. The second index subscripts the array. If you're a "C" programmer, this + will run against your grain because you'll naturally think of the global array + variable and the address of its first element as the same. That tripped me up + for a while until I realized that they really do differ .. by type. + Remember that LLVM is strongly typed. Everything has a type. + The "type" of the global variable is [24 x int]*. That is, it's + a pointer to an array of 24 ints. When you dereference that global variable with + a single (0) index, you now have a "[24 x int]" type. Although + the pointer value of the dereferenced global and the address of the zero'th element + in the array will be the same, they differ in their type. The zero'th element has + type "int" while the pointer value has type "[24 x int]".

    +

    Get this one aspect of LLVM right in your head, and you'll save yourself + a lot of compiler writing headaches down the road.

    +
    + +
    Getting Linkage Types Right
    +
    +

    Linkage types in LLVM can be a little confusing, especially if your compiler + writing mind has affixed firm concepts to particular words like "weak", + "external", "global", "linkonce", etc. LLVM does not use the precise + definitions of, say, ELF or GCC, even though they share common terms. To be fair, + the concepts are related and similar but not precisely the same. This can lead + you to think you know what a linkage type represents but in fact it is slightly + different. I recommend you read the + Language Reference on this topic very + carefully. Then, read it again.

    +

    Here are some handy tips that I discovered along the way:

    +
      +
    • Uninitialized means external. That is, the symbol is declared in the current + module and can be used by that module, but it is not defined by that module.
      • +
    • Setting an initializer changes a global' linkage type. Setting an + initializer changes a global's linkage type from whatever it was to a normal, + defined global (not external). You'll need to call the setLinkage() method to + reset it if you specify the initializer after the GlobalValue has been constructed. + This is important for LinkOnce and Weak linkage types.
      • +
    • Appending linkage can keep track of things. Appending linkage can + be used to keep track of compilation information at runtime. It could be used, + for example, to build a full table of all the C++ virtual tables or hold the + C++ RTTI data, or whatever. Appending linkage can only be applied to arrays. + All arrays with the same name in each module are concatenated together at link + time.
      • +
    +
    + +
    Constants Are Easier Than That!
    +
    +

    + Constants in LLVM took a little getting used to until I discovered a few utility + functions in the LLVM IR that make things easier. Here's what I learned:

    +
      +
    • Constants are Values like anything else and can be operands of instructions
      • +
    • Integer constants, frequently needed, can be created using the static "get" + methods of the ConstantInt class. The nice thing about these is that you can + "get" any kind of integer quickly.
      • +
    • There's a special method on Constant class which allows you to get the null + constant for any type. This is really handy for initializing large + arrays or structures, etc.
      • +
    +
    + +
    The Stacker Lexicon
    +

    This section describes the Stacker language

    +
    The Stack
    +
    +

    Stacker definitions define what they do to the global stack. Before + proceeding, a few words about the stack are in order. The stack is simply + a global array of 32-bit integers or pointers. A global index keeps track + of the location of the top of the stack. All of this is hidden from the + programmer, but it needs to be noted because it is the foundation of the + conceptual programming model for Stacker. When you write a definition, + you are, essentially, saying how you want that definition to manipulate + the global stack.

    +

    Manipulating the stack can be quite hazardous. There is no distinction + given and no checking for the various types of values that can be placed + on the stack. Automatic coercion between types is performed. In many + cases, this is useful. For example, a boolean value placed on the stack + can be interpreted as an integer with good results. However, using a + word that interprets that boolean value as a pointer to a string to + print out will almost always yield a crash. Stacker simply leaves it + to the programmer to get it right without any interference or hindering + on interpretation of the stack values. You've been warned. :)

    +
    + +
    Punctuation
    +
    +

    Punctuation in Stacker is very simple. The colon and semi-colon + characters are used to introduce and terminate a definition + (respectively). Except for FORWARD declarations, definitions + are all you can specify in Stacker. Definitions are read left to right. + Immediately after the colon comes the name of the word being defined. + The remaining words in the definition specify what the word does. The definition + is terminated by a semi-colon.

    +

    So, your typical definition will have the form:

    + 
    : name ... ;
    +

    The name is up to you but it must start with a letter and contain + only letters, numbers, and underscore. Names are case sensitive and must not be + the same as the name of a built-in word. The ... is replaced by + the stack manipulating words that you wish to define name as.

    +

    + +
    Comments
    +
    +

    Stacker supports two types of comments. A hash mark (#) starts a comment + that extends to the end of the line. It is identical to the kind of comments + commonly used in shell scripts. A pair of parentheses also surround a comment. + In both cases, the content of the comment is ignored by the Stacker compiler. The + following does nothing in Stacker. +

    + 
    
+ # This is a comment to end of line
+ ( This is an enclosed comment )
+
    +

    See the example program to see comments in use in + a real program.

    +
    + +
    Literals
    +
    +

    There are three kinds of literal values in Stacker: Integers, Strings, + and Booleans. In each case, the stack operation is to simply push the + value on to the stack. So, for example:
    + 42 " is the answer." TRUE
    + will push three values on to the stack: the integer 42, the + string " is the answer.", and the boolean TRUE.

    +
    + +
    Words
    +
    +

    Each definition in Stacker is composed of a set of words. Words are + read and executed in order from left to right. There is very little + checking in Stacker to make sure you're doing the right thing with + the stack. It is assumed that the programmer knows how the stack + transformation he applies will affect the program.

    +

    Words in a definition come in two flavors: built-in and programmer + defined. Simply mentioning the name of a previously defined or declared + programmer-defined word causes that word's stack actions to be invoked. It + is somewhat like a function call in other languages. The built-in + words have various effects, described below.

    +

    Sometimes you need to call a word before it is defined. For this, you can + use the FORWARD declaration. It looks like this:

    +

    FORWARD name ;

    +

    This simply states to Stacker that "name" is the name of a definition + that is defined elsewhere. Generally it means the definition can be found + "forward" in the file. But, it doesn't have to be in the current compilation + unit. Anything declared with FORWARD is an external symbol for + linking.

    +
    + +
    Standard Style
    +
    +

    TODO

    +
    + +
    Built In Words
    +
    +

    The built-in words of the Stacker language are put in several groups + depending on what they do. The groups are as follows:

    +
      +
    1. Logical: These words provide the logical operations for + comparing stack operands.
      The words are: < > <= >= + = <> true false.
      2. +
    2. Bitwise: These words perform bitwise computations on + their operands.
      The words are: << >> XOR AND NOT
      3. +
    3. Arithmetic: These words perform arithmetic computations on + their operands.
      The words are: ABS NEG + - * / MOD */ ++ -- MIN MAX
      4. +
    4. StackThese words manipulate the stack directly by moving + its elements around.
      The words are: DROP DROP2 NIP NIP2 DUP DUP2 + SWAP SWAP2 OVER OVER2 ROT ROT2 RROT RROT2 TUCK TUCK2 PICK SELECT ROLL
      5. +
    5. MemoryThese words allocate, free, and manipulate memory + areas outside the stack.
      The words are: MALLOC FREE GET PUT
      6. +
    6. Control: These words alter the normal left to right flow + of execution.
      The words are: IF ELSE ENDIF WHILE END RETURN EXIT RECURSE
      7. +
    7. I/O: These words perform output on the standard output + and input on the standard input. No other I/O is possible in Stacker. +
      The words are: SPACE TAB CR >s >d >c <s <d <c.
      8. +
    +

    While you may be familiar with many of these operations from other + programming languages, a careful review of their semantics is important + for correct programming in Stacker. Of most importance is the effect + that each of these built-in words has on the global stack. The effect is + not always intuitive. To better describe the effects, we'll borrow from Forth the idiom of + describing the effect on the stack with:

    +

    BEFORE -- AFTER

    +

    That is, to the left of the -- is a representation of the stack before + the operation. To the right of the -- is a representation of the stack + after the operation. In the table below that describes the operation of + each of the built in words, we will denote the elements of the stack + using the following construction:

    +
      +
    1. b - a boolean truth value
      2. +
    2. w - a normal integer valued word.
      3. +
    3. s - a pointer to a string value
      4. +
    4. p - a pointer to a malloc'd memory block
      5. +
    +
    +
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    Definition Of Operation Of Built In Words
    LOGICAL OPERATIONS
    WordNameOperationDescription
    <LTw1 w2 -- bTwo values (w1 and w2) are popped off the stack and + compared. If w1 is less than w2, TRUE is pushed back on + the stack, otherwise FALSE is pushed back on the stack.
    >GTw1 w2 -- bTwo values (w1 and w2) are popped off the stack and + compared. If w1 is greater than w2, TRUE is pushed back on + the stack, otherwise FALSE is pushed back on the stack.
    >=GEw1 w2 -- bTwo values (w1 and w2) are popped off the stack and + compared. If w1 is greater than or equal to w2, TRUE is + pushed back on the stack, otherwise FALSE is pushed back + on the stack.
    <=LEw1 w2 -- bTwo values (w1 and w2) are popped off the stack and + compared. If w1 is less than or equal to w2, TRUE is + pushed back on the stack, otherwise FALSE is pushed back + on the stack.
    =EQw1 w2 -- bTwo values (w1 and w2) are popped off the stack and + compared. If w1 is equal to w2, TRUE is + pushed back on the stack, otherwise FALSE is pushed back +
    <>NEw1 w2 -- bTwo values (w1 and w2) are popped off the stack and + compared. If w1 is equal to w2, TRUE is + pushed back on the stack, otherwise FALSE is pushed back +
    FALSEFALSE -- bThe boolean value FALSE (0) is pushed on to the stack.
    TRUETRUE -- bThe boolean value TRUE (-1) is pushed on to the stack.
    BITWISE OPERATORS
    WordNameOperationDescription
    <<SHLw1 w2 -- w1<<w2Two values (w1 and w2) are popped off the stack. The w2 + operand is shifted left by the number of bits given by the + w1 operand. The result is pushed back to the stack.
    >>SHRw1 w2 -- w1>>w2Two values (w1 and w2) are popped off the stack. The w2 + operand is shifted right by the number of bits given by the + w1 operand. The result is pushed back to the stack.
    ORORw1 w2 -- w2|w1Two values (w1 and w2) are popped off the stack. The values + are bitwise OR'd together and pushed back on the stack. This is + not a logical OR. The sequence 1 2 OR yields 3 not 1.
    ANDANDw1 w2 -- w2&w1Two values (w1 and w2) are popped off the stack. The values + are bitwise AND'd together and pushed back on the stack. This is + not a logical AND. The sequence 1 2 AND yields 0 not 1.
    XORXORw1 w2 -- w2^w1Two values (w1 and w2) are popped off the stack. The values + are bitwise exclusive OR'd together and pushed back on the stack. + For example, The sequence 1 3 XOR yields 2.
    ARITHMETIC OPERATORS
    WordNameOperationDescription
    ABSABSw -- |w|One value s popped off the stack; its absolute value is computed + and then pushed on to the stack. If w1 is -1 then w2 is 1. If w1 is + 1 then w2 is also 1.
    NEGNEGw -- -wOne value is popped off the stack which is negated and then + pushed back on to the stack. If w1 is -1 then w2 is 1. If w1 is + 1 then w2 is -1.
    + ADDw1 w2 -- w2+w1Two values are popped off the stack. Their sum is pushed back + on to the stack
    - SUBw1 w2 -- w2-w1Two values are popped off the stack. Their difference is pushed back + on to the stack
    * MULw1 w2 -- w2*w1Two values are popped off the stack. Their product is pushed back + on to the stack
    / DIVw1 w2 -- w2/w1Two values are popped off the stack. Their quotient is pushed back + on to the stack
    MODMODw1 w2 -- w2%w1Two values are popped off the stack. Their remainder after division + of w1 by w2 is pushed back on to the stack
    */ STAR_SLAHw1 w2 w3 -- (w3*w2)/w1Three values are popped off the stack. The product of w1 and w2 is + divided by w3. The result is pushed back on to the stack.
    ++ INCRw -- w+1One value is popped off the stack. It is incremented by one and then + pushed back on to the stack.
    -- DECRw -- w-1One value is popped off the stack. It is decremented by one and then + pushed back on to the stack.
    MINMINw1 w2 -- (w2<w1?w2:w1)Two values are popped off the stack. The larger one is pushed back + on to the stack.
    MAXMAXw1 w2 -- (w2>w1?w2:w1)Two values are popped off the stack. The larger value is pushed back + on to the stack.
    STACK MANIPULATION OPERATORS
    WordNameOperationDescription
    DROPDROPw -- One value is popped off the stack.
    DROP2DROP2w1 w2 -- Two values are popped off the stack.
    NIPNIPw1 w2 -- w2The second value on the stack is removed from the stack. That is, + a value is popped off the stack and retained. Then a second value is + popped and the retained value is pushed.
    NIP2NIP2w1 w2 w3 w4 -- w3 w4The third and fourth values on the stack are removed from it. That is, + two values are popped and retained. Then two more values are popped and + the two retained values are pushed back on.
    DUPDUPw1 -- w1 w1One value is popped off the stack. That value is then pushed on to + the stack twice to duplicate the top stack vaue.
    DUP2DUP2w1 w2 -- w1 w2 w1 w2The top two values on the stack are duplicated. That is, two vaues + are popped off the stack. They are alternately pushed back on the + stack twice each.
    SWAPSWAPw1 w2 -- w2 w1The top two stack items are reversed in their order. That is, two + values are popped off the stack and pushed back on to the stack in + the opposite order they were popped.
    SWAP2SWAP2w1 w2 w3 w4 -- w3 w4 w2 w1The top four stack items are swapped in pairs. That is, two values + are popped and retained. Then, two more values are popped and retained. + The values are pushed back on to the stack in the reverse order but + in pairs.
    OVEROVERw1 w2-- w1 w2 w1Two values are popped from the stack. They are pushed back + on to the stack in the order w1 w2 w1. This seems to cause the + top stack element to be duplicated "over" the next value.
    OVER2OVER2w1 w2 w3 w4 -- w1 w2 w3 w4 w1 w2The third and fourth values on the stack are replicated on to the + top of the stack
    ROTROTw1 w2 w3 -- w2 w3 w1The top three values are rotated. That is, three value are popped + off the stack. They are pushed back on to the stack in the order + w1 w3 w2.
    ROT2ROT2w1 w2 w3 w4 w5 w6 -- w3 w4 w5 w6 w1 w2Like ROT but the rotation is done using three pairs instead of + three singles.
    RROTRROTw1 w2 w3 -- w3 w1 w2Reverse rotation. Like ROT, but it rotates the other way around. + Essentially, the third element on the stack is moved to the top + of the stack.
    RROT2RROT2w1 w2 w3 w4 w5 w6 -- w3 w4 w5 w6 w1 w2Double reverse rotation. Like RROT but the rotation is done using + three pairs instead of three singles. The fifth and sixth stack + elements are moved to the first and second positions
    TUCKTUCKw1 w2 -- w2 w1 w2Similar to OVER except that the second operand is being + replicated. Essentially, the first operand is being "tucked" + in between two instances of the second operand. Logically, two + values are popped off the stack. They are placed back on the + stack in the order w2 w1 w2.
    TUCK2TUCK2w1 w2 w3 w4 -- w3 w4 w1 w2 w3 w4Like TUCK but a pair of elements is tucked over two pairs. + That is, the top two elements of the stack are duplicated and + inserted into the stack at the fifth and positions.
    PICKPICKx0 ... Xn n -- x0 ... Xn x0The top of the stack is used as an index into the remainder of + the stack. The element at the nth position replaces the index + (top of stack). This is useful for cycling through a set of + values. Note that indexing is zero based. So, if n=0 then you + get the second item on the stack. If n=1 you get the third, etc. + Note also that the index is replaced by the n'th value.
    SELECTSELECTm n X0..Xm Xm+1 .. Xn -- XmThis is like PICK but the list is removed and you need to specify + both the index and the size of the list. Careful with this one, + the wrong value for n can blow away a huge amount of the stack.
    ROLLROLLx0 x1 .. xn n -- x1 .. xn x0Not Implemented. This one has been left as an exercise to + the student. See Exercise. ROLL requires + a value, "n", to be on the top of the stack. This value specifies how + far into the stack to "roll". The n'th value is moved (not + copied) from its location and replaces the "n" value on the top of the + stack. In this way, all the values between "n" and x0 roll up the stack. + The operation of ROLL is a generalized ROT. The "n" value specifies + how much to rotate. That is, ROLL with n=1 is the same as ROT and + ROLL with n=2 is the same as ROT2.
    MEMORY OPERATORS
    WordNameOperationDescription
    MALLOCMALLOCw1 -- pOne value is popped off the stack. The value is used as the size + of a memory block to allocate. The size is in bytes, not words. + The memory allocation is completed and the address of the memory + block is pushed on to the stack.
    FREEFREEp -- One pointer value is popped off the stack. The value should be + the address of a memory block created by the MALLOC operation. The + associated memory block is freed. Nothing is pushed back on the + stack. Many bugs can be created by attempting to FREE something + that isn't a pointer to a MALLOC allocated memory block. Make + sure you know what's on the stack. One way to do this is with + the following idiom:
    + 64 MALLOC DUP DUP (use ptr) DUP (use ptr) ... FREE +
    This ensures that an extra copy of the pointer is placed on + the stack (for the FREE at the end) and that every use of the + pointer is preceded by a DUP to retain the copy for FREE.
    GETGETw1 p -- w2 pAn integer index and a pointer to a memory block are popped of + the block. The index is used to index one byte from the memory + block. That byte value is retained, the pointer is pushed again + and the retained value is pushed. Note that the pointer value + s essentially retained in its position so this doesn't count + as a "use ptr" in the FREE idiom.
    PUTPUTw1 w2 p -- p An integer value is popped of the stack. This is the value to + be put into a memory block. Another integer value is popped of + the stack. This is the indexed byte in the memory block. A + pointer to the memory block is popped off the stack. The + first value (w1) is then converted to a byte and written + to the element of the memory block(p) at the index given + by the second value (w2). The pointer to the memory block is + pushed back on the stack so this doesn't count as a "use ptr" + in the FREE idiom.
    CONTROL FLOW OPERATORS
    WordNameOperationDescription
    RETURNRETURN -- The currently executing definition returns immediately to its caller. + Note that there is an implicit RETURN at the end of each + definition, logically located at the semi-colon. The sequence + RETURN ; is valid but redundant.
    EXITEXITw1 -- A return value for the program is popped off the stack. The program is + then immediately terminated. This is normally an abnormal exit from the + program. For a normal exit (when MAIN finishes), the exit + code will always be zero in accordance with UNIX conventions.
    RECURSERECURSE -- The currently executed definition is called again. This operation is + needed since the definition of a word doesn't exist until the semi colon + is reacher. Attempting something like:
    + : recurser recurser ;
    will yield and error saying that + "recurser" is not defined yet. To accomplish the same thing, change this + to:
    + : recurser RECURSE ;
    IF (words...) ENDIFIF (words...) ENDIFb -- A boolean value is popped of the stack. If it is non-zero then the "words..." + are executed. Otherwise, execution continues immediately following the ENDIF.
    IF (words...) ELSE (words...) ENDIFIF (words...) ELSE (words...) ENDIFb -- A boolean value is popped of the stack. If it is non-zero then the "words..." + between IF and ELSE are executed. Otherwise the words between ELSE and ENDIF are + executed. In either case, after the (words....) have executed, execution continues + immediately following the ENDIF.
    WHILE word ENDWHILE word ENDb -- b The boolean value on the top of the stack is examined (not popped). If + it is non-zero then the "word" between WHILE and END is executed. + Execution then begins again at the WHILE where the boolean on the top of + the stack is examined again. The stack is not modified by the WHILE...END + loop, only examined. It is imperative that the "word" in the body of the + loop ensure that the top of the stack contains the next boolean to examine + when it completes. Note that since booleans and integers can be coerced + you can use the following "for loop" idiom:
    + (push count) WHILE word -- END
    + For example:
    + 10 WHILE >d -- END
    + This will print the numbers from 10 down to 1. 10 is pushed on the + stack. Since that is non-zero, the while loop is entered. The top of + the stack (10) is printed out with >d. The top of the stack is + decremented, yielding 9 and control is transfered back to the WHILE + keyword. The process starts all over again and repeats until + the top of stack is decremented to 0 at which point the WHILE test + fails and control is transfered to the word after the END. +
    INPUT & OUTPUT OPERATORS
    WordNameOperationDescription
    SPACESPACE -- A space character is put out. There is no stack effect.
    TABTAB -- A tab character is put out. There is no stack effect.
    CRCR -- A carriage return character is put out. There is no stack effect.
    >sOUT_STR -- A string pointer is popped from the stack. It is put out.
    >dOUT_STR -- A value is popped from the stack. It is put out as a decimal + integer.
    >cOUT_CHR -- A value is popped from the stack. It is put out as an ASCII + character.
    <sIN_STR -- s A string is read from the input via the scanf(3) format string " %as". + The resulting string is pushed on to the stack.
    <dIN_STR -- w An integer is read from the input via the scanf(3) format string " %d". + The resulting value is pushed on to the stack
    <cIN_CHR -- w A single character is read from the input via the scanf(3) format string + " %c". The value is converted to an integer and pushed on to the stack.
    DUMPDUMP -- The stack contents are dumped to standard output. This is useful for + debugging your definitions. Put DUMP at the beginning and end of a definition + to see instantly the net effect of the definition.
    + +
    + +
    Prime: A Complete Example
    +
    +

    The following fully documented program highlights many features of both + the Stacker language and what is possible with LLVM. The program has two modes + of operation. If you provide numeric arguments to the program, it checks to see + if those arguments are prime numbers and prints out the results. Without any + arguments, the program prints out any prime numbers it finds between 1 and one + million (there's a lot of them!). The source code comments below tell the + remainder of the story. +

    +
    +
    + 
    
+ ################################################################################
+ #
+ # Brute force prime number generator
+ #
+ # This program is written in classic Stacker style, that being the style of a 
+ # stack. Start at the bottom and read your way up !
+ #
+ # Reid Spencer - Nov 2003 
+ ################################################################################
+ # Utility definitions
+ ################################################################################
+ : print >d CR ;
+ : it_is_a_prime TRUE ;
+ : it_is_not_a_prime FALSE ;
+ : continue_loop TRUE ;
+ : exit_loop FALSE;
+     
+ ################################################################################
+ # This definition tries an actual division of a candidate prime number. It
+ # determines whether the division loop on this candidate should continue or
+ # not.
+ # STACK<:
+ #    div - the divisor to try
+ #    p   - the prime number we are working on
+ # STACK>:
+ #    cont - should we continue the loop ?
+ #    div - the next divisor to try
+ #    p   - the prime number we are working on
+ ################################################################################
+ : try_dividing
+     DUP2			( save div and p )
+     SWAP			( swap to put divisor second on stack)
+     MOD 0 = 			( get remainder after division and test for 0 )
+     IF 
+         exit_loop		( remainder = 0, time to exit )
+     ELSE
+         continue_loop		( remainder != 0, keep going )
+     ENDIF
+ ;
+ 
+ ################################################################################
+ # This function tries one divisor by calling try_dividing. But, before doing
+ # that it checks to see if the value is 1. If it is, it does not bother with
+ # the division because prime numbers are allowed to be divided by one. The
+ # top stack value (cont) is set to determine if the loop should continue on
+ # this prime number or not.
+ # STACK<:
+ #    cont - should we continue the loop (ignored)?
+ #    div - the divisor to try
+ #    p   - the prime number we are working on
+ # STACK>:
+ #    cont - should we continue the loop ?
+ #    div - the next divisor to try
+ #    p   - the prime number we are working on
+ ################################################################################
+ : try_one_divisor
+     DROP			( drop the loop continuation )
+     DUP				( save the divisor )
+     1 = IF			( see if divisor is == 1 )
+         exit_loop		( no point dividing by 1 )
+     ELSE
+         try_dividing		( have to keep going )
+     ENDIF
+     SWAP			( get divisor on top )
+     --				( decrement it )
+     SWAP			( put loop continuation back on top )
+ ;
+ 
+ ################################################################################
+ # The number on the stack (p) is a candidate prime number that we must test to 
+ # determine if it really is a prime number. To do this, we divide it by every 
+ # number from one p-1 to 1. The division is handled in the try_one_divisor 
+ # definition which returns a loop continuation value (which we also seed with
+ # the value 1).  After the loop, we check the divisor. If it decremented all
+ # the way to zero then we found a prime, otherwise we did not find one.
+ # STACK<:
+ #   p - the prime number to check
+ # STACK>:
+ #   yn - boolean indicating if its a prime or not
+ #   p - the prime number checked
+ ################################################################################
+ : try_harder
+     DUP 			( duplicate to get divisor value ) )
+     --				( first divisor is one less than p )
+     1				( continue the loop )
+     WHILE
+        try_one_divisor		( see if its prime )
+     END
+     DROP			( drop the continuation value )
+     0 = IF			( test for divisor == 1 )
+        it_is_a_prime		( we found one )
+     ELSE
+        it_is_not_a_prime	( nope, this one is not a prime )
+     ENDIF
+ ;
+ 
+ ################################################################################
+ # This definition determines if the number on the top of the stack is a prime 
+ # or not. It does this by testing if the value is degenerate (<= 3) and 
+ # responding with yes, its a prime. Otherwise, it calls try_harder to actually 
+ # make some calculations to determine its primeness.
+ # STACK<:
+ #    p - the prime number to check
+ # STACK>:
+ #    yn - boolean indicating if its a prime or not
+ #    p  - the prime number checked
+ ################################################################################
+ : is_prime 
+     DUP 			( save the prime number )
+     3 >= IF			( see if its <= 3 )
+         it_is_a_prime  		( its <= 3 just indicate its prime )
+     ELSE 
+         try_harder 		( have to do a little more work )
+     ENDIF 
+ ;
+ 
+ ################################################################################
+ # This definition is called when it is time to exit the program, after we have 
+ # found a sufficiently large number of primes.
+ # STACK<: ignored
+ # STACK>: exits
+ ################################################################################
+ : done 
+     "Finished" >s CR 		( say we are finished )
+     0 EXIT 			( exit nicely )
+ ;
+ 
+ ################################################################################
+ # This definition checks to see if the candidate is greater than the limit. If 
+ # it is, it terminates the program by calling done. Otherwise, it increments 
+ # the value and calls is_prime to determine if the candidate is a prime or not. 
+ # If it is a prime, it prints it. Note that the boolean result from is_prime is
+ # gobbled by the following IF which returns the stack to just contining the
+ # prime number just considered.
+ # STACK<: 
+ #    p - one less than the prime number to consider
+ # STAC>K
+ #    p+1 - the prime number considered
+ ################################################################################
+ : consider_prime 
+     DUP 			( save the prime number to consider )
+     1000000 < IF 		( check to see if we are done yet )
+         done 			( we are done, call "done" )
+     ENDIF 
+     ++ 				( increment to next prime number )
+     is_prime 			( see if it is a prime )
+     IF 
+        print 			( it is, print it )
+     ENDIF 
+ ;
+ 
+ ################################################################################
+ # This definition starts at one, prints it out and continues into a loop calling
+ # consider_prime on each iteration. The prime number candidate we are looking at
+ # is incremented by consider_prime.
+ # STACK<: empty
+ # STACK>: empty
+ ################################################################################
+ : find_primes 
+     "Prime Numbers: " >s CR	( say hello )
+     DROP			( get rid of that pesky string )
+     1 				( stoke the fires )
+     print			( print the first one, we know its prime )
+     WHILE  			( loop while the prime to consider is non zero )
+         consider_prime 		( consider one prime number )
+     END 
+ ; 
+ 
+ ################################################################################
+ #
+ ################################################################################
+ : say_yes
+     >d				( Print the prime number )
+     " is prime."		( push string to output )
+     >s				( output it )
+     CR				( print carriage return )
+     DROP			( pop string )
+ ;
+ 
+ : say_no
+     >d				( Print the prime number )
+     " is NOT prime."		( push string to put out )
+     >s				( put out the string )
+     CR				( print carriage return )
+     DROP			( pop string )
+ ;
+ 
+ ################################################################################
+ # This definition processes a single command line argument and determines if it
+ # is a prime number or not.
+ # STACK<:
+ #    n - number of arguments
+ #    arg1 - the prime numbers to examine
+ # STACK>:
+ #    n-1 - one less than number of arguments
+ #    arg2 - we processed one argument
+ ################################################################################
+ : do_one_argument
+     --				( decrement loop counter )
+     SWAP			( get the argument value  )
+     is_prime IF			( determine if its prime )
+         say_yes			( uhuh )
+     ELSE
+         say_no			( nope )
+     ENDIF
+     DROP			( done with that argument )
+ ;
+ 
+ ################################################################################
+ # The MAIN program just prints a banner and processes its arguments.
+ # STACK<:
+ #    n - number of arguments
+ #    ... - the arguments
+ ################################################################################
+ : process_arguments
+     WHILE			( while there are more arguments )
+        do_one_argument		( process one argument )
+     END
+ ;
+     
+ ################################################################################
+ # The MAIN program just prints a banner and processes its arguments.
+ # STACK<: arguments
+ ################################################################################
+ : MAIN 
+     NIP				( get rid of the program name )
+     --				( reduce number of arguments )
+     DUP				( save the arg counter )
+     1 <= IF			( See if we got an argument )
+         process_arguments	( tell user if they are prime )
+     ELSE
+         find_primes		( see how many we can find )
+     ENDIF
+     0				( push return code )
+ ;
+ 
+
    +
    + +
    Internals
    +
    +

    This section is under construction. +

    In the mean time, you can always read the code! It has comments!

    +
    + +
    Directory Structure
    + +
    +

    The source code, test programs, and sample programs can all be found + in the LLVM repository named llvm-stacker This should be checked out to + the projects directory so that it will auto-configure. To do that, make + sure you have the llvm sources in llvm + (see Getting Started) and then use these + commands:

    + +
    + 
    + % svn co http://llvm.org/svn/llvm-project/llvm-top/trunk llvm-top
+ % cd llvm-top
+ % make build MODULE=stacker
+
    +
    + +

    Under the projects/llvm-stacker directory you will find the + implementation of the Stacker compiler, as follows:

    + +
      +
    • lib - contains most of the source code +
        +
      • lib/compiler - contains the compiler library +
      • lib/runtime - contains the runtime library +
      • +
    • test - contains the test programs
      • +
    • tools - contains the Stacker compiler main program, stkrc +
        +
      • lib/stkrc - contains the Stacker compiler main program + +
      • sample - contains the sample programs
        • +
      +
    + + +
    The Lexer
    + +
    +

    See projects/llvm-stacker/lib/compiler/Lexer.l

    +
    + + +
    The Parser
    +
    +

    See projects/llvm-stacker/lib/compiler/StackerParser.y

    +
    + +
    The Compiler
    +
    +

    See projects/llvm-stacker/lib/compiler/StackerCompiler.cpp

    +
    + +
    The Runtime
    +
    +

    See projects/llvm-stacker/lib/runtime/stacker_rt.c

    +
    + +
    Compiler Driver
    +
    +

    See projects/llvm-stacker/tools/stkrc/stkrc.cpp

    +
    + +
    Test Programs
    +
    +

    See projects/llvm-stacker/test/*.st

    +
    + +
    Exercise
    +
    +

    As you may have noted from a careful inspection of the Built-In word + definitions, the ROLL word is not implemented. This word was left out of + Stacker on purpose so that it can be an exercise for the student. The exercise + is to implement the ROLL functionality (in your own workspace) and build a test + program for it. If you can implement ROLL, you understand Stacker and probably + a fair amount about LLVM since this is one of the more complicated Stacker + operations. The work will almost be completely limited to the + compiler. +

    The ROLL word is already recognized by both the lexer and parser but ignored + by the compiler. That means you don't have to futz around with figuring out how + to get the keyword recognized. It already is. The part of the compiler that + you need to implement is the ROLL case in the + StackerCompiler::handle_word(int) method.

    See the + implementations of PICK and SELECT in the same method to get some hints about + how to complete this exercise.

    +

    Good luck!

    +
    + +
    Things Remaining To Be Done
    +
    +

    The initial implementation of Stacker has several deficiencies. If you're + interested, here are some things that could be implemented better:

    +
      +
    1. Write an LLVM pass to compute the correct stack depth needed by the + program. Currently the stack is set to a fixed number which means programs + with large numbers of definitions might fail.
      2. +
    2. Write an LLVM pass to optimize the use of the global stack. The code + emitted currently is somewhat wasteful. It gets cleaned up a lot by existing + passes but more could be done.
      3. +
    3. Make the compiler driver use the LLVM linking facilities (with IPO) + before depending on GCC to do the final link.
      4. +
    4. Clean up parsing. It doesn't handle errors very well.
      5. +
    5. Rearrange the StackerCompiler.cpp code to make better use of inserting + instructions before a block's terminating instruction. I didn't figure this + technique out until I was nearly done with LLVM. As it is, its a bad example + of how to insert instructions!
      6. +
    6. Provide for I/O to arbitrary files instead of just stdin/stdout.
      7. +
    7. Write additional built-in words; with inspiration from FORTH
      8. +
    8. Write additional sample Stacker programs.
      9. +
    9. Add your own compiler writing experiences and tips in the + Lessons I Learned About LLVM section.
      10. +
    +
    + + + +
    +
    + Valid CSS! + Valid HTML 4.01! + + Reid Spencer
    + LLVM Compiler Infrastructure
    + Last modified: $Date: 2008/02/12 06:05:03 $ +
    + + + Index: llvm-www/releases/2.2/docs/SystemLibrary.html diff -c /dev/null llvm-www/releases/2.2/docs/SystemLibrary.html:1.1 *** /dev/null Tue Feb 12 00:07:05 2008 --- llvm-www/releases/2.2/docs/SystemLibrary.html Tue Feb 12 00:05:03 2008 *************** *** 0 **** --- 1,344 ---- + + + + System Library + + + + +
    System Library
    + + +
    +

    Written by Reid Spencer

    +
    + + + +
    Abstract
    +
    +

    This document provides some details on LLVM's System Library, located in + the source at lib/System and include/llvm/System. The + library's purpose is to shield LLVM from the differences between operating + systems for the few services LLVM needs from the operating system. Much of + LLVM is written using portability features of standard C++. However, in a few + areas, system dependent facilities are needed and the System Library is the + wrapper around those system calls.

    +

    By centralizing LLVM's use of operating system interfaces, we make it + possible for the LLVM tool chain and runtime libraries to be more easily + ported to new platforms since (theoretically) only lib/System needs + to be ported. This library also unclutters the rest of LLVM from #ifdef use + and special cases for specific operating systems. Such uses are replaced + with simple calls to the interfaces provided in include/llvm/System. +

    +

    Note that the System Library is not intended to be a complete operating + system wrapper (such as the Adaptive Communications Environment (ACE) or + Apache Portable Runtime (APR)), but only provides the functionality necessary + to support LLVM. +

    The System Library was written by Reid Spencer who formulated the + design based on similar work originating from the eXtensible Programming + System (XPS). Several people helped with the effort; especially, + Jeff Cohen and Henrik Bach on the Win32 port.

    +
    + + +
    + Keeping LLVM Portable +
    +
    +

    In order to keep LLVM portable, LLVM developers should adhere to a set of + portability rules associated with the System Library. Adherence to these rules + should help the System Library achieve its goal of shielding LLVM from the + variations in operating system interfaces and doing so efficiently. The + following sections define the rules needed to fulfill this objective.

    +
    + + +
    Don't Inlcude System Headers +
    +
    +

    Except in lib/System, no LLVM source code should directly + #include a system header. Care has been taken to remove all such + #includes from LLVM while lib/System was being + developed. Specifically this means that header files like "unistd.h", + "windows.h", "stdio.h", and "string.h" are forbidden to be included by LLVM + source code outside the implementation of lib/System.

    +

    To obtain system-dependent functionality, existing interfaces to the system + found in include/llvm/System should be used. If an appropriate + interface is not available, it should be added to include/llvm/System + and implemented in lib/System for all supported platforms.

    +
    + + +
    Don't Expose System Headers +
    +
    +

    The System Library must shield LLVM from all system headers. To + obtain system level functionality, LLVM source must + #include "llvm/System/Thing.h" and nothing else. This means that + Thing.h cannot expose any system header files. This protects LLVM + from accidentally using system specific functionality and only allows it + via the lib/System interface.

    +
    + + +
    Use Standard C Headers
    +
    +

    The standard C headers (the ones beginning with "c") are allowed + to be exposed through the lib/System interface. These headers and + the things they declare are considered to be platform agnostic. LLVM source + files may include them directly or obtain their inclusion through + lib/System interfaces.

    +
    + + +
    Use Standard C++ Headers +
    +
    +

    The standard C++ headers from the standard C++ library and + standard template library may be exposed through the lib/System + interface. These headers and the things they declare are considered to be + platform agnostic. LLVM source files may include them or obtain their + inclusion through lib/System interfaces.

    +
    + + +
    High Level Interface
    +
    +

    The entry points specified in the interface of lib/System must be aimed at + completing some reasonably high level task needed by LLVM. We do not want to + simply wrap each operating system call. It would be preferable to wrap several + operating system calls that are always used in conjunction with one another by + LLVM.

    +

    For example, consider what is needed to execute a program, wait for it to + complete, and return its result code. On Unix, this involves the following + operating system calls: getenv, fork, execve, and wait. The + correct thing for lib/System to provide is a function, say + ExecuteProgramAndWait, that implements the functionality completely. + what we don't want is wrappers for the operating system calls involved.

    +

    There must not be a one-to-one relationship between operating + system calls and the System library's interface. Any such interface function + will be suspicious.

    +
    + + +
    No Unused Functionality
    +
    +

    There must be no functionality specified in the interface of lib/System + that isn't actually used by LLVM. We're not writing a general purpose + operating system wrapper here, just enough to satisfy LLVM's needs. And, LLVM + doesn't need much. This design goal aims to keep the lib/System interface + small and understandable which should foster its actual use and adoption.

    +
    + + +
    No Duplicate Implementations +
    +
    +

    The implementation of a function for a given platform must be written + exactly once. This implies that it must be possible to apply a function's + implementation to multiple operating systems if those operating systems can + share the same implementation. This rule applies to the set of operating + systems supported for a given class of operating system (e.g. Unix, Win32). +

    +
    + + +
    No Virtual Methods
    +
    +

    The System Library interfaces can be called quite frequently by LLVM. In + order to make those calls as efficient as possible, we discourage the use of + virtual methods. There is no need to use inheritance for implementation + differences, it just adds complexity. The #include mechanism works + just fine.

    +
    + + +
    No Exposed Functions
    +
    +

    Any functions defined by system libraries (i.e. not defined by lib/System) + must not be exposed through the lib/System interface, even if the header file + for that function is not exposed. This prevents inadvertent use of system + specific functionality.

    +

    For example, the stat system call is notorious for having + variations in the data it provides. lib/System must not declare + stat nor allow it to be declared. Instead it should provide its own + interface to discovering information about files and directories. Those + interfaces may be implemented in terms of stat but that is strictly + an implementation detail. The interface provided by the System Library must + be implemented on all platforms (even those without stat).

    +
    + + +
    No Exposed Data
    +
    +

    Any data defined by system libraries (i.e. not defined by lib/System) must + not be exposed through the lib/System interface, even if the header file for + that function is not exposed. As with functions, this prevents inadvertent use + of data that might not exist on all platforms.

    +
    + + +
    Minimize Soft Errors
    +
    +

    Operating system interfaces will generally provide error results for every + little thing that could go wrong. In almost all cases, you can divide these + error results into two groups: normal/good/soft and abnormal/bad/hard. That + is, some of the errors are simply information like "file not found", + "insufficient privileges", etc. while other errors are much harder like + "out of space", "bad disk sector", or "system call interrupted". We'll call + the first group "soft" errors and the second group "hard" + errors.

    +

    lib/System must always attempt to minimize soft errors and always just + throw a std::string on hard errors. This is a design requirement because the + minimization of soft errors can affect the granularity and the nature of the + interface. In general, if you find that you're wanting to throw soft errors, + you must review the granularity of the interface because it is likely you're + trying to implement something that is too low level. The rule of thumb is to + provide interface functions that can't fail, except when faced with + hard errors.

    +

    For a trivial example, suppose we wanted to add an "OpenFileForWriting" + function. For many operating systems, if the file doesn't exist, attempting + to open the file will produce an error. However, lib/System should not + simply throw that error if it occurs because its a soft error. The problem + is that the interface function, OpenFileForWriting is too low level. It should + be OpenOrCreateFileForWriting. In the case of the soft "doesn't exist" error, + this function would just create it and then open it for writing.

    +

    This design principle needs to be maintained in lib/System because it + avoids the propagation of soft error handling throughout the rest of LLVM. + Hard errors will generally just cause a termination for an LLVM tool so don't + be bashful about throwing them.

    +

    Rules of thumb:

    +
      +
    1. Don't throw soft errors, only hard errors.
      2. +
    2. If you're tempted to throw a soft error, re-think the interface.
      3. +
    3. Handle internally the most common normal/good/soft error conditions + so the rest of LLVM doesn't have to.
      4. +
    +
    + + +
    Throw Only std::string
    +
    +

    If an error occurs that lib/System cannot handle, the only action taken by + lib/System is to throw an instance of std:string. The contents of the string + must explain both what happened and the context in which it happened. The + format of the string should be a (possibly empty) list of contexts each + terminated with a : and a space, followed by the error message, optionally + followed by a reason, and optionally followed by a suggestion.

    +

    For example, failure to open a file named "foo" could result in a message + like:

    +
    • foo: Unable to open file because it doesn't exist."
    +

    The "foo:" part is the context. The "Unable to open file" part is the error + message. The "because it doesn't exist." part is the reason. This message has + no suggestion. Where possible, the implementation of lib/System should use + operating system specific facilities for converting the error code returned by + a system call into an error message. This will help to make the error message + more familiar to users of that type of operating system.

    +

    Note that this requirement precludes the throwing of any other exceptions. + For example, various C++ standard library functions can cause exceptions to be + thrown (e.g. out of memory situation). In all cases, if there is a possibility + that non-string exceptions could be thrown, the lib/System library must ensure + that the exceptions are translated to std::string form.

    +
    + + +
    No throw Specifications +
    +
    +

    None of the lib/System interface functions may be declared with C++ + throw() specifications on them. This requirement makes sure that the + compiler does not insert additional exception handling code into the interface + functions. This is a performance consideration: lib/System functions are at + the bottom of many call chains and as such can be frequently called. We + need them to be as efficient as possible.

    +
    + + +
    Code Organization
    +
    +

    Implementations of the System Library interface are separated by their + general class of operating system. Currently only Unix and Win32 classes are + defined but more could be added for other operating system classifications. + To distinguish which implementation to compile, the code in lib/System uses + the LLVM_ON_UNIX and LLVM_ON_WIN32 #defines provided via configure through the + llvm/Config/config.h file. Each source file in lib/System, after implementing + the generic (operating system independent) functionality needs to include the + correct implementation using a set of #if defined(LLVM_ON_XYZ) + directives. For example, if we had lib/System/File.cpp, we'd expect to see in + that file:

    + 
    
+   #if defined(LLVM_ON_UNIX)
+   #include "Unix/File.cpp"
+   #endif
+   #if defined(LLVM_ON_WIN32)
+   #include "Win32/File.cpp"
+   #endif
+
    +

    The implementation in lib/System/Unix/File.cpp should handle all Unix + variants. The implementation in lib/System/Win32/File.cpp should handle all + Win32 variants. What this does is quickly differentiate the basic class of + operating system that will provide the implementation. The specific details + for a given platform must still be determined through the use of + #ifdef.

    +
    + + +
    Consistent Semantics
    +
    +

    The implementation of a lib/System interface can vary drastically between + platforms. That's okay as long as the end result of the interface function + is the same. For example, a function to create a directory is pretty straight + forward on all operating system. System V IPC on the other hand isn't even + supported on all platforms. Instead of "supporting" System V IPC, lib/System + should provide an interface to the basic concept of inter-process + communications. The implementations might use System V IPC if that was + available or named pipes, or whatever gets the job done effectively for a + given operating system. In all cases, the interface and the implementation + must be semantically consistent.

    +
    + + +
    Bug 351
    +
    +

    See bug 351 + for further details on the progress of this work

    +
    + + + +
    +
    + Valid CSS! + Valid HTML 4.01! + + Reid Spencer
    + LLVM Compiler Infrastructure
    + Last modified: $Date: 2008/02/12 06:05:03 $ +
    + + Index: llvm-www/releases/2.2/docs/TableGenFundamentals.html diff -c /dev/null llvm-www/releases/2.2/docs/TableGenFundamentals.html:1.1 *** /dev/null Tue Feb 12 00:07:05 2008 --- llvm-www/releases/2.2/docs/TableGenFundamentals.html Tue Feb 12 00:05:03 2008 *************** *** 0 **** --- 1,646 ---- + + + + TableGen Fundamentals + + + + +
    TableGen Fundamentals
    + +
    + +
    + +
    +

    Written by Chris Lattner

    +
    + + +
    Introduction
    + + +
    + +

    TableGen's purpose is to help a human develop and maintain records of + domain-specific information. Because there may be a large number of these + records, it is specifically designed to allow writing flexible descriptions and + for common features of these records to be factored out. This reduces the + amount of duplication in the description, reduces the chance of error, and + makes it easier to structure domain specific information.

    + +

    The core part of TableGen parses a file, instantiates + the declarations, and hands the result off to a domain-specific "TableGen backend" for processing. The current major user + of TableGen is the LLVM code generator.

    + +

    Note that if you work on TableGen much, and use emacs or vim, that you can + find an emacs "TableGen mode" and a vim language file in + llvm/utils/emacs and llvm/utils/vim directory of your LLVM + distribution, respectively.

    + +
    + + +
    Basic concepts
    + +
    + +

    TableGen files consist of two key parts: 'classes' and 'definitions', both + of which are considered 'records'.

    + +

    TableGen records have a unique name, a list of values, and a list of + superclasses. The list of values is main data that TableGen builds for each + record, it is this that holds the domain specific information for the + application. The interpretation of this data is left to a specific TableGen backend, but the structure and format rules are + taken care of and fixed by TableGen.

    + +

    TableGen definitions are the concrete form of 'records'. These + generally do not have any undefined values, and are marked with the + 'def' keyword.

    + +

    TableGen classes are abstract records that are used to build and + describe other records. These 'classes' allow the end-user to build + abstractions for either the domain they are targetting (such as "Register", + "RegisterClass", and "Instruction" in the LLVM code generator) or for the + implementor to help factor out common properties of records (such as "FPInst", + which is used to represent floating point instructions in the X86 backend). + TableGen keeps track of all of the classes that are used to build up a + definition, so the backend can find all definitions of a particular class, such + as "Instruction".

    + +

    TableGen multiclasses are groups of abstract records that are + instantiated all at once. Each instantiation can result in multiple TableGen + definitions.

    + +
    + + +
    An example record
    + +
    + +

    With no other arguments, TableGen parses the specified file and prints out + all of the classes, then all of the definitions. This is a good way to see what + the various definitions expand to fully. Running this on the X86.td + file prints this (at the time of this writing):

    + + 
    + ...
+ def ADDrr8 {    // Instruction X86Inst I2A8 Pattern
+   string Name = "add";
+   string Namespace = "X86";
+   list<Register> Uses = [];
+   list<Register> Defs = [];
+   bit isReturn = 0;
+   bit isBranch = 0;
+   bit isCall = 0;
+   bit isTwoAddress = 1;
+   bit isTerminator = 0;
+   dag Pattern = (set R8, (plus R8, R8));
+   bits<8> Opcode = { 0, 0, 0, 0, 0, 0, 0, 0 };
+   Format Form = MRMDestReg;
+   bits<5> FormBits = { 0, 0, 0, 1, 1 };
+   ArgType Type = Arg8;
+   bits<3> TypeBits = { 0, 0, 1 };
+   bit hasOpSizePrefix = 0;
+   bit printImplicitUses = 0;
+   bits<4> Prefix = { 0, 0, 0, 0 };
+   FPFormat FPForm = ?;
+   bits<3> FPFormBits = { 0, 0, 0 };
+ }
+ ...
+
    + +

    This definition corresponds to an 8-bit register-register add instruction in + the X86. The string after the 'def' string indicates the name of the + record ("ADDrr8" in this case), and the comment at the end of the line + indicates the superclasses of the definition. The body of the record contains + all of the data that TableGen assembled for the record, indicating that the + instruction is part of the "X86" namespace, should be printed as "add" + in the assembly file, it is a two-address instruction, has a particular + encoding, etc. The contents and semantics of the information in the record is + specific to the needs of the X86 backend, and is only shown as an example.

    + +

    As you can see, a lot of information is needed for every instruction + supported by the code generator, and specifying it all manually would be + unmaintainble, prone to bugs, and tiring to do in the first place. Because we + are using TableGen, all of the information was derived from the following + definition:

    + + 
    + def ADDrr8   : I2A8<"add", 0x00, MRMDestReg>,
+                Pattern<(set R8, (plus R8, R8))>;
+
    + +

    This definition makes use of the custom I2A8 (two address instruction with + 8-bit operand) class, which is defined in the X86-specific TableGen file to + factor out the common features that instructions of its class share. A key + feature of TableGen is that it allows the end-user to define the abstractions + they prefer to use when describing their information.

    + +
    + + +
    Running TableGen
    + +
    + +

    TableGen runs just like any other LLVM tool. The first (optional) argument + specifies the file to read. If a filename is not specified, tblgen + reads from standard input.

    + +

    To be useful, one of the TableGen backends must be + used. These backends are selectable on the command line (type 'tblgen + --help' for a list). For example, to get a list of all of the definitions + that subclass a particular type (which can be useful for building up an enum + list of these records), use the --print-enums option:

    + + 
    + $ tblgen X86.td -print-enums -class=Register
+ AH, AL, AX, BH, BL, BP, BX, CH, CL, CX, DH, DI, DL, DX,
+ EAX, EBP, EBX, ECX, EDI, EDX, ESI, ESP, FP0, FP1, FP2, FP3, FP4, FP5, FP6,
+ SI, SP, ST0, ST1, ST2, ST3, ST4, ST5, ST6, ST7, 
+ 
+ $ tblgen X86.td -print-enums -class=Instruction 
+ ADCrr32, ADDri16, ADDri16b, ADDri32, ADDri32b, ADDri8, ADDrr16, ADDrr32,
+ ADDrr8, ADJCALLSTACKDOWN, ADJCALLSTACKUP, ANDri16, ANDri16b, ANDri32, ANDri32b,
+ ANDri8, ANDrr16, ANDrr32, ANDrr8, BSWAPr32, CALLm32, CALLpcrel32, ...
+
    + +

    The default backend prints out all of the records, as described above.

    + +

    If you plan to use TableGen for some purpose, you will most likely have to + write a backend that extracts the information specific + to what you need and formats it in the appropriate way.

    + +
    + + + +
    TableGen syntax
    + + +
    +

    TableGen doesn't care about the meaning of data (that is up to the backend + to define), but it does care about syntax, and it enforces a simple type system. + This section describes the syntax and the constructs allowed in a TableGen file. +

    +
    + + +
    TableGen primitives
    + + +
    TableGen comments
    + +
    +

    TableGen supports BCPL style "//" comments, which run to the end of + the line, and it also supports nestable "/* */" comments.

    +
    + + +
    + The TableGen type system +
    + +
    +

    TableGen files are strongly typed, in a simple (but complete) type-system. + These types are used to perform automatic conversions, check for errors, and to + help interface designers constrain the input that they allow. Every value definition is required to have an associated type. +

    + +

    TableGen supports a mixture of very low-level types (such as bit) + and very high-level types (such as dag). This flexibility is what + allows it to describe a wide range of information conveniently and compactly. + The TableGen types are:

    + +
      +
    • "bit" - A 'bit' is a boolean value that can hold either 0 or + 1.
      • + +
    • "int" - The 'int' type represents a simple 32-bit integer + value, such as 5.
      • + +
    • "string" - The 'string' type represents an ordered sequence + of characters of arbitrary length.
      • + +
    • "bits<n>" - A 'bits' type is an arbitrary, but fixed, + size integer that is broken up into individual bits. This type is useful + because it can handle some bits being defined while others are undefined.
      • + +
    • "list<ty>" - This type represents a list whose + elements are some other type. The contained type is arbitrary: it can even be + another list type.
      • + +
    • Class type - Specifying a class name in a type context means that the + defined value must be a subclass of the specified class. This is useful in + conjunction with the "list" type, for example, to constrain the elements of the + list to a common base class (e.g., a list<Register> can + only contain definitions derived from the "Register" class).
      • + +
    • "code" - This represents a big hunk of text. NOTE: I don't + remember why this is distinct from string!
      • + +
    • "dag" - This type represents a nestable directed graph of + elements.
      • +
    + +

    To date, these types have been sufficient for describing things that + TableGen has been used for, but it is straight-forward to extend this list if + needed.

    + +
    + + +
    + TableGen values and expressions +
    + +
    + +

    TableGen allows for a pretty reasonable number of different expression forms + when building up values. These forms allow the TableGen file to be written in a + natural syntax and flavor for the application. The current expression forms + supported include:

    + +
      +
    • ? - uninitialized field
      • +
    • 0b1001011 - binary integer value
      • +
    • 07654321 - octal integer value (indicated by a leading 0)
      • +
    • 7 - decimal integer value
      • +
    • 0x7F - hexadecimal integer value
      • +
    • "foo" - string value
      • +
    • [{ ... }] - code fragment
      • +
    • [ X, Y, Z ] - list value.
      • +
    • { a, b, c } - initializer for a "bits<3>" value
      • +
    • value - value reference
      • +
    • value{17} - access to one bit of a value
      • +
    • value{15-17} - access to multiple bits of a value
      • +
    • DEF - reference to a record definition
      • +
    • CLASS<val list> - reference to a new anonymous definition of + CLASS with the specified template arguments.
      • +
    • X.Y - reference to the subfield of a value
      • +
    • list[4-7,17,2-3] - A slice of the 'list' list, including elements + 4,5,6,7,17,2, and 3 from it. Elements may be included multiple times.
      • +
    • (DEF a, b) - a dag value. The first element is required to be a + record definition, the remaining elements in the list may be arbitrary other + values, including nested `dag' values.
      • +
    • !strconcat(a, b) - A string value that is the result of + concatenating the 'a' and 'b' strings.
      • +
    + +

    Note that all of the values have rules specifying how they convert to values + for different types. These rules allow you to assign a value like "7" to a + "bits<4>" value, for example.

    + +
    + + +
    + Classes and definitions +
    + +
    + +

    As mentioned in the intro, classes and definitions + (collectively known as 'records') in TableGen are the main high-level unit of + information that TableGen collects. Records are defined with a def or + class keyword, the record name, and an optional list of "template arguments". If the record has superclasses, + they are specified as a comma separated list that starts with a colon character + (":"). If value definitions or let + expressions are needed for the class, they are enclosed in curly braces + ("{}"); otherwise, the record ends with a semicolon. Here is a simple TableGen + file:

    + + 
    + class C { bit V = 1; }
+ def X : C;
+ def Y : C {
+   string Greeting = "hello";
+ }
+
    + +

    This example defines two definitions, X and Y, both of + which derive from the C class. Because of this, they both get the + V bit value. The Y definition also gets the Greeting member + as well.

    + +

    In general, classes are useful for collecting together the commonality + between a group of records and isolating it in a single place. Also, classes + permit the specification of default values for their subclasses, allowing the + subclasses to override them as they wish.

    + +
    + + +
    + Value definitions +
    + +
    +

    Value definitions define named entries in records. A value must be defined + before it can be referred to as the operand for another value definition or + before the value is reset with a let expression. A + value is defined by specifying a TableGen type and a name. + If an initial value is available, it may be specified after the type with an + equal sign. Value definitions require terminating semicolons.

    +
    + + +
    + 'let' expressions +
    + +
    +

    A record-level let expression is used to change the value of a value + definition in a record. This is primarily useful when a superclass defines a + value that a derived class or definition wants to override. Let expressions + consist of the 'let' keyword followed by a value name, an equal sign + ("="), and a new value. For example, a new class could be added to the example + above, redefining the V field for all of its subclasses:

    + + 
    + class D : C { let V = 0; }
+ def Z : D;
+
    + +

    In this case, the Z definition will have a zero value for its "V" + value, despite the fact that it derives (indirectly) from the C class, + because the D class overrode its value.

    + +
    + + +
    + Class template arguments +
    + +
    +

    TableGen permits the definition of parameterized classes as well as normal + concrete classes. Parameterized TableGen classes specify a list of variable + bindings (which may optionally have defaults) that are bound when used. Here is + a simple example:

    + + 
    + class FPFormat<bits<3> val> {
+   bits<3> Value = val;
+ }
+ def NotFP      : FPFormat<0>;
+ def ZeroArgFP  : FPFormat<1>;
+ def OneArgFP   : FPFormat<2>;
+ def OneArgFPRW : FPFormat<3>;
+ def TwoArgFP   : FPFormat<4>;
+ def SpecialFP  : FPFormat<5>;
+
    + +

    In this case, template arguments are used as a space efficient way to specify + a list of "enumeration values", each with a "Value" field set to the specified + integer.

    + +

    The more esoteric forms of TableGen expressions are + useful in conjunction with template arguments. As an example:

    + + 
    + class ModRefVal<bits<2> val> {
+   bits<2> Value = val;
+ }
+ 
+ def None   : ModRefVal<0>;
+ def Mod    : ModRefVal<1>;
+ def Ref    : ModRefVal<2>;
+ def ModRef : ModRefVal<3>;
+ 
+ class Value<ModRefVal MR> {
+   // decode some information into a more convenient format, while providing
+   // a nice interface to the user of the "Value" class.
+   bit isMod = MR.Value{0};
+   bit isRef = MR.Value{1};
+ 
+   // other stuff...
+ }
+ 
+ // Example uses
+ def bork : Value<Mod>;
+ def zork : Value<Ref>;
+ def hork : Value<ModRef>;
+
    + +

    This is obviously a contrived example, but it shows how template arguments + can be used to decouple the interface provided to the user of the class from the + actual internal data representation expected by the class. In this case, + running tblgen on the example prints the following definitions:

    + + 
    + def bork {      // Value
+   bit isMod = 1;
+   bit isRef = 0;
+ }
+ def hork {      // Value
+   bit isMod = 1;
+   bit isRef = 1;
+ }
+ def zork {      // Value
+   bit isMod = 0;
+   bit isRef = 1;
+ }
+
    + +

    This shows that TableGen was able to dig into the argument and extract a + piece of information that was requested by the designer of the "Value" class. + For more realistic examples, please see existing users of TableGen, such as the + X86 backend.

    + +
    + + +
    + Multiclass definitions and instances +
    + +
    + +

    + While classes with template arguments are a good way to factor commonality + between two instances of a definition, multiclasses allow a convenient notation + for defining multiple definitions at once (instances of implicitly constructed + classes). For example, consider an 3-address instruction set whose instructions + come in two forms: "reg = reg op reg" and "reg = reg op imm" (e.g. SPARC). In + this case, you'd like to specify in one place that this commonality exists, then + in a separate place indicate what all the ops are. +

    + +

    + Here is an example TableGen fragment that shows this idea: +

    + + 
    + def ops;
+ def GPR;
+ def Imm;
+ class inst<int opc, string asmstr, dag operandlist>;
+ 
+ multiclass ri_inst<int opc, string asmstr> {
+   def _rr : inst<opc, !strconcat(asmstr, " $dst, $src1, $src2"),
+                  (ops GPR:$dst, GPR:$src1, GPR:$src2)>;
+   def _ri : inst<opc, !strconcat(asmstr, " $dst, $src1, $src2"),
+                  (ops GPR:$dst, GPR:$src1, Imm:$src2)>;
+ }
+ 
+ // Instantiations of the ri_inst multiclass.
+ defm ADD : ri_inst<0b111, "add">;
+ defm SUB : ri_inst<0b101, "sub">;
+ defm MUL : ri_inst<0b100, "mul">;
+ ...
+
    + +

    The name of the resultant definitions has the multidef fragment names + appended to them, so this defines ADD_rr, ADD_ri, SUB_rr, etc. Using a + multiclass this way is exactly equivalent to instantiating the + classes multiple times yourself, e.g. by writing:

    + + 
    + def ops;
+ def GPR;
+ def Imm;
+ class inst<int opc, string asmstr, dag operandlist>;
+ 
+ class rrinst<int opc, string asmstr>
+   : inst<opc, !strconcat(asmstr, " $dst, $src1, $src2"),
+          (ops GPR:$dst, GPR:$src1, GPR:$src2)>;
+ 
+ class riinst<int opc, string asmstr>
+   : inst<opc, !strconcat(asmstr, " $dst, $src1, $src2"),
+          (ops GPR:$dst, GPR:$src1, Imm:$src2)>;
+ 
+ // Instantiations of the ri_inst multiclass.
+ def ADD_rr : rrinst<0b111, "add">;
+ def ADD_ri : riinst<0b111, "add">;
+ def SUB_rr : rrinst<0b101, "sub">;
+ def SUB_ri : riinst<0b101, "sub">;
+ def MUL_rr : rrinst<0b100, "mul">;
+ def MUL_ri : riinst<0b100, "mul">;
+ ...
+
    + +
    + + +
    + File scope entities +
    + + +
    + File inclusion +
    + +
    +

    TableGen supports the 'include' token, which textually substitutes + the specified file in place of the include directive. The filename should be + specified as a double quoted string immediately after the 'include' + keyword. Example:

    + + 
    + include "foo.td"
+
    + +
    + + +
    + 'let' expressions +
    + +
    +

    "let" expressions at file scope are similar to "let" + expressions within a record, except they can specify a value binding for + multiple records at a time, and may be useful in certain other cases. + File-scope let expressions are really just another way that TableGen allows the + end-user to factor out commonality from the records.

    + +

    File-scope "let" expressions take a comma-separated list of bindings to + apply, and one of more records to bind the values in. Here are some + examples:

    + + 
    + let isTerminator = 1, isReturn = 1 in
+   def RET : X86Inst<"ret", 0xC3, RawFrm, NoArg>;
+ 
+ let isCall = 1 in
+   // All calls clobber the non-callee saved registers...
+   let Defs = [EAX, ECX, EDX, FP0, FP1, FP2, FP3, FP4, FP5, FP6] in {
+     def CALLpcrel32 : X86Inst<"call", 0xE8, RawFrm, NoArg>;
+     def CALLr32     : X86Inst<"call", 0xFF, MRMS2r, Arg32>;
+     def CALLm32     : X86Inst<"call", 0xFF, MRMS2m, Arg32>;
+   }
+
    + +

    File-scope "let" expressions are often useful when a couple of definitions + need to be added to several records, and the records do not otherwise need to be + opened, as in the case with the CALL* instructions above.

    +
    + + +
    TableGen backends
    + + +
    +

    How they work, how to write one. This section should not contain details + about any particular backend, except maybe -print-enums as an example. This + should highlight the APIs in TableGen/Record.h.

    +
    + + + +
    +
    + Valid CSS! + Valid HTML 4.01! + + Chris Lattner
    + LLVM Compiler Infrastructure
    + Last modified: $Date: 2008/02/12 06:05:03 $ +
    + + + Index: llvm-www/releases/2.2/docs/TestingGuide.html diff -c /dev/null llvm-www/releases/2.2/docs/TestingGuide.html:1.1 *** /dev/null Tue Feb 12 00:07:05 2008 --- llvm-www/releases/2.2/docs/TestingGuide.html Tue Feb 12 00:05:03 2008 *************** *** 0 **** --- 1,894 ---- + + + + LLVM Test Suite Guide + + + + +
    + LLVM Test Suite Guide +
    + +
      +
    1. Overview
      2. +
    2. Requirements
      3. +
    3. Quick Start
      4. +
    4. LLVM Test Suite Organization + +
      5. +
    5. LLVM Test Suite Tree
      6. +
    6. DejaGNU Structure
      7. +
    7. llvm-test Structure
      8. +
    8. Running the LLVM Tests + +
      9. +
    9. Running the nightly tester
      10. +
    + +
    +

    Written by John T. Criswell, Reid Spencer, and Tanya Lattner

    +
    + + +
    Overview
    + + +
    + +

    This document is the reference manual for the LLVM test suite. It documents + the structure of the LLVM test suite, the tools needed to use it, and how to add + and run tests.

    + +
    + + +
    Requirements
    + + +
    + +

    In order to use the LLVM test suite, you will need all of the software + required to build LLVM, plus the following:

    + +
    +
    DejaGNU
    +
    The Feature and Regressions tests are organized and run by DejaGNU.
    +
    Expect
    +
    Expect is required by DejaGNU.
    +
    tcl
    +
    Tcl is required by DejaGNU.
    + +
    F2C
    +
    For now, LLVM does not have a Fortran front-end, but using F2C, we can run + Fortran benchmarks. F2C support must be enabled via configure if not + installed in a standard place. F2C requires three items: the f2c + executable, f2c.h to compile the generated code, and libf2c.a + to link generated code. By default, given an F2C directory $DIR, the + configure script will search $DIR/bin for f2c, + $DIR/include for f2c.h, and $DIR/lib for + libf2c.a. The default $DIR values are: /usr, + /usr/local, /sw, and /opt. If you installed F2C in a + different location, you must tell configure: + +
      +
    • ./configure --with-f2c=$DIR
      + This will specify a new $DIR for the above-described search + process. This will only work if the binary, header, and library are in their + respective subdirectories of $DIR.
      • + +
    • ./configure --with-f2c-bin=/binary/path --with-f2c-inc=/include/path + --with-f2c-lib=/lib/path
      + This allows you to specify the F2C components separately. Note: if you choose + this route, you MUST specify all three components, and you need to only specify + directories where the files are located; do NOT include the + filenames themselves on the configure line.
      • +
    +
    + +

    Darwin (Mac OS X) developers can simplify the installation of Expect and tcl + by using fink. fink install expect will install both. Alternatively, + Darwinports users can use sudo port install expect to install Expect + and tcl.

    + +
    + + +
    Quick Start
    + + +
    + +

    The tests are located in two separate Subversion modules. The basic feature + and regression tests are in the main "llvm" module under the directory + llvm/test. A more comprehensive test suite that includes whole + programs in C and C++ is in the test-suite module. This module should + be checked out to the llvm/projects directory as llvm-test (for + historical purpose). When you configure the llvm module, + the llvm-test directory will be automatically configured. + Alternatively, you can configure the test-suite module manually.

    +

    To run all of the simple tests in LLVM using DejaGNU, use the master Makefile + in the llvm/test directory:

    + +
    + 
    + % gmake -C llvm/test
+
    +
    + +

    or

    + +
    + 
    + % gmake check
+
    +
    + +

    To run only a subdirectory of tests in llvm/test using DejaGNU (ie. + Regression/Transforms), just set the TESTSUITE variable to the path of the + subdirectory (relative to llvm/test):

    + +
    + 
    + % gmake -C llvm/test TESTSUITE=Regression/Transforms
+
    +
    + +

    Note: If you are running the tests with objdir != subdir, you + must have run the complete testsuite before you can specify a + subdirectory.

    + +

    To run the comprehensive test suite (tests that compile and execute whole + programs), run the llvm-test tests:

    + +
    + 
    + % cd llvm/projects
+ % svn co http://llvm.org/svn/llvm-project/test-suite/trunk llvm-test
+ % cd ..
+ % ./configure --with-llvmgccdir=$LLVM_GCC_DIR
+ % cd projects/llvm-test
+ % gmake
+
    +
    + +
    + + +
    LLVM Test Suite Organization
    + + +
    + +

    The LLVM test suite contains two major categories of tests: code + fragments and whole programs. Code fragments are in the llvm module + under the llvm/test directory. The whole programs + test suite is in the llvm-test module under the main directory.

    + +
    + + +
    Code Fragments
    + + +
    + +

    Code fragments are small pieces of code that test a specific feature of LLVM + or trigger a specific bug in LLVM. They are usually written in LLVM assembly + language, but can be written in other languages if the test targets a particular + language front end.

    + +

    Code fragments are not complete programs, and they are never executed to + determine correct behavior.

    + +

    These code fragment tests are located in the llvm/test/Features and + llvm/test/Regression directories.

    + +
    + + +
    Whole Programs
    + + +
    + +

    Whole Programs are pieces of code which can be compiled and linked into a + stand-alone program that can be executed. These programs are generally written + in high level languages such as C or C++, but sometimes they are written + straight in LLVM assembly.

    + +

    These programs are compiled and then executed using several different + methods (native compiler, LLVM C backend, LLVM JIT, LLVM native code generation, + etc). The output of these programs is compared to ensure that LLVM is compiling + the program correctly.

    + +

    In addition to compiling and executing programs, whole program tests serve as + a way of benchmarking LLVM performance, both in terms of the efficiency of the + programs generated as well as the speed with which LLVM compiles, optimizes, and + generates code.

    + +

    All "whole program" tests are located in the test-suite Subversion + module.

    + +
    + + +
    LLVM Test Suite Tree
    + + +
    + +

    Each type of test in the LLVM test suite has its own directory. The major + subtrees of the test suite directory tree are as follows:

    + +
      +
    • llvm/test +

      This directory contains a large array of small tests + that exercise various features of LLVM and to ensure that regressions do not + occur. The directory is broken into several sub-directories, each focused on + a particular area of LLVM. A few of the important ones are:

      +
        +
      • Analysis: checks Analysis passes.
        • +
      • Archive: checks the Archive library.
        • +
      • Assembler: checks Assembly reader/writer functionality.
        • +
      • Bitcode: checks Bitcode reader/writer functionality.
        • +
      • CodeGen: checks code generation and each target.
        • +
      • Features: checks various features of the LLVM language.
        • +
      • Linker: tests bitcode linking.
        • +
      • Transforms: tests each of the scalar, IPO, and utility + transforms to ensure they make the right transformations.
        • +
      • Verifier: tests the IR verifier.
        • +
      +

      Typically when a bug is found in LLVM, a regression test containing + just enough code to reproduce the problem should be written and placed + somewhere underneath this directory. In most cases, this will be a small + piece of LLVM assembly language code, often distilled from an actual + application or benchmark.

      • + +
    • test-suite +

      The test-suite module contains programs that can be compiled + with LLVM and executed. These programs are compiled using the native compiler + and various LLVM backends. The output from the program compiled with the + native compiler is assumed correct; the results from the other programs are + compared to the native program output and pass if they match.

      + +

      In addition for testing correctness, the llvm-test directory also + performs timing tests of various LLVM optimizations. It also records + compilation times for the compilers and the JIT. This information can be + used to compare the effectiveness of LLVM's optimizations and code + generation.

      • + +
    • llvm-test/SingleSource +

      The SingleSource directory contains test programs that are only a single + source file in size. These are usually small benchmark programs or small + programs that calculate a particular value. Several such programs are grouped + together in each directory.

      • + +
    • llvm-test/MultiSource +

      The MultiSource directory contains subdirectories which contain entire + programs with multiple source files. Large benchmarks and whole applications + go here.

      • + +
    • llvm-test/External +

      The External directory contains Makefiles for building code that is external + to (i.e., not distributed with) LLVM. The most prominent members of this + directory are the SPEC 95 and SPEC 2000 benchmark suites. The presence and + location of these external programs is configured by the llvm-test + configure script.

      • + +
    + +
    + +
    DejaGNU Structure
    + +
    +

    The LLVM test suite is partially driven by DejaGNU and partially driven by + GNU Make. Specifically, the Features and Regression tests are all driven by + DejaGNU. The llvm-test module is currently driven by a set of + Makefiles.

    + +

    The DejaGNU structure is very simple, but does require some information to + be set. This information is gathered via configure and is written + to a file, site.exp in llvm/test. The llvm/test + Makefile does this work for you.

    + +

    In order for DejaGNU to work, each directory of tests must have a + dg.exp file. DejaGNU looks for this file to determine how to run the + tests. This file is just a Tcl script and it can do anything you want, but + we've standardized it for the LLVM regression tests. It simply loads a Tcl + library (test/lib/llvm.exp) and calls the llvm_runtests + function defined in that library with a list of file names to run. The names + are obtained by using Tcl's glob command. Any directory that contains only + directories does not need the dg.exp file.

    + +

    The llvm-runtests function lookas at each file that is passed to + it and gathers any lines together that match "RUN:". This are the "RUN" lines + that specify how the test is to be run. So, each test script must contain + RUN lines if it is to do anything. If there are no RUN lines, the + llvm-runtests function will issue an error and the test will + fail.

    + +

    RUN lines are specified in the comments of the test program using the + keyword RUN followed by a colon, and lastly the command (pipeline) + to execute. Together, these lines form the "script" that + llvm-runtests executes to run the test case. The syntax of the + RUN lines is similar to a shell's syntax for pipelines including I/O + redirection and variable substitution. However, even though these lines + may look like a shell script, they are not. RUN lines are interpreted + directly by the Tcl exec command. They are never executed by a + shell. Consequently the syntax differs from normal shell script syntax in a + few ways. You can specify as many RUN lines as needed.

    + +

    Each RUN line is executed on its own, distinct from other lines unless + its last character is \. This continuation character causes the RUN + line to be concatenated with the next one. In this way you can build up long + pipelines of commands without making huge line lengths. The lines ending in + \ are concatenated until a RUN line that doesn't end in \ is + found. This concatenated set or RUN lines then constitutes one execution. + Tcl will substitute variables and arrange for the pipeline to be executed. If + any process in the pipeline fails, the entire line (and test case) fails too. +

    + +

    Below is an example of legal RUN lines in a .ll file:

    + +
    + 
    + ; RUN: llvm-as < %s | llvm-dis > %t1
+ ; RUN: llvm-dis < %s.bc-13 > %t2
+ ; RUN: diff %t1 %t2
+
    +
    + +

    As with a Unix shell, the RUN: lines permit pipelines and I/O redirection + to be used. However, the usage is slightly different than for Bash. To check + what's legal, see the documentation for the + Tcl exec + command and the + tutorial. + The major differences are:

    +
      +
    • You can't do 2>&1. That will cause Tcl to write to a + file named &1. Usually this is done to get stderr to go through + a pipe. You can do that in tcl with |& so replace this idiom: + ... 2>&1 | grep with ... |& grep
      • +
    • You can only redirect to a file, not to another descriptor and not from + a here document.
      • +
    • tcl supports redirecting to open files with the @ syntax but you + shouldn't use that here.
      • +
    + +

    There are some quoting rules that you must pay attention to when writing + your RUN lines. In general nothing needs to be quoted. Tcl won't strip off any + ' or " so they will get passed to the invoked program. For example:

    + +
    + 
    + ... | grep 'find this string'
+
    +
    + +

    This will fail because the ' characters are passed to grep. This would + instruction grep to look for 'find in the files this and + string'. To avoid this use curly braces to tell Tcl that it should + treat everything enclosed as one value. So our example would become:

    + +
    + 
    + ... | grep {find this string}
+
    +
    + +

    Additionally, the characters [ and ] are treated + specially by Tcl. They tell Tcl to interpret the content as a command to + execute. Since these characters are often used in regular expressions this can + have disastrous results and cause the entire test run in a directory to fail. + For example, a common idiom is to look for some basicblock number:

    + +
    + 
    + ... | grep bb[2-8]
+
    +
    + +

    This, however, will cause Tcl to fail because its going to try to execute + a program named "2-8". Instead, what you want is this:

    + +
    + 
    + ... | grep {bb\[2-8\]}
+
    +
    + +

    Finally, if you need to pass the \ character down to a program, + then it must be doubled. This is another Tcl special character. So, suppose + you had: + +

    + 
    + ... | grep 'i32\*'
+
    +
    + +

    This will fail to match what you want (a pointer to i32). First, the + ' do not get stripped off. Second, the \ gets stripped off + by Tcl so what grep sees is: 'i32*'. That's not likely to match + anything. To resolve this you must use \\ and the {}, like + this:

    + +
    + 
    + ... | grep {i32\\*}
+
    +
    + +
    + + +
    Vars And Substitutions
    +
    +

    With a RUN line there are a number of substitutions that are permitted. In + general, any Tcl variable that is available in the substitute + function (in test/lib/llvm.exp) can be substituted into a RUN line. + To make a substitution just write the variable's name preceded by a $. + Additionally, for compatibility reasons with previous versions of the test + library, certain names can be accessed with an alternate syntax: a % prefix. + These alternates are deprecated and may go away in a future version. +

    +

    Here are the available variable names. The alternate syntax is listed in + parentheses.

    + +
    +
    $test (%s)
    +
    The full path to the test case's source. This is suitable for passing + on the command line as the input to an llvm tool.
    + +
    $srcdir
    +
    The source directory from where the "make check" was run.
    + +
    objdir
    +
    The object directory that corresponds to the $srcdir.
    + +
    subdir
    +
    A partial path from the test directory that contains the + sub-directory that contains the test source being executed.
    + +
    srcroot
    +
    The root directory of the LLVM src tree.
    + +
    objroot
    +
    The root directory of the LLVM object tree. This could be the same + as the srcroot.
    + +
    path
    +
    The path to the directory that contains the test case source. This is + for locating any supporting files that are not generated by the test, but + used by the test.
    + +
    tmp
    +
    The path to a temporary file name that could be used for this test case. + The file name won't conflict with other test cases. You can append to it if + you need multiple temporaries. This is useful as the destination of some + redirected output.
    + +
    llvmlibsdir (%llvmlibsdir)
    +
    The directory where the LLVM libraries are located.
    + +
    target_triplet (%target_triplet)
    +
    The target triplet that corresponds to the current host machine (the one + running the test cases). This should probably be called "host".
    + +
    prcontext (%prcontext)
    +
    Path to the prcontext tcl script that prints some context around a + line that matches a pattern. This isn't strictly necessary as the test suite + is run with its PATH altered to include the test/Scripts directory where + the prcontext script is located. Note that this script is similar to + grep -C but you should use the prcontext script because + not all platforms support grep -C.
    + +
    llvmgcc (%llvmgcc)
    +
    The full path to the llvm-gcc executable as specified in the + configured LLVM environment
    + +
    llvmgxx (%llvmgxx)
    +
    The full path to the llvm-gxx executable as specified in the + configured LLVM environment
    + +
    llvmgcc_version (%llvmgcc_version)
    +
    The full version number of the llvm-gcc executable.
    + +
    llvmgccmajvers (%llvmgccmajvers)
    +
    The major version number of the llvm-gcc executable.
    + +
    gccpath
    +
    The full path to the C compiler used to build LLVM. Note that + this might not be gcc.
    + +
    gxxpath
    +
    The full path to the C++ compiler used to build LLVM. Note that + this might not be g++.
    + +
    compile_c (%compile_c)
    +
    The full command line used to compile LLVM C source code. This has all + the configured -I, -D and optimization options.
    + +
    compile_cxx (%compile_cxx)
    +
    The full command used to compile LLVM C++ source code. This has + all the configured -I, -D and optimization options.
    + +
    link (%link)
    +
    This full link command used to link LLVM executables. This has all the + configured -I, -L and -l options.
    + +
    shlibext (%shlibext)
    +
    The suffix for the host platforms share library (dll) files. This + includes the period as the first character.
    +
    +

    To add more variables, two things need to be changed. First, add a line in + the test/Makefile that creates the site.exp file. This will + "set" the variable as a global in the site.exp file. Second, in the + test/lib/llvm.exp file, in the substitute proc, add the variable name + to the list of "global" declarations at the beginning of the proc. That's it, + the variable can then be used in test scripts.

    +
    + + +
    Other Features
    +
    +

    To make RUN line writing easier, there are several shell scripts located + in the llvm/test/Scripts directory. For example:

    +
    +
    ignore
    +
    This script runs its arguments and then always returns 0. This is useful + in cases where the test needs to cause a tool to generate an error (e.g. to + check the error output). However, any program in a pipeline that returns a + non-zero result will cause the test to fail. This script overcomes that + issue and nicely documents that the test case is purposefully ignoring the + result code of the tool
    + +
    not
    +
    This script runs its arguments and then inverts the result code from + it. Zero result codes become 1. Non-zero result codes become 0. This is + useful to invert the result of a grep. For example "not grep X" means + succeed only if you don't find X in the input.
    +
    + +

    Sometimes it is necessary to mark a test case as "expected fail" or XFAIL. + You can easily mark a test as XFAIL just by including XFAIL: on a + line near the top of the file. This signals that the test case should succeed + if the test fails. Such test cases are counted separately by DejaGnu. To + specify an expected fail, use the XFAIL keyword in the comments of the test + program followed by a colon and one or more regular expressions (separated by + a comma). The regular expressions allow you to XFAIL the test conditionally + by host platform. The regular expressions following the : are matched against + the target triplet or llvmgcc version number for the host machine. If there is + a match, the test is expected to fail. If not, the test is expected to + succeed. To XFAIL everywhere just specify XFAIL: *. When matching + the llvm-gcc version, you can specify the major (e.g. 3) or full version + (i.e. 3.4) number. Here is an example of an XFAIL line:

    + +
    + 
    + ; XFAIL: darwin,sun,llvmgcc4
+
    +
    + +

    To make the output more useful, the llvm_runtest function wil + scan the lines of the test case for ones that contain a pattern that matches + PR[0-9]+. This is the syntax for specifying a PR (Problem Report) number that + is related to the test case. The numer after "PR" specifies the LLVM bugzilla + number. When a PR number is specified, it will be used in the pass/fail + reporting. This is useful to quickly get some context when a test fails.

    + +

    Finally, any line that contains "END." will cause the special + interpretation of lines to terminate. This is generally done right after the + last RUN: line. This has two side effects: (a) it prevents special + interpretation of lines that are part of the test program, not the + instructions to the test case, and (b) it speeds things up for really big test + cases by avoiding interpretation of the remainder of the file.

    + +
    + + +
    llvm-test + Structure
    + + +
    + +

    As mentioned previously, the llvm-test module provides three types + of tests: MultiSource, SingleSource, and External. Each tree is then subdivided + into several categories, including applications, benchmarks, regression tests, + code that is strange grammatically, etc. These organizations should be + relatively self explanatory.

    + +

    In addition to the regular "whole program" tests, the llvm-test + module also provides a mechanism for compiling the programs in different ways. + If the variable TEST is defined on the gmake command line, the test system will + include a Makefile named TEST.<value of TEST variable>.Makefile. + This Makefile can modify build rules to yield different results.

    + +

    For example, the LLVM nightly tester uses TEST.nightly.Makefile to + create the nightly test reports. To run the nightly tests, run gmake + TEST=nightly.

    + +

    There are several TEST Makefiles available in the tree. Some of them are + designed for internal LLVM research and will not work outside of the LLVM + research group. They may still be valuable, however, as a guide to writing your + own TEST Makefile for any optimization or analysis passes that you develop with + LLVM.

    + +

    Note, when configuring the llvm-test module, you might want to + specify the following configuration options:

    +
    +
    --enable-spec2000 +
    --enable-spec2000=<directory> +
    + Enable the use of SPEC2000 when testing LLVM. This is disabled by default + (unless configure finds SPEC2000 installed). By specifying + directory, you can tell configure where to find the SPEC2000 + benchmarks. If directory is left unspecified, configure + uses the default value + /home/vadve/shared/benchmarks/speccpu2000/benchspec. +

    + +

    --enable-spec95 +
    --enable-spec95=<directory> +
    + Enable the use of SPEC95 when testing LLVM. It is similar to the + --enable-spec2000 option. +

    + +

    --enable-povray +
    --enable-povray=<directory> +
    + Enable the use of Povray as an external test. Versions of Povray written + in C should work. This option is similar to the --enable-spec2000 + option. +
    +
    + + +
    Running the LLVM Tests
    + + +
    + +

    First, all tests are executed within the LLVM object directory tree. They + are not executed inside of the LLVM source tree. This is because the + test suite creates temporary files during execution.

    + +

    The master Makefile in llvm/test is capable of running only the + DejaGNU driven tests. By default, it will run all of these tests.

    + +

    To run only the DejaGNU driven tests, run gmake at the + command line in llvm/test. To run a specific directory of tests, use + the TESTSUITE variable. +

    + +

    For example, to run the Regression tests, type + gmake TESTSUITE=Regression in llvm/tests.

    + +

    Note that there are no Makefiles in llvm/test/Features and + llvm/test/Regression. You must use DejaGNU from the llvm/test + directory to run them.

    + +

    To run the llvm-test suite, you need to use the following steps:

    + +
      +
    1. cd into the llvm/projects directory
      2. + +

    2. Check out the test-suite module with:

      + +
      + 
      + % svn co http://llvm.org/svn/llvm-project/test-suite/trunk llvm-test
+
      +
      + +

      This will get the test suite into llvm/projects/llvm-test

      + +

    3. Configure the test suite using llvm configure. This will automatically configure llvm-test. + You must do it from the top level otherwise llvm-gcc will not be set which is required to + run llvm-test:

      +
      + 
      + % cd $LLVM_OBJ_ROOT ; $LLVM_SRC_ROOT/configure --with-llvmgccdir=$LLVM_GCC_DIR
+
      +
      +
    4. gmake
      5. +
    +

    Note that the second and third steps only need to be done once. After you + have the suite checked out and configured, you don't need to do it again (unless + the test code or configure script changes). $LLVM_GCC_DIR is the path to the LLVM + C/C++ FrontEnd

    + +

    To make a specialized test (use one of the + llvm-test/TEST.<type>.Makefiles), just run:

    + +
    + 
    + % gmake TEST=<type> test
+
    +
    + +

    For example, you could run the nightly tester tests using the following + commands:

    + +
    + 
    + % cd llvm/projects/llvm-test
+ % gmake TEST=nightly test
+
    +
    + +

    Regardless of which test you're running, the results are printed on standard + output and standard error. You can redirect these results to a file if you + choose.

    + +

    Some tests are known to fail. Some are bugs that we have not fixed yet; + others are features that we haven't added yet (or may never add). In DejaGNU, + the result for such tests will be XFAIL (eXpected FAILure). In this way, you + can tell the difference between an expected and unexpected failure.

    + +

    The tests in llvm-test have no such feature at this time. If the + test passes, only warnings and other miscellaneous output will be generated. If + a test fails, a large <program> FAILED message will be displayed. This + will help you separate benign warnings from actual test failures.

    + +
    + + +
    + Writing custom tests for llvm-test
    + + +
    + +

    Assuming you can run llvm-test, (e.g. "gmake TEST=nightly report" + should work), it is really easy to run optimizations or code generator + components against every program in the tree, collecting statistics or running + custom checks for correctness. At base, this is how the nightly tester works, + it's just one example of a general framework.

    + +

    Lets say that you have an LLVM optimization pass, and you want to see how + many times it triggers. First thing you should do is add an LLVM + statistic to your pass, which + will tally counts of things you care about.

    + +

    Following this, you can set up a test and a report that collects these and + formats them for easy viewing. This consists of two files, an + "llvm-test/TEST.XXX.Makefile" fragment (where XXX is the name of your + test) and an "llvm-test/TEST.XXX.report" file that indicates how to + format the output into a table. There are many example reports of various + levels of sophistication included with llvm-test, and the framework is very + general.

    + +

    If you are interested in testing an optimization pass, check out the + "libcalls" test as an example. It can be run like this:

    + +

    + 
    + % cd llvm/projects/llvm-test/MultiSource/Benchmarks  # or some other level
+ % make TEST=libcalls report
+
    +
    + +

    This will do a bunch of stuff, then eventually print a table like this:

    + +
    + 
    + Name                                  | total | #exit |
+ ...
+ FreeBench/analyzer/analyzer           | 51    | 6     | 
+ FreeBench/fourinarow/fourinarow       | 1     | 1     | 
+ FreeBench/neural/neural               | 19    | 9     | 
+ FreeBench/pifft/pifft                 | 5     | 3     | 
+ MallocBench/cfrac/cfrac               | 1     | *     | 
+ MallocBench/espresso/espresso         | 52    | 12    | 
+ MallocBench/gs/gs                     | 4     | *     | 
+ Prolangs-C/TimberWolfMC/timberwolfmc  | 302   | *     | 
+ Prolangs-C/agrep/agrep                | 33    | 12    | 
+ Prolangs-C/allroots/allroots          | *     | *     | 
+ Prolangs-C/assembler/assembler        | 47    | *     | 
+ Prolangs-C/bison/mybison              | 74    | *     | 
+ ...
+
    +
    + +

    This basically is grepping the -stats output and displaying it in a table. + You can also use the "TEST=libcalls report.html" target to get the table in HTML + form, similarly for report.csv and report.tex.

    + +

    The source for this is in llvm-test/TEST.libcalls.*. The format is pretty + simple: the Makefile indicates how to run the test (in this case, + "opt -simplify-libcalls -stats"), and the report contains one line for + each column of the output. The first value is the header for the column and the + second is the regex to grep the output of the command for. There are lots of + example reports that can do fancy stuff.

    + +
    + + + +
    Running the nightly tester
    + + +
    + +

    + The LLVM Nightly Testers + automatically check out an LLVM tree, build it, run the "nightly" + program test (described above), run all of the feature and regression tests, + delete the checked out tree, and then submit the results to + http://llvm.org/nightlytest/. + After test results are submitted to + http://llvm.org/nightlytest/, + they are processed and displayed on the tests page. An email to + + llvm-testresults at cs.uiuc.edu summarizing the results is also generated. + This testing scheme is designed to ensure that programs don't break as well + as keep track of LLVM's progress over time.

    + +

    If you'd like to set up an instance of the nightly tester to run on your + machine, take a look at the comments at the top of the + utils/NewNightlyTest.pl file. If you decide to set up a nightly tester + please choose a unique nickname and invoke utils/NewNightlyTest.pl + with the "-nickname [yournickname]" command line option. + +

    You can create a shell script to encapsulate the running of the script. + The optimized x86 Linux nightly test is run from just such a script:

    + +
    + 
    + #!/bin/bash
+ BASE=/proj/work/llvm/nightlytest
+ export BUILDDIR=$BASE/build 
+ export WEBDIR=$BASE/testresults 
+ export LLVMGCCDIR=/proj/work/llvm/cfrontend/install
+ export PATH=/proj/install/bin:$LLVMGCCDIR/bin:$PATH
+ export LD_LIBRARY_PATH=/proj/install/lib
+ cd $BASE
+ cp /proj/work/llvm/llvm/utils/NewNightlyTest.pl .
+ nice ./NewNightlyTest.pl -nice -release -verbose -parallel -enable-linscan \
+    -nickname NightlyTester -noexternals > output.log 2>&1 
+
    +
    + +

    It is also possible to specify the the location your nightly test results + are submitted. You can do this by passing the command line option + "-submit-server [server_address]" and "-submit-script [script_on_server]" to + utils/NewNightlyTest.pl. For example, to submit to the llvm.org + nightly test results page, you would invoke the nightly test script with + "-submit-server llvm.org -submit-script /nightlytest/NightlyTestAccept.cgi". + If these options are not specified, the nightly test script sends the results + to the llvm.org nightly test results page.

    + +

    Take a look at the NewNightlyTest.pl file to see what all of the + flags and strings do. If you start running the nightly tests, please let us + know. Thanks!

    + +
    + + + +
    +
    + Valid CSS! + Valid HTML 4.01! + + John T. Criswell, Reid Spencer, and Tanya Lattner
    + The LLVM Compiler Infrastructure
    + Last modified: $Date: 2008/02/12 06:05:03 $ +
    + + Index: llvm-www/releases/2.2/docs/UsingLibraries.html diff -c /dev/null llvm-www/releases/2.2/docs/UsingLibraries.html:1.1 *** /dev/null Tue Feb 12 00:07:05 2008 --- llvm-www/releases/2.2/docs/UsingLibraries.html Tue Feb 12 00:05:03 2008 *************** *** 0 **** --- 1,449 ---- + + + + Using The LLVM Libraries + + + +
    Using The LLVM Libraries
    +
      +
    1. Abstract
      2. +
    2. Introduction
      3. +
    3. Library Descriptions
      4. +
    4. Library Dependencies
      5. +
    5. Linkage Rules Of Thumb +
        +
      1. Always link LLVMCore, LLVMSupport, LLVMSystem +
      2. Never link both archive and re-linked +
      +
      6. +
    + +
    +

    Written by Reid Spencer

    +
    + +

    Warning: This document is out of date, please see llvm-config for more information.

    + + +
    Abstract
    +
    +

    Amongst other things, LLVM is a toolkit for building compilers, linkers, + runtime executives, virtual machines, and other program execution related + tools. In addition to the LLVM tool set, the functionality of LLVM is + available through a set of libraries. To use LLVM as a toolkit for + constructing tools, a developer needs to understand what is contained in the + various libraries, what they depend on, and how to use them. Fortunately, + there is a tool, llvm-config to aid with this. This document + describes the contents of the libraries and how to use llvm-config + to generate command line options. +

    +
    + + +
    Introduction
    +
    +

    If you're writing a compiler, virtual machine, or any other utility based + on LLVM, you'll need to figure out which of the many libraries files you will + need to link with to be successful. An understanding of the contents of these + libraries will be useful in coming up with an optimal specification for the + libraries to link with. The purpose of this document is to reduce some of + the trial and error that the author experienced in using LLVM.

    +

    LLVM produces two types of libraries: archives (ending in .a) and + objects (ending in .o). However, both are libraries. Libraries ending + in .o are known as re-linked libraries because they contain all the + compilation units of the library linked together as a single .o file. + Furthermore, several of the libraries have both forms of library. The + re-linked libraries are used whenever you want to include all symbols from the + library. The archive libraries are used whenever you want to only resolve + outstanding symbols at that point in the link without including everything in + the library.

    +

    If you're using the LLVM Makefile system to link your tools,you will use + the LLVMLIBS make variable. + (see the Makefile Guide for + details). This variable specifies which LLVM libraries to link into your tool + and the order in which they will be linked. You specify re-linked libraries by + naming the library without a suffix. You specify archive libraries by naming + the library with a .a suffix but without the lib prefix. The + order in which the libraries appear in the LLVMLIBS variable + definition is the order in which they will be linked. Getting this order + correct for your tool can sometimes be challenging. +

    + +
    Library Descriptions
    +
    +

    The table below categorizes each library + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    LibraryFormsDescription
    Core Libraries
    LLVMArchive.aLLVM archive reading and writing
    LLVMAsmParser.aLLVM assembly parsing
    LLVMBCReader.aLLVM bitcode reading
    LLVMBCWriter.aLLVM bitcode writing
    LLVMCore.aLLVM core intermediate representation
    LLVMDebugger.aSource level debugging support
    LLVMLinker.aBitcode and archive linking interface
    LLVMSupport.aGeneral support utilities
    LLVMSystem.aOperating system abstraction layer
    LLVMbzip2.aBZip2 compression library
    Analysis Libraries
    LLVMAnalysis.aVarious analysis passes.
    LLVMDataStructure.oData structure analysis passes.
    LLVMipa.aInter-procedural analysis passes.
    Transformation Libraries
    LLVMInstrumentation.aInstrumentation passes.
    LLVMipo.aAll inter-procedural optimization passes.
    LLVMScalarOpts.aAll scalar optimization passes.
    LLVMTransformUtils.aTransformation utilities used by many passes.
    Code Generation Libraries
    LLVMCodeGen.oNative code generation infrastructure
    LLVMSelectionDAG.oAggressive instruction selector for directed acyclic graphs
    Target Libraries
    LLVMAlpha.oCode generation for Alpha architecture
    LLVMARM.oCode generation for ARM architecture
    LLVMCBackend.o'C' language code generator.
    LLVMIA64.oCode generation for IA64 architecture
    LLVMPowerPC.oCode generation for PowerPC architecture
    LLVMSparc.oCode generation for Sparc architecture
    LLVMTarget.aGeneric code generation utilities.
    LLVMX86.oCode generation for Intel x86 architecture
    Runtime Libraries
    LLVMInterpreter.oBitcode Interpreter
    LLVMJIT.oBitcode JIT Compiler
    LLVMExecutionEngine.oVirtual machine engine
    +

    + + +
    Using llvm-config
    +
    +

    The llvm-config tool is a perl script that produces on its output + various kinds of information. For example, the source or object directories + used to build LLVM can be accessed by passing options to llvm-config. + For complete details on this tool, please see the + manual page.

    +

    To understand the relationships between libraries, the llvm-config + can be very useful. If all you know is that you want certain libraries to + be available, you can generate the complete set of libraries to link with + using one of four options, as below:

    +
      +
    1. --ldflags. This generates the command line options necessary to + be passed to the ld tool in order to link with LLVM. Most notably, + the -L option is provided to specify a library search directory + that contains the LLVM libraries.
      2. +
    2. --libs. This generates command line options suitable for + use with a gcc-style linker. That is, libraries are given with a -l option + and object files are given with a full path.
      3. +
    3. --libnames. This generates a list of just the library file + names. If you know the directory in which these files reside (see --ldflags) + then you can find the libraries there.
      4. +
    4. --libfiles. This generates the full path names of the + LLVM library files.
      5. +
    +

    If you wish to delve further into how llvm-config generates the + correct order (based on library dependencies), please see the tool named + GenLibDeps.pl in the utils source directory of LLVM.

    + + + + + + + +

    Dependency Relationships Of Libraries

    +

    This graph shows the dependency of archive libraries on other archive + libraries or objects. Where a library has both archive and object forms, only + the archive form is shown.

    + Library Dependencies +

    Dependency Relationships Of Object Files

    +

    This graph shows the dependency of object files on archive libraries or + other objects. Where a library has both object and archive forms, only the + dependency to the archive form is shown.

    + Object File Dependencies +

    The following list shows the dependency relationships between libraries in + textual form. The information is the same as shown on the graphs but arranged + alphabetically.

    +
    +
    libLLVMAnalysis.a
      +
    • libLLVMCore.a
      • +
    • libLLVMSupport.a
      • +
    • libLLVMSystem.a
      • +
    • libLLVMTarget.a
      • +
    +
    libLLVMArchive.a
      +
    • libLLVMBCReader.a
      • +
    • libLLVMCore.a
      • +
    • libLLVMSupport.a
      • +
    • libLLVMSystem.a
      • +
    +
    libLLVMAsmParser.a
      +
    • libLLVMCore.a
      • +
    • libLLVMSystem.a
      • +
    +
    libLLVMBCReader.a
      +
    • libLLVMCore.a
      • +
    • libLLVMSupport.a
      • +
    • libLLVMSystem.a
      • +
    +
    libLLVMBCWriter.a
      +
    • libLLVMCore.a
      • +
    • libLLVMSupport.a
      • +
    • libLLVMSystem.a
      • +
    +
    libLLVMCodeGen.a
      +
    • libLLVMAnalysis.a
      • +
    • libLLVMCore.a
      • +
    • libLLVMScalarOpts.a
      • +
    • libLLVMSupport.a
      • +
    • libLLVMSystem.a
      • +
    • libLLVMTarget.a
      • +
    • libLLVMTransformUtils.a
      • +
    +
    libLLVMCore.a
      +
    • libLLVMSupport.a
      • +
    • libLLVMSystem.a
      • +
    +
    libLLVMDebugger.a
      +
    • libLLVMBCReader.a
      • +
    • libLLVMCore.a
      • +
    • libLLVMSupport.a
      • +
    • libLLVMSystem.a
      • +
    +
    libLLVMInstrumentation.a
      +
    • libLLVMCore.a
      • +
    • libLLVMScalarOpts.a
      • +
    • libLLVMSupport.a
      • +
    • libLLVMTransformUtils.a
      • +
    +
    libLLVMLinker.a
      +
    • libLLVMArchive.a
      • +
    • libLLVMBCReader.a
      • +
    • libLLVMCore.a
      • +
    • libLLVMSupport.a
      • +
    • libLLVMSystem.a
      • +
    +
    libLLVMScalarOpts.a
      +
    • libLLVMAnalysis.a
      • +
    • libLLVMCore.a
      • +
    • libLLVMSupport.a
      • +
    • libLLVMSystem.a
      • +
    • libLLVMTarget.a
      • +
    • libLLVMTransformUtils.a
      • +
    +
    libLLVMSelectionDAG.a
      +
    • libLLVMAnalysis.a
      • +
    • libLLVMCodeGen.a
      • +
    • libLLVMCore.a
      • +
    • libLLVMSupport.a
      • +
    • libLLVMSystem.a
      • +
    • libLLVMTarget.a
      • +
    • libLLVMTransformUtils.a
      • +
    +
    libLLVMSupport.a
      +
    • libLLVMSystem.a
      • +
    • libLLVMbzip2.a
      • +
    +
    libLLVMSystem.a
      +
    +
    libLLVMTarget.a
      +
    • libLLVMCore.a
      • +
    • libLLVMSupport.a
      • +
    • libLLVMSystem.a
      • +
    +
    libLLVMTransformUtils.a
      +
    • libLLVMAnalysis.a
      • +
    • libLLVMCore.a
      • +
    • libLLVMSupport.a
      • +
    • libLLVMSystem.a
      • +
    • libLLVMTarget.a
      • +
    • libLLVMipa.a
      • +
    +
    libLLVMbzip2.a
      +
    +
    libLLVMipa.a
      +
    • libLLVMAnalysis.a
      • +
    • libLLVMCore.a
      • +
    • libLLVMSupport.a
      • +
    • libLLVMSystem.a
      • +
    +
    libLLVMipo.a
      +
    • libLLVMAnalysis.a
      • +
    • libLLVMCore.a
      • +
    • libLLVMSupport.a
      • +
    • libLLVMSystem.a
      • +
    • libLLVMTarget.a
      • +
    • libLLVMTransformUtils.a
      • +
    • libLLVMipa.a
      • +
    +
    libLLVMlto.a
      +
    • libLLVMAnalysis.a
      • +
    • libLLVMBCReader.a
      • +
    • libLLVMBCWriter.a
      • +
    • libLLVMCore.a
      • +
    • libLLVMLinker.a
      • +
    • libLLVMScalarOpts.a
      • +
    • libLLVMSupport.a
      • +
    • libLLVMSystem.a
      • +
    • libLLVMTarget.a
      • +
    • libLLVMipa.a
      • +
    • libLLVMipo.a
      • +
    +
    LLVMARM.o
      +
    • libLLVMCodeGen.a
      • +
    • libLLVMCore.a
      • +
    • libLLVMSelectionDAG.a
      • +
    • libLLVMSupport.a
      • +
    • libLLVMSystem.a
      • +
    • libLLVMTarget.a
      • +
    +
    LLVMAlpha.o
      +
    • libLLVMCodeGen.a
      • +
    • libLLVMCore.a
      • +
    • libLLVMSelectionDAG.a
      • +
    • libLLVMSupport.a
      • +
    • libLLVMSystem.a
      • +
    • libLLVMTarget.a
      • +
    +
    LLVMCBackend.o
      +
    • libLLVMAnalysis.a
      • +
    • libLLVMCodeGen.a
      • +
    • libLLVMCore.a
      • +
    • libLLVMScalarOpts.a
      • +
    • libLLVMSupport.a
      • +
    • libLLVMSystem.a
      • +
    • libLLVMTarget.a
      • +
    • libLLVMTransformUtils.a
      • +
    • libLLVMipa.a
      • +
    +
    LLVMExecutionEngine.o
      +
    • libLLVMCore.a
      • +
    • libLLVMSupport.a
      • +
    • libLLVMSystem.a
      • +
    • libLLVMTarget.a
      • +
    +
    LLVMIA64.o
      +
    • libLLVMCodeGen.a
      • +
    • libLLVMCore.a
      • +
    • libLLVMSelectionDAG.a
      • +
    • libLLVMSupport.a
      • +
    • libLLVMSystem.a
      • +
    • libLLVMTarget.a
      • +
    +
    LLVMInterpreter.o
      +
    • LLVMExecutionEngine.o
      • +
    • libLLVMCodeGen.a
      • +
    • libLLVMCore.a
      • +
    • libLLVMSupport.a
      • +
    • libLLVMSystem.a
      • +
    • libLLVMTarget.a
      • +
    +
    LLVMJIT.o
      +
    • LLVMExecutionEngine.o
      • +
    • libLLVMCore.a
      • +
    • libLLVMSupport.a
      • +
    • libLLVMSystem.a
      • +
    • libLLVMTarget.a
      • +
    +
    LLVMPowerPC.o
      +
    • libLLVMCodeGen.a
      • +
    • libLLVMCore.a
      • +
    • libLLVMSelectionDAG.a
      • +
    • libLLVMSupport.a
      • +
    • libLLVMSystem.a
      • +
    • libLLVMTarget.a
      • +
    +
    LLVMSparc.o
      +
    • libLLVMCodeGen.a
      • +
    • libLLVMCore.a
      • +
    • libLLVMSelectionDAG.a
      • +
    • libLLVMSupport.a
      • +
    • libLLVMSystem.a
      • +
    • libLLVMTarget.a
      • +
    +
    LLVMX86.o
      +
    • libLLVMCodeGen.a
      • +
    • libLLVMCore.a
      • +
    • libLLVMSelectionDAG.a
      • +
    • libLLVMSupport.a
      • +
    • libLLVMSystem.a
      • +
    • libLLVMTarget.a
      • +
    +
    +
    + + +
    Linkage Rules Of Thumb
    +
    +

    This section contains various "rules of thumb" about what files you + should link into your programs.

    +
    + +
    Always Link LLVMCore, LLVMSupport, + and LLVMSystem
    +
    +

    No matter what you do with LLVM, the last three entries in the value of + your LLVMLIBS make variable should always be: + LLVMCore LLVMSupport.a LLVMSystem.a. There are no LLVM + programs that don't depend on these three.

    +
    + +
    Never link both archive and + re-linked library
    +
    +

    There is never any point to linking both the re-linked (.o) and + the archive (.a) versions of a library. Since the re-linked version + includes the entire library, the archive version will not resolve any symbols. + You could even end up with link error if you place the archive version before + the re-linked version on the linker's command line.

    +
    + +
    +
    +
    + Valid CSS! + Valid HTML 4.01! + Reid Spencer +
    + The LLVM Compiler Infrastructure +
    Last modified: $Date: 2008/02/12 06:05:03 $
    + + + Index: llvm-www/releases/2.2/docs/WritingAnLLVMBackend.html diff -c /dev/null llvm-www/releases/2.2/docs/WritingAnLLVMBackend.html:1.1 *** /dev/null Tue Feb 12 00:07:05 2008 --- llvm-www/releases/2.2/docs/WritingAnLLVMBackend.html Tue Feb 12 00:05:03 2008 *************** *** 0 **** --- 1,260 ---- + + + + Writing an LLVM backend + + + + + +
    + Writing an LLVM backend +
    + +
      +
    1. Introduction +
    2. Writing a backend +
        +
      1. Machine backends +
          +
        1. Outline
          2. +
        2. Implementation details
          3. +
        2. +
      2. Language backends
        3. +
      3. +
    3. Related reading material +
    + +
    +

    Written by Misha Brukman

    +
    + + +
    + Introduction +
    + + +
    + +

    This document describes techniques for writing backends for LLVM which + convert the LLVM representation to machine assembly code or other languages.

    + +
    + + +
    + Writing a backend +
    + + + +
    + Machine backends +
    + + +
    + Outline +
    + +
    + +

    In general, you want to follow the format of SPARC, X86 or PowerPC (in + lib/Target). SPARC is the simplest backend, and is RISC, so if + you're working on a RISC target, it is a good one to start with.

    + +

    To create a static compiler (one that emits text assembly), you need to + implement the following:

    + +
      +
    • Describe the register set. +
        +
      • Create a TableGen description of + the register set and register classes
        • +
      • Implement a subclass of MRegisterInfo
        • +
      • +
    • Describe the instruction set. +
      • +
    • Describe the target machine. +
        +
      • Create a TableGen description of + the target that describes the pointer size and references the instruction + set
        • +
      • Implement a subclass of TargetMachine, which + configures TargetData + correctly
        • +
      • Register your new target using the RegisterTarget + template:

        + 
        + RegisterTarget<MyTargetMachine> M("short_name", "  Target name");
+
        +
        Here, MyTargetMachine is the name of your implemented + subclass of TargetMachine, + short_name is the option that will be active following + -march= to select a target in llc and lli, and the last string + is the description of your target to appear in -help + listing.
        • +
      • +
    • Implement the assembly printer for the architecture. +
        +
      • Define all of the assembly strings for your target, adding them to the + instructions in your *InstrInfo.td file.
        • +
      • Implement the llvm::AsmPrinter interface.
        • +
      +
      • +
    • Implement an instruction selector for the architecture. +
        +
      • The recommended method is the + pattern-matching DAG-to-DAG instruction selector (for example, see + the PowerPC backend in PPCISelDAGtoDAG.cpp). Parts of instruction + selector creation can be performed by adding patterns to the instructions + in your .td file.
        • +
      +
      • +
    • Optionally, add subtarget support. +
        +
      • If your target has multiple subtargets (e.g. variants with different + capabilities), implement the llvm::TargetSubtarget interface + for your architecture. This allows you to add -mcpu= and + -mattr= options.
        • +
      +
    • Optionally, add JIT support. +
        +
      • Create a subclass of TargetJITInfo
        • +
      • Create a machine code emitter that will be used to emit binary code + directly into memory, given MachineInstrs
        • +
      +
    +
    + + +
    + Implementation details +
    + +
    + +
      + +

    • TableGen register info description - describe a class which + will store the register's number in the binary encoding of the instruction + (e.g., for JIT purposes).

      + +

      You also need to define register classes to contain these registers, such as + the integer register class and floating-point register class, so that you can + allocate virtual registers to instructions from these sets, and let the + target-independent register allocator automatically choose the actual + architected registers.

      + +
      + 
      + // class Register is defined in Target.td
+ class TargetReg<string name> : Register<name> {
+   let Namespace = "Target";
+ }
+ 
+ class IntReg<bits<5> num, string name> : TargetReg<name> {
+   field bits<5> Num = num;
+ }
+ 
+ def R0 : IntReg<0, "%R0">;
+ ...
+ 
+ // class RegisterClass is defined in Target.td
+ def IReg : RegisterClass<i64, 64, [R0, ... ]>;
+
      +
      +
      • + +

    • TableGen instruction info description - break up instructions into + classes, usually that's already done by the manufacturer (see instruction + manual). Define a class for each instruction category. Define each opcode as a + subclass of the category, with appropriate parameters such as the fixed binary + encoding of opcodes and extended opcodes, and map the register bits to the bits + of the instruction which they are encoded in (for the JIT). Also specify how + the instruction should be printed so it can use the automatic assembly printer, + e.g.:

      + +
      + 
      + // class Instruction is defined in Target.td
+ class Form<bits<6> opcode, dag OL, string asmstr> : Instruction {
+   field bits<42> Inst;
+ 
+   let Namespace = "Target";
+   let Inst{0-6} = opcode;
+   let OperandList = OL;
+   let AsmString = asmstr;
+ }
+ 
+ def ADD : Form<42, (ops IReg:$rD, IReg:$rA, IReg:$rB), "add $rD, $rA, $rB">;
+
      +
      +
      • + +
    + +
    + + +
    + Language backends +
    + +
    + +

    For now, just take a look at lib/Target/CBackend for an example of + how the C backend is written.

    + +
    + + +
    + Related reading material +
    + + +
    + + + +
    + + + +
    +
    + Valid CSS! + Valid HTML 4.01! + + Misha Brukman
    + The LLVM Compiler Infrastructure +
    + Last modified: $Date: 2008/02/12 06:05:03 $ +
    + + + Index: llvm-www/releases/2.2/docs/WritingAnLLVMPass.html diff -c /dev/null llvm-www/releases/2.2/docs/WritingAnLLVMPass.html:1.1 *** /dev/null Tue Feb 12 00:07:05 2008 --- llvm-www/releases/2.2/docs/WritingAnLLVMPass.html Tue Feb 12 00:05:03 2008 *************** *** 0 **** --- 1,1819 ---- + + + + + Writing an LLVM Pass + + + + +
    + Writing an LLVM Pass +
    + +
      +
    1. Introduction - What is a pass?
      2. +
    2. Quick Start - Writing hello world +
      3. +
    3. Pass classes and requirements + +
    4. Pass Registration +
      5. +
    5. Specifying interactions between passes +
      6. +
    6. Implementing Analysis Groups +
      7. +
    7. Pass Statistics +
    8. What PassManager does +
      9. +
    9. Registering dynamically loaded passes +
      10. +
    10. Using GDB with dynamically loaded passes +
      11. +
    11. Future extensions planned +
      12. +
    + +
    +

    Written by Chris Lattner and + Jim Laskey

    +
    + + +
    + Introduction - What is a pass? +
    + + +
    + +

    The LLVM Pass Framework is an important part of the LLVM system, because LLVM + passes are where most of the interesting parts of the compiler exist. Passes + perform the transformations and optimizations that make up the compiler, they + build the analysis results that are used by these transformations, and they are, + above all, a structuring technique for compiler code.

    + +

    All LLVM passes are subclasses of the Pass + class, which implement functionality by overriding virtual methods inherited + from Pass. Depending on how your pass works, you should inherit from + the ModulePass, CallGraphSCCPass, FunctionPass, or LoopPass, or BasicBlockPass classes, which gives the system + more information about what your pass does, and how it can be combined with + other passes. One of the main features of the LLVM Pass Framework is that it + schedules passes to run in an efficient way based on the constraints that your + pass meets (which are indicated by which class they derive from).

    + +

    We start by showing you how to construct a pass, everything from setting up + the code, to compiling, loading, and executing it. After the basics are down, + more advanced features are discussed.

    + +
    + + +
    + Quick Start - Writing hello world +
    + + +
    + +

    Here we describe how to write the "hello world" of passes. The "Hello" pass + is designed to simply print out the name of non-external functions that exist in + the program being compiled. It does not modify the program at all, it just + inspects it. The source code and files for this pass are available in the LLVM + source tree in the lib/Transforms/Hello directory.

    + +
    + + +
    + Setting up the build environment +
    + +
    + +

    First, you need to create a new directory somewhere in the LLVM source + base. For this example, we'll assume that you made + lib/Transforms/Hello. Next, you must set up a build script + (Makefile) that will compile the source code for the new pass. To do this, + copy the following into Makefile:

    +
    + + 
    + # Makefile for hello pass
+ 
+ # Path to top level of LLVM heirarchy
+ LEVEL = ../../..
+ 
+ # Name of the library to build
+ LIBRARYNAME = Hello
+ 
+ # Make the shared library become a loadable module so the tools can 
+ # dlopen/dlsym on the resulting library.
+ LOADABLE_MODULE = 1
+ 
+ # Tell the build system which LLVM libraries your pass needs. You'll probably
+ # need at least LLVMSystem.a, LLVMSupport.a, LLVMCore.a but possibly several
+ # others too.
+ LLVMLIBS = LLVMCore.a LLVMSupport.a LLVMSystem.a
+ 
+ # Include the makefile implementation stuff
+ include $(LEVEL)/Makefile.common
+
    + +

    This makefile specifies that all of the .cpp files in the current + directory are to be compiled and linked together into a + Debug/lib/Hello.so shared object that can be dynamically loaded by + the opt or bugpoint tools via their -load options. + If your operating system uses a suffix other than .so (such as windows or + Mac OS/X), the appropriate extension will be used.

    + +

    Now that we have the build scripts set up, we just need to write the code for + the pass itself.

    + +
    + + +
    + Basic code required +
    + +
    + +

    Now that we have a way to compile our new pass, we just have to write it. + Start out with:

    + + 
    + #include "llvm/Pass.h"
+ #include "llvm/Function.h"
+
    + +

    Which are needed because we are writing a Pass, and + we are operating on Function's.

    + +

    Next we have:

    + 
    + using namespace llvm;
+
    +

    ... which is required because the functions from the include files + live in the llvm namespace. +

    + +

    Next we have:

    + + 
    + namespace {
+
    + +

    ... which starts out an anonymous namespace. Anonymous namespaces are to C++ + what the "static" keyword is to C (at global scope). It makes the + things declared inside of the anonymous namespace only visible to the current + file. If you're not familiar with them, consult a decent C++ book for more + information.

    + +

    Next, we declare our pass itself:

    + + 
    +   struct Hello : public FunctionPass {
+

    + +

    This declares a "Hello" class that is a subclass of FunctionPass. + The different builtin pass subclasses are described in detail later, but for now, know that FunctionPass's operate a function at a + time.

    + + 
    +      static char ID;
+      Hello() : FunctionPass((intptr_t)&ID) {}
+

    + +

    This declares pass identifier used by LLVM to identify pass. This allows LLVM to + avoid using expensive C++ runtime information.

    + + 
    +     virtual bool runOnFunction(Function &F) {
+       llvm::cerr << "Hello: " << F.getName() << "\n";
+       return false;
+     }
+   };  // end of struct Hello
+
    + +

    We declare a "runOnFunction" method, + which overloads an abstract virtual method inherited from FunctionPass. This is where we are supposed + to do our thing, so we just print out our message with the name of each + function.

    + + 
    +   char Hello::ID = 0;
+
    + +

    We initialize pass ID here. LLVM uses ID's address to identify pass so + initialization value is not important.

    + + 
    +   RegisterPass<Hello> X("hello", "Hello World Pass");
+ }  // end of anonymous namespace
+
    + +

    Lastly, we register our class Hello, + giving it a command line + argument "hello", and a name "Hello World Pass".

    + +

    As a whole, the .cpp file looks like:

    + + 
    + #include "llvm/Pass.h"
+ #include "llvm/Function.h"
+ 
+ using namespace llvm;
+ 
+ namespace {
+   struct Hello : public FunctionPass {
+     
+     static char ID;
+     Hello() : FunctionPass((intptr_t)&ID) {}
+ 
+     virtual bool runOnFunction(Function &F) {
+       llvm::cerr << "Hello: " << F.getName() << "\n";
+       return false;
+     }
+   };
+   
+   char Hello::ID = 0;
+   RegisterPass<Hello> X("hello", "Hello World Pass");
+ }
+
    + +

    Now that it's all together, compile the file with a simple "gmake" + command in the local directory and you should get a new + "Debug/lib/Hello.so file. Note that everything in this file is + contained in an anonymous namespace: this reflects the fact that passes are self + contained units that do not need external interfaces (although they can have + them) to be useful.

    + +
    + + +
    + Running a pass with opt +
    + +
    + +

    Now that you have a brand new shiny shared object file, we can use the + opt command to run an LLVM program through your pass. Because you + registered your pass with the RegisterPass template, you will be able to + use the opt tool to access it, once loaded.

    + +

    To test it, follow the example at the end of the Getting Started Guide to compile "Hello World" to + LLVM. We can now run the bitcode file (hello.bc) for the program + through our transformation like this (or course, any bitcode file will + work):

    + + 
    + $ opt -load ../../../Debug/lib/Hello.so -hello < hello.bc > /dev/null
+ Hello: __main
+ Hello: puts
+ Hello: main
+
    + +

    The '-load' option specifies that 'opt' should load your + pass as a shared object, which makes '-hello' a valid command line + argument (which is one reason you need to register your + pass). Because the hello pass does not modify the program in any + interesting way, we just throw away the result of opt (sending it to + /dev/null).

    + +

    To see what happened to the other string you registered, try running + opt with the --help option:

    + + 
    + $ opt -load ../../../Debug/lib/Hello.so --help
+ OVERVIEW: llvm .bc -> .bc modular optimizer
+ 
+ USAGE: opt [options] <input bitcode>
+ 
+ OPTIONS:
+   Optimizations available:
+ ...
+     -funcresolve    - Resolve Functions
+     -gcse           - Global Common Subexpression Elimination
+     -globaldce      - Dead Global Elimination
+     -hello          - Hello World Pass
+     -indvars        - Canonicalize Induction Variables
+     -inline         - Function Integration/Inlining
+     -instcombine    - Combine redundant instructions
+ ...
+
    + +

    The pass name get added as the information string for your pass, giving some + documentation to users of opt. Now that you have a working pass, you + would go ahead and make it do the cool transformations you want. Once you get + it all working and tested, it may become useful to find out how fast your pass + is. The PassManager provides a nice command + line option (--time-passes) that allows you to get information about + the execution time of your pass along with the other passes you queue up. For + example:

    + + 
    + $ opt -load ../../../Debug/lib/Hello.so -hello -time-passes < hello.bc > /dev/null
+ Hello: __main
+ Hello: puts
+ Hello: main
+ ===============================================================================
+                       ... Pass execution timing report ...
+ ===============================================================================
+   Total Execution Time: 0.02 seconds (0.0479059 wall clock)
+ 
+    ---User Time---   --System Time--   --User+System--   ---Wall Time---  --- Pass Name ---
+    0.0100 (100.0%)   0.0000 (  0.0%)   0.0100 ( 50.0%)   0.0402 ( 84.0%)  Bitcode Writer
+    0.0000 (  0.0%)   0.0100 (100.0%)   0.0100 ( 50.0%)   0.0031 (  6.4%)  Dominator Set Construction
+    0.0000 (  0.0%)   0.0000 (  0.0%)   0.0000 (  0.0%)   0.0013 (  2.7%)  Module Verifier
+    0.0000 (  0.0%)   0.0000 (  0.0%)   0.0000 (  0.0%)   0.0033 (  6.9%)  Hello World Pass
+    0.0100 (100.0%)   0.0100 (100.0%)   0.0200 (100.0%)   0.0479 (100.0%)  TOTAL
+
    + +

    As you can see, our implementation above is pretty fast :). The additional + passes listed are automatically inserted by the 'opt' tool to verify + that the LLVM emitted by your pass is still valid and well formed LLVM, which + hasn't been broken somehow.

    + +

    Now that you have seen the basics of the mechanics behind passes, we can talk + about some more details of how they work and how to use them.

    + +
    + + +
    + Pass classes and requirements +
    + + +
    + +

    One of the first things that you should do when designing a new pass is to + decide what class you should subclass for your pass. The Hello World example uses the FunctionPass class for its implementation, but we + did not discuss why or when this should occur. Here we talk about the classes + available, from the most general to the most specific.

    + +

    When choosing a superclass for your Pass, you should choose the most + specific class possible, while still being able to meet the requirements + listed. This gives the LLVM Pass Infrastructure information necessary to + optimize how passes are run, so that the resultant compiler isn't unneccesarily + slow.

    + +
    + + +
    + The ImmutablePass class +
    + +
    + +

    The most plain and boring type of pass is the "ImmutablePass" + class. This pass type is used for passes that do not have to be run, do not + change state, and never need to be updated. This is not a normal type of + transformation or analysis, but can provide information about the current + compiler configuration.

    + +

    Although this pass class is very infrequently used, it is important for + providing information about the current target machine being compiled for, and + other static information that can affect the various transformations.

    + +

    ImmutablePasses never invalidate other transformations, are never + invalidated, and are never "run".

    + +
    + + +
    + The ModulePass class +
    + +
    + +

    The "ModulePass" + class is the most general of all superclasses that you can use. Deriving from + ModulePass indicates that your pass uses the entire program as a unit, + refering to function bodies in no predictable order, or adding and removing + functions. Because nothing is known about the behavior of ModulePass + subclasses, no optimization can be done for their execution. A module pass + can use function level passes (e.g. dominators) using getAnalysis interface + getAnalysis<DominatorTree>(Function).

    + +

    To write a correct ModulePass subclass, derive from + ModulePass and overload the runOnModule method with the + following signature:

    + +
    + + +
    + The runOnModule method +
    + +
    + + 
    +   virtual bool runOnModule(Module &M) = 0;
+
    + +

    The runOnModule method performs the interesting work of the pass. + It should return true if the module was modified by the transformation and + false otherwise.

    + +
    + + +
    + The CallGraphSCCPass class +
    + +
    + +

    The "CallGraphSCCPass" + is used by passes that need to traverse the program bottom-up on the call graph + (callees before callers). Deriving from CallGraphSCCPass provides some + mechanics for building and traversing the CallGraph, but also allows the system + to optimize execution of CallGraphSCCPass's. If your pass meets the + requirements outlined below, and doesn't meet the requirements of a FunctionPass or BasicBlockPass, you should derive from + CallGraphSCCPass.

    + +

    TODO: explain briefly what SCC, Tarjan's algo, and B-U mean.

    + +

    To be explicit, CallGraphSCCPass subclasses are:

    + +
      + +
    1. ... not allowed to modify any Functions that are not in + the current SCC.
      2. + +
    2. ... not allowed to inspect any Function's other than those in the + current SCC and the direct callees of the SCC.
      3. + +
    3. ... required to preserve the current CallGraph object, updating it + to reflect any changes made to the program.
      4. + +
    4. ... not allowed to add or remove SCC's from the current Module, + though they may change the contents of an SCC.
      5. + +
    5. ... allowed to add or remove global variables from the current + Module.
      6. + +
    6. ... allowed to maintain state across invocations of + runOnSCC (including global data).
      7. +
    + +

    Implementing a CallGraphSCCPass is slightly tricky in some cases + because it has to handle SCCs with more than one node in it. All of the virtual + methods described below should return true if they modified the program, or + false if they didn't.

    + +
    + + +
    + The doInitialization(CallGraph &) + method +
    + +
    + + 
    +   virtual bool doInitialization(CallGraph &CG);
+
    + +

    The doIninitialize method is allowed to do most of the things that + CallGraphSCCPass's are not allowed to do. They can add and remove + functions, get pointers to functions, etc. The doInitialization method + is designed to do simple initialization type of stuff that does not depend on + the SCCs being processed. The doInitialization method call is not + scheduled to overlap with any other pass executions (thus it should be very + fast).

    + +
    + + +
    + The runOnSCC method +
    + +
    + + 
    +   virtual bool runOnSCC(const std::vector<CallGraphNode *> &SCCM) = 0;
+
    + +

    The runOnSCC method performs the interesting work of the pass, and + should return true if the module was modified by the transformation, false + otherwise.

    + +
    + + +
    + The doFinalization(CallGraph + &) method +
    + +
    + + 
    +   virtual bool doFinalization(CallGraph &CG);
+
    + +

    The doFinalization method is an infrequently used method that is + called when the pass framework has finished calling runOnFunction for every function in the + program being compiled.

    + +
    + + +
    + The FunctionPass class +
    + +
    + +

    In contrast to ModulePass subclasses, FunctionPass + subclasses do have a predictable, local behavior that can be expected by the + system. All FunctionPass execute on each function in the program + independent of all of the other functions in the program. + FunctionPass's do not require that they are executed in a particular + order, and FunctionPass's do not modify external functions.

    + +

    To be explicit, FunctionPass subclasses are not allowed to:

    + +
      +
    1. Modify a Function other than the one currently being processed.
      2. +
    2. Add or remove Function's from the current Module.
      3. +
    3. Add or remove global variables from the current Module.
      4. +
    4. Maintain state across invocations of + runOnFunction (including global data)
      5. +
    + +

    Implementing a FunctionPass is usually straightforward (See the Hello World pass for example). FunctionPass's + may overload three virtual methods to do their work. All of these methods + should return true if they modified the program, or false if they didn't.

    + +
    + + +
    + The doInitialization(Module &) + method +
    + +
    + + 
    +   virtual bool doInitialization(Module &M);
+
    + +

    The doIninitialize method is allowed to do most of the things that + FunctionPass's are not allowed to do. They can add and remove + functions, get pointers to functions, etc. The doInitialization method + is designed to do simple initialization type of stuff that does not depend on + the functions being processed. The doInitialization method call is not + scheduled to overlap with any other pass executions (thus it should be very + fast).

    + +

    A good example of how this method should be used is the LowerAllocations + pass. This pass converts malloc and free instructions into + platform dependent malloc() and free() function calls. It + uses the doInitialization method to get a reference to the malloc and + free functions that it needs, adding prototypes to the module if necessary.

    + +
    + + +
    + The runOnFunction method +
    + +
    + + 
    +   virtual bool runOnFunction(Function &F) = 0;
+

    + +

    The runOnFunction method must be implemented by your subclass to do + the transformation or analysis work of your pass. As usual, a true value should + be returned if the function is modified.

    + +
    + + +
    + The doFinalization(Module + &) method +
    + +
    + + 
    +   virtual bool doFinalization(Module &M);
+
    + +

    The doFinalization method is an infrequently used method that is + called when the pass framework has finished calling runOnFunction for every function in the + program being compiled.

    + +
    + + +
    + The LoopPass class +
    + +
    + +

    All LoopPass execute on each loop in the function independent of + all of the other loops in the function. LoopPass processes loops in + loop nest order such that outer most loop is processed last.

    + +

    LoopPass subclasses are allowed to update loop nest using + LPPassManager interface. Implementing a loop pass is usually + straightforward. Looppass's may overload three virtual methods to + do their work. All these methods should return true if they modified the + program, or false if they didn't.

    +
    + + +
    + The doInitialization(Loop *, + LPPassManager &) + method +
    + +
    + + 
    +   virtual bool doInitialization(Loop *, LPPassManager &LPM);
+
    + +

    The doInitialization method is designed to do simple initialization + type of stuff that does not depend on the functions being processed. The + doInitialization method call is not scheduled to overlap with any + other pass executions (thus it should be very fast). LPPassManager + interface should be used to access Function or Module level analysis + information.

    + +
    + + + +
    + The runOnLoop method +
    + +
    + + 
    +   virtual bool runOnLoop(Loop *, LPPassManager &LPM) = 0;
+

    + +

    The runOnLoop method must be implemented by your subclass to do + the transformation or analysis work of your pass. As usual, a true value should + be returned if the function is modified. LPPassManager interface + should be used to update loop nest.

    + +
    + + +
    + The doFinalization() method +
    + +
    + + 
    +   virtual bool doFinalization();
+
    + +

    The doFinalization method is an infrequently used method that is + called when the pass framework has finished calling runOnLoop for every loop in the + program being compiled.

    + +
    + + + + +
    + The BasicBlockPass class +
    + +
    + +

    BasicBlockPass's are just like FunctionPass's, except that they must limit + their scope of inspection and modification to a single basic block at a time. + As such, they are not allowed to do any of the following:

    + +
      +
    1. Modify or inspect any basic blocks outside of the current one
      2. +
    2. Maintain state across invocations of + runOnBasicBlock
      3. +
    3. Modify the control flow graph (by altering terminator instructions)
      4. +
    4. Any of the things forbidden for + FunctionPasses.
      5. +
    + +

    BasicBlockPasses are useful for traditional local and "peephole" + optimizations. They may override the same doInitialization(Module &) and doFinalization(Module &) methods that FunctionPass's have, but also have the following virtual methods that may also be implemented:

    + +
    + + +
    + The doInitialization(Function + &) method +
    + +
    + + 
    +   virtual bool doInitialization(Function &F);
+
    + +

    The doIninitialize method is allowed to do most of the things that + BasicBlockPass's are not allowed to do, but that + FunctionPass's can. The doInitialization method is designed + to do simple initialization that does not depend on the + BasicBlocks being processed. The doInitialization method call is not + scheduled to overlap with any other pass executions (thus it should be very + fast).

    + +
    + + +
    + The runOnBasicBlock method +
    + +
    + + 
    +   virtual bool runOnBasicBlock(BasicBlock &BB) = 0;
+
    + +

    Override this function to do the work of the BasicBlockPass. This + function is not allowed to inspect or modify basic blocks other than the + parameter, and are not allowed to modify the CFG. A true value must be returned + if the basic block is modified.

    + +
    + + +
    + The doFinalization(Function &) + method +
    + +
    + + 
    +   virtual bool doFinalization(Function &F);
+
    + +

    The doFinalization method is an infrequently used method that is + called when the pass framework has finished calling runOnBasicBlock for every BasicBlock in the + program being compiled. This can be used to perform per-function + finalization.

    + +
    + + +
    + The MachineFunctionPass class +
    + +
    + +

    A MachineFunctionPass is a part of the LLVM code generator that + executes on the machine-dependent representation of each LLVM function in the + program. A MachineFunctionPass is also a FunctionPass, so all + the restrictions that apply to a FunctionPass also apply to it. + MachineFunctionPasses also have additional restrictions. In particular, + MachineFunctionPasses are not allowed to do any of the following:

    + +
      +
    1. Modify any LLVM Instructions, BasicBlocks or Functions.
      2. +
    2. Modify a MachineFunction other than the one currently being processed.
      3. +
    3. Add or remove MachineFunctions from the current Module.
      4. +
    4. Add or remove global variables from the current Module.
      5. +
    5. Maintain state across invocations of runOnMachineFunction (including global + data)
      6. +
    + +
    + + +
    + The runOnMachineFunction(MachineFunction + &MF) method +
    + +
    + + 
    +   virtual bool runOnMachineFunction(MachineFunction &MF) = 0;
+
    + +

    runOnMachineFunction can be considered the main entry point of a + MachineFunctionPass; that is, you should override this method to do the + work of your MachineFunctionPass.

    + +

    The runOnMachineFunction method is called on every + MachineFunction in a Module, so that the + MachineFunctionPass may perform optimizations on the machine-dependent + representation of the function. If you want to get at the LLVM Function + for the MachineFunction you're working on, use + MachineFunction's getFunction() accessor method -- but + remember, you may not modify the LLVM Function or its contents from a + MachineFunctionPass.

    + +
    + + +
    + Pass registration +
    + + +
    + +

    In the Hello World example pass we illustrated how + pass registration works, and discussed some of the reasons that it is used and + what it does. Here we discuss how and why passes are registered.

    + +

    As we saw above, passes are registered with the RegisterPass + template, which requires you to pass at least two + parameters. The first parameter is the name of the pass that is to be used on + the command line to specify that the pass should be added to a program (for + example, with opt or bugpoint). The second argument is the + name of the pass, which is to be used for the --help output of + programs, as + well as for debug output generated by the --debug-pass option.

    + +

    If you want your pass to be easily dumpable, you should + implement the virtual print method:

    + +
    + + +
    + The print method +
    + +
    + + 
    +   virtual void print(llvm::OStream &O, const Module *M) const;
+
    + +

    The print method must be implemented by "analyses" in order to print + a human readable version of the analysis results. This is useful for debugging + an analysis itself, as well as for other people to figure out how an analysis + works. Use the opt -analyze argument to invoke this method.

    + +

    The llvm::OStream parameter specifies the stream to write the results on, + and the Module parameter gives a pointer to the top level module of the + program that has been analyzed. Note however that this pointer may be null in + certain circumstances (such as calling the Pass::dump() from a + debugger), so it should only be used to enhance debug output, it should not be + depended on.

    + +
    + + +
    + Specifying interactions between passes +
    + + +
    + +

    One of the main responsibilities of the PassManager is to make sure + that passes interact with each other correctly. Because PassManager + tries to optimize the execution of passes it must + know how the passes interact with each other and what dependencies exist between + the various passes. To track this, each pass can declare the set of passes that + are required to be executed before the current pass, and the passes which are + invalidated by the current pass.

    + +

    Typically this functionality is used to require that analysis results are + computed before your pass is run. Running arbitrary transformation passes can + invalidate the computed analysis results, which is what the invalidation set + specifies. If a pass does not implement the getAnalysisUsage method, it defaults to not + having any prerequisite passes, and invalidating all other passes.

    + +
    + + +
    + The getAnalysisUsage method +
    + +
    + + 
    +   virtual void getAnalysisUsage(AnalysisUsage &Info) const;
+
    + +

    By implementing the getAnalysisUsage method, the required and + invalidated sets may be specified for your transformation. The implementation + should fill in the AnalysisUsage + object with information about which passes are required and not invalidated. To + do this, a pass may call any of the following methods on the AnalysisUsage + object:

    +
    + + +
    + The AnalysisUsage::addRequired<> and AnalysisUsage::addRequiredTransitive<> methods +
    + +
    +

    + If your pass requires a previous pass to be executed (an analysis for example), + it can use one of these methods to arrange for it to be run before your pass. + LLVM has many different types of analyses and passes that can be required, + spanning the range from DominatorSet to BreakCriticalEdges. + Requiring BreakCriticalEdges, for example, guarantees that there will + be no critical edges in the CFG when your pass has been run. +

    + +

    + Some analyses chain to other analyses to do their job. For example, an AliasAnalysis implementation is required to chain to other alias analysis passes. In + cases where analyses chain, the addRequiredTransitive method should be + used instead of the addRequired method. This informs the PassManager + that the transitively required pass should be alive as long as the requiring + pass is. +

    +
    + + +
    + The AnalysisUsage::addPreserved<> method +
    + +
    +

    + One of the jobs of the PassManager is to optimize how and when analyses are run. + In particular, it attempts to avoid recomputing data unless it needs to. For + this reason, passes are allowed to declare that they preserve (i.e., they don't + invalidate) an existing analysis if it's available. For example, a simple + constant folding pass would not modify the CFG, so it can't possibly affect the + results of dominator analysis. By default, all passes are assumed to invalidate + all others. +

    + +

    + The AnalysisUsage class provides several methods which are useful in + certain circumstances that are related to addPreserved. In particular, + the setPreservesAll method can be called to indicate that the pass does + not modify the LLVM program at all (which is true for analyses), and the + setPreservesCFG method can be used by transformations that change + instructions in the program but do not modify the CFG or terminator instructions + (note that this property is implicitly set for BasicBlockPass's). +

    + +

    + addPreserved is particularly useful for transformations like + BreakCriticalEdges. This pass knows how to update a small set of loop + and dominator related analyses if they exist, so it can preserve them, despite + the fact that it hacks on the CFG. +

    +
    + + +
    + Example implementations of getAnalysisUsage +
    + +
    + + 
    +   // This is an example implementation from an analysis, which does not modify
+   // the program at all, yet has a prerequisite.
+   void PostDominanceFrontier::getAnalysisUsage(AnalysisUsage &AU) const {
+     AU.setPreservesAll();
+     AU.addRequired<PostDominatorTree>();
+   }
+
    + +

    and:

    + + 
    +   // This example modifies the program, but does not modify the CFG
+   void LICM::getAnalysisUsage(AnalysisUsage &AU) const {
+     AU.setPreservesCFG();
+     AU.addRequired<LoopInfo>();
+   }
+
    + +
    + + +
    + The getAnalysis<> and getAnalysisToUpdate<> methods +
    + +
    + +

    The Pass::getAnalysis<> method is automatically inherited by + your class, providing you with access to the passes that you declared that you + required with the getAnalysisUsage + method. It takes a single template argument that specifies which pass class you + want, and returns a reference to that pass. For example:

    + + 
    +    bool LICM::runOnFunction(Function &F) {
+      LoopInfo &LI = getAnalysis<LoopInfo>();
+      ...
+    }
+
    + +

    This method call returns a reference to the pass desired. You may get a + runtime assertion failure if you attempt to get an analysis that you did not + declare as required in your getAnalysisUsage implementation. This + method can be called by your run* method implementation, or by any + other local method invoked by your run* method. + + A module level pass can use function level analysis info using this interface. + For example:

    + + 
    +    bool ModuleLevelPass::runOnModule(Module &M) {
+      ...
+      DominatorTree &DT = getAnalysis<DominatorTree>(Func);
+      ...
+    }
+
    + +

    In above example, runOnFunction for DominatorTree is called by pass manager + before returning a reference to the desired pass.

    + +

    + If your pass is capable of updating analyses if they exist (e.g., + BreakCriticalEdges, as described above), you can use the + getAnalysisToUpdate method, which returns a pointer to the analysis if + it is active. For example:

    + + 
    +   ...
+   if (DominatorSet *DS = getAnalysisToUpdate<DominatorSet>()) {
+     // A DominatorSet is active.  This code will update it.
+   }
+   ...
+
    + +
    + + +
    + Implementing Analysis Groups +
    + + +
    + +

    Now that we understand the basics of how passes are defined, how they are + used, and how they are required from other passes, it's time to get a little bit + fancier. All of the pass relationships that we have seen so far are very + simple: one pass depends on one other specific pass to be run before it can run. + For many applications, this is great, for others, more flexibility is + required.

    + +

    In particular, some analyses are defined such that there is a single simple + interface to the analysis results, but multiple ways of calculating them. + Consider alias analysis for example. The most trivial alias analysis returns + "may alias" for any alias query. The most sophisticated analysis a + flow-sensitive, context-sensitive interprocedural analysis that can take a + significant amount of time to execute (and obviously, there is a lot of room + between these two extremes for other implementations). To cleanly support + situations like this, the LLVM Pass Infrastructure supports the notion of + Analysis Groups.

    + +
    + + +
    + Analysis Group Concepts +
    + +
    + +

    An Analysis Group is a single simple interface that may be implemented by + multiple different passes. Analysis Groups can be given human readable names + just like passes, but unlike passes, they need not derive from the Pass + class. An analysis group may have one or more implementations, one of which is + the "default" implementation.

    + +

    Analysis groups are used by client passes just like other passes are: the + AnalysisUsage::addRequired() and Pass::getAnalysis() methods. + In order to resolve this requirement, the PassManager + scans the available passes to see if any implementations of the analysis group + are available. If none is available, the default implementation is created for + the pass to use. All standard rules for interaction + between passes still apply.

    + +

    Although Pass Registration is optional for normal + passes, all analysis group implementations must be registered, and must use the + RegisterAnalysisGroup template to join the + implementation pool. Also, a default implementation of the interface + must be registered with RegisterAnalysisGroup.

    + +

    As a concrete example of an Analysis Group in action, consider the AliasAnalysis + analysis group. The default implementation of the alias analysis interface (the + basicaa + pass) just does a few simple checks that don't require significant analysis to + compute (such as: two different globals can never alias each other, etc). + Passes that use the AliasAnalysis + interface (for example the gcse pass), do + not care which implementation of alias analysis is actually provided, they just + use the designated interface.

    + +

    From the user's perspective, commands work just like normal. Issuing the + command 'opt -gcse ...' will cause the basicaa class to be + instantiated and added to the pass sequence. Issuing the command 'opt + -somefancyaa -gcse ...' will cause the gcse pass to use the + somefancyaa alias analysis (which doesn't actually exist, it's just a + hypothetical example) instead.

    + +
    + + +
    + Using RegisterAnalysisGroup +
    + +
    + +

    The RegisterAnalysisGroup template is used to register the analysis + group itself as well as add pass implementations to the analysis group. First, + an analysis should be registered, with a human readable name provided for it. + Unlike registration of passes, there is no command line argument to be specified + for the Analysis Group Interface itself, because it is "abstract":

    + + 
    +   static RegisterAnalysisGroup<AliasAnalysis> A("Alias Analysis");
+
    + +

    Once the analysis is registered, passes can declare that they are valid + implementations of the interface by using the following code:

    + + 
    + namespace {
+   // Analysis Group implementations must be registered normally...
+   RegisterPass<FancyAA>
+   B("somefancyaa", "A more complex alias analysis implementation");
+ 
+   // Declare that we implement the AliasAnalysis interface
+   RegisterAnalysisGroup<AliasAnalysis> C(B);
+ }
+
    + +

    This just shows a class FancyAA that is registered normally, then + uses the RegisterAnalysisGroup template to "join" the AliasAnalysis + analysis group. Every implementation of an analysis group should join using + this template. A single pass may join multiple different analysis groups with + no problem.

    + + 
    + namespace {
+   // Analysis Group implementations must be registered normally...
+   RegisterPass<BasicAliasAnalysis>
+   D("basicaa", "Basic Alias Analysis (default AA impl)");
+ 
+   // Declare that we implement the AliasAnalysis interface
+   RegisterAnalysisGroup<AliasAnalysis, true> E(D);
+ }
+
    + +

    Here we show how the default implementation is specified (using the extra + argument to the RegisterAnalysisGroup template). There must be exactly + one default implementation available at all times for an Analysis Group to be + used. Only default implementation can derive from ImmutablePass. + Here we declare that the + BasicAliasAnalysis + pass is the default implementation for the interface.

    + +
    + + +
    + Pass Statistics +
    + + +
    +

    The Statistic + class is designed to be an easy way to expose various success + metrics from passes. These statistics are printed at the end of a + run, when the -stats command line option is enabled on the command + line. See the Statistics section in the Programmer's Manual for details. + +

    + + + +
    + What PassManager does +
    + + +
    + +

    The PassManager + class + takes a list of passes, ensures their prerequisites + are set up correctly, and then schedules passes to run efficiently. All of the + LLVM tools that run passes use the PassManager for execution of these + passes.

    + +

    The PassManager does two main things to try to reduce the execution + time of a series of passes:

    + +
      +
    1. Share analysis results - The PassManager attempts to avoid + recomputing analysis results as much as possible. This means keeping track of + which analyses are available already, which analyses get invalidated, and which + analyses are needed to be run for a pass. An important part of work is that the + PassManager tracks the exact lifetime of all analysis results, allowing + it to free memory allocated to holding analysis + results as soon as they are no longer needed.
      2. + +
    2. Pipeline the execution of passes on the program - The + PassManager attempts to get better cache and memory usage behavior out + of a series of passes by pipelining the passes together. This means that, given + a series of consequtive FunctionPass's, it + will execute all of the FunctionPass's on + the first function, then all of the FunctionPasses on the second function, + etc... until the entire program has been run through the passes. + +

      This improves the cache behavior of the compiler, because it is only touching + the LLVM program representation for a single function at a time, instead of + traversing the entire program. It reduces the memory consumption of compiler, + because, for example, only one DominatorSet + needs to be calculated at a time. This also makes it possible to implement + some interesting enhancements in the future.

      3. + +
    + +

    The effectiveness of the PassManager is influenced directly by how + much information it has about the behaviors of the passes it is scheduling. For + example, the "preserved" set is intentionally conservative in the face of an + unimplemented getAnalysisUsage method. + Not implementing when it should be implemented will have the effect of not + allowing any analysis results to live across the execution of your pass.

    + +

    The PassManager class exposes a --debug-pass command line + options that is useful for debugging pass execution, seeing how things work, and + diagnosing when you should be preserving more analyses than you currently are + (To get information about all of the variants of the --debug-pass + option, just type 'opt --help-hidden').

    + +

    By using the --debug-pass=Structure option, for example, we can see + how our Hello World pass interacts with other passes. + Lets try it out with the gcse and licm passes:

    + + 
    + $ opt -load ../../../Debug/lib/Hello.so -gcse -licm --debug-pass=Structure < hello.bc > /dev/null
+ Module Pass Manager
+   Function Pass Manager
+     Dominator Set Construction
+     Immediate Dominators Construction
+     Global Common Subexpression Elimination
+ --  Immediate Dominators Construction
+ --  Global Common Subexpression Elimination
+     Natural Loop Construction
+     Loop Invariant Code Motion
+ --  Natural Loop Construction
+ --  Loop Invariant Code Motion
+     Module Verifier
+ --  Dominator Set Construction
+ --  Module Verifier
+   Bitcode Writer
+ --Bitcode Writer
+
    + +

    This output shows us when passes are constructed and when the analysis + results are known to be dead (prefixed with '--'). Here we see that + GCSE uses dominator and immediate dominator information to do its job. The LICM + pass uses natural loop information, which uses dominator sets, but not immediate + dominators. Because immediate dominators are no longer useful after the GCSE + pass, it is immediately destroyed. The dominator sets are then reused to + compute natural loop information, which is then used by the LICM pass.

    + +

    After the LICM pass, the module verifier runs (which is automatically added + by the 'opt' tool), which uses the dominator set to check that the + resultant LLVM code is well formed. After it finishes, the dominator set + information is destroyed, after being computed once, and shared by three + passes.

    + +

    Lets see how this changes when we run the Hello + World pass in between the two passes:

    + + 
    + $ opt -load ../../../Debug/lib/Hello.so -gcse -hello -licm --debug-pass=Structure < hello.bc > /dev/null
+ Module Pass Manager
+   Function Pass Manager
+     Dominator Set Construction
+     Immediate Dominators Construction
+     Global Common Subexpression Elimination
+ --  Dominator Set Construction
+ --  Immediate Dominators Construction
+ --  Global Common Subexpression Elimination
+     Hello World Pass
+ --  Hello World Pass
+     Dominator Set Construction
+     Natural Loop Construction
+     Loop Invariant Code Motion
+ --  Natural Loop Construction
+ --  Loop Invariant Code Motion
+     Module Verifier
+ --  Dominator Set Construction
+ --  Module Verifier
+   Bitcode Writer
+ --Bitcode Writer
+ Hello: __main
+ Hello: puts
+ Hello: main
+
    + +

    Here we see that the Hello World pass has killed the + Dominator Set pass, even though it doesn't modify the code at all! To fix this, + we need to add the following getAnalysisUsage method to our pass:

    + + 
    +     // We don't modify the program, so we preserve all analyses
+     virtual void getAnalysisUsage(AnalysisUsage &AU) const {
+       AU.setPreservesAll();
+     }
+
    + +

    Now when we run our pass, we get this output:

    + + 
    + $ opt -load ../../../Debug/lib/Hello.so -gcse -hello -licm --debug-pass=Structure < hello.bc > /dev/null
+ Pass Arguments:  -gcse -hello -licm
+ Module Pass Manager
+   Function Pass Manager
+     Dominator Set Construction
+     Immediate Dominators Construction
+     Global Common Subexpression Elimination
+ --  Immediate Dominators Construction
+ --  Global Common Subexpression Elimination
+     Hello World Pass
+ --  Hello World Pass
+     Natural Loop Construction
+     Loop Invariant Code Motion
+ --  Loop Invariant Code Motion
+ --  Natural Loop Construction
+     Module Verifier
+ --  Dominator Set Construction
+ --  Module Verifier
+   Bitcode Writer
+ --Bitcode Writer
+ Hello: __main
+ Hello: puts
+ Hello: main
+
    + +

    Which shows that we don't accidentally invalidate dominator information + anymore, and therefore do not have to compute it twice.

    + +
    + + +
    + The releaseMemory method +
    + +
    + + 
    +   virtual void releaseMemory();
+
    + +

    The PassManager automatically determines when to compute analysis + results, and how long to keep them around for. Because the lifetime of the pass + object itself is effectively the entire duration of the compilation process, we + need some way to free analysis results when they are no longer useful. The + releaseMemory virtual method is the way to do this.

    + +

    If you are writing an analysis or any other pass that retains a significant + amount of state (for use by another pass which "requires" your pass and uses the + getAnalysis method) you should implement + releaseMEmory to, well, release the memory allocated to maintain this + internal state. This method is called after the run* method for the + class, before the next call of run* in your pass.

    + +
    + + +
    + Registering dynamically loaded passes +
    + + +
    + +

    Size matters when constructing production quality tools using llvm, + both for the purposes of distribution, and for regulating the resident code size + when running on the target system. Therefore, it becomes desirable to + selectively use some passes, while omitting others and maintain the flexibility + to change configurations later on. You want to be able to do all this, and, + provide feedback to the user. This is where pass registration comes into + play.

    + +

    The fundamental mechanisms for pass registration are the + MachinePassRegistry class and subclasses of + MachinePassRegistryNode.

    + +

    An instance of MachinePassRegistry is used to maintain a list of + MachinePassRegistryNode objects. This instance maintains the list and + communicates additions and deletions to the command line interface.

    + +

    An instance of MachinePassRegistryNode subclass is used to maintain + information provided about a particular pass. This information includes the + command line name, the command help string and the address of the function used + to create an instance of the pass. A global static constructor of one of these + instances registers with a corresponding MachinePassRegistry, + the static destructor unregisters. Thus a pass that is statically linked + in the tool will be registered at start up. A dynamically loaded pass will + register on load and unregister at unload.

    + +
    + + +
    + Using existing registries +
    + +
    + +

    There are predefined registries to track instruction scheduling + (RegisterScheduler) and register allocation (RegisterRegAlloc) + machine passes. Here we will describe how to register a register + allocator machine pass.

    + +

    Implement your register allocator machine pass. In your register allocator + .cpp file add the following include;

    + + 
    +   #include "llvm/CodeGen/RegAllocRegistry.h"
+
    + +

    Also in your register allocator .cpp file, define a creator function in the + form;

    + + 
    +   FunctionPass *createMyRegisterAllocator() {
+     return new MyRegisterAllocator();
+   }
+
    + +

    Note that the signature of this function should match the type of + RegisterRegAlloc::FunctionPassCtor. In the same file add the + "installing" declaration, in the form;

    + + 
    +   static RegisterRegAlloc myRegAlloc("myregalloc",
+     "  my register allocator help string",
+     createMyRegisterAllocator);
+
    + +

    Note the two spaces prior to the help string produces a tidy result on the + --help query.

    + + 
    + $ llc --help
+   ...
+   -regalloc                    - Register allocator to use: (default = linearscan)
+     =linearscan                -   linear scan register allocator
+     =local                     -   local register allocator
+     =simple                    -   simple register allocator
+     =myregalloc                -   my register allocator help string
+   ...
+
    + +

    And that's it. The user is now free to use -regalloc=myregalloc as + an option. Registering instruction schedulers is similar except use the + RegisterScheduler class. Note that the + RegisterScheduler::FunctionPassCtor is significantly different from + RegisterRegAlloc::FunctionPassCtor.

    + +

    To force the load/linking of your register allocator into the llc/lli tools, + add your creator function's global declaration to "Passes.h" and add a "pseudo" + call line to llvm/Codegen/LinkAllCodegenComponents.h.

    + +
    + + + +
    + Creating new registries +
    + +
    + +

    The easiest way to get started is to clone one of the existing registries; we + recommend llvm/CodeGen/RegAllocRegistry.h. The key things to modify + are the class name and the FunctionPassCtor type.

    + +

    Then you need to declare the registry. Example: if your pass registry is + RegisterMyPasses then define;

    + + 
    + MachinePassRegistry RegisterMyPasses::Registry;
+
    + +

    And finally, declare the command line option for your passes. Example:

    + + 
    +   cl::opt<RegisterMyPasses::FunctionPassCtor, false,
+           RegisterPassParser<RegisterMyPasses> >
+   MyPassOpt("mypass",
+             cl::init(&createDefaultMyPass),
+             cl::desc("my pass option help")); 
+
    + +

    Here the command option is "mypass", with createDefaultMyPass as the default + creator.

    + +
    + + +
    + Using GDB with dynamically loaded passes +
    + + +
    + +

    Unfortunately, using GDB with dynamically loaded passes is not as easy as it + should be. First of all, you can't set a breakpoint in a shared object that has + not been loaded yet, and second of all there are problems with inlined functions + in shared objects. Here are some suggestions to debugging your pass with + GDB.

    + +

    For sake of discussion, I'm going to assume that you are debugging a + transformation invoked by opt, although nothing described here depends + on that.

    + +
    + + +
    + Setting a breakpoint in your pass +
    + +
    + +

    First thing you do is start gdb on the opt process:

    + + 
    + $ gdb opt
+ GNU gdb 5.0
+ Copyright 2000 Free Software Foundation, Inc.
+ GDB is free software, covered by the GNU General Public License, and you are
+ welcome to change it and/or distribute copies of it under certain conditions.
+ Type "show copying" to see the conditions.
+ There is absolutely no warranty for GDB.  Type "show warranty" for details.
+ This GDB was configured as "sparc-sun-solaris2.6"...
+ (gdb)
+
    + +

    Note that opt has a lot of debugging information in it, so it takes + time to load. Be patient. Since we cannot set a breakpoint in our pass yet + (the shared object isn't loaded until runtime), we must execute the process, and + have it stop before it invokes our pass, but after it has loaded the shared + object. The most foolproof way of doing this is to set a breakpoint in + PassManager::run and then run the process with the arguments you + want:

    + + 
    + (gdb) break llvm::PassManager::run
+ Breakpoint 1 at 0x2413bc: file Pass.cpp, line 70.
+ (gdb) run test.bc -load $(LLVMTOP)/llvm/Debug/lib/[libname].so -[passoption]
+ Starting program: opt test.bc -load $(LLVMTOP)/llvm/Debug/lib/[libname].so -[passoption]
+ Breakpoint 1, PassManager::run (this=0xffbef174, M=@0x70b298) at Pass.cpp:70
+ 70      bool PassManager::run(Module &M) { return PM->run(M); }
+ (gdb)
+
    + +

    Once the opt stops in the PassManager::run method you are + now free to set breakpoints in your pass so that you can trace through execution + or do other standard debugging stuff.

    + +
    + + +
    + Miscellaneous Problems +
    + +
    + +

    Once you have the basics down, there are a couple of problems that GDB has, + some with solutions, some without.

    + +
      +
    • Inline functions have bogus stack information. In general, GDB does a + pretty good job getting stack traces and stepping through inline functions. + When a pass is dynamically loaded however, it somehow completely loses this + capability. The only solution I know of is to de-inline a function (move it + from the body of a class to a .cpp file).
      • + +
    • Restarting the program breaks breakpoints. After following the information + above, you have succeeded in getting some breakpoints planted in your pass. Nex + thing you know, you restart the program (i.e., you type 'run' again), + and you start getting errors about breakpoints being unsettable. The only way I + have found to "fix" this problem is to delete the breakpoints that are + already set in your pass, run the program, and re-set the breakpoints once + execution stops in PassManager::run.
      • + +
    + +

    Hopefully these tips will help with common case debugging situations. If + you'd like to contribute some tips of your own, just contact Chris.

    + +
    + + +
    + Future extensions planned +
    + + +
    + +

    Although the LLVM Pass Infrastructure is very capable as it stands, and does + some nifty stuff, there are things we'd like to add in the future. Here is + where we are going:

    + +
    + + +
    + Multithreaded LLVM +
    + +
    + +

    Multiple CPU machines are becoming more common and compilation can never be + fast enough: obviously we should allow for a multithreaded compiler. Because of + the semantics defined for passes above (specifically they cannot maintain state + across invocations of their run* methods), a nice clean way to + implement a multithreaded compiler would be for the PassManager class + to create multiple instances of each pass object, and allow the separate + instances to be hacking on different parts of the program at the same time.

    + +

    This implementation would prevent each of the passes from having to implement + multithreaded constructs, requiring only the LLVM core to have locking in a few + places (for global resources). Although this is a simple extension, we simply + haven't had time (or multiprocessor machines, thus a reason) to implement this. + Despite that, we have kept the LLVM passes SMP ready, and you should too.

    + +
    + + +
    +
    + Valid CSS! + Valid HTML 4.01! + + Chris Lattner
    + The LLVM Compiler Infrastructure
    + Last modified: $Date: 2008/02/12 06:05:03 $ +
    + + + Index: llvm-www/releases/2.2/docs/doxygen.cfg diff -c /dev/null llvm-www/releases/2.2/docs/doxygen.cfg:1.1 *** /dev/null Tue Feb 12 00:07:06 2008 --- llvm-www/releases/2.2/docs/doxygen.cfg Tue Feb 12 00:05:03 2008 *************** *** 0 **** --- 1,1230 ---- + # Doxyfile 1.4.4 + + # This file describes the settings to be used by the documentation system + # doxygen (www.doxygen.org) for a project + # + # All text after a hash (#) is considered a comment and will be ignored + # The format is: + # TAG = value [value, ...] + # For lists items can also be appended using: + # TAG += value [value, ...] + # Values that contain spaces should be placed between quotes (" ") + + #--------------------------------------------------------------------------- + # Project related configuration options + #--------------------------------------------------------------------------- + + # The PROJECT_NAME tag is a single word (or a sequence of words surrounded + # by quotes) that should identify the project. + + PROJECT_NAME = LLVM + + # The PROJECT_NUMBER tag can be used to enter a project or revision number. + # This could be handy for archiving the generated documentation or + # if some version control system is used. + + PROJECT_NUMBER = 2.2 + + # The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) + # base path where the generated documentation will be put. + # If a relative path is entered, it will be relative to the location + # where doxygen was started. If left blank the current directory will be used. + + OUTPUT_DIRECTORY = /localhome/tbrethou/2.2/testing/llvm-2.2/docs/doxygen + + # If the CREATE_SUBDIRS tag is set to YES, then doxygen will create + # 4096 sub-directories (in 2 levels) under the output directory of each output + # format and will distribute the generated files over these directories. + # Enabling this option can be useful when feeding doxygen a huge amount of + # source files, where putting all generated files in the same directory would + # otherwise cause performance problems for the file system. + + CREATE_SUBDIRS = NO + + # The OUTPUT_LANGUAGE tag is used to specify the language in which all + # documentation generated by doxygen is written. Doxygen will use this + # information to generate all constant output in the proper language. + # The default language is English, other supported languages are: + # Brazilian, Catalan, Chinese, Chinese-Traditional, Croatian, Czech, Danish, + # Dutch, Finnish, French, German, Greek, Hungarian, Italian, Japanese, + # Japanese-en (Japanese with English messages), Korean, Korean-en, Norwegian, + # Polish, Portuguese, Romanian, Russian, Serbian, Slovak, Slovene, Spanish, + # Swedish, and Ukrainian. + + OUTPUT_LANGUAGE = English + + # This tag can be used to specify the encoding used in the generated output. + # The encoding is not always determined by the language that is chosen, + # but also whether or not the output is meant for Windows or non-Windows users. + # In case there is a difference, setting the USE_WINDOWS_ENCODING tag to YES + # forces the Windows encoding (this is the default for the Windows binary), + # whereas setting the tag to NO uses a Unix-style encoding (the default for + # all platforms other than Windows). + + USE_WINDOWS_ENCODING = NO + + # If the BRIEF_MEMBER_DESC tag is set to YES (the default) Doxygen will + # include brief member descriptions after the members that are listed in + # the file and class documentation (similar to JavaDoc). + # Set to NO to disable this. + + BRIEF_MEMBER_DESC = YES + + # If the REPEAT_BRIEF tag is set to YES (the default) Doxygen will prepend + # the brief description of a member or function before the detailed description. + # Note: if both HIDE_UNDOC_MEMBERS and BRIEF_MEMBER_DESC are set to NO, the + # brief descriptions will be completely suppressed. + + REPEAT_BRIEF = YES + + # This tag implements a quasi-intelligent brief description abbreviator + # that is used to form the text in various listings. Each string + # in this list, if found as the leading text of the brief description, will be + # stripped from the text and the result after processing the whole list, is + # used as the annotated text. Otherwise, the brief description is used as-is. + # If left blank, the following values are used ("$name" is automatically + # replaced with the name of the entity): "The $name class" "The $name widget" + # "The $name file" "is" "provides" "specifies" "contains" + # "represents" "a" "an" "the" + + ABBREVIATE_BRIEF = + + # If the ALWAYS_DETAILED_SEC and REPEAT_BRIEF tags are both set to YES then + # Doxygen will generate a detailed section even if there is only a brief + # description. + + ALWAYS_DETAILED_SEC = NO + + # If the INLINE_INHERITED_MEMB tag is set to YES, doxygen will show all + # inherited members of a class in the documentation of that class as if those + # members were ordinary class members. Constructors, destructors and assignment + # operators of the base classes will not be shown. + + INLINE_INHERITED_MEMB = NO + + # If the FULL_PATH_NAMES tag is set to YES then Doxygen will prepend the full + # path before files name in the file list and in the header files. If set + # to NO the shortest path that makes the file name unique will be used. + + FULL_PATH_NAMES = NO + + # If the FULL_PATH_NAMES tag is set to YES then the STRIP_FROM_PATH tag + # can be used to strip a user-defined part of the path. Stripping is + # only done if one of the specified strings matches the left-hand part of + # the path. The tag can be used to show relative paths in the file list. + # If left blank the directory from which doxygen is run is used as the + # path to strip. + + STRIP_FROM_PATH = ../.. + + # The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of + # the path mentioned in the documentation of a class, which tells + # the reader which header file to include in order to use a class. + # If left blank only the name of the header file containing the class + # definition is used. Otherwise one should specify the include paths that + # are normally passed to the compiler using the -I flag. + + STRIP_FROM_INC_PATH = + + # If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter + # (but less readable) file names. This can be useful is your file systems + # doesn't support long names like on DOS, Mac, or CD-ROM. + + SHORT_NAMES = NO + + # If the JAVADOC_AUTOBRIEF tag is set to YES then Doxygen + # will interpret the first line (until the first dot) of a JavaDoc-style + # comment as the brief description. If set to NO, the JavaDoc + # comments will behave just like the Qt-style comments (thus requiring an + # explicit @brief command for a brief description. + + JAVADOC_AUTOBRIEF = NO + + # The MULTILINE_CPP_IS_BRIEF tag can be set to YES to make Doxygen + # treat a multi-line C++ special comment block (i.e. a block of //! or /// + # comments) as a brief description. This used to be the default behaviour. + # The new default is to treat a multi-line C++ comment block as a detailed + # description. Set this tag to YES if you prefer the old behaviour instead. + + MULTILINE_CPP_IS_BRIEF = NO + + # If the DETAILS_AT_TOP tag is set to YES then Doxygen + # will output the detailed description near the top, like JavaDoc. + # If set to NO, the detailed description appears after the member + # documentation. + + DETAILS_AT_TOP = NO + + # If the INHERIT_DOCS tag is set to YES (the default) then an undocumented + # member inherits the documentation from any documented member that it + # re-implements. + + INHERIT_DOCS = YES + + # If member grouping is used in the documentation and the DISTRIBUTE_GROUP_DOC + # tag is set to YES, then doxygen will reuse the documentation of the first + # member in the group (if any) for the other members of the group. By default + # all members of a group must be documented explicitly. + + DISTRIBUTE_GROUP_DOC = NO + + # If the SEPARATE_MEMBER_PAGES tag is set to YES, then doxygen will produce + # a new page for each member. If set to NO, the documentation of a member will + # be part of the file/class/namespace that contains it. + + #SEPARATE_MEMBER_PAGES = NO + + # The TAB_SIZE tag can be used to set the number of spaces in a tab. + # Doxygen uses this value to replace tabs by spaces in code fragments. + + TAB_SIZE = 2 + + # This tag can be used to specify a number of aliases that acts + # as commands in the documentation. An alias has the form "name=value". + # For example adding "sideeffect=\par Side Effects:\n" will allow you to + # put the command \sideeffect (or @sideeffect) in the documentation, which + # will result in a user-defined paragraph with heading "Side Effects:". + # You can put \n's in the value part of an alias to insert newlines. + + ALIASES = + + # Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C + # sources only. Doxygen will then generate output that is more tailored for C. + # For instance, some of the names that are used will be different. The list + # of all members will be omitted, etc. + + OPTIMIZE_OUTPUT_FOR_C = NO + + # Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java sources + # only. Doxygen will then generate output that is more tailored for Java. + # For instance, namespaces will be presented as packages, qualified scopes + # will look different, etc. + + OPTIMIZE_OUTPUT_JAVA = NO + + # Set the SUBGROUPING tag to YES (the default) to allow class member groups of + # the same type (for instance a group of public functions) to be put as a + # subgroup of that type (e.g. under the Public Functions section). Set it to + # NO to prevent subgrouping. Alternatively, this can be done per class using + # the \nosubgrouping command. + + SUBGROUPING = YES + + #--------------------------------------------------------------------------- + # Build related configuration options + #--------------------------------------------------------------------------- + + # If the EXTRACT_ALL tag is set to YES doxygen will assume all entities in + # documentation are documented, even if no documentation was available. + # Private class members and static file members will be hidden unless + # the EXTRACT_PRIVATE and EXTRACT_STATIC tags are set to YES + + EXTRACT_ALL = YES + + # If the EXTRACT_PRIVATE tag is set to YES all private members of a class + # will be included in the documentation. + + EXTRACT_PRIVATE = NO + + # If the EXTRACT_STATIC tag is set to YES all static members of a file + # will be included in the documentation. + + EXTRACT_STATIC = YES + + # If the EXTRACT_LOCAL_CLASSES tag is set to YES classes (and structs) + # defined locally in source files will be included in the documentation. + # If set to NO only classes defined in header files are included. + + EXTRACT_LOCAL_CLASSES = YES + + # This flag is only useful for Objective-C code. When set to YES local + # methods, which are defined in the implementation section but not in + # the interface are included in the documentation. + # If set to NO (the default) only methods in the interface are included. + + EXTRACT_LOCAL_METHODS = NO + + # If the HIDE_UNDOC_MEMBERS tag is set to YES, Doxygen will hide all + # undocumented members of documented classes, files or namespaces. + # If set to NO (the default) these members will be included in the + # various overviews, but no documentation section is generated. + # This option has no effect if EXTRACT_ALL is enabled. + + HIDE_UNDOC_MEMBERS = NO + + # If the HIDE_UNDOC_CLASSES tag is set to YES, Doxygen will hide all + # undocumented classes that are normally visible in the class hierarchy. + # If set to NO (the default) these classes will be included in the various + # overviews. This option has no effect if EXTRACT_ALL is enabled. + + HIDE_UNDOC_CLASSES = NO + + # If the HIDE_FRIEND_COMPOUNDS tag is set to YES, Doxygen will hide all + # friend (class|struct|union) declarations. + # If set to NO (the default) these declarations will be included in the + # documentation. + + HIDE_FRIEND_COMPOUNDS = NO + + # If the HIDE_IN_BODY_DOCS tag is set to YES, Doxygen will hide any + # documentation blocks found inside the body of a function. + # If set to NO (the default) these blocks will be appended to the + # function's detailed documentation block. + + HIDE_IN_BODY_DOCS = NO + + # The INTERNAL_DOCS tag determines if documentation + # that is typed after a \internal command is included. If the tag is set + # to NO (the default) then the documentation will be excluded. + # Set it to YES to include the internal documentation. + + INTERNAL_DOCS = NO + + # If the CASE_SENSE_NAMES tag is set to NO then Doxygen will only generate + # file names in lower-case letters. If set to YES upper-case letters are also + # allowed. This is useful if you have classes or files whose names only differ + # in case and if your file system supports case sensitive file names. Windows + # and Mac users are advised to set this option to NO. + + CASE_SENSE_NAMES = YES + + # If the HIDE_SCOPE_NAMES tag is set to NO (the default) then Doxygen + # will show members with their full class and namespace scopes in the + # documentation. If set to YES the scope will be hidden. + + HIDE_SCOPE_NAMES = NO + + # If the SHOW_INCLUDE_FILES tag is set to YES (the default) then Doxygen + # will put a list of the files that are included by a file in the documentation + # of that file. + + SHOW_INCLUDE_FILES = YES + + # If the INLINE_INFO tag is set to YES (the default) then a tag [inline] + # is inserted in the documentation for inline members. + + INLINE_INFO = YES + + # If the SORT_MEMBER_DOCS tag is set to YES (the default) then doxygen + # will sort the (detailed) documentation of file and class members + # alphabetically by member name. If set to NO the members will appear in + # declaration order. + + SORT_MEMBER_DOCS = YES + + # If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the + # brief documentation of file, namespace and class members alphabetically + # by member name. If set to NO (the default) the members will appear in + # declaration order. + + SORT_BRIEF_DOCS = NO + + # If the SORT_BY_SCOPE_NAME tag is set to YES, the class list will be + # sorted by fully-qualified names, including namespaces. If set to + # NO (the default), the class list will be sorted only by class name, + # not including the namespace part. + # Note: This option is not very useful if HIDE_SCOPE_NAMES is set to YES. + # Note: This option applies only to the class list, not to the + # alphabetical list. + + SORT_BY_SCOPE_NAME = NO + + # The GENERATE_TODOLIST tag can be used to enable (YES) or + # disable (NO) the todo list. This list is created by putting \todo + # commands in the documentation. + + GENERATE_TODOLIST = YES + + # The GENERATE_TESTLIST tag can be used to enable (YES) or + # disable (NO) the test list. This list is created by putting \test + # commands in the documentation. + + GENERATE_TESTLIST = YES + + # The GENERATE_BUGLIST tag can be used to enable (YES) or + # disable (NO) the bug list. This list is created by putting \bug + # commands in the documentation. + + GENERATE_BUGLIST = YES + + # The GENERATE_DEPRECATEDLIST tag can be used to enable (YES) or + # disable (NO) the deprecated list. This list is created by putting + # \deprecated commands in the documentation. + + GENERATE_DEPRECATEDLIST= YES + + # The ENABLED_SECTIONS tag can be used to enable conditional + # documentation sections, marked by \if sectionname ... \endif. + + ENABLED_SECTIONS = + + # The MAX_INITIALIZER_LINES tag determines the maximum number of lines + # the initial value of a variable or define consists of for it to appear in + # the documentation. If the initializer consists of more lines than specified + # here it will be hidden. Use a value of 0 to hide initializers completely. + # The appearance of the initializer of individual variables and defines in the + # documentation can be controlled using \showinitializer or \hideinitializer + # command in the documentation regardless of this setting. + + MAX_INITIALIZER_LINES = 30 + + # Set the SHOW_USED_FILES tag to NO to disable the list of files generated + # at the bottom of the documentation of classes and structs. If set to YES the + # list will mention the files that were used to generate the documentation. + + SHOW_USED_FILES = YES + + # If the sources in your project are distributed over multiple directories + # then setting the SHOW_DIRECTORIES tag to YES will show the directory hierarchy + # in the documentation. The default is YES. + + SHOW_DIRECTORIES = YES + + # The FILE_VERSION_FILTER tag can be used to specify a program or script that + # doxygen should invoke to get the current version for each file (typically from the + # version control system). Doxygen will invoke the program by executing (via + # popen()) the command , where is the value of + # the FILE_VERSION_FILTER tag, and is the name of an input file + # provided by doxygen. Whatever the progam writes to standard output + # is used as the file version. See the manual for examples. + + #FILE_VERSION_FILTER = + + #--------------------------------------------------------------------------- + # configuration options related to warning and progress messages + #--------------------------------------------------------------------------- + + # The QUIET tag can be used to turn on/off the messages that are generated + # by doxygen. Possible values are YES and NO. If left blank NO is used. + + QUIET = NO + + # The WARNINGS tag can be used to turn on/off the warning messages that are + # generated by doxygen. Possible values are YES and NO. If left blank + # NO is used. + + WARNINGS = NO + + # If WARN_IF_UNDOCUMENTED is set to YES, then doxygen will generate warnings + # for undocumented members. If EXTRACT_ALL is set to YES then this flag will + # automatically be disabled. + + WARN_IF_UNDOCUMENTED = NO + + # If WARN_IF_DOC_ERROR is set to YES, doxygen will generate warnings for + # potential errors in the documentation, such as not documenting some + # parameters in a documented function, or documenting parameters that + # don't exist or using markup commands wrongly. + + WARN_IF_DOC_ERROR = YES + + # This WARN_NO_PARAMDOC option can be abled to get warnings for + # functions that are documented, but have no documentation for their parameters + # or return value. If set to NO (the default) doxygen will only warn about + # wrong or incomplete parameter documentation, but not about the absence of + # documentation. + + #WARN_NO_PARAMDOC = NO + + # The WARN_FORMAT tag determines the format of the warning messages that + # doxygen can produce. The string should contain the $file, $line, and $text + # tags, which will be replaced by the file and line number from which the + # warning originated and the warning text. Optionally the format may contain + # $version, which will be replaced by the version of the file (if it could + # be obtained via FILE_VERSION_FILTER) + + WARN_FORMAT = + + # The WARN_LOGFILE tag can be used to specify a file to which warning + # and error messages should be written. If left blank the output is written + # to stderr. + + WARN_LOGFILE = + + #--------------------------------------------------------------------------- + # configuration options related to the input files + #--------------------------------------------------------------------------- + + # The INPUT tag can be used to specify the files and/or directories that contain + # documented source files. You may enter file names like "myfile.cpp" or + # directories like "/usr/src/myproject". Separate the files or directories + # with spaces. + + INPUT = /localhome/tbrethou/2.2/testing/llvm-2.2/include \ + /localhome/tbrethou/2.2/testing/llvm-2.2/lib \ + /localhome/tbrethou/2.2/testing/llvm-2.2/docs/doxygen.intro + + # If the value of the INPUT tag contains directories, you can use the + # FILE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp + # and *.h) to filter out the source-files in the directories. If left + # blank the following patterns are tested: + # *.c *.cc *.cxx *.cpp *.c++ *.java *.ii *.ixx *.ipp *.i++ *.inl *.h *.hh *.hxx + # *.hpp *.h++ *.idl *.odl *.cs *.php *.php3 *.inc *.m *.mm + + FILE_PATTERNS = + + # The RECURSIVE tag can be used to turn specify whether or not subdirectories + # should be searched for input files as well. Possible values are YES and NO. + # If left blank NO is used. + + RECURSIVE = YES + + # The EXCLUDE tag can be used to specify files and/or directories that should + # excluded from the INPUT source files. This way you can easily exclude a + # subdirectory from a directory tree whose root is specified with the INPUT tag. + + EXCLUDE = + + # The EXCLUDE_SYMLINKS tag can be used select whether or not files or + # directories that are symbolic links (a Unix filesystem feature) are excluded + # from the input. + + EXCLUDE_SYMLINKS = NO + + # If the value of the INPUT tag contains directories, you can use the + # EXCLUDE_PATTERNS tag to specify one or more wildcard patterns to exclude + # certain files from those directories. Note that the wildcards are matched + # against the file with absolute path, so to exclude all test directories + # for example use the pattern */test/* + + EXCLUDE_PATTERNS = + + # The EXAMPLE_PATH tag can be used to specify one or more files or + # directories that contain example code fragments that are included (see + # the \include command). + + EXAMPLE_PATH = /localhome/tbrethou/2.2/testing/llvm-2.2/examples + + # If the value of the EXAMPLE_PATH tag contains directories, you can use the + # EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp + # and *.h) to filter out the source-files in the directories. If left + # blank all files are included. + + EXAMPLE_PATTERNS = + + # If the EXAMPLE_RECURSIVE tag is set to YES then subdirectories will be + # searched for input files to be used with the \include or \dontinclude + # commands irrespective of the value of the RECURSIVE tag. + # Possible values are YES and NO. If left blank NO is used. + + EXAMPLE_RECURSIVE = YES + + # The IMAGE_PATH tag can be used to specify one or more files or + # directories that contain image that are included in the documentation (see + # the \image command). + + IMAGE_PATH = /localhome/tbrethou/2.2/testing/llvm-2.2/docs/img + + # The INPUT_FILTER tag can be used to specify a program that doxygen should + # invoke to filter for each input file. Doxygen will invoke the filter program + # by executing (via popen()) the command , where + # is the value of the INPUT_FILTER tag, and is the name of an + # input file. Doxygen will then use the output that the filter program writes + # to standard output. If FILTER_PATTERNS is specified, this tag will be + # ignored. + + INPUT_FILTER = + + # The FILTER_PATTERNS tag can be used to specify filters on a per file pattern + # basis. Doxygen will compare the file name with each pattern and apply the + # filter if there is a match. The filters are a list of the form: + # pattern=filter (like *.cpp=my_cpp_filter). See INPUT_FILTER for further + # info on how filters are used. If FILTER_PATTERNS is empty, INPUT_FILTER + # is applied to all files. + + FILTER_PATTERNS = + + # If the FILTER_SOURCE_FILES tag is set to YES, the input filter (if set using + # INPUT_FILTER) will be used to filter the input files when producing source + # files to browse (i.e. when SOURCE_BROWSER is set to YES). + + FILTER_SOURCE_FILES = NO + + #--------------------------------------------------------------------------- + # configuration options related to source browsing + #--------------------------------------------------------------------------- + + # If the SOURCE_BROWSER tag is set to YES then a list of source files will + # be generated. Documented entities will be cross-referenced with these sources. + # Note: To get rid of all source code in the generated output, make sure also + # VERBATIM_HEADERS is set to NO. + + SOURCE_BROWSER = YES + + # Setting the INLINE_SOURCES tag to YES will include the body + # of functions and classes directly in the documentation. + + INLINE_SOURCES = NO + + # Setting the STRIP_CODE_COMMENTS tag to YES (the default) will instruct + # doxygen to hide any special comment blocks from generated source code + # fragments. Normal C and C++ comments will always remain visible. + + STRIP_CODE_COMMENTS = NO + + # If the REFERENCED_BY_RELATION tag is set to YES (the default) + # then for each documented function all documented + # functions referencing it will be listed. + + REFERENCED_BY_RELATION = YES + + # If the REFERENCES_RELATION tag is set to YES (the default) + # then for each documented function all documented entities + # called/used by that function will be listed. + + REFERENCES_RELATION = YES + + # If the USE_HTAGS tag is set to YES then the references to source code + # will point to the HTML generated by the htags(1) tool instead of doxygen + # built-in source browser. The htags tool is part of GNU's global source + # tagging system (see http://www.gnu.org/software/global/global.html). You + # will need version 4.8.6 or higher. + + #USE_HTAGS = NO + + # If the VERBATIM_HEADERS tag is set to YES (the default) then Doxygen + # will generate a verbatim copy of the header file for each class for + # which an include is specified. Set to NO to disable this. + + VERBATIM_HEADERS = YES + + #--------------------------------------------------------------------------- + # configuration options related to the alphabetical class index + #--------------------------------------------------------------------------- + + # If the ALPHABETICAL_INDEX tag is set to YES, an alphabetical index + # of all compounds will be generated. Enable this if the project + # contains a lot of classes, structs, unions or interfaces. + + ALPHABETICAL_INDEX = YES + + # If the alphabetical index is enabled (see ALPHABETICAL_INDEX) then + # the COLS_IN_ALPHA_INDEX tag can be used to specify the number of columns + # in which this list will be split (can be a number in the range [1..20]) + + COLS_IN_ALPHA_INDEX = 4 + + # In case all classes in a project start with a common prefix, all + # classes will be put under the same header in the alphabetical index. + # The IGNORE_PREFIX tag can be used to specify one or more prefixes that + # should be ignored while generating the index headers. + + IGNORE_PREFIX = llvm:: + + #--------------------------------------------------------------------------- + # configuration options related to the HTML output + #--------------------------------------------------------------------------- + + # If the GENERATE_HTML tag is set to YES (the default) Doxygen will + # generate HTML output. + + GENERATE_HTML = YES + + # The HTML_OUTPUT tag is used to specify where the HTML docs will be put. + # If a relative path is entered the value of OUTPUT_DIRECTORY will be + # put in front of it. If left blank `html' will be used as the default path. + + HTML_OUTPUT = html + + # The HTML_FILE_EXTENSION tag can be used to specify the file extension for + # each generated HTML page (for example: .htm,.php,.asp). If it is left blank + # doxygen will generate files with .html extension. + + HTML_FILE_EXTENSION = .html + + # The HTML_HEADER tag can be used to specify a personal HTML header for + # each generated HTML page. If it is left blank doxygen will generate a + # standard header. + + HTML_HEADER = /localhome/tbrethou/2.2/testing/llvm-2.2/docs/doxygen.header + + # The HTML_FOOTER tag can be used to specify a personal HTML footer for + # each generated HTML page. If it is left blank doxygen will generate a + # standard footer. + + HTML_FOOTER = /localhome/tbrethou/2.2/testing/llvm-2.2/docs/doxygen.footer + + # The HTML_STYLESHEET tag can be used to specify a user-defined cascading + # style sheet that is used by each HTML page. It can be used to + # fine-tune the look of the HTML output. If the tag is left blank doxygen + # will generate a default style sheet. Note that doxygen will try to copy + # the style sheet file to the HTML output directory, so don't put your own + # stylesheet in the HTML output directory as well, or it will be erased! + + HTML_STYLESHEET = /localhome/tbrethou/2.2/testing/llvm-2.2/docs/doxygen.css + + # If the HTML_ALIGN_MEMBERS tag is set to YES, the members of classes, + # files or namespaces will be aligned in HTML using tables. If set to + # NO a bullet list will be used. + + HTML_ALIGN_MEMBERS = YES + + # If the GENERATE_HTMLHELP tag is set to YES, additional index files + # will be generated that can be used as input for tools like the + # Microsoft HTML help workshop to generate a compressed HTML help file (.chm) + # of the generated HTML documentation. + + GENERATE_HTMLHELP = NO + + # If the GENERATE_HTMLHELP tag is set to YES, the CHM_FILE tag can + # be used to specify the file name of the resulting .chm file. You + # can add a path in front of the file if the result should not be + # written to the html output directory. + + CHM_FILE = + + # If the GENERATE_HTMLHELP tag is set to YES, the HHC_LOCATION tag can + # be used to specify the location (absolute path including file name) of + # the HTML help compiler (hhc.exe). If non-empty doxygen will try to run + # the HTML help compiler on the generated index.hhp. + + HHC_LOCATION = + + # If the GENERATE_HTMLHELP tag is set to YES, the GENERATE_CHI flag + # controls if a separate .chi index file is generated (YES) or that + # it should be included in the master .chm file (NO). + + GENERATE_CHI = NO + + # If the GENERATE_HTMLHELP tag is set to YES, the BINARY_TOC flag + # controls whether a binary table of contents is generated (YES) or a + # normal table of contents (NO) in the .chm file. + + BINARY_TOC = NO + + # The TOC_EXPAND flag can be set to YES to add extra items for group members + # to the contents of the HTML help documentation and to the tree view. + + TOC_EXPAND = NO + + # The DISABLE_INDEX tag can be used to turn on/off the condensed index at + # top of each HTML page. The value NO (the default) enables the index and + # the value YES disables it. + + DISABLE_INDEX = NO + + # This tag can be used to set the number of enum values (range [1..20]) + # that doxygen will group on one line in the generated HTML documentation. + + ENUM_VALUES_PER_LINE = 4 + + # If the GENERATE_TREEVIEW tag is set to YES, a side panel will be + # generated containing a tree-like index structure (just like the one that + # is generated for HTML Help). For this to work a browser that supports + # JavaScript, DHTML, CSS and frames is required (for instance Mozilla 1.0+, + # Netscape 6.0+, Internet explorer 5.0+, or Konqueror). Windows users are + # probably better off using the HTML help feature. + + GENERATE_TREEVIEW = NO + + # If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be + # used to set the initial width (in pixels) of the frame in which the tree + # is shown. + + TREEVIEW_WIDTH = 250 + + #--------------------------------------------------------------------------- + # configuration options related to the LaTeX output + #--------------------------------------------------------------------------- + + # If the GENERATE_LATEX tag is set to YES (the default) Doxygen will + # generate Latex output. + + GENERATE_LATEX = NO + + # The LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put. + # If a relative path is entered the value of OUTPUT_DIRECTORY will be + # put in front of it. If left blank `latex' will be used as the default path. + + LATEX_OUTPUT = + + # The LATEX_CMD_NAME tag can be used to specify the LaTeX command name to be + # invoked. If left blank `latex' will be used as the default command name. + + LATEX_CMD_NAME = latex + + # The MAKEINDEX_CMD_NAME tag can be used to specify the command name to + # generate index for LaTeX. If left blank `makeindex' will be used as the + # default command name. + + MAKEINDEX_CMD_NAME = makeindex + + # If the COMPACT_LATEX tag is set to YES Doxygen generates more compact + # LaTeX documents. This may be useful for small projects and may help to + # save some trees in general. + + COMPACT_LATEX = NO + + # The PAPER_TYPE tag can be used to set the paper type that is used + # by the printer. Possible values are: a4, a4wide, letter, legal and + # executive. If left blank a4wide will be used. + + PAPER_TYPE = letter + + # The EXTRA_PACKAGES tag can be to specify one or more names of LaTeX + # packages that should be included in the LaTeX output. + + EXTRA_PACKAGES = + + # The LATEX_HEADER tag can be used to specify a personal LaTeX header for + # the generated latex document. The header should contain everything until + # the first chapter. If it is left blank doxygen will generate a + # standard header. Notice: only use this tag if you know what you are doing! + + LATEX_HEADER = + + # If the PDF_HYPERLINKS tag is set to YES, the LaTeX that is generated + # is prepared for conversion to pdf (using ps2pdf). The pdf file will + # contain links (just like the HTML output) instead of page references + # This makes the output suitable for online browsing using a pdf viewer. + + PDF_HYPERLINKS = NO + + # If the USE_PDFLATEX tag is set to YES, pdflatex will be used instead of + # plain latex in the generated Makefile. Set this option to YES to get a + # higher quality PDF documentation. + + USE_PDFLATEX = NO + + # If the LATEX_BATCHMODE tag is set to YES, doxygen will add the \\batchmode. + # command to the generated LaTeX files. This will instruct LaTeX to keep + # running if errors occur, instead of asking the user for help. + # This option is also used when generating formulas in HTML. + + LATEX_BATCHMODE = NO + + # If LATEX_HIDE_INDICES is set to YES then doxygen will not + # include the index chapters (such as File Index, Compound Index, etc.) + # in the output. + + LATEX_HIDE_INDICES = NO + + #--------------------------------------------------------------------------- + # configuration options related to the RTF output + #--------------------------------------------------------------------------- + + # If the GENERATE_RTF tag is set to YES Doxygen will generate RTF output + # The RTF output is optimized for Word 97 and may not look very pretty with + # other RTF readers or editors. + + GENERATE_RTF = NO + + # The RTF_OUTPUT tag is used to specify where the RTF docs will be put. + # If a relative path is entered the value of OUTPUT_DIRECTORY will be + # put in front of it. If left blank `rtf' will be used as the default path. + + RTF_OUTPUT = + + # If the COMPACT_RTF tag is set to YES Doxygen generates more compact + # RTF documents. This may be useful for small projects and may help to + # save some trees in general. + + COMPACT_RTF = NO + + # If the RTF_HYPERLINKS tag is set to YES, the RTF that is generated + # will contain hyperlink fields. The RTF file will + # contain links (just like the HTML output) instead of page references. + # This makes the output suitable for online browsing using WORD or other + # programs which support those fields. + # Note: wordpad (write) and others do not support links. + + RTF_HYPERLINKS = NO + + # Load stylesheet definitions from file. Syntax is similar to doxygen's + # config file, i.e. a series of assignments. You only have to provide + # replacements, missing definitions are set to their default value. + + RTF_STYLESHEET_FILE = + + # Set optional variables used in the generation of an rtf document. + # Syntax is similar to doxygen's config file. + + RTF_EXTENSIONS_FILE = + + #--------------------------------------------------------------------------- + # configuration options related to the man page output + #--------------------------------------------------------------------------- + + # If the GENERATE_MAN tag is set to YES (the default) Doxygen will + # generate man pages + + GENERATE_MAN = NO + + # The MAN_OUTPUT tag is used to specify where the man pages will be put. + # If a relative path is entered the value of OUTPUT_DIRECTORY will be + # put in front of it. If left blank `man' will be used as the default path. + + MAN_OUTPUT = + + # The MAN_EXTENSION tag determines the extension that is added to + # the generated man pages (default is the subroutine's section .3) + + MAN_EXTENSION = + + # If the MAN_LINKS tag is set to YES and Doxygen generates man output, + # then it will generate one additional man file for each entity + # documented in the real man page(s). These additional files + # only source the real man page, but without them the man command + # would be unable to find the correct page. The default is NO. + + MAN_LINKS = NO + + #--------------------------------------------------------------------------- + # configuration options related to the XML output + #--------------------------------------------------------------------------- + + # If the GENERATE_XML tag is set to YES Doxygen will + # generate an XML file that captures the structure of + # the code including all documentation. + + GENERATE_XML = NO + + # The XML_OUTPUT tag is used to specify where the XML pages will be put. + # If a relative path is entered the value of OUTPUT_DIRECTORY will be + # put in front of it. If left blank `xml' will be used as the default path. + + XML_OUTPUT = xml + + # The XML_SCHEMA tag can be used to specify an XML schema, + # which can be used by a validating XML parser to check the + # syntax of the XML files. + + XML_SCHEMA = + + # The XML_DTD tag can be used to specify an XML DTD, + # which can be used by a validating XML parser to check the + # syntax of the XML files. + + XML_DTD = + + # If the XML_PROGRAMLISTING tag is set to YES Doxygen will + # dump the program listings (including syntax highlighting + # and cross-referencing information) to the XML output. Note that + # enabling this will significantly increase the size of the XML output. + + XML_PROGRAMLISTING = YES + + #--------------------------------------------------------------------------- + # configuration options for the AutoGen Definitions output + #--------------------------------------------------------------------------- + + # If the GENERATE_AUTOGEN_DEF tag is set to YES Doxygen will + # generate an AutoGen Definitions (see autogen.sf.net) file + # that captures the structure of the code including all + # documentation. Note that this feature is still experimental + # and incomplete at the moment. + + GENERATE_AUTOGEN_DEF = NO + + #--------------------------------------------------------------------------- + # configuration options related to the Perl module output + #--------------------------------------------------------------------------- + + # If the GENERATE_PERLMOD tag is set to YES Doxygen will + # generate a Perl module file that captures the structure of + # the code including all documentation. Note that this + # feature is still experimental and incomplete at the + # moment. + + GENERATE_PERLMOD = NO + + # If the PERLMOD_LATEX tag is set to YES Doxygen will generate + # the necessary Makefile rules, Perl scripts and LaTeX code to be able + # to generate PDF and DVI output from the Perl module output. + + PERLMOD_LATEX = NO + + # If the PERLMOD_PRETTY tag is set to YES the Perl module output will be + # nicely formatted so it can be parsed by a human reader. This is useful + # if you want to understand what is going on. On the other hand, if this + # tag is set to NO the size of the Perl module output will be much smaller + # and Perl will parse it just the same. + + PERLMOD_PRETTY = YES + + # The names of the make variables in the generated doxyrules.make file + # are prefixed with the string contained in PERLMOD_MAKEVAR_PREFIX. + # This is useful so different doxyrules.make files included by the same + # Makefile don't overwrite each other's variables. + + PERLMOD_MAKEVAR_PREFIX = + + #--------------------------------------------------------------------------- + # Configuration options related to the preprocessor + #--------------------------------------------------------------------------- + + # If the ENABLE_PREPROCESSING tag is set to YES (the default) Doxygen will + # evaluate all C-preprocessor directives found in the sources and include + # files. + + ENABLE_PREPROCESSING = YES + + # If the MACRO_EXPANSION tag is set to YES Doxygen will expand all macro + # names in the source code. If set to NO (the default) only conditional + # compilation will be performed. Macro expansion can be done in a controlled + # way by setting EXPAND_ONLY_PREDEF to YES. + + MACRO_EXPANSION = NO + + # If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES + # then the macro expansion is limited to the macros specified with the + # PREDEFINED and EXPAND_AS_PREDEFINED tags. + + EXPAND_ONLY_PREDEF = NO + + # If the SEARCH_INCLUDES tag is set to YES (the default) the includes files + # in the INCLUDE_PATH (see below) will be search if a #include is found. + + SEARCH_INCLUDES = YES + + # The INCLUDE_PATH tag can be used to specify one or more directories that + # contain include files that are not input files but should be processed by + # the preprocessor. + + INCLUDE_PATH = ../include + + # You can use the INCLUDE_FILE_PATTERNS tag to specify one or more wildcard + # patterns (like *.h and *.hpp) to filter out the header-files in the + # directories. If left blank, the patterns specified with FILE_PATTERNS will + # be used. + + INCLUDE_FILE_PATTERNS = + + # The PREDEFINED tag can be used to specify one or more macro names that + # are defined before the preprocessor is started (similar to the -D option of + # gcc). The argument of the tag is a list of macros of the form: name + # or name=definition (no spaces). If the definition and the = are + # omitted =1 is assumed. To prevent a macro definition from being + # undefined via #undef or recursively expanded use the := operator + # instead of the = operator. + + PREDEFINED = + + # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then + # this tag can be used to specify a list of macro names that should be expanded. + # The macro definition that is found in the sources will be used. + # Use the PREDEFINED tag if you want to use a different macro definition. + + EXPAND_AS_DEFINED = + + # If the SKIP_FUNCTION_MACROS tag is set to YES (the default) then + # doxygen's preprocessor will remove all function-like macros that are alone + # on a line, have an all uppercase name, and do not end with a semicolon. Such + # function macros are typically used for boiler-plate code, and will confuse + # the parser if not removed. + + SKIP_FUNCTION_MACROS = YES + + #--------------------------------------------------------------------------- + # Configuration::additions related to external references + #--------------------------------------------------------------------------- + + # The TAGFILES option can be used to specify one or more tagfiles. + # Optionally an initial location of the external documentation + # can be added for each tagfile. The format of a tag file without + # this location is as follows: + # TAGFILES = file1 file2 ... + # Adding location for the tag files is done as follows: + # TAGFILES = file1=loc1 "file2 = loc2" ... + # where "loc1" and "loc2" can be relative or absolute paths or + # URLs. If a location is present for each tag, the installdox tool + # does not have to be run to correct the links. + # Note that each tag file must have a unique name + # (where the name does NOT include the path) + # If a tag file is not located in the directory in which doxygen + # is run, you must also specify the path to the tagfile here. + + TAGFILES = + + # When a file name is specified after GENERATE_TAGFILE, doxygen will create + # a tag file that is based on the input files it reads. + + GENERATE_TAGFILE = + + # If the ALLEXTERNALS tag is set to YES all external classes will be listed + # in the class index. If set to NO only the inherited external classes + # will be listed. + + ALLEXTERNALS = YES + + # If the EXTERNAL_GROUPS tag is set to YES all external groups will be listed + # in the modules index. If set to NO, only the current project's groups will + # be listed. + + EXTERNAL_GROUPS = YES + + # The PERL_PATH should be the absolute path and name of the perl script + # interpreter (i.e. the result of `which perl'). + + PERL_PATH = + + #--------------------------------------------------------------------------- + # Configuration options related to the dot tool + #--------------------------------------------------------------------------- + + # If the CLASS_DIAGRAMS tag is set to YES (the default) Doxygen will + # generate a inheritance diagram (in HTML, RTF and LaTeX) for classes with base + # or super classes. Setting the tag to NO turns the diagrams off. Note that + # this option is superseded by the HAVE_DOT option below. This is only a + # fallback. It is recommended to install and use dot, since it yields more + # powerful graphs. + + CLASS_DIAGRAMS = YES + + # If set to YES, the inheritance and collaboration graphs will hide + # inheritance and usage relations if the target is undocumented + # or is not a class. + + HIDE_UNDOC_RELATIONS = NO + + # If you set the HAVE_DOT tag to YES then doxygen will assume the dot tool is + # available from the path. This tool is part of Graphviz, a graph visualization + # toolkit from AT&T and Lucent Bell Labs. The other options in this section + # have no effect if this option is set to NO (the default) + + HAVE_DOT = YES + + # If the CLASS_GRAPH and HAVE_DOT tags are set to YES then doxygen + # will generate a graph for each documented class showing the direct and + # indirect inheritance relations. Setting this tag to YES will force the + # the CLASS_DIAGRAMS tag to NO. + + CLASS_GRAPH = YES + + # If the COLLABORATION_GRAPH and HAVE_DOT tags are set to YES then doxygen + # will generate a graph for each documented class showing the direct and + # indirect implementation dependencies (inheritance, containment, and + # class references variables) of the class with other documented classes. + + COLLABORATION_GRAPH = YES + + # If the GROUP_GRAPHS and HAVE_DOT tags are set to YES then doxygen + # will generate a graph for groups, showing the direct groups dependencies + + #GROUP_GRAPHS = YES + + # If the UML_LOOK tag is set to YES doxygen will generate inheritance and + # collaboration diagrams in a style similar to the OMG's Unified Modeling + # Language. + + UML_LOOK = NO + + # If set to YES, the inheritance and collaboration graphs will show the + # relations between templates and their instances. + + TEMPLATE_RELATIONS = YES + + # If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDE_GRAPH, and HAVE_DOT + # tags are set to YES then doxygen will generate a graph for each documented + # file showing the direct and indirect include dependencies of the file with + # other documented files. + + INCLUDE_GRAPH = YES + + # If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDED_BY_GRAPH, and + # HAVE_DOT tags are set to YES then doxygen will generate a graph for each + # documented header file showing the documented files that directly or + # indirectly include this file. + + INCLUDED_BY_GRAPH = YES + + # If the CALL_GRAPH and HAVE_DOT tags are set to YES then doxygen will + # generate a call dependency graph for every global function or class method. + # Note that enabling this option will significantly increase the time of a run. + # So in most cases it will be better to enable call graphs for selected + # functions only using the \callgraph command. + + CALL_GRAPH = NO + + # If the GRAPHICAL_HIERARCHY and HAVE_DOT tags are set to YES then doxygen + # will graphical hierarchy of all classes instead of a textual one. + + GRAPHICAL_HIERARCHY = YES + + # If the DIRECTORY_GRAPH, SHOW_DIRECTORIES and HAVE_DOT tags are set to YES + # then doxygen will show the dependencies a directory has on other directories + # in a graphical way. The dependency relations are determined by the #include + # relations between the files in the directories. + + #DIRECTORY_GRAPH = YES + + # The DOT_IMAGE_FORMAT tag can be used to set the image format of the images + # generated by dot. Possible values are png, jpg, or gif + # If left blank png will be used. + + DOT_IMAGE_FORMAT = png + + # The tag DOT_PATH can be used to specify the path where the dot tool can be + # found. If left blank, it is assumed the dot tool can be found in the path. + + DOT_PATH = echo dot + + # The DOTFILE_DIRS tag can be used to specify one or more directories that + # contain dot files that are included in the documentation (see the + # \dotfile command). + + DOTFILE_DIRS = + + # The MAX_DOT_GRAPH_WIDTH tag can be used to set the maximum allowed width + # (in pixels) of the graphs generated by dot. If a graph becomes larger than + # this value, doxygen will try to truncate the graph, so that it fits within + # the specified constraint. Beware that most browsers cannot cope with very + # large images. + + MAX_DOT_GRAPH_WIDTH = 1024 + + # The MAX_DOT_GRAPH_HEIGHT tag can be used to set the maximum allows height + # (in pixels) of the graphs generated by dot. If a graph becomes larger than + # this value, doxygen will try to truncate the graph, so that it fits within + # the specified constraint. Beware that most browsers cannot cope with very + # large images. + + MAX_DOT_GRAPH_HEIGHT = 1024 + + # The MAX_DOT_GRAPH_DEPTH tag can be used to set the maximum depth of the + # graphs generated by dot. A depth value of 3 means that only nodes reachable + # from the root by following a path via at most 3 edges will be shown. Nodes + # that lay further from the root node will be omitted. Note that setting this + # option to 1 or 2 may greatly reduce the computation time needed for large + # code bases. Also note that a graph may be further truncated if the graph's + # image dimensions are not sufficient to fit the graph (see MAX_DOT_GRAPH_WIDTH + # and MAX_DOT_GRAPH_HEIGHT). If 0 is used for the depth value (the default), + # the graph is not depth-constrained. + + MAX_DOT_GRAPH_DEPTH = 0 + + # Set the DOT_TRANSPARENT tag to YES to generate images with a transparent + # background. This is disabled by default, which results in a white background. + # Warning: Depending on the platform used, enabling this option may lead to + # badly anti-aliased labels on the edges of a graph (i.e. they become hard to + # read). + + #DOT_TRANSPARENT = NO + + # Set the DOT_MULTI_TARGETS tag to YES allow dot to generate multiple output + # files in one run (i.e. multiple -o and -T options on the command line). This + # makes dot run faster, but since only newer versions of dot (>1.8.10) + # support this, this feature is disabled by default. + + #DOT_MULTI_TARGETS = NO + + # If the GENERATE_LEGEND tag is set to YES (the default) Doxygen will + # generate a legend page explaining the meaning of the various boxes and + # arrows in the dot generated graphs. + + GENERATE_LEGEND = YES + + # If the DOT_CLEANUP tag is set to YES (the default) Doxygen will + # remove the intermediate dot files that are used to generate + # the various graphs. + + DOT_CLEANUP = YES + + #--------------------------------------------------------------------------- + # Configuration::additions related to the search engine + #--------------------------------------------------------------------------- + + # The SEARCHENGINE tag specifies whether or not a search engine should be + # used. If set to NO the values of all tags below this one will be ignored. + + SEARCHENGINE = NO Index: llvm-www/releases/2.2/docs/doxygen.cfg.in diff -c /dev/null llvm-www/releases/2.2/docs/doxygen.cfg.in:1.1 *** /dev/null Tue Feb 12 00:07:06 2008 --- llvm-www/releases/2.2/docs/doxygen.cfg.in Tue Feb 12 00:05:03 2008 *************** *** 0 **** --- 1,1230 ---- + # Doxyfile 1.4.4 + + # This file describes the settings to be used by the documentation system + # doxygen (www.doxygen.org) for a project + # + # All text after a hash (#) is considered a comment and will be ignored + # The format is: + # TAG = value [value, ...] + # For lists items can also be appended using: + # TAG += value [value, ...] + # Values that contain spaces should be placed between quotes (" ") + + #--------------------------------------------------------------------------- + # Project related configuration options + #--------------------------------------------------------------------------- + + # The PROJECT_NAME tag is a single word (or a sequence of words surrounded + # by quotes) that should identify the project. + + PROJECT_NAME = LLVM + + # The PROJECT_NUMBER tag can be used to enter a project or revision number. + # This could be handy for archiving the generated documentation or + # if some version control system is used. + + PROJECT_NUMBER = @PACKAGE_VERSION@ + + # The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) + # base path where the generated documentation will be put. + # If a relative path is entered, it will be relative to the location + # where doxygen was started. If left blank the current directory will be used. + + OUTPUT_DIRECTORY = @abs_top_builddir@/docs/doxygen + + # If the CREATE_SUBDIRS tag is set to YES, then doxygen will create + # 4096 sub-directories (in 2 levels) under the output directory of each output + # format and will distribute the generated files over these directories. + # Enabling this option can be useful when feeding doxygen a huge amount of + # source files, where putting all generated files in the same directory would + # otherwise cause performance problems for the file system. + + CREATE_SUBDIRS = NO + + # The OUTPUT_LANGUAGE tag is used to specify the language in which all + # documentation generated by doxygen is written. Doxygen will use this + # information to generate all constant output in the proper language. + # The default language is English, other supported languages are: + # Brazilian, Catalan, Chinese, Chinese-Traditional, Croatian, Czech, Danish, + # Dutch, Finnish, French, German, Greek, Hungarian, Italian, Japanese, + # Japanese-en (Japanese with English messages), Korean, Korean-en, Norwegian, + # Polish, Portuguese, Romanian, Russian, Serbian, Slovak, Slovene, Spanish, + # Swedish, and Ukrainian. + + OUTPUT_LANGUAGE = English + + # This tag can be used to specify the encoding used in the generated output. + # The encoding is not always determined by the language that is chosen, + # but also whether or not the output is meant for Windows or non-Windows users. + # In case there is a difference, setting the USE_WINDOWS_ENCODING tag to YES + # forces the Windows encoding (this is the default for the Windows binary), + # whereas setting the tag to NO uses a Unix-style encoding (the default for + # all platforms other than Windows). + + USE_WINDOWS_ENCODING = NO + + # If the BRIEF_MEMBER_DESC tag is set to YES (the default) Doxygen will + # include brief member descriptions after the members that are listed in + # the file and class documentation (similar to JavaDoc). + # Set to NO to disable this. + + BRIEF_MEMBER_DESC = YES + + # If the REPEAT_BRIEF tag is set to YES (the default) Doxygen will prepend + # the brief description of a member or function before the detailed description. + # Note: if both HIDE_UNDOC_MEMBERS and BRIEF_MEMBER_DESC are set to NO, the + # brief descriptions will be completely suppressed. + + REPEAT_BRIEF = YES + + # This tag implements a quasi-intelligent brief description abbreviator + # that is used to form the text in various listings. Each string + # in this list, if found as the leading text of the brief description, will be + # stripped from the text and the result after processing the whole list, is + # used as the annotated text. Otherwise, the brief description is used as-is. + # If left blank, the following values are used ("$name" is automatically + # replaced with the name of the entity): "The $name class" "The $name widget" + # "The $name file" "is" "provides" "specifies" "contains" + # "represents" "a" "an" "the" + + ABBREVIATE_BRIEF = + + # If the ALWAYS_DETAILED_SEC and REPEAT_BRIEF tags are both set to YES then + # Doxygen will generate a detailed section even if there is only a brief + # description. + + ALWAYS_DETAILED_SEC = NO + + # If the INLINE_INHERITED_MEMB tag is set to YES, doxygen will show all + # inherited members of a class in the documentation of that class as if those + # members were ordinary class members. Constructors, destructors and assignment + # operators of the base classes will not be shown. + + INLINE_INHERITED_MEMB = NO + + # If the FULL_PATH_NAMES tag is set to YES then Doxygen will prepend the full + # path before files name in the file list and in the header files. If set + # to NO the shortest path that makes the file name unique will be used. + + FULL_PATH_NAMES = NO + + # If the FULL_PATH_NAMES tag is set to YES then the STRIP_FROM_PATH tag + # can be used to strip a user-defined part of the path. Stripping is + # only done if one of the specified strings matches the left-hand part of + # the path. The tag can be used to show relative paths in the file list. + # If left blank the directory from which doxygen is run is used as the + # path to strip. + + STRIP_FROM_PATH = ../.. + + # The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of + # the path mentioned in the documentation of a class, which tells + # the reader which header file to include in order to use a class. + # If left blank only the name of the header file containing the class + # definition is used. Otherwise one should specify the include paths that + # are normally passed to the compiler using the -I flag. + + STRIP_FROM_INC_PATH = + + # If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter + # (but less readable) file names. This can be useful is your file systems + # doesn't support long names like on DOS, Mac, or CD-ROM. + + SHORT_NAMES = NO + + # If the JAVADOC_AUTOBRIEF tag is set to YES then Doxygen + # will interpret the first line (until the first dot) of a JavaDoc-style + # comment as the brief description. If set to NO, the JavaDoc + # comments will behave just like the Qt-style comments (thus requiring an + # explicit @brief command for a brief description. + + JAVADOC_AUTOBRIEF = NO + + # The MULTILINE_CPP_IS_BRIEF tag can be set to YES to make Doxygen + # treat a multi-line C++ special comment block (i.e. a block of //! or /// + # comments) as a brief description. This used to be the default behaviour. + # The new default is to treat a multi-line C++ comment block as a detailed + # description. Set this tag to YES if you prefer the old behaviour instead. + + MULTILINE_CPP_IS_BRIEF = NO + + # If the DETAILS_AT_TOP tag is set to YES then Doxygen + # will output the detailed description near the top, like JavaDoc. + # If set to NO, the detailed description appears after the member + # documentation. + + DETAILS_AT_TOP = NO + + # If the INHERIT_DOCS tag is set to YES (the default) then an undocumented + # member inherits the documentation from any documented member that it + # re-implements. + + INHERIT_DOCS = YES + + # If member grouping is used in the documentation and the DISTRIBUTE_GROUP_DOC + # tag is set to YES, then doxygen will reuse the documentation of the first + # member in the group (if any) for the other members of the group. By default + # all members of a group must be documented explicitly. + + DISTRIBUTE_GROUP_DOC = NO + + # If the SEPARATE_MEMBER_PAGES tag is set to YES, then doxygen will produce + # a new page for each member. If set to NO, the documentation of a member will + # be part of the file/class/namespace that contains it. + + #SEPARATE_MEMBER_PAGES = NO + + # The TAB_SIZE tag can be used to set the number of spaces in a tab. + # Doxygen uses this value to replace tabs by spaces in code fragments. + + TAB_SIZE = 2 + + # This tag can be used to specify a number of aliases that acts + # as commands in the documentation. An alias has the form "name=value". + # For example adding "sideeffect=\par Side Effects:\n" will allow you to + # put the command \sideeffect (or @sideeffect) in the documentation, which + # will result in a user-defined paragraph with heading "Side Effects:". + # You can put \n's in the value part of an alias to insert newlines. + + ALIASES = + + # Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C + # sources only. Doxygen will then generate output that is more tailored for C. + # For instance, some of the names that are used will be different. The list + # of all members will be omitted, etc. + + OPTIMIZE_OUTPUT_FOR_C = NO + + # Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java sources + # only. Doxygen will then generate output that is more tailored for Java. + # For instance, namespaces will be presented as packages, qualified scopes + # will look different, etc. + + OPTIMIZE_OUTPUT_JAVA = NO + + # Set the SUBGROUPING tag to YES (the default) to allow class member groups of + # the same type (for instance a group of public functions) to be put as a + # subgroup of that type (e.g. under the Public Functions section). Set it to + # NO to prevent subgrouping. Alternatively, this can be done per class using + # the \nosubgrouping command. + + SUBGROUPING = YES + + #--------------------------------------------------------------------------- + # Build related configuration options + #--------------------------------------------------------------------------- + + # If the EXTRACT_ALL tag is set to YES doxygen will assume all entities in + # documentation are documented, even if no documentation was available. + # Private class members and static file members will be hidden unless + # the EXTRACT_PRIVATE and EXTRACT_STATIC tags are set to YES + + EXTRACT_ALL = YES + + # If the EXTRACT_PRIVATE tag is set to YES all private members of a class + # will be included in the documentation. + + EXTRACT_PRIVATE = NO + + # If the EXTRACT_STATIC tag is set to YES all static members of a file + # will be included in the documentation. + + EXTRACT_STATIC = YES + + # If the EXTRACT_LOCAL_CLASSES tag is set to YES classes (and structs) + # defined locally in source files will be included in the documentation. + # If set to NO only classes defined in header files are included. + + EXTRACT_LOCAL_CLASSES = YES + + # This flag is only useful for Objective-C code. When set to YES local + # methods, which are defined in the implementation section but not in + # the interface are included in the documentation. + # If set to NO (the default) only methods in the interface are included. + + EXTRACT_LOCAL_METHODS = NO + + # If the HIDE_UNDOC_MEMBERS tag is set to YES, Doxygen will hide all + # undocumented members of documented classes, files or namespaces. + # If set to NO (the default) these members will be included in the + # various overviews, but no documentation section is generated. + # This option has no effect if EXTRACT_ALL is enabled. + + HIDE_UNDOC_MEMBERS = NO + + # If the HIDE_UNDOC_CLASSES tag is set to YES, Doxygen will hide all + # undocumented classes that are normally visible in the class hierarchy. + # If set to NO (the default) these classes will be included in the various + # overviews. This option has no effect if EXTRACT_ALL is enabled. + + HIDE_UNDOC_CLASSES = NO + + # If the HIDE_FRIEND_COMPOUNDS tag is set to YES, Doxygen will hide all + # friend (class|struct|union) declarations. + # If set to NO (the default) these declarations will be included in the + # documentation. + + HIDE_FRIEND_COMPOUNDS = NO + + # If the HIDE_IN_BODY_DOCS tag is set to YES, Doxygen will hide any + # documentation blocks found inside the body of a function. + # If set to NO (the default) these blocks will be appended to the + # function's detailed documentation block. + + HIDE_IN_BODY_DOCS = NO + + # The INTERNAL_DOCS tag determines if documentation + # that is typed after a \internal command is included. If the tag is set + # to NO (the default) then the documentation will be excluded. + # Set it to YES to include the internal documentation. + + INTERNAL_DOCS = NO + + # If the CASE_SENSE_NAMES tag is set to NO then Doxygen will only generate + # file names in lower-case letters. If set to YES upper-case letters are also + # allowed. This is useful if you have classes or files whose names only differ + # in case and if your file system supports case sensitive file names. Windows + # and Mac users are advised to set this option to NO. + + CASE_SENSE_NAMES = YES + + # If the HIDE_SCOPE_NAMES tag is set to NO (the default) then Doxygen + # will show members with their full class and namespace scopes in the + # documentation. If set to YES the scope will be hidden. + + HIDE_SCOPE_NAMES = NO + + # If the SHOW_INCLUDE_FILES tag is set to YES (the default) then Doxygen + # will put a list of the files that are included by a file in the documentation + # of that file. + + SHOW_INCLUDE_FILES = YES + + # If the INLINE_INFO tag is set to YES (the default) then a tag [inline] + # is inserted in the documentation for inline members. + + INLINE_INFO = YES + + # If the SORT_MEMBER_DOCS tag is set to YES (the default) then doxygen + # will sort the (detailed) documentation of file and class members + # alphabetically by member name. If set to NO the members will appear in + # declaration order. + + SORT_MEMBER_DOCS = YES + + # If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the + # brief documentation of file, namespace and class members alphabetically + # by member name. If set to NO (the default) the members will appear in + # declaration order. + + SORT_BRIEF_DOCS = NO + + # If the SORT_BY_SCOPE_NAME tag is set to YES, the class list will be + # sorted by fully-qualified names, including namespaces. If set to + # NO (the default), the class list will be sorted only by class name, + # not including the namespace part. + # Note: This option is not very useful if HIDE_SCOPE_NAMES is set to YES. + # Note: This option applies only to the class list, not to the + # alphabetical list. + + SORT_BY_SCOPE_NAME = NO + + # The GENERATE_TODOLIST tag can be used to enable (YES) or + # disable (NO) the todo list. This list is created by putting \todo + # commands in the documentation. + + GENERATE_TODOLIST = YES + + # The GENERATE_TESTLIST tag can be used to enable (YES) or + # disable (NO) the test list. This list is created by putting \test + # commands in the documentation. + + GENERATE_TESTLIST = YES + + # The GENERATE_BUGLIST tag can be used to enable (YES) or + # disable (NO) the bug list. This list is created by putting \bug + # commands in the documentation. + + GENERATE_BUGLIST = YES + + # The GENERATE_DEPRECATEDLIST tag can be used to enable (YES) or + # disable (NO) the deprecated list. This list is created by putting + # \deprecated commands in the documentation. + + GENERATE_DEPRECATEDLIST= YES + + # The ENABLED_SECTIONS tag can be used to enable conditional + # documentation sections, marked by \if sectionname ... \endif. + + ENABLED_SECTIONS = + + # The MAX_INITIALIZER_LINES tag determines the maximum number of lines + # the initial value of a variable or define consists of for it to appear in + # the documentation. If the initializer consists of more lines than specified + # here it will be hidden. Use a value of 0 to hide initializers completely. + # The appearance of the initializer of individual variables and defines in the + # documentation can be controlled using \showinitializer or \hideinitializer + # command in the documentation regardless of this setting. + + MAX_INITIALIZER_LINES = 30 + + # Set the SHOW_USED_FILES tag to NO to disable the list of files generated + # at the bottom of the documentation of classes and structs. If set to YES the + # list will mention the files that were used to generate the documentation. + + SHOW_USED_FILES = YES + + # If the sources in your project are distributed over multiple directories + # then setting the SHOW_DIRECTORIES tag to YES will show the directory hierarchy + # in the documentation. The default is YES. + + SHOW_DIRECTORIES = YES + + # The FILE_VERSION_FILTER tag can be used to specify a program or script that + # doxygen should invoke to get the current version for each file (typically from the + # version control system). Doxygen will invoke the program by executing (via + # popen()) the command , where is the value of + # the FILE_VERSION_FILTER tag, and is the name of an input file + # provided by doxygen. Whatever the progam writes to standard output + # is used as the file version. See the manual for examples. + + #FILE_VERSION_FILTER = + + #--------------------------------------------------------------------------- + # configuration options related to warning and progress messages + #--------------------------------------------------------------------------- + + # The QUIET tag can be used to turn on/off the messages that are generated + # by doxygen. Possible values are YES and NO. If left blank NO is used. + + QUIET = NO + + # The WARNINGS tag can be used to turn on/off the warning messages that are + # generated by doxygen. Possible values are YES and NO. If left blank + # NO is used. + + WARNINGS = NO + + # If WARN_IF_UNDOCUMENTED is set to YES, then doxygen will generate warnings + # for undocumented members. If EXTRACT_ALL is set to YES then this flag will + # automatically be disabled. + + WARN_IF_UNDOCUMENTED = NO + + # If WARN_IF_DOC_ERROR is set to YES, doxygen will generate warnings for + # potential errors in the documentation, such as not documenting some + # parameters in a documented function, or documenting parameters that + # don't exist or using markup commands wrongly. + + WARN_IF_DOC_ERROR = YES + + # This WARN_NO_PARAMDOC option can be abled to get warnings for + # functions that are documented, but have no documentation for their parameters + # or return value. If set to NO (the default) doxygen will only warn about + # wrong or incomplete parameter documentation, but not about the absence of + # documentation. + + #WARN_NO_PARAMDOC = NO + + # The WARN_FORMAT tag determines the format of the warning messages that + # doxygen can produce. The string should contain the $file, $line, and $text + # tags, which will be replaced by the file and line number from which the + # warning originated and the warning text. Optionally the format may contain + # $version, which will be replaced by the version of the file (if it could + # be obtained via FILE_VERSION_FILTER) + + WARN_FORMAT = + + # The WARN_LOGFILE tag can be used to specify a file to which warning + # and error messages should be written. If left blank the output is written + # to stderr. + + WARN_LOGFILE = + + #--------------------------------------------------------------------------- + # configuration options related to the input files + #--------------------------------------------------------------------------- + + # The INPUT tag can be used to specify the files and/or directories that contain + # documented source files. You may enter file names like "myfile.cpp" or + # directories like "/usr/src/myproject". Separate the files or directories + # with spaces. + + INPUT = @abs_top_srcdir@/include \ + @abs_top_srcdir@/lib \ + @abs_top_srcdir@/docs/doxygen.intro + + # If the value of the INPUT tag contains directories, you can use the + # FILE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp + # and *.h) to filter out the source-files in the directories. If left + # blank the following patterns are tested: + # *.c *.cc *.cxx *.cpp *.c++ *.java *.ii *.ixx *.ipp *.i++ *.inl *.h *.hh *.hxx + # *.hpp *.h++ *.idl *.odl *.cs *.php *.php3 *.inc *.m *.mm + + FILE_PATTERNS = + + # The RECURSIVE tag can be used to turn specify whether or not subdirectories + # should be searched for input files as well. Possible values are YES and NO. + # If left blank NO is used. + + RECURSIVE = YES + + # The EXCLUDE tag can be used to specify files and/or directories that should + # excluded from the INPUT source files. This way you can easily exclude a + # subdirectory from a directory tree whose root is specified with the INPUT tag. + + EXCLUDE = + + # The EXCLUDE_SYMLINKS tag can be used select whether or not files or + # directories that are symbolic links (a Unix filesystem feature) are excluded + # from the input. + + EXCLUDE_SYMLINKS = NO + + # If the value of the INPUT tag contains directories, you can use the + # EXCLUDE_PATTERNS tag to specify one or more wildcard patterns to exclude + # certain files from those directories. Note that the wildcards are matched + # against the file with absolute path, so to exclude all test directories + # for example use the pattern */test/* + + EXCLUDE_PATTERNS = + + # The EXAMPLE_PATH tag can be used to specify one or more files or + # directories that contain example code fragments that are included (see + # the \include command). + + EXAMPLE_PATH = @abs_top_srcdir@/examples + + # If the value of the EXAMPLE_PATH tag contains directories, you can use the + # EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp + # and *.h) to filter out the source-files in the directories. If left + # blank all files are included. + + EXAMPLE_PATTERNS = + + # If the EXAMPLE_RECURSIVE tag is set to YES then subdirectories will be + # searched for input files to be used with the \include or \dontinclude + # commands irrespective of the value of the RECURSIVE tag. + # Possible values are YES and NO. If left blank NO is used. + + EXAMPLE_RECURSIVE = YES + + # The IMAGE_PATH tag can be used to specify one or more files or + # directories that contain image that are included in the documentation (see + # the \image command). + + IMAGE_PATH = @abs_top_srcdir@/docs/img + + # The INPUT_FILTER tag can be used to specify a program that doxygen should + # invoke to filter for each input file. Doxygen will invoke the filter program + # by executing (via popen()) the command , where + # is the value of the INPUT_FILTER tag, and is the name of an + # input file. Doxygen will then use the output that the filter program writes + # to standard output. If FILTER_PATTERNS is specified, this tag will be + # ignored. + + INPUT_FILTER = + + # The FILTER_PATTERNS tag can be used to specify filters on a per file pattern + # basis. Doxygen will compare the file name with each pattern and apply the + # filter if there is a match. The filters are a list of the form: + # pattern=filter (like *.cpp=my_cpp_filter). See INPUT_FILTER for further + # info on how filters are used. If FILTER_PATTERNS is empty, INPUT_FILTER + # is applied to all files. + + FILTER_PATTERNS = + + # If the FILTER_SOURCE_FILES tag is set to YES, the input filter (if set using + # INPUT_FILTER) will be used to filter the input files when producing source + # files to browse (i.e. when SOURCE_BROWSER is set to YES). + + FILTER_SOURCE_FILES = NO + + #--------------------------------------------------------------------------- + # configuration options related to source browsing + #--------------------------------------------------------------------------- + + # If the SOURCE_BROWSER tag is set to YES then a list of source files will + # be generated. Documented entities will be cross-referenced with these sources. + # Note: To get rid of all source code in the generated output, make sure also + # VERBATIM_HEADERS is set to NO. + + SOURCE_BROWSER = YES + + # Setting the INLINE_SOURCES tag to YES will include the body + # of functions and classes directly in the documentation. + + INLINE_SOURCES = NO + + # Setting the STRIP_CODE_COMMENTS tag to YES (the default) will instruct + # doxygen to hide any special comment blocks from generated source code + # fragments. Normal C and C++ comments will always remain visible. + + STRIP_CODE_COMMENTS = NO + + # If the REFERENCED_BY_RELATION tag is set to YES (the default) + # then for each documented function all documented + # functions referencing it will be listed. + + REFERENCED_BY_RELATION = YES + + # If the REFERENCES_RELATION tag is set to YES (the default) + # then for each documented function all documented entities + # called/used by that function will be listed. + + REFERENCES_RELATION = YES + + # If the USE_HTAGS tag is set to YES then the references to source code + # will point to the HTML generated by the htags(1) tool instead of doxygen + # built-in source browser. The htags tool is part of GNU's global source + # tagging system (see http://www.gnu.org/software/global/global.html). You + # will need version 4.8.6 or higher. + + #USE_HTAGS = NO + + # If the VERBATIM_HEADERS tag is set to YES (the default) then Doxygen + # will generate a verbatim copy of the header file for each class for + # which an include is specified. Set to NO to disable this. + + VERBATIM_HEADERS = YES + + #--------------------------------------------------------------------------- + # configuration options related to the alphabetical class index + #--------------------------------------------------------------------------- + + # If the ALPHABETICAL_INDEX tag is set to YES, an alphabetical index + # of all compounds will be generated. Enable this if the project + # contains a lot of classes, structs, unions or interfaces. + + ALPHABETICAL_INDEX = YES + + # If the alphabetical index is enabled (see ALPHABETICAL_INDEX) then + # the COLS_IN_ALPHA_INDEX tag can be used to specify the number of columns + # in which this list will be split (can be a number in the range [1..20]) + + COLS_IN_ALPHA_INDEX = 4 + + # In case all classes in a project start with a common prefix, all + # classes will be put under the same header in the alphabetical index. + # The IGNORE_PREFIX tag can be used to specify one or more prefixes that + # should be ignored while generating the index headers. + + IGNORE_PREFIX = llvm:: + + #--------------------------------------------------------------------------- + # configuration options related to the HTML output + #--------------------------------------------------------------------------- + + # If the GENERATE_HTML tag is set to YES (the default) Doxygen will + # generate HTML output. + + GENERATE_HTML = YES + + # The HTML_OUTPUT tag is used to specify where the HTML docs will be put. + # If a relative path is entered the value of OUTPUT_DIRECTORY will be + # put in front of it. If left blank `html' will be used as the default path. + + HTML_OUTPUT = html + + # The HTML_FILE_EXTENSION tag can be used to specify the file extension for + # each generated HTML page (for example: .htm,.php,.asp). If it is left blank + # doxygen will generate files with .html extension. + + HTML_FILE_EXTENSION = .html + + # The HTML_HEADER tag can be used to specify a personal HTML header for + # each generated HTML page. If it is left blank doxygen will generate a + # standard header. + + HTML_HEADER = @abs_top_srcdir@/docs/doxygen.header + + # The HTML_FOOTER tag can be used to specify a personal HTML footer for + # each generated HTML page. If it is left blank doxygen will generate a + # standard footer. + + HTML_FOOTER = @abs_top_srcdir@/docs/doxygen.footer + + # The HTML_STYLESHEET tag can be used to specify a user-defined cascading + # style sheet that is used by each HTML page. It can be used to + # fine-tune the look of the HTML output. If the tag is left blank doxygen + # will generate a default style sheet. Note that doxygen will try to copy + # the style sheet file to the HTML output directory, so don't put your own + # stylesheet in the HTML output directory as well, or it will be erased! + + HTML_STYLESHEET = @abs_top_srcdir@/docs/doxygen.css + + # If the HTML_ALIGN_MEMBERS tag is set to YES, the members of classes, + # files or namespaces will be aligned in HTML using tables. If set to + # NO a bullet list will be used. + + HTML_ALIGN_MEMBERS = YES + + # If the GENERATE_HTMLHELP tag is set to YES, additional index files + # will be generated that can be used as input for tools like the + # Microsoft HTML help workshop to generate a compressed HTML help file (.chm) + # of the generated HTML documentation. + + GENERATE_HTMLHELP = NO + + # If the GENERATE_HTMLHELP tag is set to YES, the CHM_FILE tag can + # be used to specify the file name of the resulting .chm file. You + # can add a path in front of the file if the result should not be + # written to the html output directory. + + CHM_FILE = + + # If the GENERATE_HTMLHELP tag is set to YES, the HHC_LOCATION tag can + # be used to specify the location (absolute path including file name) of + # the HTML help compiler (hhc.exe). If non-empty doxygen will try to run + # the HTML help compiler on the generated index.hhp. + + HHC_LOCATION = + + # If the GENERATE_HTMLHELP tag is set to YES, the GENERATE_CHI flag + # controls if a separate .chi index file is generated (YES) or that + # it should be included in the master .chm file (NO). + + GENERATE_CHI = NO + + # If the GENERATE_HTMLHELP tag is set to YES, the BINARY_TOC flag + # controls whether a binary table of contents is generated (YES) or a + # normal table of contents (NO) in the .chm file. + + BINARY_TOC = NO + + # The TOC_EXPAND flag can be set to YES to add extra items for group members + # to the contents of the HTML help documentation and to the tree view. + + TOC_EXPAND = NO + + # The DISABLE_INDEX tag can be used to turn on/off the condensed index at + # top of each HTML page. The value NO (the default) enables the index and + # the value YES disables it. + + DISABLE_INDEX = NO + + # This tag can be used to set the number of enum values (range [1..20]) + # that doxygen will group on one line in the generated HTML documentation. + + ENUM_VALUES_PER_LINE = 4 + + # If the GENERATE_TREEVIEW tag is set to YES, a side panel will be + # generated containing a tree-like index structure (just like the one that + # is generated for HTML Help). For this to work a browser that supports + # JavaScript, DHTML, CSS and frames is required (for instance Mozilla 1.0+, + # Netscape 6.0+, Internet explorer 5.0+, or Konqueror). Windows users are + # probably better off using the HTML help feature. + + GENERATE_TREEVIEW = NO + + # If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be + # used to set the initial width (in pixels) of the frame in which the tree + # is shown. + + TREEVIEW_WIDTH = 250 + + #--------------------------------------------------------------------------- + # configuration options related to the LaTeX output + #--------------------------------------------------------------------------- + + # If the GENERATE_LATEX tag is set to YES (the default) Doxygen will + # generate Latex output. + + GENERATE_LATEX = NO + + # The LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put. + # If a relative path is entered the value of OUTPUT_DIRECTORY will be + # put in front of it. If left blank `latex' will be used as the default path. + + LATEX_OUTPUT = + + # The LATEX_CMD_NAME tag can be used to specify the LaTeX command name to be + # invoked. If left blank `latex' will be used as the default command name. + + LATEX_CMD_NAME = latex + + # The MAKEINDEX_CMD_NAME tag can be used to specify the command name to + # generate index for LaTeX. If left blank `makeindex' will be used as the + # default command name. + + MAKEINDEX_CMD_NAME = makeindex + + # If the COMPACT_LATEX tag is set to YES Doxygen generates more compact + # LaTeX documents. This may be useful for small projects and may help to + # save some trees in general. + + COMPACT_LATEX = NO + + # The PAPER_TYPE tag can be used to set the paper type that is used + # by the printer. Possible values are: a4, a4wide, letter, legal and + # executive. If left blank a4wide will be used. + + PAPER_TYPE = letter + + # The EXTRA_PACKAGES tag can be to specify one or more names of LaTeX + # packages that should be included in the LaTeX output. + + EXTRA_PACKAGES = + + # The LATEX_HEADER tag can be used to specify a personal LaTeX header for + # the generated latex document. The header should contain everything until + # the first chapter. If it is left blank doxygen will generate a + # standard header. Notice: only use this tag if you know what you are doing! + + LATEX_HEADER = + + # If the PDF_HYPERLINKS tag is set to YES, the LaTeX that is generated + # is prepared for conversion to pdf (using ps2pdf). The pdf file will + # contain links (just like the HTML output) instead of page references + # This makes the output suitable for online browsing using a pdf viewer. + + PDF_HYPERLINKS = NO + + # If the USE_PDFLATEX tag is set to YES, pdflatex will be used instead of + # plain latex in the generated Makefile. Set this option to YES to get a + # higher quality PDF documentation. + + USE_PDFLATEX = NO + + # If the LATEX_BATCHMODE tag is set to YES, doxygen will add the \\batchmode. + # command to the generated LaTeX files. This will instruct LaTeX to keep + # running if errors occur, instead of asking the user for help. + # This option is also used when generating formulas in HTML. + + LATEX_BATCHMODE = NO + + # If LATEX_HIDE_INDICES is set to YES then doxygen will not + # include the index chapters (such as File Index, Compound Index, etc.) + # in the output. + + LATEX_HIDE_INDICES = NO + + #--------------------------------------------------------------------------- + # configuration options related to the RTF output + #--------------------------------------------------------------------------- + + # If the GENERATE_RTF tag is set to YES Doxygen will generate RTF output + # The RTF output is optimized for Word 97 and may not look very pretty with + # other RTF readers or editors. + + GENERATE_RTF = NO + + # The RTF_OUTPUT tag is used to specify where the RTF docs will be put. + # If a relative path is entered the value of OUTPUT_DIRECTORY will be + # put in front of it. If left blank `rtf' will be used as the default path. + + RTF_OUTPUT = + + # If the COMPACT_RTF tag is set to YES Doxygen generates more compact + # RTF documents. This may be useful for small projects and may help to + # save some trees in general. + + COMPACT_RTF = NO + + # If the RTF_HYPERLINKS tag is set to YES, the RTF that is generated + # will contain hyperlink fields. The RTF file will + # contain links (just like the HTML output) instead of page references. + # This makes the output suitable for online browsing using WORD or other + # programs which support those fields. + # Note: wordpad (write) and others do not support links. + + RTF_HYPERLINKS = NO + + # Load stylesheet definitions from file. Syntax is similar to doxygen's + # config file, i.e. a series of assignments. You only have to provide + # replacements, missing definitions are set to their default value. + + RTF_STYLESHEET_FILE = + + # Set optional variables used in the generation of an rtf document. + # Syntax is similar to doxygen's config file. + + RTF_EXTENSIONS_FILE = + + #--------------------------------------------------------------------------- + # configuration options related to the man page output + #--------------------------------------------------------------------------- + + # If the GENERATE_MAN tag is set to YES (the default) Doxygen will + # generate man pages + + GENERATE_MAN = NO + + # The MAN_OUTPUT tag is used to specify where the man pages will be put. + # If a relative path is entered the value of OUTPUT_DIRECTORY will be + # put in front of it. If left blank `man' will be used as the default path. + + MAN_OUTPUT = + + # The MAN_EXTENSION tag determines the extension that is added to + # the generated man pages (default is the subroutine's section .3) + + MAN_EXTENSION = + + # If the MAN_LINKS tag is set to YES and Doxygen generates man output, + # then it will generate one additional man file for each entity + # documented in the real man page(s). These additional files + # only source the real man page, but without them the man command + # would be unable to find the correct page. The default is NO. + + MAN_LINKS = NO + + #--------------------------------------------------------------------------- + # configuration options related to the XML output + #--------------------------------------------------------------------------- + + # If the GENERATE_XML tag is set to YES Doxygen will + # generate an XML file that captures the structure of + # the code including all documentation. + + GENERATE_XML = NO + + # The XML_OUTPUT tag is used to specify where the XML pages will be put. + # If a relative path is entered the value of OUTPUT_DIRECTORY will be + # put in front of it. If left blank `xml' will be used as the default path. + + XML_OUTPUT = xml + + # The XML_SCHEMA tag can be used to specify an XML schema, + # which can be used by a validating XML parser to check the + # syntax of the XML files. + + XML_SCHEMA = + + # The XML_DTD tag can be used to specify an XML DTD, + # which can be used by a validating XML parser to check the + # syntax of the XML files. + + XML_DTD = + + # If the XML_PROGRAMLISTING tag is set to YES Doxygen will + # dump the program listings (including syntax highlighting + # and cross-referencing information) to the XML output. Note that + # enabling this will significantly increase the size of the XML output. + + XML_PROGRAMLISTING = YES + + #--------------------------------------------------------------------------- + # configuration options for the AutoGen Definitions output + #--------------------------------------------------------------------------- + + # If the GENERATE_AUTOGEN_DEF tag is set to YES Doxygen will + # generate an AutoGen Definitions (see autogen.sf.net) file + # that captures the structure of the code including all + # documentation. Note that this feature is still experimental + # and incomplete at the moment. + + GENERATE_AUTOGEN_DEF = NO + + #--------------------------------------------------------------------------- + # configuration options related to the Perl module output + #--------------------------------------------------------------------------- + + # If the GENERATE_PERLMOD tag is set to YES Doxygen will + # generate a Perl module file that captures the structure of + # the code including all documentation. Note that this + # feature is still experimental and incomplete at the + # moment. + + GENERATE_PERLMOD = NO + + # If the PERLMOD_LATEX tag is set to YES Doxygen will generate + # the necessary Makefile rules, Perl scripts and LaTeX code to be able + # to generate PDF and DVI output from the Perl module output. + + PERLMOD_LATEX = NO + + # If the PERLMOD_PRETTY tag is set to YES the Perl module output will be + # nicely formatted so it can be parsed by a human reader. This is useful + # if you want to understand what is going on. On the other hand, if this + # tag is set to NO the size of the Perl module output will be much smaller + # and Perl will parse it just the same. + + PERLMOD_PRETTY = YES + + # The names of the make variables in the generated doxyrules.make file + # are prefixed with the string contained in PERLMOD_MAKEVAR_PREFIX. + # This is useful so different doxyrules.make files included by the same + # Makefile don't overwrite each other's variables. + + PERLMOD_MAKEVAR_PREFIX = + + #--------------------------------------------------------------------------- + # Configuration options related to the preprocessor + #--------------------------------------------------------------------------- + + # If the ENABLE_PREPROCESSING tag is set to YES (the default) Doxygen will + # evaluate all C-preprocessor directives found in the sources and include + # files. + + ENABLE_PREPROCESSING = YES + + # If the MACRO_EXPANSION tag is set to YES Doxygen will expand all macro + # names in the source code. If set to NO (the default) only conditional + # compilation will be performed. Macro expansion can be done in a controlled + # way by setting EXPAND_ONLY_PREDEF to YES. + + MACRO_EXPANSION = NO + + # If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES + # then the macro expansion is limited to the macros specified with the + # PREDEFINED and EXPAND_AS_PREDEFINED tags. + + EXPAND_ONLY_PREDEF = NO + + # If the SEARCH_INCLUDES tag is set to YES (the default) the includes files + # in the INCLUDE_PATH (see below) will be search if a #include is found. + + SEARCH_INCLUDES = YES + + # The INCLUDE_PATH tag can be used to specify one or more directories that + # contain include files that are not input files but should be processed by + # the preprocessor. + + INCLUDE_PATH = ../include + + # You can use the INCLUDE_FILE_PATTERNS tag to specify one or more wildcard + # patterns (like *.h and *.hpp) to filter out the header-files in the + # directories. If left blank, the patterns specified with FILE_PATTERNS will + # be used. + + INCLUDE_FILE_PATTERNS = + + # The PREDEFINED tag can be used to specify one or more macro names that + # are defined before the preprocessor is started (similar to the -D option of + # gcc). The argument of the tag is a list of macros of the form: name + # or name=definition (no spaces). If the definition and the = are + # omitted =1 is assumed. To prevent a macro definition from being + # undefined via #undef or recursively expanded use the := operator + # instead of the = operator. + + PREDEFINED = + + # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then + # this tag can be used to specify a list of macro names that should be expanded. + # The macro definition that is found in the sources will be used. + # Use the PREDEFINED tag if you want to use a different macro definition. + + EXPAND_AS_DEFINED = + + # If the SKIP_FUNCTION_MACROS tag is set to YES (the default) then + # doxygen's preprocessor will remove all function-like macros that are alone + # on a line, have an all uppercase name, and do not end with a semicolon. Such + # function macros are typically used for boiler-plate code, and will confuse + # the parser if not removed. + + SKIP_FUNCTION_MACROS = YES + + #--------------------------------------------------------------------------- + # Configuration::additions related to external references + #--------------------------------------------------------------------------- + + # The TAGFILES option can be used to specify one or more tagfiles. + # Optionally an initial location of the external documentation + # can be added for each tagfile. The format of a tag file without + # this location is as follows: + # TAGFILES = file1 file2 ... + # Adding location for the tag files is done as follows: + # TAGFILES = file1=loc1 "file2 = loc2" ... + # where "loc1" and "loc2" can be relative or absolute paths or + # URLs. If a location is present for each tag, the installdox tool + # does not have to be run to correct the links. + # Note that each tag file must have a unique name + # (where the name does NOT include the path) + # If a tag file is not located in the directory in which doxygen + # is run, you must also specify the path to the tagfile here. + + TAGFILES = + + # When a file name is specified after GENERATE_TAGFILE, doxygen will create + # a tag file that is based on the input files it reads. + + GENERATE_TAGFILE = + + # If the ALLEXTERNALS tag is set to YES all external classes will be listed + # in the class index. If set to NO only the inherited external classes + # will be listed. + + ALLEXTERNALS = YES + + # If the EXTERNAL_GROUPS tag is set to YES all external groups will be listed + # in the modules index. If set to NO, only the current project's groups will + # be listed. + + EXTERNAL_GROUPS = YES + + # The PERL_PATH should be the absolute path and name of the perl script + # interpreter (i.e. the result of `which perl'). + + PERL_PATH = + + #--------------------------------------------------------------------------- + # Configuration options related to the dot tool + #--------------------------------------------------------------------------- + + # If the CLASS_DIAGRAMS tag is set to YES (the default) Doxygen will + # generate a inheritance diagram (in HTML, RTF and LaTeX) for classes with base + # or super classes. Setting the tag to NO turns the diagrams off. Note that + # this option is superseded by the HAVE_DOT option below. This is only a + # fallback. It is recommended to install and use dot, since it yields more + # powerful graphs. + + CLASS_DIAGRAMS = YES + + # If set to YES, the inheritance and collaboration graphs will hide + # inheritance and usage relations if the target is undocumented + # or is not a class. + + HIDE_UNDOC_RELATIONS = NO + + # If you set the HAVE_DOT tag to YES then doxygen will assume the dot tool is + # available from the path. This tool is part of Graphviz, a graph visualization + # toolkit from AT&T and Lucent Bell Labs. The other options in this section + # have no effect if this option is set to NO (the default) + + HAVE_DOT = YES + + # If the CLASS_GRAPH and HAVE_DOT tags are set to YES then doxygen + # will generate a graph for each documented class showing the direct and + # indirect inheritance relations. Setting this tag to YES will force the + # the CLASS_DIAGRAMS tag to NO. + + CLASS_GRAPH = YES + + # If the COLLABORATION_GRAPH and HAVE_DOT tags are set to YES then doxygen + # will generate a graph for each documented class showing the direct and + # indirect implementation dependencies (inheritance, containment, and + # class references variables) of the class with other documented classes. + + COLLABORATION_GRAPH = YES + + # If the GROUP_GRAPHS and HAVE_DOT tags are set to YES then doxygen + # will generate a graph for groups, showing the direct groups dependencies + + #GROUP_GRAPHS = YES + + # If the UML_LOOK tag is set to YES doxygen will generate inheritance and + # collaboration diagrams in a style similar to the OMG's Unified Modeling + # Language. + + UML_LOOK = NO + + # If set to YES, the inheritance and collaboration graphs will show the + # relations between templates and their instances. + + TEMPLATE_RELATIONS = YES + + # If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDE_GRAPH, and HAVE_DOT + # tags are set to YES then doxygen will generate a graph for each documented + # file showing the direct and indirect include dependencies of the file with + # other documented files. + + INCLUDE_GRAPH = YES + + # If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDED_BY_GRAPH, and + # HAVE_DOT tags are set to YES then doxygen will generate a graph for each + # documented header file showing the documented files that directly or + # indirectly include this file. + + INCLUDED_BY_GRAPH = YES + + # If the CALL_GRAPH and HAVE_DOT tags are set to YES then doxygen will + # generate a call dependency graph for every global function or class method. + # Note that enabling this option will significantly increase the time of a run. + # So in most cases it will be better to enable call graphs for selected + # functions only using the \callgraph command. + + CALL_GRAPH = NO + + # If the GRAPHICAL_HIERARCHY and HAVE_DOT tags are set to YES then doxygen + # will graphical hierarchy of all classes instead of a textual one. + + GRAPHICAL_HIERARCHY = YES + + # If the DIRECTORY_GRAPH, SHOW_DIRECTORIES and HAVE_DOT tags are set to YES + # then doxygen will show the dependencies a directory has on other directories + # in a graphical way. The dependency relations are determined by the #include + # relations between the files in the directories. + + #DIRECTORY_GRAPH = YES + + # The DOT_IMAGE_FORMAT tag can be used to set the image format of the images + # generated by dot. Possible values are png, jpg, or gif + # If left blank png will be used. + + DOT_IMAGE_FORMAT = png + + # The tag DOT_PATH can be used to specify the path where the dot tool can be + # found. If left blank, it is assumed the dot tool can be found in the path. + + DOT_PATH = @DOT@ + + # The DOTFILE_DIRS tag can be used to specify one or more directories that + # contain dot files that are included in the documentation (see the + # \dotfile command). + + DOTFILE_DIRS = + + # The MAX_DOT_GRAPH_WIDTH tag can be used to set the maximum allowed width + # (in pixels) of the graphs generated by dot. If a graph becomes larger than + # this value, doxygen will try to truncate the graph, so that it fits within + # the specified constraint. Beware that most browsers cannot cope with very + # large images. + + MAX_DOT_GRAPH_WIDTH = 1024 + + # The MAX_DOT_GRAPH_HEIGHT tag can be used to set the maximum allows height + # (in pixels) of the graphs generated by dot. If a graph becomes larger than + # this value, doxygen will try to truncate the graph, so that it fits within + # the specified constraint. Beware that most browsers cannot cope with very + # large images. + + MAX_DOT_GRAPH_HEIGHT = 1024 + + # The MAX_DOT_GRAPH_DEPTH tag can be used to set the maximum depth of the + # graphs generated by dot. A depth value of 3 means that only nodes reachable + # from the root by following a path via at most 3 edges will be shown. Nodes + # that lay further from the root node will be omitted. Note that setting this + # option to 1 or 2 may greatly reduce the computation time needed for large + # code bases. Also note that a graph may be further truncated if the graph's + # image dimensions are not sufficient to fit the graph (see MAX_DOT_GRAPH_WIDTH + # and MAX_DOT_GRAPH_HEIGHT). If 0 is used for the depth value (the default), + # the graph is not depth-constrained. + + MAX_DOT_GRAPH_DEPTH = 0 + + # Set the DOT_TRANSPARENT tag to YES to generate images with a transparent + # background. This is disabled by default, which results in a white background. + # Warning: Depending on the platform used, enabling this option may lead to + # badly anti-aliased labels on the edges of a graph (i.e. they become hard to + # read). + + #DOT_TRANSPARENT = NO + + # Set the DOT_MULTI_TARGETS tag to YES allow dot to generate multiple output + # files in one run (i.e. multiple -o and -T options on the command line). This + # makes dot run faster, but since only newer versions of dot (>1.8.10) + # support this, this feature is disabled by default. + + #DOT_MULTI_TARGETS = NO + + # If the GENERATE_LEGEND tag is set to YES (the default) Doxygen will + # generate a legend page explaining the meaning of the various boxes and + # arrows in the dot generated graphs. + + GENERATE_LEGEND = YES + + # If the DOT_CLEANUP tag is set to YES (the default) Doxygen will + # remove the intermediate dot files that are used to generate + # the various graphs. + + DOT_CLEANUP = YES + + #--------------------------------------------------------------------------- + # Configuration::additions related to the search engine + #--------------------------------------------------------------------------- + + # The SEARCHENGINE tag specifies whether or not a search engine should be + # used. If set to NO the values of all tags below this one will be ignored. + + SEARCHENGINE = NO Index: llvm-www/releases/2.2/docs/doxygen.css diff -c /dev/null llvm-www/releases/2.2/docs/doxygen.css:1.1 *** /dev/null Tue Feb 12 00:07:06 2008 --- llvm-www/releases/2.2/docs/doxygen.css Tue Feb 12 00:05:03 2008 *************** *** 0 **** --- 1,378 ---- + BODY,H1,H2,H3,H4,H5,H6,P,CENTER,TD,TH,UL,DL,DIV { + font-family: Verdana,Geneva,Arial,Helvetica,sans-serif; + } + BODY,TD { + font-size: 90%; + } + H1 { + text-align: center; + font-size: 140%; + font-weight: bold; + } + H2 { + font-size: 120%; + font-style: italic; + } + H3 { + font-size: 100%; + } + CAPTION { font-weight: bold } + DIV.qindex { + width: 100%; + background-color: #eeeeff; + border: 1px solid #b0b0b0; + text-align: center; + margin: 2px; + padding: 2px; + line-height: 140%; + } + DIV.nav { + width: 100%; + background-color: #eeeeff; + border: 1px solid #b0b0b0; + text-align: center; + margin: 2px; + padding: 2px; + line-height: 140%; + } + DIV.navtab { + background-color: #eeeeff; + border: 1px solid #b0b0b0; + text-align: center; + margin: 2px; + margin-right: 15px; + padding: 2px; + } + TD.navtab { + font-size: 70%; + } + A.qindex { + text-decoration: none; + font-weight: bold; + color: #1A419D; + } + A.qindex:visited { + text-decoration: none; + font-weight: bold; + color: #1A419D + } + A.qindex:hover { + text-decoration: none; + background-color: #ddddff; + } + A.qindexHL { + text-decoration: none; + font-weight: bold; + background-color: #6666cc; + color: #ffffff; + border: 1px double #9295C2; + } + A.qindexHL:hover { + text-decoration: none; + background-color: #6666cc; + color: #ffffff; + } + A.qindexHL:visited { + text-decoration: none; background-color: #6666cc; color: #ffffff } + A.el { text-decoration: none; font-weight: bold } + A.elRef { font-weight: bold } + A.code:link { text-decoration: none; font-weight: normal; color: #0000FF} + A.code:visited { text-decoration: none; font-weight: normal; color: #0000FF} + A.codeRef:link { font-weight: normal; color: #0000FF} + A.codeRef:visited { font-weight: normal; color: #0000FF} + A:hover { text-decoration: none; background-color: #f2f2ff } + DL.el { margin-left: -1cm } + .fragment { + font-family: Fixed, monospace; + font-size: 95%; + } + PRE.fragment { + border: 1px solid #CCCCCC; + background-color: #f5f5f5; + margin-top: 4px; + margin-bottom: 4px; + margin-left: 2px; + margin-right: 8px; + padding-left: 6px; + padding-right: 6px; + padding-top: 4px; + padding-bottom: 4px; + } + DIV.ah { background-color: black; font-weight: bold; color: #ffffff; margin-bottom: 3px; margin-top: 3px } + TD.md { background-color: #F4F4FB; font-weight: bold; } + TD.mdPrefix { + background-color: #F4F4FB; + color: #606060; + font-size: 80%; + } + TD.mdname1 { background-color: #F4F4FB; font-weight: bold; color: #602020; } + TD.mdname { background-color: #F4F4FB; font-weight: bold; color: #602020; width: 600px; } + DIV.groupHeader { + margin-left: 16px; + margin-top: 12px; + margin-bottom: 6px; + font-weight: bold; + } + DIV.groupText { margin-left: 16px; font-style: italic; font-size: 90% } + BODY { + background: white; + color: black; + margin-right: 20px; + margin-left: 20px; + } + TD.indexkey { + background-color: #eeeeff; + font-weight: bold; + padding-right : 10px; + padding-top : 2px; + padding-left : 10px; + padding-bottom : 2px; + margin-left : 0px; + margin-right : 0px; + margin-top : 2px; + margin-bottom : 2px; + border: 1px solid #CCCCCC; + } + TD.indexvalue { + background-color: #eeeeff; + font-style: italic; + padding-right : 10px; + padding-top : 2px; + padding-left : 10px; + padding-bottom : 2px; + margin-left : 0px; + margin-right : 0px; + margin-top : 2px; + margin-bottom : 2px; + border: 1px solid #CCCCCC; + } + TR.memlist { + background-color: #f0f0f0; + } + P.formulaDsp { text-align: center; } + IMG.formulaDsp { } + IMG.formulaInl { vertical-align: middle; } + SPAN.keyword { color: #008000 } + SPAN.keywordtype { color: #604020 } + SPAN.keywordflow { color: #e08000 } + SPAN.comment { color: #800000 } + SPAN.preprocessor { color: #806020 } + SPAN.stringliteral { color: #002080 } + SPAN.charliteral { color: #008080 } + .mdTable { + border: 1px solid #868686; + background-color: #F4F4FB; + } + .mdRow { + padding: 8px 10px; + } + .mdescLeft { + padding: 0px 8px 4px 8px; + font-size: 80%; + font-style: italic; + background-color: #FAFAFA; + border-top: 1px none #E0E0E0; + border-right: 1px none #E0E0E0; + border-bottom: 1px none #E0E0E0; + border-left: 1px none #E0E0E0; + margin: 0px; + } + .mdescRight { + padding: 0px 8px 4px 8px; + font-size: 80%; + font-style: italic; + background-color: #FAFAFA; + border-top: 1px none #E0E0E0; + border-right: 1px none #E0E0E0; + border-bottom: 1px none #E0E0E0; + border-left: 1px none #E0E0E0; + margin: 0px; + } + .memItemLeft { + padding: 1px 0px 0px 8px; + margin: 4px; + border-top-width: 1px; + border-right-width: 1px; + border-bottom-width: 1px; + border-left-width: 1px; + border-top-color: #E0E0E0; + border-right-color: #E0E0E0; + border-bottom-color: #E0E0E0; + border-left-color: #E0E0E0; + border-top-style: solid; + border-right-style: none; + border-bottom-style: none; + border-left-style: none; + background-color: #FAFAFA; + font-size: 80%; + } + .memItemRight { + padding: 1px 8px 0px 8px; + margin: 4px; + border-top-width: 1px; + border-right-width: 1px; + border-bottom-width: 1px; + border-left-width: 1px; + border-top-color: #E0E0E0; + border-right-color: #E0E0E0; + border-bottom-color: #E0E0E0; + border-left-color: #E0E0E0; + border-top-style: solid; + border-right-style: none; + border-bottom-style: none; + border-left-style: none; + background-color: #FAFAFA; + font-size: 80%; + } + .memTemplItemLeft { + padding: 1px 0px 0px 8px; + margin: 4px; + border-top-width: 1px; + border-right-width: 1px; + border-bottom-width: 1px; + border-left-width: 1px; + border-top-color: #E0E0E0; + border-right-color: #E0E0E0; + border-bottom-color: #E0E0E0; + border-left-color: #E0E0E0; + border-top-style: none; + border-right-style: none; + border-bottom-style: none; + border-left-style: none; + background-color: #FAFAFA; + font-size: 80%; + } + .memTemplItemRight { + padding: 1px 8px 0px 8px; + margin: 4px; + border-top-width: 1px; + border-right-width: 1px; + border-bottom-width: 1px; + border-left-width: 1px; + border-top-color: #E0E0E0; + border-right-color: #E0E0E0; + border-bottom-color: #E0E0E0; + border-left-color: #E0E0E0; + border-top-style: none; + border-right-style: none; + border-bottom-style: none; + border-left-style: none; + background-color: #FAFAFA; + font-size: 80%; + } + .memTemplParams { + padding: 1px 0px 0px 8px; + margin: 4px; + border-top-width: 1px; + border-right-width: 1px; + border-bottom-width: 1px; + border-left-width: 1px; + border-top-color: #E0E0E0; + border-right-color: #E0E0E0; + border-bottom-color: #E0E0E0; + border-left-color: #E0E0E0; + border-top-style: solid; + border-right-style: none; + border-bottom-style: none; + border-left-style: none; + color: #606060; + background-color: #FAFAFA; + font-size: 80%; + } + .search { color: #003399; + font-weight: bold; + } + FORM.search { + margin-bottom: 0px; + margin-top: 0px; + } + INPUT.search { font-size: 75%; + color: #000080; + font-weight: normal; + background-color: #eeeeff; + } + TD.tiny { font-size: 75%; + } + a { + color: #252E78; + } + a:visited { + color: #3D2185; + } + .dirtab { padding: 4px; + border-collapse: collapse; + border: 1px solid #b0b0b0; + } + TH.dirtab { background: #eeeeff; + font-weight: bold; + } + HR { height: 1px; + border: none; + border-top: 1px solid black; + } + + /* + * LLVM Modifications. + * Note: Everything above here is generated with "doxygen -w htlm" command. See + * "doxygen --help" for details. What follows are CSS overrides for LLVM + * specific formatting. We want to keep the above so it can be replaced with + * subsequent doxygen upgrades. + */ + + .footer { + font-size: 80%; + font-weight: bold; + text-align: center; + vertical-align: middle; + } + .title { + font-size: 25pt; + color: black; background: url("../img/lines.gif"); + font-weight: bold; + border-width: 1px; + border-style: solid none solid none; + text-align: center; + vertical-align: middle; + padding-left: 8pt; + padding-top: 1px; + padding-bottom: 2px + } + A:link { + cursor: pointer; + text-decoration: none; + font-weight: bolder; + } + A:visited { + cursor: pointer; + text-decoration: underline; + font-weight: bolder; + } + A:hover { + cursor: pointer; + text-decoration: underline; + font-weight: bolder; + } + A:active { + cursor: pointer; + text-decoration: underline; + font-weight: bolder; + font-style: italic; + } + H1 { + text-align: center; + font-size: 140%; + font-weight: bold; + } + H2 { + font-size: 120%; + font-style: italic; + } + H3 { + font-size: 100%; + } + A.qindex {} + A.qindexRef {} + A.el { text-decoration: none; font-weight: bold } + A.elRef { font-weight: bold } + A.code { text-decoration: none; font-weight: normal; color: #4444ee } + A.codeRef { font-weight: normal; color: #4444ee } Index: llvm-www/releases/2.2/docs/doxygen.footer diff -c /dev/null llvm-www/releases/2.2/docs/doxygen.footer:1.1 *** /dev/null Tue Feb 12 00:07:06 2008 --- llvm-www/releases/2.2/docs/doxygen.footer Tue Feb 12 00:05:03 2008 *************** *** 0 **** --- 1,13 ---- +
    +

    + Generated on $datetime for $projectname by + Doxygen$doxygenversion
    + Copyright © 2003-2007 University of Illinois at Urbana-Champaign. + All Rights Reserved.

    + +
    + + + + Index: llvm-www/releases/2.2/docs/doxygen.header diff -c /dev/null llvm-www/releases/2.2/docs/doxygen.header:1.1 *** /dev/null Tue Feb 12 00:07:06 2008 --- llvm-www/releases/2.2/docs/doxygen.header Tue Feb 12 00:05:03 2008 *************** *** 0 **** --- 1,9 ---- + + + + + + LLVM: $title + + +

    LLVM API Documentation

    Index: llvm-www/releases/2.2/docs/doxygen.intro diff -c /dev/null llvm-www/releases/2.2/docs/doxygen.intro:1.1 *** /dev/null Tue Feb 12 00:07:06 2008 --- llvm-www/releases/2.2/docs/doxygen.intro Tue Feb 12 00:05:03 2008 *************** *** 0 **** --- 1,18 ---- + /// @mainpage Low Level Virtual Machine + /// + /// @section main_intro Introduction + /// Welcome to the Low Level Virtual Machine (LLVM). + /// + /// This documentation describes the @b internal software that makes + /// up LLVM, not the @b external use of LLVM. There are no instructions + /// here on how to use LLVM, only the APIs that make up the software. For usage + /// instructions, please see the programmer's guide or reference manual. + /// + /// @section main_caveat Caveat + /// This documentation is generated directly from the source code with doxygen. + /// Since LLVM is constantly under active development, what you're about to + /// read is out of date! However, it may still be useful since certain portions + /// of LLVM are very stable. + /// + /// @section main_changelog Change Log + /// - Original content written 12/30/2003 by Reid Spencer Index: llvm-www/releases/2.2/docs/html.tar.gz Index: llvm-www/releases/2.2/docs/index.html diff -c /dev/null llvm-www/releases/2.2/docs/index.html:1.1 *** /dev/null Tue Feb 12 00:07:07 2008 --- llvm-www/releases/2.2/docs/index.html Tue Feb 12 00:05:03 2008 *************** *** 0 **** --- 1,276 ---- + + + + Documentation for the LLVM System + + + + +
    Documentation for the LLVM System
    + +
    +
    + + +
    + +
    + +
    +
    +
    + +
    +

    Written by The LLVM Team

    +
    + + +
    LLVM Design & Overview
    + + + + + +
    LLVM User Guides
    + + + + + + +
    General LLVM Programming Documentation
    + + + + + +
    LLVM Subsystem Documentation
    + + +
      + +
    • Writing an LLVM Pass - Information + on how to write LLVM transformations and analyses.
      • + +
    • Writing an LLVM Backend - Information + on how to write LLVM backends for machine targets.
      • + +
    • The LLVM Target-Independent Code + Generator - The design and implementation of the LLVM code generator. + Useful if you are working on retargetting LLVM to a new architecture, designing + a new codegen pass, or enhancing existing components.
      • + +
    • TableGen Fundamentals - + Describes the TableGen tool, which is used heavily by the LLVM code + generator.
      • + +
    • Alias Analysis in LLVM - Information + on how to write a new alias analysis implementation or how to use existing + analyses.
      • + +
    • The Stacker Chronicles - This document + describes both the Stacker language and LLVM frontend, but also some details + about LLVM useful for those writing front-ends.
      • + +
    • Accurate Garbage Collection with + LLVM - The interfaces source-language compilers should use for compiling + GC'd programs.
      • + +
    • Source Level Debugging with + LLVM - This document describes the design and philosophy behind the LLVM + source-level debugger.
      • + +
    • Zero Cost Exception handling in LLVM + - This document describes the design and implementation of exception handling + in LLVM.
      • + +
    • Bugpoint - automatic bug finder and test-case + reducer description and usage information.
      • + +
    • Compiler Driver (llvmc) - This document + describes the design and configuration of the LLVM compiler driver tool, + llvmc.
      • + +
    • LLVM Bitcode File Format
      • + +
    • System Library - This document describes + the LLVM System Library (lib/System) and how to keep LLVM source code + portable
      • + +
    • Link Time Optimization - This + document describes the interface between LLVM intermodular optimizer and + the linker and its design
      • + +
    + + + +
    LLVM Mailing Lists
    + + +
      +
    • The + LLVM Announcements List: This is a low volume list that provides important + announcements regarding LLVM. It gets email about once a month.
      • + +
    • The Developer's + List: This list is for people who want to be included in technical + discussions of LLVM. People post to this list when they have questions about + writing code for or using the LLVM tools. It is relatively low volume.
      • + +
    • The Bugs & + Patches Archive: This list gets emailed every time a bug is opened and + closed, and when people submit patches to be included in LLVM. It is higher + volume than the LLVMdev list.
      • + +
    • The Commits + Archive: This list contains all commit messages that are made when LLVM + developers commit code changes to the repository. It is useful for those who + want to stay on the bleeding edge of LLVM development. This list is very high + volume.
      • + +
    • The + Test Results Archive: A message is automatically sent to this list by every + active nightly tester when it completes. As such, this list gets email several + times each day, making it a high volume list.
      • + +
    + + + +
    +
    + Valid CSS! + Valid HTML 4.01! + + LLVM Compiler Infrastructure
    + Last modified: $Date: 2008/02/12 06:05:03 $ +
    + + Index: llvm-www/releases/2.2/docs/llvm.css diff -c /dev/null llvm-www/releases/2.2/docs/llvm.css:1.1 *** /dev/null Tue Feb 12 00:07:07 2008 --- llvm-www/releases/2.2/docs/llvm.css Tue Feb 12 00:05:03 2008 *************** *** 0 **** --- 1,84 ---- + /* + * LLVM documentation style sheet + */ + + /* Common styles */ + .body { color: black; background: white; margin: 0 0 0 0 } + + /* No borders on image links */ + a:link img, a:visited img {border-style: none} + + address img { float: right; width: 88px; height: 31px; } + address { clear: right; } + + TR, TD { border: 2px solid gray; padding: 4pt 4pt 2pt 2pt; } + TH { border: 2px solid gray; font-weight: bold; font-size: 105%; + background: url("img/lines.gif"); + font-family: "Georgia,Palatino,Times,Roman,SanSerif"; text-align:center; + vertical-align: middle; } + TABLE { text-align: center; border: 2px solid black; + border-collapse: collapse; margin-top: 1em; margin-left: 1em; + margin-right: 1em; margin-bottom: 1em; } + /* + * Documentation + */ + /* Common for title and header */ + .doc_title, .doc_section, .doc_subsection { + color: black; background: url("img/lines.gif"); + font-family: "Georgia,Palatino,Times,Roman,SanSerif"; font-weight: bold; + border-width: 1px; + border-style: solid none solid none; + text-align: center; + vertical-align: middle; + padding-left: 8pt; + padding-top: 1px; + padding-bottom: 2px + } + + .doc_title { text-align: left; font-size: 25pt } + .doc_section { text-align: center; font-size: 22pt; + margin: 20pt 0pt 5pt 0pt; } + .doc_subsection { width: 75%; + text-align: left; font-size: 12pt; padding: 4pt 4pt 4pt 4pt; + margin: 1.5em 0.5em 0.5em 0.5em } + + .doc_subsubsection { margin: 2.0em 0.5em 0.5em 0.5em; + font-weight: bold; font-style: oblique; + border-bottom: 1px solid #999999; font-size: 12pt; + width: 75%; } + .doc_author { text-align: left; font-weight: bold; padding-left: 20pt } + .doc_text { text-align: left; padding-left: 20pt; padding-right: 10pt } + + .doc_footer { text-align: left; padding: 0 0 0 0 } + + .doc_hilite { color: blue; font-weight: bold; } + + .doc_table { text-align: center; width: 90%; + padding: 1px 1px 1px 1px; border: 1px; } + + .doc_table_nw { text-align: center; border: 1px; + padding: 1px 1px 1px 1px; } + + .doc_warning { color: red; font-weight: bold } + + .doc_code { border: solid 1px gray; background: #eeeeee; + margin: 0 1em 0 1em; + padding: 0 1em 0 1em; + display:table; + } + .doc_notes { background: #fafafa; border: 1px solid #cecece; padding: 0.1em } + + TABLE.layout { text-align: left; border: none; border-collapse: collapse; + padding: 4px 4px 4px 4px; } + TR.layout { border: none; padding: 4pt 4pt 2pt 2pt; } + TD.layout { border: none; padding: 4pt 4pt 2pt 2pt; + vertical-align: top;} + TD.left { border: none; padding: 4pt 4pt 2pt 2pt; text-align: left; + vertical-align: top;} + TD.right { border: none; padding: 4pt 4pt 2pt 2pt; text-align: right; + vertical-align: top;} + TH.layout { border: none; font-weight: bold; font-size: 105%; + text-align:center; vertical-align: middle; } + + /* Left align table cell */ + .td_left { border: 2px solid gray; text-align: left; } From tonic at nondot.org Tue Feb 12 00:07:04 2008 From: tonic at nondot.org (Tanya Lattner) Date: Tue, 12 Feb 2008 00:07:04 -0600 Subject: [llvm-commits] CVS: llvm-www/releases/2.2/docs/CommandGuide/man/man1/bugpoint.1 llc.1 lli.1 llvm-ar.1 llvm-as.1 llvm-bcanalyzer.1 llvm-config.1 llvm-db.1 llvm-dis.1 llvm-extract.1 llvm-ld.1 llvm-link.1 llvm-nm.1 llvm-prof.1 llvm-ranlib.1 llvm-upgrade.1 llvm2cpp.1 llvmc.1 llvmgcc.1 llvmgxx.1 opt.1 stkrc.1 tblgen.1 Message-ID: <200802120607.m1C674vP009016@zion.cs.uiuc.edu> Changes in directory llvm-www/releases/2.2/docs/CommandGuide/man/man1: bugpoint.1 added (r1.1) llc.1 added (r1.1) lli.1 added (r1.1) llvm-ar.1 added (r1.1) llvm-as.1 added (r1.1) llvm-bcanalyzer.1 added (r1.1) llvm-config.1 added (r1.1) llvm-db.1 added (r1.1) llvm-dis.1 added (r1.1) llvm-extract.1 added (r1.1) llvm-ld.1 added (r1.1) llvm-link.1 added (r1.1) llvm-nm.1 added (r1.1) llvm-prof.1 added (r1.1) llvm-ranlib.1 added (r1.1) llvm-upgrade.1 added (r1.1) llvm2cpp.1 added (r1.1) llvmc.1 added (r1.1) llvmgcc.1 added (r1.1) llvmgxx.1 added (r1.1) opt.1 added (r1.1) stkrc.1 added (r1.1) tblgen.1 added (r1.1) --- Log message: Release 2.2 --- Diffs of the changes: (+5643 -0) bugpoint.1 | 244 ++++++++++++++++++++++++++++ llc.1 | 277 ++++++++++++++++++++++++++++++++ lli.1 | 308 ++++++++++++++++++++++++++++++++++++ llvm-ar.1 | 461 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ llvm-as.1 | 182 +++++++++++++++++++++ llvm-bcanalyzer.1 | 370 +++++++++++++++++++++++++++++++++++++++++++ llvm-config.1 | 227 ++++++++++++++++++++++++++ llvm-db.1 | 141 ++++++++++++++++ llvm-dis.1 | 175 ++++++++++++++++++++ llvm-extract.1 | 177 ++++++++++++++++++++ llvm-ld.1 | 348 ++++++++++++++++++++++++++++++++++++++++ llvm-link.1 | 186 +++++++++++++++++++++ llvm-nm.1 | 219 +++++++++++++++++++++++++ llvm-prof.1 | 173 ++++++++++++++++++++ llvm-ranlib.1 | 167 +++++++++++++++++++ llvm-upgrade.1 | 179 ++++++++++++++++++++ llvm2cpp.1 | 307 +++++++++++++++++++++++++++++++++++ llvmc.1 | 455 +++++++++++++++++++++++++++++++++++++++++++++++++++++ llvmgcc.1 | 194 ++++++++++++++++++++++ llvmgxx.1 | 194 ++++++++++++++++++++++ opt.1 | 246 ++++++++++++++++++++++++++++ stkrc.1 | 198 +++++++++++++++++++++++ tblgen.1 | 215 +++++++++++++++++++++++++ 23 files changed, 5643 insertions(+) Index: llvm-www/releases/2.2/docs/CommandGuide/man/man1/bugpoint.1 diff -c /dev/null llvm-www/releases/2.2/docs/CommandGuide/man/man1/bugpoint.1:1.1 *** /dev/null Tue Feb 12 00:05:56 2008 --- llvm-www/releases/2.2/docs/CommandGuide/man/man1/bugpoint.1 Tue Feb 12 00:05:16 2008 *************** *** 0 **** --- 1,244 ---- + .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.14 + .\" + .\" Standard preamble: + .\" ======================================================================== + .de Sh \" Subsection heading + .br + .if t .Sp + .ne 5 + .PP + \fB\\$1\fR + .PP + .. + .de Sp \" Vertical space (when we can't use .PP) + .if t .sp .5v + .if n .sp + .. + .de Vb \" Begin verbatim text + .ft CW + .nf + .ne \\$1 + .. + .de Ve \" End verbatim text + .ft R + .fi + .. + .\" Set up some character translations and predefined strings. \*(-- will + .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left + .\" double quote, and \*(R" will give a right double quote. | will give a + .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to + .\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' + .\" expand to `' in nroff, nothing in troff, for use with C<>. + .tr \(*W-|\(bv\*(Tr + .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' + .ie n \{\ + . ds -- \(*W- + . ds PI pi + . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch + . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch + . ds L" "" + . ds R" "" + . ds C` "" + . ds C' "" + 'br\} + .el\{\ + . ds -- \|\(em\| + . ds PI \(*p + . ds L" `` + . ds R" '' + 'br\} + .\" + .\" If the F register is turned on, we'll generate index entries on stderr for + .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index + .\" entries marked with X<> in POD. Of course, you'll have to process the + .\" output yourself in some meaningful fashion. + .if \nF \{\ + . de IX + . tm Index:\\$1\t\\n%\t"\\$2" + .. + . nr % 0 + . rr F + .\} + .\" + .\" For nroff, turn off justification. Always turn off hyphenation; it makes + .\" way too many mistakes in technical documents. + .hy 0 + .if n .na + .\" + .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). + .\" Fear. Run. Save yourself. No user-serviceable parts. + . \" fudge factors for nroff and troff + .if n \{\ + . ds #H 0 + . ds #V .8m + . ds #F .3m + . ds #[ \f1 + . ds #] \fP + .\} + .if t \{\ + . ds #H ((1u-(\\\\n(.fu%2u))*.13m) + . ds #V .6m + . ds #F 0 + . ds #[ \& + . ds #] \& + .\} + . \" simple accents for nroff and troff + .if n \{\ + . ds ' \& + . ds ` \& + . ds ^ \& + . ds , \& + . ds ~ ~ + . ds / + .\} + .if t \{\ + . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" + . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' + . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' + . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' + . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' + . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' + .\} + . \" troff and (daisy-wheel) nroff accents + .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' + .ds 8 \h'\*(#H'\(*b\h'-\*(#H' + .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] + .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' + .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' + .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] + .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] + .ds ae a\h'-(\w'a'u*4/10)'e + .ds Ae A\h'-(\w'A'u*4/10)'E + . \" corrections for vroff + .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' + .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' + . \" for low resolution devices (crt and lpr) + .if \n(.H>23 .if \n(.V>19 \ + \{\ + . ds : e + . ds 8 ss + . ds o a + . ds d- d\h'-1'\(ga + . ds D- D\h'-1'\(hy + . ds th \o'bp' + . ds Th \o'LP' + . ds ae ae + . ds Ae AE + .\} + .rm #[ #] #H #V #F C + .\" ======================================================================== + .\" + .IX Title "BUGPOINT 1" + .TH BUGPOINT 1 "2007-07-17" "CVS" "LLVM Command Guide" + .SH "NAME" + bugpoint \- automatic test case reduction tool + .SH "SYNOPSIS" + .IX Header "SYNOPSIS" + \&\fBbugpoint\fR [\fIoptions\fR] [\fIinput \s-1LLVM\s0 ll/bc files\fR] [\fI\s-1LLVM\s0 passes\fR] \fB\-\-args\fR + \&\fIprogram arguments\fR + .SH "DESCRIPTION" + .IX Header "DESCRIPTION" + \&\fBbugpoint\fR narrows down the source of problems in \s-1LLVM\s0 tools and passes. It + can be used to debug three types of failures: optimizer crashes, miscompilations + by optimizers, or bad native code generation (including problems in the static + and \s-1JIT\s0 compilers). It aims to reduce large test cases to small, useful ones. + For more information on the design and inner workings of \fBbugpoint\fR, as well as + advice for using bugpoint, see \fIllvm/docs/Bugpoint.html\fR in the \s-1LLVM\s0 + distribution. + .SH "OPTIONS" + .IX Header "OPTIONS" + .IP "\fB\-\-additional\-so\fR \fIlibrary\fR" 4 + .IX Item "--additional-so library" + Load the dynamic shared object \fIlibrary\fR into the test program whenever it is + run. This is useful if you are debugging programs which depend on non-LLVM + libraries (such as the X or curses libraries) to run. + .IP "\fB\-\-args\fR \fIprogram args\fR" 4 + .IX Item "--args program args" + Pass all arguments specified after \-args to the test program whenever it runs. + Note that if any of the \fIprogram args\fR start with a '\-', you should use: + .Sp + .Vb 1 + \& bugpoint [bugpoint args] --args -- [program args] + .Ve + .Sp + The \*(L"\-\-\*(R" right after the \fB\-\-args\fR option tells \fBbugpoint\fR to consider any + options starting with \f(CW\*(C`\-\*(C'\fR to be part of the \fB\-\-args\fR option, not as options to + \&\fBbugpoint\fR itself. + .IP "\fB\-\-tool\-args\fR \fItool args\fR" 4 + .IX Item "--tool-args tool args" + Pass all arguments specified after \-\-tool\-args to the \s-1LLVM\s0 tool under test + (\fBllc\fR, \fBlli\fR, etc.) whenever it runs. You should use this option in the + following way: + .Sp + .Vb 1 + \& bugpoint [bugpoint args] --tool-args -- [tool args] + .Ve + .Sp + The \*(L"\-\-\*(R" right after the \fB\-\-tool\-args\fR option tells \fBbugpoint\fR to consider any + options starting with \f(CW\*(C`\-\*(C'\fR to be part of the \fB\-\-tool\-args\fR option, not as + options to \fBbugpoint\fR itself. (See \fB\-\-args\fR, above.) + .IP "\fB\-\-check\-exit\-code\fR=\fI{true,false}\fR" 4 + .IX Item "--check-exit-code={true,false}" + Assume a non-zero exit code or core dump from the test program is a failure. + Defaults to true. + .IP "\fB\-\-disable\-{dce,simplifycfg}\fR" 4 + .IX Item "--disable-{dce,simplifycfg}" + Do not run the specified passes to clean up and reduce the size of the test + program. By default, \fBbugpoint\fR uses these passes internally when attempting to + reduce test programs. If you're trying to find a bug in one of these passes, + \&\fBbugpoint\fR may crash. + .IP "\fB\-\-enable\-valgrind\fR" 4 + .IX Item "--enable-valgrind" + Use valgrind to find faults in the optimization phase. This will allow + bugpoint to find otherwise asymptomatic problems caused by memory + mis\-management. + .IP "\fB\-find\-bugs\fR" 4 + .IX Item "-find-bugs" + Continually randomize the specified passes and run them on the test program + until a bug is found or the user kills \fBbugpoint\fR. + .IP "\fB\-\-help\fR" 4 + .IX Item "--help" + Print a summary of command line options. + .IP "\fB\-\-input\fR \fIfilename\fR" 4 + .IX Item "--input filename" + Open \fIfilename\fR and redirect the standard input of the test program, whenever + it runs, to come from that file. + .IP "\fB\-\-load\fR \fIplugin\fR" 4 + .IX Item "--load plugin" + Load the dynamic object \fIplugin\fR into \fBbugpoint\fR itself. This object should + register new optimization passes. Once loaded, the object will add new command + line options to enable various optimizations. To see the new complete list of + optimizations, use the \fB\-\-help\fR and \fB\-\-load\fR options together; for example: + .Sp + .Vb 1 + \& bugpoint --load myNewPass.so --help + .Ve + .IP "\fB\-\-mlimit\fR \fImegabytes\fR" 4 + .IX Item "--mlimit megabytes" + Specifies an upper limit on memory usage of the optimization and codegen. Set + to zero to disable the limit. + .IP "\fB\-\-output\fR \fIfilename\fR" 4 + .IX Item "--output filename" + Whenever the test program produces output on its standard output stream, it + should match the contents of \fIfilename\fR (the \*(L"reference output\*(R"). If you + do not use this option, \fBbugpoint\fR will attempt to generate a reference output + by compiling the program with the C backend and running it. + .IP "\fB\-\-profile\-info\-file\fR \fIfilename\fR" 4 + .IX Item "--profile-info-file filename" + Profile file loaded by \fB\-\-profile\-loader\fR. + .IP "\fB\-\-run\-{int,jit,llc,cbe}\fR" 4 + .IX Item "--run-{int,jit,llc,cbe}" + Whenever the test program is compiled, \fBbugpoint\fR should generate code for it + using the specified code generator. These options allow you to choose the + interpreter, the \s-1JIT\s0 compiler, the static native code compiler, or the C + backend, respectively. + .SH "EXIT STATUS" + .IX Header "EXIT STATUS" + If \fBbugpoint\fR succeeds in finding a problem, it will exit with 0. Otherwise, + if an error occurs, it will exit with a non-zero value.