include/llvm/Support/Alignment.h

   1 //===-- llvm/Support/Alignment.h - Useful alignment functions ---*- C++ -*-===//
   2 //
   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
   6 //
   7 //===----------------------------------------------------------------------===//
   8 //
   9 // This file contains types to represent alignments.
  10 // They are instrumented to guarantee some invariants are preserved and prevent
  11 // invalid manipulations.
  12 //
  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.
  15 //
  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.
  18 //
  19 //===----------------------------------------------------------------------===//
  20
  21 #ifndef LLVM_SUPPORT_ALIGNMENT_H_
  22 #define LLVM_SUPPORT_ALIGNMENT_H_
  23
  24 #include "llvm/ADT/Optional.h"
  25 #include "llvm/Support/Compiler.h"
  26 #include "llvm/Support/MathExtras.h"
  27 #include <cassert>
  28 #include <limits>
  29
  30 namespace llvm {
  31
  32 #define ALIGN_CHECK_ISPOSITIVE(decl)                                           \
  33   assert(decl > 0 && (#decl " should be defined"))
  34 #define ALIGN_CHECK_ISSET(decl)                                                \
  35   assert(decl.hasValue() && (#decl " should be defined"))
  36
  37 /// This struct is a compact representation of a valid (non-zero power of two)
  38 /// alignment.
  39 /// It is suitable for use as static global constants.
  40 struct Align {
  41 private:
  42   uint8_t ShiftValue = 0; /// The log2 of the required alignment.
  43                           /// ShiftValue is less than 64 by construction.
  44
  45   friend struct MaybeAlign;
  46   friend unsigned Log2(Align);
  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 bool operator>(Align Lhs, Align Rhs);
  53   friend unsigned encode(struct MaybeAlign A);
  54   friend struct MaybeAlign decodeMaybeAlign(unsigned Value);
  55
  56   /// A trivial type to allow construction of constexpr Align.
  57   /// This is currently needed to workaround a bug in GCC 5.3 which prevents
  58   /// definition of constexpr assign operators.
  59   /// https://stackoverflow.com/questions/46756288/explicitly-defaulted-function-cannot-be-declared-as-constexpr-because-the-implic
  60   /// FIXME: Remove this, make all assign operators constexpr and introduce user
  61   /// defined literals when we don't have to support GCC 5.3 anymore.
  62   /// https://llvm.org/docs/GettingStarted.html#getting-a-modern-host-c-toolchain
  63   struct LogValue {
  64     uint8_t Log;
  65   };
  66
  67 public:
  68   /// Default is byte-aligned.
  69   constexpr Align() = default;
  70   /// Do not perform checks in case of copy/move construct/assign, because the
  71   /// checks have been performed when building `Other`.
  72   constexpr Align(const Align &Other) = default;
  73   constexpr Align(Align &&Other) = default;
  74   Align &operator=(const Align &Other) = default;
  75   Align &operator=(Align &&Other) = default;
  76
  77   explicit Align(uint64_t Value) {
  78     assert(Value > 0 && "Value must not be 0");
  79     assert(llvm::isPowerOf2_64(Value) && "Alignment is not a power of 2");
  80     ShiftValue = Log2_64(Value);
  81     assert(ShiftValue < 64 && "Broken invariant");
  82   }
  83
  84   /// This is a hole in the type system and should not be abused.
  85   /// Needed to interact with C for instance.
  86   uint64_t value() const { return uint64_t(1) << ShiftValue; }
  87
  88   /// Returns a default constructed Align which corresponds to no alignment.
  89   /// This is useful to test for unalignment as it conveys clear semantic.
  90   /// `if (A != Align::None())`
  91   /// would be better than
  92   /// `if (A > Align(1))`
  93   constexpr static const Align None() { return Align(); }
  94
  95   /// Allow constructions of constexpr Align.
  96   template <size_t kValue> constexpr static LogValue Constant() {
  97     return LogValue{static_cast<uint8_t>(CTLog2<kValue>())};
  98   }
  99
 100   /// Allow constructions of constexpr Align from types.
 101   /// Compile time equivalent to Align(alignof(T)).
 102   template <typename T> constexpr static LogValue Of() {
 103     return Constant<std::alignment_of<T>::value>();
 104   }
 105
 106   /// Constexpr constructor from LogValue type.
 107   constexpr Align(LogValue CA) : ShiftValue(CA.Log) {}
 108 };
 109
 110 /// Treats the value 0 as a 1, so Align is always at least 1.
 111 inline Align assumeAligned(uint64_t Value) {
 112   return Value ? Align(Value) : Align();
 113 }
 114
 115 /// This struct is a compact representation of a valid (power of two) or
 116 /// undefined (0) alignment.
 117 struct MaybeAlign : public llvm::Optional<Align> {
 118 private:
 119   using UP = llvm::Optional<Align>;
 120
 121 public:
 122   /// Default is undefined.
 123   MaybeAlign() = default;
 124   /// Do not perform checks in case of copy/move construct/assign, because the
 125   /// checks have been performed when building `Other`.
 126   MaybeAlign(const MaybeAlign &Other) = default;
 127   MaybeAlign &operator=(const MaybeAlign &Other) = default;
 128   MaybeAlign(MaybeAlign &&Other) = default;
 129   MaybeAlign &operator=(MaybeAlign &&Other) = default;
 130
 131   /// Use llvm::Optional<Align> constructor.
 132   using UP::UP;
 133
 134   explicit MaybeAlign(uint64_t Value) {
 135     assert((Value == 0 || llvm::isPowerOf2_64(Value)) &&
 136            "Alignment is neither 0 nor a power of 2");
 137     if (Value)
 138       emplace(Value);
 139   }
 140
 141   /// For convenience, returns a valid alignment or 1 if undefined.
 142   Align valueOrOne() const { return hasValue() ? getValue() : Align(); }
 143 };
 144
 145 /// Checks that SizeInBytes is a multiple of the alignment.
 146 inline bool isAligned(Align Lhs, uint64_t SizeInBytes) {
 147   return SizeInBytes % Lhs.value() == 0;
 148 }
 149
 150 /// Checks that SizeInBytes is a multiple of the alignment.
 151 /// Returns false if the alignment is undefined.
 152 inline bool isAligned(MaybeAlign Lhs, uint64_t SizeInBytes) {
 153   ALIGN_CHECK_ISSET(Lhs);
 154   return SizeInBytes % (*Lhs).value() == 0;
 155 }
 156
 157 /// Checks that Addr is a multiple of the alignment.
 158 inline bool isAddrAligned(Align Lhs, const void *Addr) {
 159   return isAligned(Lhs, reinterpret_cast<uintptr_t>(Addr));
 160 }
 161
 162 /// Returns a multiple of A needed to store `Size` bytes.
 163 inline uint64_t alignTo(uint64_t Size, Align A) {
 164   const uint64_t value = A.value();
 165   // The following line is equivalent to `(Size + value - 1) / value * value`.
 166
 167   // The division followed by a multiplication can be thought of as a right
 168   // shift followed by a left shift which zeros out the extra bits produced in
 169   // the bump; `~(value - 1)` is a mask where all those bits being zeroed out
 170   // are just zero.
 171
 172   // Most compilers can generate this code but the pattern may be missed when
 173   // multiple functions gets inlined.
 174   return (Size + value - 1) & ~(value - 1);
 175 }
 176
 177 /// Returns a multiple of A needed to store `Size` bytes.
 178 /// Returns `Size` if current alignment is undefined.
 179 inline uint64_t alignTo(uint64_t Size, MaybeAlign A) {
 180   return A ? alignTo(Size, A.getValue()) : Size;
 181 }
 182
 183 /// Aligns `Addr` to `Alignment` bytes, rounding up.
 184 inline uintptr_t alignAddr(const void *Addr, Align Alignment) {
 185   uintptr_t ArithAddr = reinterpret_cast<uintptr_t>(Addr);
 186   assert(static_cast<uintptr_t>(ArithAddr + Alignment.value() - 1) >=
 187              ArithAddr && "Overflow");
 188   return alignTo(ArithAddr, Alignment);
 189 }
 190
 191 /// Returns the offset to the next integer (mod 2**64) that is greater than
 192 /// or equal to \p Value and is a multiple of \p Align.
 193 inline uint64_t offsetToAlignment(uint64_t Value, Align Alignment) {
 194   return alignTo(Value, Alignment) - Value;
 195 }
 196
 197 /// Returns the necessary adjustment for aligning `Addr` to `Alignment`
 198 /// bytes, rounding up.
 199 inline uint64_t offsetToAlignedAddr(const void *Addr, Align Alignment) {
 200   return offsetToAlignment(reinterpret_cast<uintptr_t>(Addr), Alignment);
 201 }
 202
 203 /// Returns the log2 of the alignment.
 204 inline unsigned Log2(Align A) { return A.ShiftValue; }
 205
 206 /// Returns the log2 of the alignment.
 207 /// \pre A must be defined.
 208 inline unsigned Log2(MaybeAlign A) {
 209   ALIGN_CHECK_ISSET(A);
 210   return Log2(A.getValue());
 211 }
 212
 213 /// Returns the alignment that satisfies both alignments.
 214 /// Same semantic as MinAlign.
 215 inline Align commonAlignment(Align A, Align B) { return std::min(A, B); }
 216
 217 /// Returns the alignment that satisfies both alignments.
 218 /// Same semantic as MinAlign.
 219 inline Align commonAlignment(Align A, uint64_t Offset) {
 220   return Align(MinAlign(A.value(), Offset));
 221 }
 222
 223 /// Returns the alignment that satisfies both alignments.
 224 /// Same semantic as MinAlign.
 225 inline MaybeAlign commonAlignment(MaybeAlign A, MaybeAlign B) {
 226   return A && B ? commonAlignment(*A, *B) : A ? A : B;
 227 }
 228
 229 /// Returns the alignment that satisfies both alignments.
 230 /// Same semantic as MinAlign.
 231 inline MaybeAlign commonAlignment(MaybeAlign A, uint64_t Offset) {
 232   return MaybeAlign(MinAlign((*A).value(), Offset));
 233 }
 234
 235 /// Returns a representation of the alignment that encodes undefined as 0.
 236 inline unsigned encode(MaybeAlign A) { return A ? A->ShiftValue + 1 : 0; }
 237
 238 /// Dual operation of the encode function above.
 239 inline MaybeAlign decodeMaybeAlign(unsigned Value) {
 240   if (Value == 0)
 241     return MaybeAlign();
 242   Align Out;
 243   Out.ShiftValue = Value - 1;
 244   return Out;
 245 }
 246
 247 /// Returns a representation of the alignment, the encoded value is positive by
 248 /// definition.
 249 inline unsigned encode(Align A) { return encode(MaybeAlign(A)); }
 250
 251 /// Comparisons between Align and scalars. Rhs must be positive.
 252 inline bool operator==(Align Lhs, uint64_t Rhs) {
 253   ALIGN_CHECK_ISPOSITIVE(Rhs);
 254   return Lhs.value() == Rhs;
 255 }
 256 inline bool operator!=(Align Lhs, uint64_t Rhs) {
 257   ALIGN_CHECK_ISPOSITIVE(Rhs);
 258   return Lhs.value() != Rhs;
 259 }
 260 inline bool operator<=(Align Lhs, uint64_t Rhs) {
 261   ALIGN_CHECK_ISPOSITIVE(Rhs);
 262   return Lhs.value() <= Rhs;
 263 }
 264 inline bool operator>=(Align Lhs, uint64_t Rhs) {
 265   ALIGN_CHECK_ISPOSITIVE(Rhs);
 266   return Lhs.value() >= Rhs;
 267 }
 268 inline bool operator<(Align Lhs, uint64_t Rhs) {
 269   ALIGN_CHECK_ISPOSITIVE(Rhs);
 270   return Lhs.value() < Rhs;
 271 }
 272 inline bool operator>(Align Lhs, uint64_t Rhs) {
 273   ALIGN_CHECK_ISPOSITIVE(Rhs);
 274   return Lhs.value() > Rhs;
 275 }
 276
 277 /// Comparisons between MaybeAlign and scalars.
 278 inline bool operator==(MaybeAlign Lhs, uint64_t Rhs) {
 279   return Lhs ? (*Lhs).value() == Rhs : Rhs == 0;
 280 }
 281 inline bool operator!=(MaybeAlign Lhs, uint64_t Rhs) {
 282   return Lhs ? (*Lhs).value() != Rhs : Rhs != 0;
 283 }
 284 inline bool operator<=(MaybeAlign Lhs, uint64_t Rhs) {
 285   ALIGN_CHECK_ISSET(Lhs);
 286   ALIGN_CHECK_ISPOSITIVE(Rhs);
 287   return (*Lhs).value() <= Rhs;
 288 }
 289 inline bool operator>=(MaybeAlign Lhs, uint64_t Rhs) {
 290   ALIGN_CHECK_ISSET(Lhs);
 291   ALIGN_CHECK_ISPOSITIVE(Rhs);
 292   return (*Lhs).value() >= Rhs;
 293 }
 294 inline bool operator<(MaybeAlign Lhs, uint64_t Rhs) {
 295   ALIGN_CHECK_ISSET(Lhs);
 296   ALIGN_CHECK_ISPOSITIVE(Rhs);
 297   return (*Lhs).value() < Rhs;
 298 }
 299 inline bool operator>(MaybeAlign Lhs, uint64_t Rhs) {
 300   ALIGN_CHECK_ISSET(Lhs);
 301   ALIGN_CHECK_ISPOSITIVE(Rhs);
 302   return (*Lhs).value() > Rhs;
 303 }
 304
 305 /// Comparisons operators between Align.
 306 inline bool operator==(Align Lhs, Align Rhs) {
 307   return Lhs.ShiftValue == Rhs.ShiftValue;
 308 }
 309 inline bool operator!=(Align Lhs, Align Rhs) {
 310   return Lhs.ShiftValue != Rhs.ShiftValue;
 311 }
 312 inline bool operator<=(Align Lhs, Align Rhs) {
 313   return Lhs.ShiftValue <= Rhs.ShiftValue;
 314 }
 315 inline bool operator>=(Align Lhs, Align Rhs) {
 316   return Lhs.ShiftValue >= Rhs.ShiftValue;
 317 }
 318 inline bool operator<(Align Lhs, Align Rhs) {
 319   return Lhs.ShiftValue < Rhs.ShiftValue;
 320 }
 321 inline bool operator>(Align Lhs, Align Rhs) {
 322   return Lhs.ShiftValue > Rhs.ShiftValue;
 323 }
 324
 325 /// Comparisons operators between Align and MaybeAlign.
 326 inline bool operator==(Align Lhs, MaybeAlign Rhs) {
 327   ALIGN_CHECK_ISSET(Rhs);
 328   return Lhs.value() == (*Rhs).value();
 329 }
 330 inline bool operator!=(Align Lhs, MaybeAlign Rhs) {
 331   ALIGN_CHECK_ISSET(Rhs);
 332   return Lhs.value() != (*Rhs).value();
 333 }
 334 inline bool operator<=(Align Lhs, MaybeAlign Rhs) {
 335   ALIGN_CHECK_ISSET(Rhs);
 336   return Lhs.value() <= (*Rhs).value();
 337 }
 338 inline bool operator>=(Align Lhs, MaybeAlign Rhs) {
 339   ALIGN_CHECK_ISSET(Rhs);
 340   return Lhs.value() >= (*Rhs).value();
 341 }
 342 inline bool operator<(Align Lhs, MaybeAlign Rhs) {
 343   ALIGN_CHECK_ISSET(Rhs);
 344   return Lhs.value() < (*Rhs).value();
 345 }
 346 inline bool operator>(Align Lhs, MaybeAlign Rhs) {
 347   ALIGN_CHECK_ISSET(Rhs);
 348   return Lhs.value() > (*Rhs).value();
 349 }
 350
 351 /// Comparisons operators between MaybeAlign and Align.
 352 inline bool operator==(MaybeAlign Lhs, Align Rhs) {
 353   ALIGN_CHECK_ISSET(Lhs);
 354   return Lhs && (*Lhs).value() == Rhs.value();
 355 }
 356 inline bool operator!=(MaybeAlign Lhs, Align Rhs) {
 357   ALIGN_CHECK_ISSET(Lhs);
 358   return Lhs && (*Lhs).value() != Rhs.value();
 359 }
 360 inline bool operator<=(MaybeAlign Lhs, Align Rhs) {
 361   ALIGN_CHECK_ISSET(Lhs);
 362   return Lhs && (*Lhs).value() <= Rhs.value();
 363 }
 364 inline bool operator>=(MaybeAlign Lhs, Align Rhs) {
 365   ALIGN_CHECK_ISSET(Lhs);
 366   return Lhs && (*Lhs).value() >= Rhs.value();
 367 }
 368 inline bool operator<(MaybeAlign Lhs, Align Rhs) {
 369   ALIGN_CHECK_ISSET(Lhs);
 370   return Lhs && (*Lhs).value() < Rhs.value();
 371 }
 372 inline bool operator>(MaybeAlign Lhs, Align Rhs) {
 373   ALIGN_CHECK_ISSET(Lhs);
 374   return Lhs && (*Lhs).value() > Rhs.value();
 375 }
 376
 377 inline Align operator/(Align Lhs, uint64_t Divisor) {
 378   assert(llvm::isPowerOf2_64(Divisor) &&
 379          "Divisor must be positive and a power of 2");
 380   assert(Lhs != 1 && "Can't halve byte alignment");
 381   return Align(Lhs.value() / Divisor);
 382 }
 383
 384 inline MaybeAlign operator/(MaybeAlign Lhs, uint64_t Divisor) {
 385   assert(llvm::isPowerOf2_64(Divisor) &&
 386          "Divisor must be positive and a power of 2");
 387   return Lhs ? Lhs.getValue() / Divisor : MaybeAlign();
 388 }
 389
 390 inline Align max(MaybeAlign Lhs, Align Rhs) {
 391   return Lhs && *Lhs > Rhs ? *Lhs : Rhs;
 392 }
 393
 394 inline Align max(Align Lhs, MaybeAlign Rhs) {
 395   return Rhs && *Rhs > Lhs ? *Rhs : Lhs;
 396 }
 397
 398 #undef ALIGN_CHECK_ISPOSITIVE
 399 #undef ALIGN_CHECK_ISSET
 400
 401 } // namespace llvm
 402
 403 #endif // LLVM_SUPPORT_ALIGNMENT_H_