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 public:
  57   /// Default is byte-aligned.
  58   constexpr Align() = default;
  59   /// Do not perform checks in case of copy/move construct/assign, because the
  60   /// checks have been performed when building `Other`.
  61   Align(const Align &Other) = default;
  62   Align &operator=(const Align &Other) = default;
  63   Align(Align &&Other) = default;
  64   Align &operator=(Align &&Other) = default;
  65
  66   explicit Align(uint64_t Value) {
  67     assert(Value > 0 && "Value must not be 0");
  68     assert(llvm::isPowerOf2_64(Value) && "Alignment is not a power of 2");
  69     ShiftValue = Log2_64(Value);
  70     assert(ShiftValue < 64 && "Broken invariant");
  71   }
  72
  73   /// This is a hole in the type system and should not be abused.
  74   /// Needed to interact with C for instance.
  75   uint64_t value() const { return uint64_t(1) << ShiftValue; }
  76
  77   /// Returns a default constructed Align which corresponds to no alignment.
  78   /// This is useful to test for unalignment as it conveys clear semantic.
  79   /// `if (A != llvm::Align::None())`
  80   /// would be better than
  81   /// `if (A > llvm::Align(1))`
  82   constexpr static const Align None() { return llvm::Align(); }
  83 };
  84
  85 /// Treats the value 0 as a 1, so Align is always at least 1.
  86 inline Align assumeAligned(uint64_t Value) {
  87   return Value ? Align(Value) : Align();
  88 }
  89
  90 /// This struct is a compact representation of a valid (power of two) or
  91 /// undefined (0) alignment.
  92 struct MaybeAlign : public llvm::Optional<Align> {
  93 private:
  94   using UP = llvm::Optional<Align>;
  95
  96 public:
  97   /// Default is undefined.
  98   MaybeAlign() = default;
  99   /// Do not perform checks in case of copy/move construct/assign, because the
 100   /// checks have been performed when building `Other`.
 101   MaybeAlign(const MaybeAlign &Other) = default;
 102   MaybeAlign &operator=(const MaybeAlign &Other) = default;
 103   MaybeAlign(MaybeAlign &&Other) = default;
 104   MaybeAlign &operator=(MaybeAlign &&Other) = default;
 105
 106   /// Use llvm::Optional<Align> constructor.
 107   using UP::UP;
 108
 109   explicit MaybeAlign(uint64_t Value) {
 110     assert((Value == 0 || llvm::isPowerOf2_64(Value)) &&
 111            "Alignment is neither 0 nor a power of 2");
 112     if (Value)
 113       emplace(Value);
 114   }
 115
 116   /// For convenience, returns a valid alignment or 1 if undefined.
 117   Align valueOrOne() const { return hasValue() ? getValue() : Align(); }
 118 };
 119
 120 /// Checks that SizeInBytes is a multiple of the alignment.
 121 inline bool isAligned(Align Lhs, uint64_t SizeInBytes) {
 122   return SizeInBytes % Lhs.value() == 0;
 123 }
 124
 125 /// Checks that SizeInBytes is a multiple of the alignment.
 126 /// Returns false if the alignment is undefined.
 127 inline bool isAligned(MaybeAlign Lhs, uint64_t SizeInBytes) {
 128   ALIGN_CHECK_ISSET(Lhs);
 129   return SizeInBytes % (*Lhs).value() == 0;
 130 }
 131
 132 /// Returns a multiple of A needed to store `Size` bytes.
 133 inline uint64_t alignTo(uint64_t Size, Align A) {
 134   return (Size + A.value() - 1) / A.value() * A.value();
 135 }
 136
 137 /// Returns a multiple of A needed to store `Size` bytes.
 138 /// Returns `Size` if current alignment is undefined.
 139 inline uint64_t alignTo(uint64_t Size, MaybeAlign A) {
 140   return A ? alignTo(Size, A.getValue()) : Size;
 141 }
 142
 143 /// Returns the offset to the next integer (mod 2**64) that is greater than
 144 /// or equal to \p Value and is a multiple of \p Align.
 145 inline uint64_t offsetToAlignment(uint64_t Value, llvm::Align Align) {
 146   return alignTo(Value, Align) - Value;
 147 }
 148
 149 /// Returns the log2 of the alignment.
 150 inline unsigned Log2(Align A) { return A.ShiftValue; }
 151
 152 /// Returns the log2 of the alignment.
 153 /// \pre A must be defined.
 154 inline unsigned Log2(MaybeAlign A) {
 155   ALIGN_CHECK_ISSET(A);
 156   return Log2(A.getValue());
 157 }
 158
 159 /// Returns the alignment that satisfies both alignments.
 160 /// Same semantic as MinAlign.
 161 inline Align commonAlignment(Align A, Align B) { return std::min(A, B); }
 162
 163 /// Returns the alignment that satisfies both alignments.
 164 /// Same semantic as MinAlign.
 165 inline Align commonAlignment(Align A, uint64_t Offset) {
 166   return Align(MinAlign(A.value(), Offset));
 167 }
 168
 169 /// Returns the alignment that satisfies both alignments.
 170 /// Same semantic as MinAlign.
 171 inline MaybeAlign commonAlignment(MaybeAlign A, MaybeAlign B) {
 172   return A && B ? commonAlignment(*A, *B) : A ? A : B;
 173 }
 174
 175 /// Returns the alignment that satisfies both alignments.
 176 /// Same semantic as MinAlign.
 177 inline MaybeAlign commonAlignment(MaybeAlign A, uint64_t Offset) {
 178   return MaybeAlign(MinAlign((*A).value(), Offset));
 179 }
 180
 181 /// Returns a representation of the alignment that encodes undefined as 0.
 182 inline unsigned encode(MaybeAlign A) { return A ? A->ShiftValue + 1 : 0; }
 183
 184 /// Dual operation of the encode function above.
 185 inline MaybeAlign decodeMaybeAlign(unsigned Value) {
 186   if (Value == 0)
 187     return MaybeAlign();
 188   Align Out;
 189   Out.ShiftValue = Value - 1;
 190   return Out;
 191 }
 192
 193 /// Returns a representation of the alignment, the encoded value is positive by
 194 /// definition.
 195 inline unsigned encode(Align A) { return encode(MaybeAlign(A)); }
 196
 197 /// Comparisons between Align and scalars. Rhs must be positive.
 198 inline bool operator==(Align Lhs, uint64_t Rhs) {
 199   ALIGN_CHECK_ISPOSITIVE(Rhs);
 200   return Lhs.value() == Rhs;
 201 }
 202 inline bool operator!=(Align Lhs, uint64_t Rhs) {
 203   ALIGN_CHECK_ISPOSITIVE(Rhs);
 204   return Lhs.value() != Rhs;
 205 }
 206 inline bool operator<=(Align Lhs, uint64_t Rhs) {
 207   ALIGN_CHECK_ISPOSITIVE(Rhs);
 208   return Lhs.value() <= Rhs;
 209 }
 210 inline bool operator>=(Align Lhs, uint64_t Rhs) {
 211   ALIGN_CHECK_ISPOSITIVE(Rhs);
 212   return Lhs.value() >= Rhs;
 213 }
 214 inline bool operator<(Align Lhs, uint64_t Rhs) {
 215   ALIGN_CHECK_ISPOSITIVE(Rhs);
 216   return Lhs.value() < Rhs;
 217 }
 218 inline bool operator>(Align Lhs, uint64_t Rhs) {
 219   ALIGN_CHECK_ISPOSITIVE(Rhs);
 220   return Lhs.value() > Rhs;
 221 }
 222
 223 /// Comparisons between MaybeAlign and scalars.
 224 inline bool operator==(MaybeAlign Lhs, uint64_t Rhs) {
 225   return Lhs ? (*Lhs).value() == Rhs : Rhs == 0;
 226 }
 227 inline bool operator!=(MaybeAlign Lhs, uint64_t Rhs) {
 228   return Lhs ? (*Lhs).value() != Rhs : Rhs != 0;
 229 }
 230 inline bool operator<=(MaybeAlign Lhs, uint64_t Rhs) {
 231   ALIGN_CHECK_ISSET(Lhs);
 232   ALIGN_CHECK_ISPOSITIVE(Rhs);
 233   return (*Lhs).value() <= Rhs;
 234 }
 235 inline bool operator>=(MaybeAlign Lhs, uint64_t Rhs) {
 236   ALIGN_CHECK_ISSET(Lhs);
 237   ALIGN_CHECK_ISPOSITIVE(Rhs);
 238   return (*Lhs).value() >= Rhs;
 239 }
 240 inline bool operator<(MaybeAlign Lhs, uint64_t Rhs) {
 241   ALIGN_CHECK_ISSET(Lhs);
 242   ALIGN_CHECK_ISPOSITIVE(Rhs);
 243   return (*Lhs).value() < Rhs;
 244 }
 245 inline bool operator>(MaybeAlign Lhs, uint64_t Rhs) {
 246   ALIGN_CHECK_ISSET(Lhs);
 247   ALIGN_CHECK_ISPOSITIVE(Rhs);
 248   return (*Lhs).value() > Rhs;
 249 }
 250
 251 /// Comparisons operators between Align.
 252 inline bool operator==(Align Lhs, Align Rhs) {
 253   return Lhs.ShiftValue == Rhs.ShiftValue;
 254 }
 255 inline bool operator!=(Align Lhs, Align Rhs) {
 256   return Lhs.ShiftValue != Rhs.ShiftValue;
 257 }
 258 inline bool operator<=(Align Lhs, Align Rhs) {
 259   return Lhs.ShiftValue <= Rhs.ShiftValue;
 260 }
 261 inline bool operator>=(Align Lhs, Align Rhs) {
 262   return Lhs.ShiftValue >= Rhs.ShiftValue;
 263 }
 264 inline bool operator<(Align Lhs, Align Rhs) {
 265   return Lhs.ShiftValue < Rhs.ShiftValue;
 266 }
 267 inline bool operator>(Align Lhs, Align Rhs) {
 268   return Lhs.ShiftValue > Rhs.ShiftValue;
 269 }
 270
 271 /// Comparisons operators between Align and MaybeAlign.
 272 inline bool operator==(Align Lhs, MaybeAlign Rhs) {
 273   ALIGN_CHECK_ISSET(Rhs);
 274   return Lhs.value() == (*Rhs).value();
 275 }
 276 inline bool operator!=(Align Lhs, MaybeAlign Rhs) {
 277   ALIGN_CHECK_ISSET(Rhs);
 278   return Lhs.value() != (*Rhs).value();
 279 }
 280 inline bool operator<=(Align Lhs, MaybeAlign Rhs) {
 281   ALIGN_CHECK_ISSET(Rhs);
 282   return Lhs.value() <= (*Rhs).value();
 283 }
 284 inline bool operator>=(Align Lhs, MaybeAlign Rhs) {
 285   ALIGN_CHECK_ISSET(Rhs);
 286   return Lhs.value() >= (*Rhs).value();
 287 }
 288 inline bool operator<(Align Lhs, MaybeAlign Rhs) {
 289   ALIGN_CHECK_ISSET(Rhs);
 290   return Lhs.value() < (*Rhs).value();
 291 }
 292 inline bool operator>(Align Lhs, MaybeAlign Rhs) {
 293   ALIGN_CHECK_ISSET(Rhs);
 294   return Lhs.value() > (*Rhs).value();
 295 }
 296
 297 /// Comparisons operators between MaybeAlign and Align.
 298 inline bool operator==(MaybeAlign Lhs, Align Rhs) {
 299   ALIGN_CHECK_ISSET(Lhs);
 300   return Lhs && (*Lhs).value() == Rhs.value();
 301 }
 302 inline bool operator!=(MaybeAlign Lhs, Align Rhs) {
 303   ALIGN_CHECK_ISSET(Lhs);
 304   return Lhs && (*Lhs).value() != Rhs.value();
 305 }
 306 inline bool operator<=(MaybeAlign Lhs, Align Rhs) {
 307   ALIGN_CHECK_ISSET(Lhs);
 308   return Lhs && (*Lhs).value() <= Rhs.value();
 309 }
 310 inline bool operator>=(MaybeAlign Lhs, Align Rhs) {
 311   ALIGN_CHECK_ISSET(Lhs);
 312   return Lhs && (*Lhs).value() >= Rhs.value();
 313 }
 314 inline bool operator<(MaybeAlign Lhs, Align Rhs) {
 315   ALIGN_CHECK_ISSET(Lhs);
 316   return Lhs && (*Lhs).value() < Rhs.value();
 317 }
 318 inline bool operator>(MaybeAlign Lhs, Align Rhs) {
 319   ALIGN_CHECK_ISSET(Lhs);
 320   return Lhs && (*Lhs).value() > Rhs.value();
 321 }
 322
 323 inline Align operator/(Align Lhs, uint64_t Divisor) {
 324   assert(llvm::isPowerOf2_64(Divisor) &&
 325          "Divisor must be positive and a power of 2");
 326   assert(Lhs != 1 && "Can't halve byte alignment");
 327   return Align(Lhs.value() / Divisor);
 328 }
 329
 330 inline MaybeAlign operator/(MaybeAlign Lhs, uint64_t Divisor) {
 331   assert(llvm::isPowerOf2_64(Divisor) &&
 332          "Divisor must be positive and a power of 2");
 333   return Lhs ? Lhs.getValue() / Divisor : MaybeAlign();
 334 }
 335
 336 #undef ALIGN_CHECK_ISPOSITIVE
 337 #undef ALIGN_CHECK_ISSET
 338
 339 } // namespace llvm
 340
 341 #endif // LLVM_SUPPORT_ALIGNMENT_H_