1 //===-- llvm/Support/Alignment.h - Useful alignment functions ---*- C++ -*-===//
3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4 // See https://llvm.org/LICENSE.txt for license information.
5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
7 //===----------------------------------------------------------------------===//
9 // This file contains types to represent alignments.
10 // They are instrumented to guarantee some invariants are preserved and prevent
11 // invalid manipulations.
13 // - Align represents an alignment in bytes, it is always set and always a valid
14 // power of two, its minimum value is 1 which means no alignment requirements.
16 // - MaybeAlign is an optional type, it may be undefined or set. When it's set
17 // you can get the underlying Align type by using the getValue() method.
19 //===----------------------------------------------------------------------===//
21 #ifndef LLVM_SUPPORT_ALIGNMENT_H_
22 #define LLVM_SUPPORT_ALIGNMENT_H_
24 #include "llvm/ADT/Optional.h"
25 #include "llvm/Support/MathExtras.h"
33 #define ALIGN_CHECK_ISPOSITIVE(decl) \
34 assert(decl > 0 && (#decl " should be defined"))
36 /// This struct is a compact representation of a valid (non-zero power of two)
38 /// It is suitable for use as static global constants.
41 uint8_t ShiftValue = 0; /// The log2 of the required alignment.
42 /// ShiftValue is less than 64 by construction.
44 friend struct MaybeAlign;
45 friend unsigned Log2(Align);
46 friend bool operator==(Align Lhs, Align Rhs);
47 friend bool operator!=(Align Lhs, Align Rhs);
48 friend bool operator<=(Align Lhs, Align Rhs);
49 friend bool operator>=(Align Lhs, Align Rhs);
50 friend bool operator<(Align Lhs, Align Rhs);
51 friend bool operator>(Align Lhs, Align Rhs);
52 friend unsigned encode(struct MaybeAlign A);
53 friend struct MaybeAlign decodeMaybeAlign(unsigned Value);
55 /// A trivial type to allow construction of constexpr Align.
56 /// This is currently needed to workaround a bug in GCC 5.3 which prevents
57 /// definition of constexpr assign operators.
58 /// https://stackoverflow.com/questions/46756288/explicitly-defaulted-function-cannot-be-declared-as-constexpr-because-the-implic
59 /// FIXME: Remove this, make all assign operators constexpr and introduce user
60 /// defined literals when we don't have to support GCC 5.3 anymore.
61 /// https://llvm.org/docs/GettingStarted.html#getting-a-modern-host-c-toolchain
67 /// Default is byte-aligned.
68 constexpr Align() = default;
69 /// Do not perform checks in case of copy/move construct/assign, because the
70 /// checks have been performed when building `Other`.
71 constexpr Align(const Align &Other) = default;
72 constexpr Align(Align &&Other) = default;
73 Align &operator=(const Align &Other) = default;
74 Align &operator=(Align &&Other) = default;
76 explicit Align(uint64_t Value) {
77 assert(Value > 0 && "Value must not be 0");
78 assert(llvm::isPowerOf2_64(Value) && "Alignment is not a power of 2");
79 ShiftValue = Log2_64(Value);
80 assert(ShiftValue < 64 && "Broken invariant");
83 /// This is a hole in the type system and should not be abused.
84 /// Needed to interact with C for instance.
85 uint64_t value() const { return uint64_t(1) << ShiftValue; }
87 /// Returns a default constructed Align which corresponds to no alignment.
88 /// It was decided to deprecate Align::None because it's too close to
89 /// llvm::None which can be used to initialize `MaybeAlign`.
90 /// MaybeAlign = llvm::None means unspecified alignment,
91 /// Align = Align::None() means alignment of one byte.
92 LLVM_ATTRIBUTE_DEPRECATED(constexpr static const Align None(),
93 "Use Align() or Align(1) instead") {
97 /// Allow constructions of constexpr Align.
98 template <size_t kValue> constexpr static LogValue Constant() {
99 return LogValue{static_cast<uint8_t>(CTLog2<kValue>())};
102 /// Allow constructions of constexpr Align from types.
103 /// Compile time equivalent to Align(alignof(T)).
104 template <typename T> constexpr static LogValue Of() {
105 return Constant<std::alignment_of<T>::value>();
108 /// Constexpr constructor from LogValue type.
109 constexpr Align(LogValue CA) : ShiftValue(CA.Log) {}
112 /// Treats the value 0 as a 1, so Align is always at least 1.
113 inline Align assumeAligned(uint64_t Value) {
114 return Value ? Align(Value) : Align();
117 /// This struct is a compact representation of a valid (power of two) or
118 /// undefined (0) alignment.
119 struct MaybeAlign : public llvm::Optional<Align> {
121 using UP = llvm::Optional<Align>;
124 /// Default is undefined.
125 MaybeAlign() = default;
126 /// Do not perform checks in case of copy/move construct/assign, because the
127 /// checks have been performed when building `Other`.
128 MaybeAlign(const MaybeAlign &Other) = default;
129 MaybeAlign &operator=(const MaybeAlign &Other) = default;
130 MaybeAlign(MaybeAlign &&Other) = default;
131 MaybeAlign &operator=(MaybeAlign &&Other) = default;
133 /// Use llvm::Optional<Align> constructor.
136 explicit MaybeAlign(uint64_t Value) {
137 assert((Value == 0 || llvm::isPowerOf2_64(Value)) &&
138 "Alignment is neither 0 nor a power of 2");
143 /// For convenience, returns a valid alignment or 1 if undefined.
144 Align valueOrOne() const { return hasValue() ? getValue() : Align(); }
147 /// Checks that SizeInBytes is a multiple of the alignment.
148 inline bool isAligned(Align Lhs, uint64_t SizeInBytes) {
149 return SizeInBytes % Lhs.value() == 0;
152 /// Checks that Addr is a multiple of the alignment.
153 inline bool isAddrAligned(Align Lhs, const void *Addr) {
154 return isAligned(Lhs, reinterpret_cast<uintptr_t>(Addr));
157 /// Returns a multiple of A needed to store `Size` bytes.
158 inline uint64_t alignTo(uint64_t Size, Align A) {
159 const uint64_t Value = A.value();
160 // The following line is equivalent to `(Size + Value - 1) / Value * Value`.
162 // The division followed by a multiplication can be thought of as a right
163 // shift followed by a left shift which zeros out the extra bits produced in
164 // the bump; `~(Value - 1)` is a mask where all those bits being zeroed out
167 // Most compilers can generate this code but the pattern may be missed when
168 // multiple functions gets inlined.
169 return (Size + Value - 1) & ~(Value - 1U);
172 /// If non-zero \p Skew is specified, the return value will be a minimal integer
173 /// that is greater than or equal to \p Size and equal to \p A * N + \p Skew for
174 /// some integer N. If \p Skew is larger than \p A, its value is adjusted to '\p
179 /// alignTo(5, Align(8), 7) = 7
180 /// alignTo(17, Align(8), 1) = 17
181 /// alignTo(~0LL, Align(8), 3) = 3
183 inline uint64_t alignTo(uint64_t Size, Align A, uint64_t Skew) {
184 const uint64_t Value = A.value();
186 return ((Size + Value - 1 - Skew) & ~(Value - 1U)) + Skew;
189 /// Returns a multiple of A needed to store `Size` bytes.
190 /// Returns `Size` if current alignment is undefined.
191 inline uint64_t alignTo(uint64_t Size, MaybeAlign A) {
192 return A ? alignTo(Size, A.getValue()) : Size;
195 /// Aligns `Addr` to `Alignment` bytes, rounding up.
196 inline uintptr_t alignAddr(const void *Addr, Align Alignment) {
197 uintptr_t ArithAddr = reinterpret_cast<uintptr_t>(Addr);
198 assert(static_cast<uintptr_t>(ArithAddr + Alignment.value() - 1) >=
201 return alignTo(ArithAddr, Alignment);
204 /// Returns the offset to the next integer (mod 2**64) that is greater than
205 /// or equal to \p Value and is a multiple of \p Align.
206 inline uint64_t offsetToAlignment(uint64_t Value, Align Alignment) {
207 return alignTo(Value, Alignment) - Value;
210 /// Returns the necessary adjustment for aligning `Addr` to `Alignment`
211 /// bytes, rounding up.
212 inline uint64_t offsetToAlignedAddr(const void *Addr, Align Alignment) {
213 return offsetToAlignment(reinterpret_cast<uintptr_t>(Addr), Alignment);
216 /// Returns the log2 of the alignment.
217 inline unsigned Log2(Align A) { return A.ShiftValue; }
219 /// Returns the alignment that satisfies both alignments.
220 /// Same semantic as MinAlign.
221 inline Align commonAlignment(Align A, Align B) { return std::min(A, B); }
223 /// Returns the alignment that satisfies both alignments.
224 /// Same semantic as MinAlign.
225 inline Align commonAlignment(Align A, uint64_t Offset) {
226 return Align(MinAlign(A.value(), Offset));
229 /// Returns the alignment that satisfies both alignments.
230 /// Same semantic as MinAlign.
231 inline MaybeAlign commonAlignment(MaybeAlign A, MaybeAlign B) {
232 return A && B ? commonAlignment(*A, *B) : A ? A : B;
235 /// Returns the alignment that satisfies both alignments.
236 /// Same semantic as MinAlign.
237 inline MaybeAlign commonAlignment(MaybeAlign A, uint64_t Offset) {
238 return MaybeAlign(MinAlign((*A).value(), Offset));
241 /// Returns a representation of the alignment that encodes undefined as 0.
242 inline unsigned encode(MaybeAlign A) { return A ? A->ShiftValue + 1 : 0; }
244 /// Dual operation of the encode function above.
245 inline MaybeAlign decodeMaybeAlign(unsigned Value) {
249 Out.ShiftValue = Value - 1;
253 /// Returns a representation of the alignment, the encoded value is positive by
255 inline unsigned encode(Align A) { return encode(MaybeAlign(A)); }
257 /// Comparisons between Align and scalars. Rhs must be positive.
258 inline bool operator==(Align Lhs, uint64_t Rhs) {
259 ALIGN_CHECK_ISPOSITIVE(Rhs);
260 return Lhs.value() == Rhs;
262 inline bool operator!=(Align Lhs, uint64_t Rhs) {
263 ALIGN_CHECK_ISPOSITIVE(Rhs);
264 return Lhs.value() != Rhs;
266 inline bool operator<=(Align Lhs, uint64_t Rhs) {
267 ALIGN_CHECK_ISPOSITIVE(Rhs);
268 return Lhs.value() <= Rhs;
270 inline bool operator>=(Align Lhs, uint64_t Rhs) {
271 ALIGN_CHECK_ISPOSITIVE(Rhs);
272 return Lhs.value() >= Rhs;
274 inline bool operator<(Align Lhs, uint64_t Rhs) {
275 ALIGN_CHECK_ISPOSITIVE(Rhs);
276 return Lhs.value() < Rhs;
278 inline bool operator>(Align Lhs, uint64_t Rhs) {
279 ALIGN_CHECK_ISPOSITIVE(Rhs);
280 return Lhs.value() > Rhs;
283 /// Comparisons between MaybeAlign and scalars.
284 inline bool operator==(MaybeAlign Lhs, uint64_t Rhs) {
285 return Lhs ? (*Lhs).value() == Rhs : Rhs == 0;
287 inline bool operator!=(MaybeAlign Lhs, uint64_t Rhs) {
288 return Lhs ? (*Lhs).value() != Rhs : Rhs != 0;
291 /// Comparisons operators between Align.
292 inline bool operator==(Align Lhs, Align Rhs) {
293 return Lhs.ShiftValue == Rhs.ShiftValue;
295 inline bool operator!=(Align Lhs, Align Rhs) {
296 return Lhs.ShiftValue != Rhs.ShiftValue;
298 inline bool operator<=(Align Lhs, Align Rhs) {
299 return Lhs.ShiftValue <= Rhs.ShiftValue;
301 inline bool operator>=(Align Lhs, Align Rhs) {
302 return Lhs.ShiftValue >= Rhs.ShiftValue;
304 inline bool operator<(Align Lhs, Align Rhs) {
305 return Lhs.ShiftValue < Rhs.ShiftValue;
307 inline bool operator>(Align Lhs, Align Rhs) {
308 return Lhs.ShiftValue > Rhs.ShiftValue;
311 // Don't allow relational comparisons with MaybeAlign.
312 bool operator<=(Align Lhs, MaybeAlign Rhs) = delete;
313 bool operator>=(Align Lhs, MaybeAlign Rhs) = delete;
314 bool operator<(Align Lhs, MaybeAlign Rhs) = delete;
315 bool operator>(Align Lhs, MaybeAlign Rhs) = delete;
317 bool operator<=(MaybeAlign Lhs, Align Rhs) = delete;
318 bool operator>=(MaybeAlign Lhs, Align Rhs) = delete;
319 bool operator<(MaybeAlign Lhs, Align Rhs) = delete;
320 bool operator>(MaybeAlign Lhs, Align Rhs) = delete;
322 bool operator<=(MaybeAlign Lhs, MaybeAlign Rhs) = delete;
323 bool operator>=(MaybeAlign Lhs, MaybeAlign Rhs) = delete;
324 bool operator<(MaybeAlign Lhs, MaybeAlign Rhs) = delete;
325 bool operator>(MaybeAlign Lhs, MaybeAlign Rhs) = delete;
327 inline Align operator*(Align Lhs, uint64_t Rhs) {
328 assert(Rhs > 0 && "Rhs must be positive");
329 return Align(Lhs.value() * Rhs);
332 inline MaybeAlign operator*(MaybeAlign Lhs, uint64_t Rhs) {
333 assert(Rhs > 0 && "Rhs must be positive");
334 return Lhs ? Lhs.getValue() * Rhs : MaybeAlign();
337 inline Align operator/(Align Lhs, uint64_t Divisor) {
338 assert(llvm::isPowerOf2_64(Divisor) &&
339 "Divisor must be positive and a power of 2");
340 assert(Lhs != 1 && "Can't halve byte alignment");
341 return Align(Lhs.value() / Divisor);
344 inline MaybeAlign operator/(MaybeAlign Lhs, uint64_t Divisor) {
345 assert(llvm::isPowerOf2_64(Divisor) &&
346 "Divisor must be positive and a power of 2");
347 return Lhs ? Lhs.getValue() / Divisor : MaybeAlign();
350 inline Align max(MaybeAlign Lhs, Align Rhs) {
351 return Lhs && *Lhs > Rhs ? *Lhs : Rhs;
354 inline Align max(Align Lhs, MaybeAlign Rhs) {
355 return Rhs && *Rhs > Lhs ? *Rhs : Lhs;
359 // For usage in LLVM_DEBUG macros.
360 inline std::string DebugStr(const Align &A) {
361 return std::to_string(A.value());
363 // For usage in LLVM_DEBUG macros.
364 inline std::string DebugStr(const MaybeAlign &MA) {
366 return std::to_string(MA->value());
371 #undef ALIGN_CHECK_ISPOSITIVE
375 #endif // LLVM_SUPPORT_ALIGNMENT_H_