1 //===- ConstantRange.h - Represent a range ----------------------*- 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 // Represent a range of possible values that may occur when the program is run
10 // for an integral value.  This keeps track of a lower and upper bound for the
11 // constant, which MAY wrap around the end of the numeric range.  To do this, it
12 // keeps track of a [lower, upper) bound, which specifies an interval just like
13 // STL iterators.  When used with boolean values, the following are important
14 // ranges: :
15 //
16 //  [F, F) = {}     = Empty set
17 //  [T, F) = {T}
18 //  [F, T) = {F}
19 //  [T, T) = {F, T} = Full set
20 //
21 // The other integral ranges use min/max values for special range values. For
22 // example, for 8-bit types, it uses:
23 // [0, 0)     = {}       = Empty set
24 // [255, 255) = {0..255} = Full Set
25 //
26 // Note that ConstantRange can be used to represent either signed or
27 // unsigned ranges.
28 //
29 //===----------------------------------------------------------------------===//
30 
31 #ifndef LLVM_IR_CONSTANTRANGE_H
32 #define LLVM_IR_CONSTANTRANGE_H
33 
34 #include "llvm/ADT/APInt.h"
35 #include "llvm/IR/InstrTypes.h"
36 #include "llvm/IR/Instruction.h"
37 #include "llvm/Support/Compiler.h"
38 #include <cstdint>
39 
40 namespace llvm {
41 
42 class MDNode;
43 class raw_ostream;
44 struct KnownBits;
45 
46 /// This class represents a range of values.
47 class LLVM_NODISCARD ConstantRange {
48   APInt Lower, Upper;
49 
50   /// Create empty constant range with same bitwidth.
51   ConstantRange getEmpty() const {
52     return ConstantRange(getBitWidth(), false);
53   }
54 
55   /// Create full constant range with same bitwidth.
56   ConstantRange getFull() const {
57     return ConstantRange(getBitWidth(), true);
58   }
59 
60 public:
61   /// Initialize a full or empty set for the specified bit width.
62   explicit ConstantRange(uint32_t BitWidth, bool isFullSet);
63 
64   /// Initialize a range to hold the single specified value.
65   ConstantRange(APInt Value);
66 
67   /// Initialize a range of values explicitly. This will assert out if
68   /// Lower==Upper and Lower != Min or Max value for its type. It will also
69   /// assert out if the two APInt's are not the same bit width.
70   ConstantRange(APInt Lower, APInt Upper);
71 
72   /// Create empty constant range with the given bit width.
73   static ConstantRange getEmpty(uint32_t BitWidth) {
74     return ConstantRange(BitWidth, false);
75   }
76 
77   /// Create full constant range with the given bit width.
78   static ConstantRange getFull(uint32_t BitWidth) {
79     return ConstantRange(BitWidth, true);
80   }
81 
82   /// Create non-empty constant range with the given bounds. If Lower and
83   /// Upper are the same, a full range is returned.
84   static ConstantRange getNonEmpty(APInt Lower, APInt Upper) {
85     if (Lower == Upper)
86       return getFull(Lower.getBitWidth());
87     return ConstantRange(std::move(Lower), std::move(Upper));
88   }
89 
90   /// Initialize a range based on a known bits constraint. The IsSigned flag
91   /// indicates whether the constant range should not wrap in the signed or
92   /// unsigned domain.
93   static ConstantRange fromKnownBits(const KnownBits &Known, bool IsSigned);
94 
95   /// Produce the smallest range such that all values that may satisfy the given
96   /// predicate with any value contained within Other is contained in the
97   /// returned range.  Formally, this returns a superset of
98   /// 'union over all y in Other . { x : icmp op x y is true }'.  If the exact
99   /// answer is not representable as a ConstantRange, the return value will be a
100   /// proper superset of the above.
101   ///
102   /// Example: Pred = ult and Other = i8 [2, 5) returns Result = [0, 4)
103   static ConstantRange makeAllowedICmpRegion(CmpInst::Predicate Pred,
104                                              const ConstantRange &Other);
105 
106   /// Produce the largest range such that all values in the returned range
107   /// satisfy the given predicate with all values contained within Other.
108   /// Formally, this returns a subset of
109   /// 'intersection over all y in Other . { x : icmp op x y is true }'.  If the
110   /// exact answer is not representable as a ConstantRange, the return value
111   /// will be a proper subset of the above.
112   ///
113   /// Example: Pred = ult and Other = i8 [2, 5) returns [0, 2)
114   static ConstantRange makeSatisfyingICmpRegion(CmpInst::Predicate Pred,
115                                                 const ConstantRange &Other);
116 
117   /// Produce the exact range such that all values in the returned range satisfy
118   /// the given predicate with any value contained within Other. Formally, this
119   /// returns the exact answer when the superset of 'union over all y in Other
120   /// is exactly same as the subset of intersection over all y in Other.
121   /// { x : icmp op x y is true}'.
122   ///
123   /// Example: Pred = ult and Other = i8 3 returns [0, 3)
124   static ConstantRange makeExactICmpRegion(CmpInst::Predicate Pred,
125                                            const APInt &Other);
126 
127   /// Does the predicate \p Pred hold between ranges this and \p Other?
128   /// NOTE: false does not mean that inverse predicate holds!
129   bool icmp(CmpInst::Predicate Pred, const ConstantRange &Other) const;
130 
131   /// Produce the largest range containing all X such that "X BinOp Y" is
132   /// guaranteed not to wrap (overflow) for *all* Y in Other. However, there may
133   /// be *some* Y in Other for which additional X not contained in the result
134   /// also do not overflow.
135   ///
136   /// NoWrapKind must be one of OBO::NoUnsignedWrap or OBO::NoSignedWrap.
137   ///
138   /// Examples:
139   ///  typedef OverflowingBinaryOperator OBO;
140   ///  #define MGNR makeGuaranteedNoWrapRegion
141   ///  MGNR(Add, [i8 1, 2), OBO::NoSignedWrap) == [-128, 127)
142   ///  MGNR(Add, [i8 1, 2), OBO::NoUnsignedWrap) == [0, -1)
143   ///  MGNR(Add, [i8 0, 1), OBO::NoUnsignedWrap) == Full Set
144   ///  MGNR(Add, [i8 -1, 6), OBO::NoSignedWrap) == [INT_MIN+1, INT_MAX-4)
145   ///  MGNR(Sub, [i8 1, 2), OBO::NoSignedWrap) == [-127, 128)
146   ///  MGNR(Sub, [i8 1, 2), OBO::NoUnsignedWrap) == [1, 0)
147   static ConstantRange makeGuaranteedNoWrapRegion(Instruction::BinaryOps BinOp,
148                                                   const ConstantRange &Other,
149                                                   unsigned NoWrapKind);
150 
151   /// Produce the range that contains X if and only if "X BinOp Other" does
152   /// not wrap.
153   static ConstantRange makeExactNoWrapRegion(Instruction::BinaryOps BinOp,
154                                              const APInt &Other,
155                                              unsigned NoWrapKind);
156 
157   /// Returns true if ConstantRange calculations are supported for intrinsic
158   /// with \p IntrinsicID.
159   static bool isIntrinsicSupported(Intrinsic::ID IntrinsicID);
160 
161   /// Compute range of intrinsic result for the given operand ranges.
162   static ConstantRange intrinsic(Intrinsic::ID IntrinsicID,
163                                  ArrayRef<ConstantRange> Ops);
164 
165   /// Set up \p Pred and \p RHS such that
166   /// ConstantRange::makeExactICmpRegion(Pred, RHS) == *this.  Return true if
167   /// successful.
168   bool getEquivalentICmp(CmpInst::Predicate &Pred, APInt &RHS) const;
169 
170   /// Return the lower value for this range.
171   const APInt &getLower() const { return Lower; }
172 
173   /// Return the upper value for this range.
174   const APInt &getUpper() const { return Upper; }
175 
176   /// Get the bit width of this ConstantRange.
177   uint32_t getBitWidth() const { return Lower.getBitWidth(); }
178 
179   /// Return true if this set contains all of the elements possible
180   /// for this data-type.
181   bool isFullSet() const;
182 
183   /// Return true if this set contains no members.
184   bool isEmptySet() const;
185 
186   /// Return true if this set wraps around the unsigned domain. Special cases:
187   ///  * Empty set: Not wrapped.
188   ///  * Full set: Not wrapped.
189   ///  * [X, 0) == [X, Max]: Not wrapped.
190   bool isWrappedSet() const;
191 
192   /// Return true if the exclusive upper bound wraps around the unsigned
193   /// domain. Special cases:
194   ///  * Empty set: Not wrapped.
195   ///  * Full set: Not wrapped.
196   ///  * [X, 0): Wrapped.
197   bool isUpperWrapped() const;
198 
199   /// Return true if this set wraps around the signed domain. Special cases:
200   ///  * Empty set: Not wrapped.
201   ///  * Full set: Not wrapped.
202   ///  * [X, SignedMin) == [X, SignedMax]: Not wrapped.
203   bool isSignWrappedSet() const;
204 
205   /// Return true if the (exclusive) upper bound wraps around the signed
206   /// domain. Special cases:
207   ///  * Empty set: Not wrapped.
208   ///  * Full set: Not wrapped.
209   ///  * [X, SignedMin): Wrapped.
210   bool isUpperSignWrapped() const;
211 
212   /// Return true if the specified value is in the set.
213   bool contains(const APInt &Val) const;
214 
215   /// Return true if the other range is a subset of this one.
216   bool contains(const ConstantRange &CR) const;
217 
218   /// If this set contains a single element, return it, otherwise return null.
219   const APInt *getSingleElement() const {
220     if (Upper == Lower + 1)
221       return &Lower;
222     return nullptr;
223   }
224 
225   /// If this set contains all but a single element, return it, otherwise return
226   /// null.
227   const APInt *getSingleMissingElement() const {
228     if (Lower == Upper + 1)
229       return &Upper;
230     return nullptr;
231   }
232 
233   /// Return true if this set contains exactly one member.
234   bool isSingleElement() const { return getSingleElement() != nullptr; }
235 
236   /// Compare set size of this range with the range CR.
237   bool isSizeStrictlySmallerThan(const ConstantRange &CR) const;
238 
239   /// Compare set size of this range with Value.
240   bool isSizeLargerThan(uint64_t MaxSize) const;
241 
242   /// Return true if all values in this range are negative.
243   bool isAllNegative() const;
244 
245   /// Return true if all values in this range are non-negative.
246   bool isAllNonNegative() const;
247 
248   /// Return the largest unsigned value contained in the ConstantRange.
249   APInt getUnsignedMax() const;
250 
251   /// Return the smallest unsigned value contained in the ConstantRange.
252   APInt getUnsignedMin() const;
253 
254   /// Return the largest signed value contained in the ConstantRange.
255   APInt getSignedMax() const;
256 
257   /// Return the smallest signed value contained in the ConstantRange.
258   APInt getSignedMin() const;
259 
260   /// Return true if this range is equal to another range.
261   bool operator==(const ConstantRange &CR) const {
262     return Lower == CR.Lower && Upper == CR.Upper;
263   }
264   bool operator!=(const ConstantRange &CR) const {
265     return !operator==(CR);
266   }
267 
268   /// Compute the maximal number of active bits needed to represent every value
269   /// in this range.
270   unsigned getActiveBits() const;
271 
272   /// Compute the maximal number of bits needed to represent every value
273   /// in this signed range.
274   unsigned getMinSignedBits() const;
275 
276   /// Subtract the specified constant from the endpoints of this constant range.
277   ConstantRange subtract(const APInt &CI) const;
278 
279   /// Subtract the specified range from this range (aka relative complement of
280   /// the sets).
281   ConstantRange difference(const ConstantRange &CR) const;
282 
283   /// If represented precisely, the result of some range operations may consist
284   /// of multiple disjoint ranges. As only a single range may be returned, any
285   /// range covering these disjoint ranges constitutes a valid result, but some
286   /// may be more useful than others depending on context. The preferred range
287   /// type specifies whether a range that is non-wrapping in the unsigned or
288   /// signed domain, or has the smallest size, is preferred. If a signedness is
289   /// preferred but all ranges are non-wrapping or all wrapping, then the
290   /// smallest set size is preferred. If there are multiple smallest sets, any
291   /// one of them may be returned.
292   enum PreferredRangeType { Smallest, Unsigned, Signed };
293 
294   /// Return the range that results from the intersection of this range with
295   /// another range. If the intersection is disjoint, such that two results
296   /// are possible, the preferred range is determined by the PreferredRangeType.
297   ConstantRange intersectWith(const ConstantRange &CR,
298                               PreferredRangeType Type = Smallest) const;
299 
300   /// Return the range that results from the union of this range
301   /// with another range.  The resultant range is guaranteed to include the
302   /// elements of both sets, but may contain more.  For example, [3, 9) union
303   /// [12,15) is [3, 15), which includes 9, 10, and 11, which were not included
304   /// in either set before.
305   ConstantRange unionWith(const ConstantRange &CR,
306                           PreferredRangeType Type = Smallest) const;
307 
308   /// Return a new range representing the possible values resulting
309   /// from an application of the specified cast operator to this range. \p
310   /// BitWidth is the target bitwidth of the cast.  For casts which don't
311   /// change bitwidth, it must be the same as the source bitwidth.  For casts
312   /// which do change bitwidth, the bitwidth must be consistent with the
313   /// requested cast and source bitwidth.
314   ConstantRange castOp(Instruction::CastOps CastOp,
315                        uint32_t BitWidth) const;
316 
317   /// Return a new range in the specified integer type, which must
318   /// be strictly larger than the current type.  The returned range will
319   /// correspond to the possible range of values if the source range had been
320   /// zero extended to BitWidth.
321   ConstantRange zeroExtend(uint32_t BitWidth) const;
322 
323   /// Return a new range in the specified integer type, which must
324   /// be strictly larger than the current type.  The returned range will
325   /// correspond to the possible range of values if the source range had been
326   /// sign extended to BitWidth.
327   ConstantRange signExtend(uint32_t BitWidth) const;
328 
329   /// Return a new range in the specified integer type, which must be
330   /// strictly smaller than the current type.  The returned range will
331   /// correspond to the possible range of values if the source range had been
332   /// truncated to the specified type.
333   ConstantRange truncate(uint32_t BitWidth) const;
334 
335   /// Make this range have the bit width given by \p BitWidth. The
336   /// value is zero extended, truncated, or left alone to make it that width.
337   ConstantRange zextOrTrunc(uint32_t BitWidth) const;
338 
339   /// Make this range have the bit width given by \p BitWidth. The
340   /// value is sign extended, truncated, or left alone to make it that width.
341   ConstantRange sextOrTrunc(uint32_t BitWidth) const;
342 
343   /// Return a new range representing the possible values resulting
344   /// from an application of the specified binary operator to an left hand side
345   /// of this range and a right hand side of \p Other.
346   ConstantRange binaryOp(Instruction::BinaryOps BinOp,
347                          const ConstantRange &Other) const;
348 
349   /// Return a new range representing the possible values resulting
350   /// from an application of the specified overflowing binary operator to a
351   /// left hand side of this range and a right hand side of \p Other given
352   /// the provided knowledge about lack of wrapping \p NoWrapKind.
353   ConstantRange overflowingBinaryOp(Instruction::BinaryOps BinOp,
354                                     const ConstantRange &Other,
355                                     unsigned NoWrapKind) const;
356 
357   /// Return a new range representing the possible values resulting
358   /// from an addition of a value in this range and a value in \p Other.
359   ConstantRange add(const ConstantRange &Other) const;
360 
361   /// Return a new range representing the possible values resulting
362   /// from an addition with wrap type \p NoWrapKind of a value in this
363   /// range and a value in \p Other.
364   /// If the result range is disjoint, the preferred range is determined by the
365   /// \p PreferredRangeType.
366   ConstantRange addWithNoWrap(const ConstantRange &Other, unsigned NoWrapKind,
367                               PreferredRangeType RangeType = Smallest) const;
368 
369   /// Return a new range representing the possible values resulting
370   /// from a subtraction of a value in this range and a value in \p Other.
371   ConstantRange sub(const ConstantRange &Other) const;
372 
373   /// Return a new range representing the possible values resulting
374   /// from an subtraction with wrap type \p NoWrapKind of a value in this
375   /// range and a value in \p Other.
376   /// If the result range is disjoint, the preferred range is determined by the
377   /// \p PreferredRangeType.
378   ConstantRange subWithNoWrap(const ConstantRange &Other, unsigned NoWrapKind,
379                               PreferredRangeType RangeType = Smallest) const;
380 
381   /// Return a new range representing the possible values resulting
382   /// from a multiplication of a value in this range and a value in \p Other,
383   /// treating both this and \p Other as unsigned ranges.
384   ConstantRange multiply(const ConstantRange &Other) const;
385 
386   /// Return a new range representing the possible values resulting
387   /// from a signed maximum of a value in this range and a value in \p Other.
388   ConstantRange smax(const ConstantRange &Other) const;
389 
390   /// Return a new range representing the possible values resulting
391   /// from an unsigned maximum of a value in this range and a value in \p Other.
392   ConstantRange umax(const ConstantRange &Other) const;
393 
394   /// Return a new range representing the possible values resulting
395   /// from a signed minimum of a value in this range and a value in \p Other.
396   ConstantRange smin(const ConstantRange &Other) const;
397 
398   /// Return a new range representing the possible values resulting
399   /// from an unsigned minimum of a value in this range and a value in \p Other.
400   ConstantRange umin(const ConstantRange &Other) const;
401 
402   /// Return a new range representing the possible values resulting
403   /// from an unsigned division of a value in this range and a value in
404   /// \p Other.
405   ConstantRange udiv(const ConstantRange &Other) const;
406 
407   /// Return a new range representing the possible values resulting
408   /// from a signed division of a value in this range and a value in
409   /// \p Other. Division by zero and division of SignedMin by -1 are considered
410   /// undefined behavior, in line with IR, and do not contribute towards the
411   /// result.
412   ConstantRange sdiv(const ConstantRange &Other) const;
413 
414   /// Return a new range representing the possible values resulting
415   /// from an unsigned remainder operation of a value in this range and a
416   /// value in \p Other.
417   ConstantRange urem(const ConstantRange &Other) const;
418 
419   /// Return a new range representing the possible values resulting
420   /// from a signed remainder operation of a value in this range and a
421   /// value in \p Other.
422   ConstantRange srem(const ConstantRange &Other) const;
423 
424   /// Return a new range representing the possible values resulting from
425   /// a binary-xor of a value in this range by an all-one value,
426   /// aka bitwise complement operation.
427   ConstantRange binaryNot() const;
428 
429   /// Return a new range representing the possible values resulting
430   /// from a binary-and of a value in this range by a value in \p Other.
431   ConstantRange binaryAnd(const ConstantRange &Other) const;
432 
433   /// Return a new range representing the possible values resulting
434   /// from a binary-or of a value in this range by a value in \p Other.
435   ConstantRange binaryOr(const ConstantRange &Other) const;
436 
437   /// Return a new range representing the possible values resulting
438   /// from a binary-xor of a value in this range by a value in \p Other.
439   ConstantRange binaryXor(const ConstantRange &Other) const;
440 
441   /// Return a new range representing the possible values resulting
442   /// from a left shift of a value in this range by a value in \p Other.
443   /// TODO: This isn't fully implemented yet.
444   ConstantRange shl(const ConstantRange &Other) const;
445 
446   /// Return a new range representing the possible values resulting from a
447   /// logical right shift of a value in this range and a value in \p Other.
448   ConstantRange lshr(const ConstantRange &Other) const;
449 
450   /// Return a new range representing the possible values resulting from a
451   /// arithmetic right shift of a value in this range and a value in \p Other.
452   ConstantRange ashr(const ConstantRange &Other) const;
453 
454   /// Perform an unsigned saturating addition of two constant ranges.
455   ConstantRange uadd_sat(const ConstantRange &Other) const;
456 
457   /// Perform a signed saturating addition of two constant ranges.
458   ConstantRange sadd_sat(const ConstantRange &Other) const;
459 
460   /// Perform an unsigned saturating subtraction of two constant ranges.
461   ConstantRange usub_sat(const ConstantRange &Other) const;
462 
463   /// Perform a signed saturating subtraction of two constant ranges.
464   ConstantRange ssub_sat(const ConstantRange &Other) const;
465 
466   /// Perform an unsigned saturating multiplication of two constant ranges.
467   ConstantRange umul_sat(const ConstantRange &Other) const;
468 
469   /// Perform a signed saturating multiplication of two constant ranges.
470   ConstantRange smul_sat(const ConstantRange &Other) const;
471 
472   /// Perform an unsigned saturating left shift of this constant range by a
473   /// value in \p Other.
474   ConstantRange ushl_sat(const ConstantRange &Other) const;
475 
476   /// Perform a signed saturating left shift of this constant range by a
477   /// value in \p Other.
478   ConstantRange sshl_sat(const ConstantRange &Other) const;
479 
480   /// Return a new range that is the logical not of the current set.
481   ConstantRange inverse() const;
482 
483   /// Calculate absolute value range. If the original range contains signed
484   /// min, then the resulting range will contain signed min if and only if
485   /// \p IntMinIsPoison is false.
486   ConstantRange abs(bool IntMinIsPoison = false) const;
487 
488   /// Represents whether an operation on the given constant range is known to
489   /// always or never overflow.
490   enum class OverflowResult {
491     /// Always overflows in the direction of signed/unsigned min value.
492     AlwaysOverflowsLow,
493     /// Always overflows in the direction of signed/unsigned max value.
494     AlwaysOverflowsHigh,
495     /// May or may not overflow.
496     MayOverflow,
497     /// Never overflows.
498     NeverOverflows,
499   };
500 
501   /// Return whether unsigned add of the two ranges always/never overflows.
502   OverflowResult unsignedAddMayOverflow(const ConstantRange &Other) const;
503 
504   /// Return whether signed add of the two ranges always/never overflows.
505   OverflowResult signedAddMayOverflow(const ConstantRange &Other) const;
506 
507   /// Return whether unsigned sub of the two ranges always/never overflows.
508   OverflowResult unsignedSubMayOverflow(const ConstantRange &Other) const;
509 
510   /// Return whether signed sub of the two ranges always/never overflows.
511   OverflowResult signedSubMayOverflow(const ConstantRange &Other) const;
512 
513   /// Return whether unsigned mul of the two ranges always/never overflows.
514   OverflowResult unsignedMulMayOverflow(const ConstantRange &Other) const;
515 
516   /// Print out the bounds to a stream.
517   void print(raw_ostream &OS) const;
518 
519   /// Allow printing from a debugger easily.
520   void dump() const;
521 };
522 
523 inline raw_ostream &operator<<(raw_ostream &OS, const ConstantRange &CR) {
524   CR.print(OS);
525   return OS;
526 }
527 
528 /// Parse out a conservative ConstantRange from !range metadata.
529 ///
530 /// E.g. if RangeMD is !{i32 0, i32 10, i32 15, i32 20} then return [0, 20).
531 ConstantRange getConstantRangeFromMetadata(const MDNode &RangeMD);
532 
533 } // end namespace llvm
534 
535 #endif // LLVM_IR_CONSTANTRANGE_H
536