contrib/llvm-project/clang/include/clang/Basic/FixedPoint.h

   1 //===- FixedPoint.h - Fixed point constant handling -------------*- 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 /// \file
  10 /// Defines the fixed point number interface.
  11 /// This is a class for abstracting various operations performed on fixed point
  12 /// types described in ISO/IEC JTC1 SC22 WG14 N1169 starting at clause 4.
  13 //
  14 //===----------------------------------------------------------------------===//
  15
  16 #ifndef LLVM_CLANG_BASIC_FIXEDPOINT_H
  17 #define LLVM_CLANG_BASIC_FIXEDPOINT_H
  18
  19 #include "llvm/ADT/APSInt.h"
  20 #include "llvm/ADT/SmallString.h"
  21 #include "llvm/Support/raw_ostream.h"
  22
  23 namespace clang {
  24
  25 class ASTContext;
  26 class QualType;
  27
  28 /// The fixed point semantics work similarly to llvm::fltSemantics. The width
  29 /// specifies the whole bit width of the underlying scaled integer (with padding
  30 /// if any). The scale represents the number of fractional bits in this type.
  31 /// When HasUnsignedPadding is true and this type is unsigned, the first bit
  32 /// in the value this represents is treated as padding.
  33 class FixedPointSemantics {
  34 public:
  35   FixedPointSemantics(unsigned Width, unsigned Scale, bool IsSigned,
  36                       bool IsSaturated, bool HasUnsignedPadding)
  37       : Width(Width), Scale(Scale), IsSigned(IsSigned),
  38         IsSaturated(IsSaturated), HasUnsignedPadding(HasUnsignedPadding) {
  39     assert(Width >= Scale && "Not enough room for the scale");
  40     assert(!(IsSigned && HasUnsignedPadding) &&
  41            "Cannot have unsigned padding on a signed type.");
  42   }
  43
  44   unsigned getWidth() const { return Width; }
  45   unsigned getScale() const { return Scale; }
  46   bool isSigned() const { return IsSigned; }
  47   bool isSaturated() const { return IsSaturated; }
  48   bool hasUnsignedPadding() const { return HasUnsignedPadding; }
  49
  50   void setSaturated(bool Saturated) { IsSaturated = Saturated; }
  51
  52   /// Return the number of integral bits represented by these semantics. These
  53   /// are separate from the fractional bits and do not include the sign or
  54   /// padding bit.
  55   unsigned getIntegralBits() const {
  56     if (IsSigned || (!IsSigned && HasUnsignedPadding))
  57       return Width - Scale - 1;
  58     else
  59       return Width - Scale;
  60   }
  61
  62   /// Return the FixedPointSemantics that allows for calculating the full
  63   /// precision semantic that can precisely represent the precision and ranges
  64   /// of both input values. This does not compute the resulting semantics for a
  65   /// given binary operation.
  66   FixedPointSemantics
  67   getCommonSemantics(const FixedPointSemantics &Other) const;
  68
  69   /// Return the FixedPointSemantics for an integer type.
  70   static FixedPointSemantics GetIntegerSemantics(unsigned Width,
  71                                                  bool IsSigned) {
  72     return FixedPointSemantics(Width, /*Scale=*/0, IsSigned,
  73                                /*IsSaturated=*/false,
  74                                /*HasUnsignedPadding=*/false);
  75   }
  76
  77 private:
  78   unsigned Width          : 16;
  79   unsigned Scale          : 13;
  80   unsigned IsSigned       : 1;
  81   unsigned IsSaturated    : 1;
  82   unsigned HasUnsignedPadding : 1;
  83 };
  84
  85 /// The APFixedPoint class works similarly to APInt/APSInt in that it is a
  86 /// functional replacement for a scaled integer. It is meant to replicate the
  87 /// fixed point types proposed in ISO/IEC JTC1 SC22 WG14 N1169. The class carries
  88 /// info about the fixed point type's width, sign, scale, and saturation, and
  89 /// provides different operations that would normally be performed on fixed point
  90 /// types.
  91 ///
  92 /// Semantically this does not represent any existing C type other than fixed
  93 /// point types and should eventually be moved to LLVM if fixed point types gain
  94 /// native IR support.
  95 class APFixedPoint {
  96 public:
  97   APFixedPoint(const llvm::APInt &Val, const FixedPointSemantics &Sema)
  98       : Val(Val, !Sema.isSigned()), Sema(Sema) {
  99     assert(Val.getBitWidth() == Sema.getWidth() &&
 100            "The value should have a bit width that matches the Sema width");
 101   }
 102
 103   APFixedPoint(uint64_t Val, const FixedPointSemantics &Sema)
 104       : APFixedPoint(llvm::APInt(Sema.getWidth(), Val, Sema.isSigned()),
 105                      Sema) {}
 106
 107   // Zero initialization.
 108   APFixedPoint(const FixedPointSemantics &Sema) : APFixedPoint(0, Sema) {}
 109
 110   llvm::APSInt getValue() const { return llvm::APSInt(Val, !Sema.isSigned()); }
 111   inline unsigned getWidth() const { return Sema.getWidth(); }
 112   inline unsigned getScale() const { return Sema.getScale(); }
 113   inline bool isSaturated() const { return Sema.isSaturated(); }
 114   inline bool isSigned() const { return Sema.isSigned(); }
 115   inline bool hasPadding() const { return Sema.hasUnsignedPadding(); }
 116   FixedPointSemantics getSemantics() const { return Sema; }
 117
 118   bool getBoolValue() const { return Val.getBoolValue(); }
 119
 120   // Convert this number to match the semantics provided. If the overflow
 121   // parameter is provided, set this value to true or false to indicate if this
 122   // operation results in an overflow.
 123   APFixedPoint convert(const FixedPointSemantics &DstSema,
 124                        bool *Overflow = nullptr) const;
 125
 126   // Perform binary operations on a fixed point type. The resulting fixed point
 127   // value will be in the common, full precision semantics that can represent
 128   // the precision and ranges of both input values. See convert() for an
 129   // explanation of the Overflow parameter.
 130   APFixedPoint add(const APFixedPoint &Other, bool *Overflow = nullptr) const;
 131   APFixedPoint sub(const APFixedPoint &Other, bool *Overflow = nullptr) const;
 132   APFixedPoint mul(const APFixedPoint &Other, bool *Overflow = nullptr) const;
 133   APFixedPoint div(const APFixedPoint &Other, bool *Overflow = nullptr) const;
 134
 135   /// Perform a unary negation (-X) on this fixed point type, taking into
 136   /// account saturation if applicable.
 137   APFixedPoint negate(bool *Overflow = nullptr) const;
 138
 139   APFixedPoint shr(unsigned Amt) const {
 140     return APFixedPoint(Val >> Amt, Sema);
 141   }
 142
 143   APFixedPoint shl(unsigned Amt) const {
 144     return APFixedPoint(Val << Amt, Sema);
 145   }
 146
 147   /// Return the integral part of this fixed point number, rounded towards
 148   /// zero. (-2.5k -> -2)
 149   llvm::APSInt getIntPart() const {
 150     if (Val < 0 && Val != -Val) // Cover the case when we have the min val
 151       return -(-Val >> getScale());
 152     else
 153       return Val >> getScale();
 154   }
 155
 156   /// Return the integral part of this fixed point number, rounded towards
 157   /// zero. The value is stored into an APSInt with the provided width and sign.
 158   /// If the overflow parameter is provided, and the integral value is not able
 159   /// to be fully stored in the provided width and sign, the overflow parameter
 160   /// is set to true.
 161   ///
 162   /// If the overflow parameter is provided, set this value to true or false to
 163   /// indicate if this operation results in an overflow.
 164   llvm::APSInt convertToInt(unsigned DstWidth, bool DstSign,
 165                             bool *Overflow = nullptr) const;
 166
 167   void toString(llvm::SmallVectorImpl<char> &Str) const;
 168   std::string toString() const {
 169     llvm::SmallString<40> S;
 170     toString(S);
 171     return std::string(S.str());
 172   }
 173
 174   // If LHS > RHS, return 1. If LHS == RHS, return 0. If LHS < RHS, return -1.
 175   int compare(const APFixedPoint &Other) const;
 176   bool operator==(const APFixedPoint &Other) const {
 177     return compare(Other) == 0;
 178   }
 179   bool operator!=(const APFixedPoint &Other) const {
 180     return compare(Other) != 0;
 181   }
 182   bool operator>(const APFixedPoint &Other) const { return compare(Other) > 0; }
 183   bool operator<(const APFixedPoint &Other) const { return compare(Other) < 0; }
 184   bool operator>=(const APFixedPoint &Other) const {
 185     return compare(Other) >= 0;
 186   }
 187   bool operator<=(const APFixedPoint &Other) const {
 188     return compare(Other) <= 0;
 189   }
 190
 191   static APFixedPoint getMax(const FixedPointSemantics &Sema);
 192   static APFixedPoint getMin(const FixedPointSemantics &Sema);
 193
 194   /// Create an APFixedPoint with a value equal to that of the provided integer,
 195   /// and in the same semantics as the provided target semantics. If the value
 196   /// is not able to fit in the specified fixed point semantics, and the
 197   /// overflow parameter is provided, it is set to true.
 198   static APFixedPoint getFromIntValue(const llvm::APSInt &Value,
 199                                       const FixedPointSemantics &DstFXSema,
 200                                       bool *Overflow = nullptr);
 201
 202 private:
 203   llvm::APSInt Val;
 204   FixedPointSemantics Sema;
 205 };
 206
 207 inline llvm::raw_ostream &operator<<(llvm::raw_ostream &OS,
 208                                      const APFixedPoint &FX) {
 209   OS << FX.toString();
 210   return OS;
 211 }
 212
 213 }  // namespace clang
 214
 215 #endif