forked from OSchip/llvm-project
[LLVM][Alignment] Update documentation
Reviewers: aprantl Subscribers: llvm-commits Tags: #llvm Differential Revision: https://reviews.llvm.org/D65558 llvm-svn: 367655
This commit is contained in:
Guillaume Chatelet
parent
09fac2450b
commit
8113c93fb1
|
|
@ -34,13 +34,13 @@ namespace llvm {
|
|||
#define ALIGN_CHECK_ISSET(decl) \
|
||||
assert(decl.hasValue() && (#decl " should be defined"))
|
||||
|
||||
// This struct is a compact representation of a valid (non-zero power of two)
|
||||
// alignment.
|
||||
// It is suitable for use as static global constants.
|
||||
/// This struct is a compact representation of a valid (non-zero power of two)
|
||||
/// alignment.
|
||||
/// It is suitable for use as static global constants.
|
||||
struct Align {
|
||||
private:
|
||||
uint8_t ShiftValue = 0; // The log2 of the required alignment.
|
||||
// ShiftValue is less than 64 by construction.
|
||||
uint8_t ShiftValue = 0; /// The log2 of the required alignment.
|
||||
/// ShiftValue is less than 64 by construction.
|
||||
|
||||
friend struct MaybeAlign;
|
||||
friend unsigned Log2(Align);
|
||||
|
|
@ -54,10 +54,10 @@ private:
|
|||
friend struct MaybeAlign decodeMaybeAlign(unsigned Value);
|
||||
|
||||
public:
|
||||
// Default is byte-aligned.
|
||||
/// Default is byte-aligned.
|
||||
Align() = default;
|
||||
// Do not perform checks in case of copy/move construct/assign, because the
|
||||
// checks have been performed when building `Other`.
|
||||
/// Do not perform checks in case of copy/move construct/assign, because the
|
||||
/// checks have been performed when building `Other`.
|
||||
Align(const Align &Other) = default;
|
||||
Align &operator=(const Align &Other) = default;
|
||||
Align(Align &&Other) = default;
|
||||
|
|
@ -70,33 +70,33 @@ public:
|
|||
assert(ShiftValue < 64 && "Broken invariant");
|
||||
}
|
||||
|
||||
// This is a hole in the type system and should not be abused.
|
||||
// Needed to interact with C for instance.
|
||||
/// This is a hole in the type system and should not be abused.
|
||||
/// Needed to interact with C for instance.
|
||||
uint64_t value() const { return uint64_t(1) << ShiftValue; }
|
||||
};
|
||||
|
||||
// Treats the value 0 as a 1, so Align is always at least 1.
|
||||
/// Treats the value 0 as a 1, so Align is always at least 1.
|
||||
inline Align assumeAligned(uint64_t Value) {
|
||||
return Value ? Align(Value) : Align();
|
||||
}
|
||||
|
||||
// This struct is a compact representation of a valid (power of two) or
|
||||
// undefined (0) alignment.
|
||||
/// This struct is a compact representation of a valid (power of two) or
|
||||
/// undefined (0) alignment.
|
||||
struct MaybeAlign : public llvm::Optional<Align> {
|
||||
private:
|
||||
using UP = llvm::Optional<Align>;
|
||||
|
||||
public:
|
||||
// Default is undefined.
|
||||
/// Default is undefined.
|
||||
MaybeAlign() = default;
|
||||
// Do not perform checks in case of copy/move construct/assign, because the
|
||||
// checks have been performed when building `Other`.
|
||||
/// Do not perform checks in case of copy/move construct/assign, because the
|
||||
/// checks have been performed when building `Other`.
|
||||
MaybeAlign(const MaybeAlign &Other) = default;
|
||||
MaybeAlign &operator=(const MaybeAlign &Other) = default;
|
||||
MaybeAlign(MaybeAlign &&Other) = default;
|
||||
MaybeAlign &operator=(MaybeAlign &&Other) = default;
|
||||
|
||||
// Use llvm::Optional<Align> constructor.
|
||||
/// Use llvm::Optional<Align> constructor.
|
||||
using UP::UP;
|
||||
|
||||
explicit MaybeAlign(uint64_t Value) {
|
||||
|
|
@ -106,78 +106,69 @@ public:
|
|||
emplace(Value);
|
||||
}
|
||||
|
||||
// For convenience, returns a valid alignment or 1 if undefined.
|
||||
/// For convenience, returns a valid alignment or 1 if undefined.
|
||||
Align valueOrOne() const { return hasValue() ? getValue() : Align(); }
|
||||
};
|
||||
|
||||
// -----------------------------------------------------------------------------
|
||||
// isAligned: Checks that SizeInBytes is a multiple of the alignment.
|
||||
// -----------------------------------------------------------------------------
|
||||
|
||||
/// Checks that SizeInBytes is a multiple of the alignment.
|
||||
inline bool isAligned(Align Lhs, uint64_t SizeInBytes) {
|
||||
return SizeInBytes % Lhs.value() == 0;
|
||||
}
|
||||
|
||||
// Returns false if the alignment is undefined.
|
||||
/// Checks that SizeInBytes is a multiple of the alignment.
|
||||
/// Returns false if the alignment is undefined.
|
||||
inline bool isAligned(MaybeAlign Lhs, uint64_t SizeInBytes) {
|
||||
ALIGN_CHECK_ISSET(Lhs);
|
||||
return SizeInBytes % (*Lhs).value() == 0;
|
||||
}
|
||||
|
||||
// -----------------------------------------------------------------------------
|
||||
// alignTo: Returns a multiple of A needed to store `Size` bytes.
|
||||
// -----------------------------------------------------------------------------
|
||||
|
||||
/// Returns a multiple of A needed to store `Size` bytes.
|
||||
inline uint64_t alignTo(uint64_t Size, Align A) {
|
||||
return (Size + A.value() - 1) / A.value() * A.value();
|
||||
}
|
||||
|
||||
// Returns `Size` if current alignment is undefined.
|
||||
/// Returns a multiple of A needed to store `Size` bytes.
|
||||
/// Returns `Size` if current alignment is undefined.
|
||||
inline uint64_t alignTo(uint64_t Size, MaybeAlign A) {
|
||||
return A ? alignTo(Size, A.getValue()) : Size;
|
||||
}
|
||||
|
||||
// -----------------------------------------------------------------------------
|
||||
// log2: Returns the log2 of the alignment.
|
||||
// e.g. Align(16).log2() == 4
|
||||
// -----------------------------------------------------------------------------
|
||||
|
||||
/// Returns the log2 of the alignment.
|
||||
inline unsigned Log2(Align A) { return A.ShiftValue; }
|
||||
|
||||
/// Returns the log2 of the alignment.
|
||||
/// \pre A must be defined.
|
||||
inline unsigned Log2(MaybeAlign A) {
|
||||
ALIGN_CHECK_ISSET(A);
|
||||
return Log2(A.getValue());
|
||||
}
|
||||
|
||||
// -----------------------------------------------------------------------------
|
||||
// commonAlignment: returns the alignment that satisfies both alignments.
|
||||
// Same semantic as MinAlign.
|
||||
// -----------------------------------------------------------------------------
|
||||
|
||||
/// Returns the alignment that satisfies both alignments.
|
||||
/// Same semantic as MinAlign.
|
||||
inline Align commonAlignment(Align A, Align B) { return std::min(A, B); }
|
||||
|
||||
/// Returns the alignment that satisfies both alignments.
|
||||
/// Same semantic as MinAlign.
|
||||
inline Align commonAlignment(Align A, uint64_t Offset) {
|
||||
return Align(MinAlign(A.value(), Offset));
|
||||
}
|
||||
|
||||
/// Returns the alignment that satisfies both alignments.
|
||||
/// Same semantic as MinAlign.
|
||||
inline MaybeAlign commonAlignment(MaybeAlign A, MaybeAlign B) {
|
||||
return A && B ? commonAlignment(*A, *B) : A ? A : B;
|
||||
}
|
||||
|
||||
/// Returns the alignment that satisfies both alignments.
|
||||
/// Same semantic as MinAlign.
|
||||
inline MaybeAlign commonAlignment(MaybeAlign A, uint64_t Offset) {
|
||||
return MaybeAlign(MinAlign((*A).value(), Offset));
|
||||
}
|
||||
|
||||
// -----------------------------------------------------------------------------
|
||||
// Encode/Decode
|
||||
// -----------------------------------------------------------------------------
|
||||
|
||||
// Returns a more compact representation of the alignment.
|
||||
// An undefined MaybeAlign is encoded as 0.
|
||||
/// Returns a representation of the alignment that encodes undefined as 0.
|
||||
inline unsigned encode(MaybeAlign A) { return A ? A->ShiftValue + 1 : 0; }
|
||||
|
||||
// Dual operation of the encode function above.
|
||||
/// Dual operation of the encode function above.
|
||||
inline MaybeAlign decodeMaybeAlign(unsigned Value) {
|
||||
if (Value == 0)
|
||||
return MaybeAlign();
|
||||
|
|
@ -186,17 +177,11 @@ inline MaybeAlign decodeMaybeAlign(unsigned Value) {
|
|||
return Out;
|
||||
}
|
||||
|
||||
// Returns a more compact representation of the alignment.
|
||||
// The encoded value is positive by definition.
|
||||
// e.g. Align(1).encode() == 1
|
||||
// e.g. Align(16).encode() == 5
|
||||
/// Returns a representation of the alignment, the encoded value is positive by
|
||||
/// definition.
|
||||
inline unsigned encode(Align A) { return encode(MaybeAlign(A)); }
|
||||
|
||||
// -----------------------------------------------------------------------------
|
||||
// Comparisons
|
||||
// -----------------------------------------------------------------------------
|
||||
|
||||
// Comparisons between Align and scalars. Rhs must be positive.
|
||||
/// Comparisons between Align and scalars. Rhs must be positive.
|
||||
inline bool operator==(Align Lhs, uint64_t Rhs) {
|
||||
ALIGN_CHECK_ISPOSITIVE(Rhs);
|
||||
return Lhs.value() == Rhs;
|
||||
|
|
@ -222,7 +207,7 @@ inline bool operator>(Align Lhs, uint64_t Rhs) {
|
|||
return Lhs.value() > Rhs;
|
||||
}
|
||||
|
||||
// Comparisons between MaybeAlign and scalars.
|
||||
/// Comparisons between MaybeAlign and scalars.
|
||||
inline bool operator==(MaybeAlign Lhs, uint64_t Rhs) {
|
||||
return Lhs ? (*Lhs).value() == Rhs : Rhs == 0;
|
||||
}
|
||||
|
|
@ -250,7 +235,7 @@ inline bool operator>(MaybeAlign Lhs, uint64_t Rhs) {
|
|||
return (*Lhs).value() > Rhs;
|
||||
}
|
||||
|
||||
// Comparisons operators between Align.
|
||||
/// Comparisons operators between Align.
|
||||
inline bool operator==(Align Lhs, Align Rhs) {
|
||||
return Lhs.ShiftValue == Rhs.ShiftValue;
|
||||
}
|
||||
|
|
@ -270,7 +255,7 @@ inline bool operator>(Align Lhs, Align Rhs) {
|
|||
return Lhs.ShiftValue > Rhs.ShiftValue;
|
||||
}
|
||||
|
||||
// Comparisons operators between Align and MaybeAlign.
|
||||
/// Comparisons operators between Align and MaybeAlign.
|
||||
inline bool operator==(Align Lhs, MaybeAlign Rhs) {
|
||||
ALIGN_CHECK_ISSET(Rhs);
|
||||
return Lhs.value() == (*Rhs).value();
|
||||
|
|
@ -296,7 +281,7 @@ inline bool operator>(Align Lhs, MaybeAlign Rhs) {
|
|||
return Lhs.value() > (*Rhs).value();
|
||||
}
|
||||
|
||||
// Comparisons operators between MaybeAlign and Align.
|
||||
/// Comparisons operators between MaybeAlign and Align.
|
||||
inline bool operator==(MaybeAlign Lhs, Align Rhs) {
|
||||
ALIGN_CHECK_ISSET(Lhs);
|
||||
return Lhs && (*Lhs).value() == Rhs.value();
|
||||
|
|
@ -322,10 +307,6 @@ inline bool operator>(MaybeAlign Lhs, Align Rhs) {
|
|||
return Lhs && (*Lhs).value() > Rhs.value();
|
||||
}
|
||||
|
||||
// -----------------------------------------------------------------------------
|
||||
// Division
|
||||
// -----------------------------------------------------------------------------
|
||||
|
||||
inline Align operator/(Align Lhs, uint64_t Divisor) {
|
||||
assert(llvm::isPowerOf2_64(Divisor) &&
|
||||
"Divisor must be positive and a power of 2");
|
||||
|
|
|
|||
Loading…
Reference in New Issue