From 64cf50d348702d27f793e10b1997ff2cc87bff05 Mon Sep 17 00:00:00 2001 From: Chandler Carruth Date: Mon, 20 Oct 2014 10:27:53 +0000 Subject: [PATCH] Clean up the comments and doxygen for DataLayout. git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@220191 91177308-0d34-0410-b5e6-96231b3b80d8 --- include/llvm/IR/DataLayout.h | 195 ++++++++++++++++++++++--------------------- 1 file changed, 99 insertions(+), 96 deletions(-) diff --git a/include/llvm/IR/DataLayout.h b/include/llvm/IR/DataLayout.h index bfd880a874f..d2224f7913d 100644 --- a/include/llvm/IR/DataLayout.h +++ b/include/llvm/IR/DataLayout.h @@ -27,7 +27,8 @@ #include "llvm/Pass.h" #include "llvm/Support/DataTypes.h" -// this needs to be outside of the namespace, to avoid conflict with llvm-c decl +// This needs to be outside of the namespace, to avoid conflict with llvm-c +// decl. typedef struct LLVMOpaqueTargetData *LLVMTargetDataRef; namespace llvm { @@ -52,12 +53,12 @@ enum AlignTypeEnum { AGGREGATE_ALIGN = 'a' ///< Aggregate alignment }; -/// Layout alignment element. +/// \brief Layout alignment element. /// /// Stores the alignment data associated with a given alignment type (integer, /// vector, float) and type bit width. /// -/// @note The unusual order of elements in the structure attempts to reduce +/// \note The unusual order of elements in the structure attempts to reduce /// padding and make the structure slightly more cache friendly. struct LayoutAlignElem { unsigned AlignType : 8; ///< Alignment type (AlignTypeEnum) @@ -65,18 +66,16 @@ struct LayoutAlignElem { unsigned ABIAlign : 16; ///< ABI alignment for this type/bitw unsigned PrefAlign : 16; ///< Pref. alignment for this type/bitw - /// Initializer static LayoutAlignElem get(AlignTypeEnum align_type, unsigned abi_align, unsigned pref_align, uint32_t bit_width); - /// Equality predicate bool operator==(const LayoutAlignElem &rhs) const; }; -/// Layout pointer alignment element. +/// \brief Layout pointer alignment element. /// /// Stores the alignment data associated with a given pointer and address space. /// -/// @note The unusual order of elements in the structure attempts to reduce +/// \note The unusual order of elements in the structure attempts to reduce /// padding and make the structure slightly more cache friendly. struct PointerAlignElem { unsigned ABIAlign; ///< ABI alignment for this type/bitw @@ -87,18 +86,21 @@ struct PointerAlignElem { /// Initializer static PointerAlignElem get(uint32_t AddressSpace, unsigned ABIAlign, unsigned PrefAlign, uint32_t TypeByteWidth); - /// Equality predicate bool operator==(const PointerAlignElem &rhs) const; }; -/// This class holds a parsed version of the target data layout string in a -/// module and provides methods for querying it. The target data layout string -/// is specified *by the target* - a frontend generating LLVM IR is required to -/// generate the right target data for the target being codegen'd to. +/// \brief A parsed version of the target data layout string in and methods for +/// querying it. +/// +/// The target data layout string is specified *by the target* - a frontend +/// generating LLVM IR is required to generate the right target data for the +/// target being codegen'd to. class DataLayout { private: - bool LittleEndian; ///< Defaults to false - unsigned StackNaturalAlign; ///< Stack natural alignment + /// Defaults to false. + bool LittleEndian; + + unsigned StackNaturalAlign; enum ManglingModeT { MM_None, @@ -109,15 +111,11 @@ private: }; ManglingModeT ManglingMode; - SmallVector LegalIntWidths; ///< Legal Integers. + SmallVector LegalIntWidths; - /// Alignments - Where the primitive type alignment data is stored. - /// - /// @sa reset(). - /// @note Could support multiple size pointer alignments, e.g., 32-bit - /// pointers vs. 64-bit pointers by extending LayoutAlignment, but for now, - /// we don't. + /// \brief Primitive type alignment data. SmallVector Alignments; + typedef SmallVector PointersTy; PointersTy Pointers; @@ -128,31 +126,28 @@ private: PointersTy::iterator findPointerLowerBound(uint32_t AddressSpace); - /// InvalidAlignmentElem - This member is a signal that a requested alignment - /// type and bit width were not found in the SmallVector. + /// This member is a signal that a requested alignment type and bit width were + /// not found in the SmallVector. static const LayoutAlignElem InvalidAlignmentElem; - /// InvalidPointerElem - This member is a signal that a requested pointer - /// type and bit width were not found in the DenseSet. + /// This member is a signal that a requested pointer type and bit width were + /// not found in the DenseSet. static const PointerAlignElem InvalidPointerElem; // The StructType -> StructLayout map. mutable void *LayoutMap; - //! Set/initialize target alignments void setAlignment(AlignTypeEnum align_type, unsigned abi_align, unsigned pref_align, uint32_t bit_width); unsigned getAlignmentInfo(AlignTypeEnum align_type, uint32_t bit_width, bool ABIAlign, Type *Ty) const; - - //! Set/initialize pointer alignments void setPointerAlignment(uint32_t AddrSpace, unsigned ABIAlign, unsigned PrefAlign, uint32_t TypeByteWidth); - //! Internal helper method that returns requested alignment for type. + /// Internal helper method that returns requested alignment for type. unsigned getAlignment(Type *Ty, bool abi_or_pref) const; - /// Valid alignment predicate. + /// \brief Valid alignment predicate. /// /// Predicate that tests a LayoutAlignElem reference returned by get() against /// InvalidAlignmentElem. @@ -160,7 +155,7 @@ private: return &align != &InvalidAlignmentElem; } - /// Valid pointer predicate. + /// \brief Valid pointer predicate. /// /// Predicate that tests a PointerAlignElem reference returned by get() against /// InvalidPointerElem. @@ -211,18 +206,19 @@ public: bool isLittleEndian() const { return LittleEndian; } bool isBigEndian() const { return !LittleEndian; } - /// getStringRepresentation - Return the string representation of the - /// DataLayout. This representation is in the same format accepted by the - /// string constructor above. + /// \brief Returns the string representation of the DataLayout. + /// + /// This representation is in the same format accepted by the string + /// constructor above. std::string getStringRepresentation() const; - /// isLegalInteger - This function returns true if the specified type is - /// known to be a native integer type supported by the CPU. For example, - /// i64 is not native on most 32-bit CPUs and i37 is not native on any known - /// one. This returns false if the integer width is not legal. + /// \brief Returns true if the specified type is known to be a native integer + /// type supported by the CPU. /// - /// The width is specified in bits. + /// For example, i64 is not native on most 32-bit CPUs and i37 is not native + /// on any known one. This returns false if the integer width is not legal. /// + /// The width is specified in bits. bool isLegalInteger(unsigned Width) const { for (unsigned LegalIntWidth : LegalIntWidths) if (LegalIntWidth == Width) @@ -283,10 +279,11 @@ public: static const char *getManglingComponent(const Triple &T); - /// fitsInLegalInteger - This function returns true if the specified type fits - /// in a native integer type supported by the CPU. For example, if the CPU - /// only supports i32 as a native integer type, then i27 fits in a legal - /// integer type but i45 does not. + /// \brief Returns true if the specified type fits in a native integer type + /// supported by the CPU. + /// + /// For example, if the CPU only supports i32 as a native integer type, then + /// i27 fits in a legal integer type but i45 does not. bool fitsInLegalInteger(unsigned Width) const { for (unsigned LegalIntWidth : LegalIntWidths) if (Width <= LegalIntWidth) @@ -344,99 +341,107 @@ public: /// [*] The alloc size depends on the alignment, and thus on the target. /// These values are for x86-32 linux. - /// getTypeSizeInBits - Return the number of bits necessary to hold the - /// specified type. For example, returns 36 for i36 and 80 for x86_fp80. - /// The type passed must have a size (Type::isSized() must return true). + /// \brief Returns the number of bits necessary to hold the specified type. + /// + /// For example, returns 36 for i36 and 80 for x86_fp80. The type passed must + /// have a size (Type::isSized() must return true). uint64_t getTypeSizeInBits(Type *Ty) const; - /// getTypeStoreSize - Return the maximum number of bytes that may be - /// overwritten by storing the specified type. For example, returns 5 - /// for i36 and 10 for x86_fp80. + /// \brief Returns the maximum number of bytes that may be overwritten by + /// storing the specified type. + /// + /// For example, returns 5 for i36 and 10 for x86_fp80. uint64_t getTypeStoreSize(Type *Ty) const { return (getTypeSizeInBits(Ty)+7)/8; } - /// getTypeStoreSizeInBits - Return the maximum number of bits that may be - /// overwritten by storing the specified type; always a multiple of 8. For - /// example, returns 40 for i36 and 80 for x86_fp80. + /// \brief Returns the maximum number of bits that may be overwritten by + /// storing the specified type; always a multiple of 8. + /// + /// For example, returns 40 for i36 and 80 for x86_fp80. uint64_t getTypeStoreSizeInBits(Type *Ty) const { return 8*getTypeStoreSize(Ty); } - /// getTypeAllocSize - Return the offset in bytes between successive objects - /// of the specified type, including alignment padding. This is the amount - /// that alloca reserves for this type. For example, returns 12 or 16 for - /// x86_fp80, depending on alignment. + /// \brief Returns the offset in bytes between successive objects of the + /// specified type, including alignment padding. + /// + /// This is the amount that alloca reserves for this type. For example, + /// returns 12 or 16 for x86_fp80, depending on alignment. uint64_t getTypeAllocSize(Type *Ty) const { // Round up to the next alignment boundary. return RoundUpToAlignment(getTypeStoreSize(Ty), getABITypeAlignment(Ty)); } - /// getTypeAllocSizeInBits - Return the offset in bits between successive - /// objects of the specified type, including alignment padding; always a - /// multiple of 8. This is the amount that alloca reserves for this type. - /// For example, returns 96 or 128 for x86_fp80, depending on alignment. + /// \brief Returns the offset in bits between successive objects of the + /// specified type, including alignment padding; always a multiple of 8. + /// + /// This is the amount that alloca reserves for this type. For example, + /// returns 96 or 128 for x86_fp80, depending on alignment. uint64_t getTypeAllocSizeInBits(Type *Ty) const { return 8*getTypeAllocSize(Ty); } - /// getABITypeAlignment - Return the minimum ABI-required alignment for the - /// specified type. + /// \brief Returns the minimum ABI-required alignment for the specified type. unsigned getABITypeAlignment(Type *Ty) const; - /// getABIIntegerTypeAlignment - Return the minimum ABI-required alignment for - /// an integer type of the specified bitwidth. + /// \brief Returns the minimum ABI-required alignment for an integer type of + /// the specified bitwidth. unsigned getABIIntegerTypeAlignment(unsigned BitWidth) const; - /// getPrefTypeAlignment - Return the preferred stack/global alignment for - /// the specified type. This is always at least as good as the ABI alignment. + /// \brief Returns the preferred stack/global alignment for the specified + /// type. + /// + /// This is always at least as good as the ABI alignment. unsigned getPrefTypeAlignment(Type *Ty) const; - /// getPreferredTypeAlignmentShift - Return the preferred alignment for the - /// specified type, returned as log2 of the value (a shift amount). + /// \brief Returns the preferred alignment for the specified type, returned as + /// log2 of the value (a shift amount). unsigned getPreferredTypeAlignmentShift(Type *Ty) const; - /// getIntPtrType - Return an integer type with size at least as big as that - /// of a pointer in the given address space. + /// \brief Returns an integer type with size at least as big as that of a + /// pointer in the given address space. IntegerType *getIntPtrType(LLVMContext &C, unsigned AddressSpace = 0) const; - /// getIntPtrType - Return an integer (vector of integer) type with size at - /// least as big as that of a pointer of the given pointer (vector of pointer) - /// type. + /// \brief Returns an integer (vector of integer) type with size at least as + /// big as that of a pointer of the given pointer (vector of pointer) type. Type *getIntPtrType(Type *) const; - /// getSmallestLegalIntType - Return the smallest integer type with size at - /// least as big as Width bits. + /// \brief Returns the smallest integer type with size at least as big as + /// Width bits. Type *getSmallestLegalIntType(LLVMContext &C, unsigned Width = 0) const; - /// getLargestLegalIntType - Return the largest legal integer type, or null if - /// none are set. + /// \brief Returns the largest legal integer type, or null if none are set. Type *getLargestLegalIntType(LLVMContext &C) const { unsigned LargestSize = getLargestLegalIntTypeSize(); return (LargestSize == 0) ? nullptr : Type::getIntNTy(C, LargestSize); } - /// getLargestLegalIntTypeSize - Return the size of largest legal integer - /// type size, or 0 if none are set. + /// \brief Returns the size of largest legal integer type size, or 0 if none + /// are set. unsigned getLargestLegalIntTypeSize() const; - /// getIndexedOffset - return the offset from the beginning of the type for - /// the specified indices. This is used to implement getelementptr. + /// \brief Returns the offset from the beginning of the type for the specified + /// indices. + /// + /// This is used to implement getelementptr. uint64_t getIndexedOffset(Type *Ty, ArrayRef Indices) const; - /// getStructLayout - Return a StructLayout object, indicating the alignment - /// of the struct, its size, and the offsets of its fields. Note that this - /// information is lazily cached. + /// \brief Returns a StructLayout object, indicating the alignment of the + /// struct, its size, and the offsets of its fields. + /// + /// Note that this information is lazily cached. const StructLayout *getStructLayout(StructType *Ty) const; - /// getPreferredAlignment - Return the preferred alignment of the specified - /// global. This includes an explicitly requested alignment (if the global - /// has one). + /// \brief Returns the preferred alignment of the specified global. + /// + /// This includes an explicitly requested alignment (if the global has one). unsigned getPreferredAlignment(const GlobalVariable *GV) const; - /// getPreferredAlignmentLog - Return the preferred alignment of the - /// specified global, returned in log form. This includes an explicitly - /// requested alignment (if the global has one). + /// \brief Returns the preferred alignment of the specified global, returned + /// in log form. + /// + /// This includes an explicitly requested alignment (if the global has one). unsigned getPreferredAlignmentLog(const GlobalVariable *GV) const; }; @@ -464,9 +469,8 @@ public: bool doInitialization(Module &M) override; }; -/// StructLayout - used to lazily calculate structure layout information for a -/// target machine, based on the DataLayout structure. -/// +/// Used to lazily calculate structure layout information for a target machine, +/// based on the DataLayout structure. class StructLayout { uint64_t StructSize; unsigned StructAlignment; @@ -486,9 +490,8 @@ public: return StructAlignment; } - /// getElementContainingOffset - Given a valid byte offset into the structure, - /// return the structure index that contains it. - /// + /// \brief Given a valid byte offset into the structure, returns the structure + /// index that contains it. unsigned getElementContainingOffset(uint64_t Offset) const; uint64_t getElementOffset(unsigned Idx) const { -- 2.11.0