contrib/llvm/tools/clang/include/clang/Basic/TargetCXXABI.h

   1 //===--- TargetCXXABI.h - C++ ABI Target Configuration ----------*- C++ -*-===//
   2 //
   3 //                     The LLVM Compiler Infrastructure
   4 //
   5 // This file is distributed under the University of Illinois Open Source
   6 // License. See LICENSE.TXT for details.
   7 //
   8 //===----------------------------------------------------------------------===//
   9 ///
  10 /// \file
  11 /// \brief Defines the TargetCXXABI class, which abstracts details of the
  12 /// C++ ABI that we're targeting.
  13 ///
  14 //===----------------------------------------------------------------------===//
  15
  16 #ifndef LLVM_CLANG_BASIC_TARGETCXXABI_H
  17 #define LLVM_CLANG_BASIC_TARGETCXXABI_H
  18
  19 #include "llvm/Support/ErrorHandling.h"
  20
  21 namespace clang {
  22
  23 /// \brief The basic abstraction for the target C++ ABI.
  24 class TargetCXXABI {
  25 public:
  26   /// \brief The basic C++ ABI kind.
  27   enum Kind {
  28     /// The generic Itanium ABI is the standard ABI of most open-source
  29     /// and Unix-like platforms.  It is the primary ABI targeted by
  30     /// many compilers, including Clang and GCC.
  31     ///
  32     /// It is documented here:
  33     ///   http://www.codesourcery.com/public/cxx-abi/
  34     GenericItanium,
  35
  36     /// The generic ARM ABI is a modified version of the Itanium ABI
  37     /// proposed by ARM for use on ARM-based platforms.
  38     ///
  39     /// These changes include:
  40     ///   - the representation of member function pointers is adjusted
  41     ///     to not conflict with the 'thumb' bit of ARM function pointers;
  42     ///   - constructors and destructors return 'this';
  43     ///   - guard variables are smaller;
  44     ///   - inline functions are never key functions;
  45     ///   - array cookies have a slightly different layout;
  46     ///   - additional convenience functions are specified;
  47     ///   - and more!
  48     ///
  49     /// It is documented here:
  50     ///    http://infocenter.arm.com
  51     ///                    /help/topic/com.arm.doc.ihi0041c/IHI0041C_cppabi.pdf
  52     GenericARM,
  53
  54     /// The iOS ABI is a partial implementation of the ARM ABI.
  55     /// Several of the features of the ARM ABI were not fully implemented
  56     /// in the compilers that iOS was launched with.
  57     ///
  58     /// Essentially, the iOS ABI includes the ARM changes to:
  59     ///   - member function pointers,
  60     ///   - guard variables,
  61     ///   - array cookies, and
  62     ///   - constructor/destructor signatures.
  63     iOS,
  64
  65     /// The iOS 64-bit ABI is follows ARM's published 64-bit ABI more
  66     /// closely, but we don't guarantee to follow it perfectly.
  67     ///
  68     /// It is documented here:
  69     ///    http://infocenter.arm.com
  70     ///                  /help/topic/com.arm.doc.ihi0059a/IHI0059A_cppabi64.pdf
  71     iOS64,
  72
  73     /// WatchOS is a modernisation of the iOS ABI, which roughly means it's
  74     /// the iOS64 ABI ported to 32-bits. The primary difference from iOS64 is
  75     /// that RTTI objects must still be unique at the moment.
  76     WatchOS,
  77
  78     /// The generic AArch64 ABI is also a modified version of the Itanium ABI,
  79     /// but it has fewer divergences than the 32-bit ARM ABI.
  80     ///
  81     /// The relevant changes from the generic ABI in this case are:
  82     ///   - representation of member function pointers adjusted as in ARM.
  83     ///   - guard variables  are smaller.
  84     GenericAArch64,
  85
  86     /// The generic Mips ABI is a modified version of the Itanium ABI.
  87     ///
  88     /// At the moment, only change from the generic ABI in this case is:
  89     ///   - representation of member function pointers adjusted as in ARM.
  90     GenericMIPS,
  91
  92     /// The WebAssembly ABI is a modified version of the Itanium ABI.
  93     ///
  94     /// The changes from the Itanium ABI are:
  95     ///   - representation of member function pointers is adjusted, as in ARM;
  96     ///   - member functions are not specially aligned;
  97     ///   - constructors and destructors return 'this', as in ARM;
  98     ///   - guard variables are 32-bit on wasm32, as in ARM;
  99     ///   - unused bits of guard variables are reserved, as in ARM;
 100     ///   - inline functions are never key functions, as in ARM;
 101     ///   - C++11 POD rules are used for tail padding, as in iOS64.
 102     ///
 103     /// TODO: At present the WebAssembly ABI is not considered stable, so none
 104     /// of these details is necessarily final yet.
 105     WebAssembly,
 106
 107     /// The Microsoft ABI is the ABI used by Microsoft Visual Studio (and
 108     /// compatible compilers).
 109     ///
 110     /// FIXME: should this be split into Win32 and Win64 variants?
 111     ///
 112     /// Only scattered and incomplete official documentation exists.
 113     Microsoft
 114   };
 115
 116 private:
 117   // Right now, this class is passed around as a cheap value type.
 118   // If you add more members, especially non-POD members, please
 119   // audit the users to pass it by reference instead.
 120   Kind TheKind;
 121
 122 public:
 123   /// A bogus initialization of the platform ABI.
 124   TargetCXXABI() : TheKind(GenericItanium) {}
 125
 126   TargetCXXABI(Kind kind) : TheKind(kind) {}
 127
 128   void set(Kind kind) {
 129     TheKind = kind;
 130   }
 131
 132   Kind getKind() const { return TheKind; }
 133
 134   /// \brief Does this ABI generally fall into the Itanium family of ABIs?
 135   bool isItaniumFamily() const {
 136     switch (getKind()) {
 137     case GenericAArch64:
 138     case GenericItanium:
 139     case GenericARM:
 140     case iOS:
 141     case iOS64:
 142     case WatchOS:
 143     case GenericMIPS:
 144     case WebAssembly:
 145       return true;
 146
 147     case Microsoft:
 148       return false;
 149     }
 150     llvm_unreachable("bad ABI kind");
 151   }
 152
 153   /// \brief Is this ABI an MSVC-compatible ABI?
 154   bool isMicrosoft() const {
 155     switch (getKind()) {
 156     case GenericAArch64:
 157     case GenericItanium:
 158     case GenericARM:
 159     case iOS:
 160     case iOS64:
 161     case WatchOS:
 162     case GenericMIPS:
 163     case WebAssembly:
 164       return false;
 165
 166     case Microsoft:
 167       return true;
 168     }
 169     llvm_unreachable("bad ABI kind");
 170   }
 171
 172   /// \brief Are member functions differently aligned?
 173   ///
 174   /// Many Itanium-style C++ ABIs require member functions to be aligned, so
 175   /// that a pointer to such a function is guaranteed to have a zero in the
 176   /// least significant bit, so that pointers to member functions can use that
 177   /// bit to distinguish between virtual and non-virtual functions. However,
 178   /// some Itanium-style C++ ABIs differentiate between virtual and non-virtual
 179   /// functions via other means, and consequently don't require that member
 180   /// functions be aligned.
 181   bool areMemberFunctionsAligned() const {
 182     switch (getKind()) {
 183     case WebAssembly:
 184       // WebAssembly doesn't require any special alignment for member functions.
 185       return false;
 186     case GenericARM:
 187     case GenericAArch64:
 188     case GenericMIPS:
 189       // TODO: ARM-style pointers to member functions put the discriminator in
 190       //       the this adjustment, so they don't require functions to have any
 191       //       special alignment and could therefore also return false.
 192     case GenericItanium:
 193     case iOS:
 194     case iOS64:
 195     case WatchOS:
 196     case Microsoft:
 197       return true;
 198     }
 199     llvm_unreachable("bad ABI kind");
 200   }
 201
 202   /// \brief Is the default C++ member function calling convention
 203   /// the same as the default calling convention?
 204   bool isMemberFunctionCCDefault() const {
 205     // Right now, this is always false for Microsoft.
 206     return !isMicrosoft();
 207   }
 208
 209   /// Are arguments to a call destroyed left to right in the callee?
 210   /// This is a fundamental language change, since it implies that objects
 211   /// passed by value do *not* live to the end of the full expression.
 212   /// Temporaries passed to a function taking a const reference live to the end
 213   /// of the full expression as usual.  Both the caller and the callee must
 214   /// have access to the destructor, while only the caller needs the
 215   /// destructor if this is false.
 216   bool areArgsDestroyedLeftToRightInCallee() const {
 217     return isMicrosoft();
 218   }
 219
 220   /// \brief Does this ABI have different entrypoints for complete-object
 221   /// and base-subobject constructors?
 222   bool hasConstructorVariants() const {
 223     return isItaniumFamily();
 224   }
 225
 226   /// \brief Does this ABI allow virtual bases to be primary base classes?
 227   bool hasPrimaryVBases() const {
 228     return isItaniumFamily();
 229   }
 230
 231   /// \brief Does this ABI use key functions?  If so, class data such as the
 232   /// vtable is emitted with strong linkage by the TU containing the key
 233   /// function.
 234   bool hasKeyFunctions() const {
 235     return isItaniumFamily();
 236   }
 237
 238   /// \brief Can an out-of-line inline function serve as a key function?
 239   ///
 240   /// This flag is only useful in ABIs where type data (for example,
 241   /// vtables and type_info objects) are emitted only after processing
 242   /// the definition of a special "key" virtual function.  (This is safe
 243   /// because the ODR requires that every virtual function be defined
 244   /// somewhere in a program.)  This usually permits such data to be
 245   /// emitted in only a single object file, as opposed to redundantly
 246   /// in every object file that requires it.
 247   ///
 248   /// One simple and common definition of "key function" is the first
 249   /// virtual function in the class definition which is not defined there.
 250   /// This rule works very well when that function has a non-inline
 251   /// definition in some non-header file.  Unfortunately, when that
 252   /// function is defined inline, this rule requires the type data
 253   /// to be emitted weakly, as if there were no key function.
 254   ///
 255   /// The ARM ABI observes that the ODR provides an additional guarantee:
 256   /// a virtual function is always ODR-used, so if it is defined inline,
 257   /// that definition must appear in every translation unit that defines
 258   /// the class.  Therefore, there is no reason to allow such functions
 259   /// to serve as key functions.
 260   ///
 261   /// Because this changes the rules for emitting type data,
 262   /// it can cause type data to be emitted with both weak and strong
 263   /// linkage, which is not allowed on all platforms.  Therefore,
 264   /// exploiting this observation requires an ABI break and cannot be
 265   /// done on a generic Itanium platform.
 266   bool canKeyFunctionBeInline() const {
 267     switch (getKind()) {
 268     case GenericARM:
 269     case iOS64:
 270     case WebAssembly:
 271     case WatchOS:
 272       return false;
 273
 274     case GenericAArch64:
 275     case GenericItanium:
 276     case iOS:   // old iOS compilers did not follow this rule
 277     case Microsoft:
 278     case GenericMIPS:
 279       return true;
 280     }
 281     llvm_unreachable("bad ABI kind");
 282   }
 283
 284   /// When is record layout allowed to allocate objects in the tail
 285   /// padding of a base class?
 286   ///
 287   /// This decision cannot be changed without breaking platform ABI
 288   /// compatibility, and yet it is tied to language guarantees which
 289   /// the committee has so far seen fit to strengthen no less than
 290   /// three separate times:
 291   ///   - originally, there were no restrictions at all;
 292   ///   - C++98 declared that objects could not be allocated in the
 293   ///     tail padding of a POD type;
 294   ///   - C++03 extended the definition of POD to include classes
 295   ///     containing member pointers; and
 296   ///   - C++11 greatly broadened the definition of POD to include
 297   ///     all trivial standard-layout classes.
 298   /// Each of these changes technically took several existing
 299   /// platforms and made them permanently non-conformant.
 300   enum TailPaddingUseRules {
 301     /// The tail-padding of a base class is always theoretically
 302     /// available, even if it's POD.  This is not strictly conforming
 303     /// in any language mode.
 304     AlwaysUseTailPadding,
 305
 306     /// Only allocate objects in the tail padding of a base class if
 307     /// the base class is not POD according to the rules of C++ TR1.
 308     /// This is non-strictly conforming in C++11 mode.
 309     UseTailPaddingUnlessPOD03,
 310
 311     /// Only allocate objects in the tail padding of a base class if
 312     /// the base class is not POD according to the rules of C++11.
 313     UseTailPaddingUnlessPOD11
 314   };
 315   TailPaddingUseRules getTailPaddingUseRules() const {
 316     switch (getKind()) {
 317     // To preserve binary compatibility, the generic Itanium ABI has
 318     // permanently locked the definition of POD to the rules of C++ TR1,
 319     // and that trickles down to derived ABIs.
 320     case GenericItanium:
 321     case GenericAArch64:
 322     case GenericARM:
 323     case iOS:
 324     case GenericMIPS:
 325       return UseTailPaddingUnlessPOD03;
 326
 327     // iOS on ARM64 and WebAssembly use the C++11 POD rules.  They do not honor
 328     // the Itanium exception about classes with over-large bitfields.
 329     case iOS64:
 330     case WebAssembly:
 331     case WatchOS:
 332       return UseTailPaddingUnlessPOD11;
 333
 334     // MSVC always allocates fields in the tail-padding of a base class
 335     // subobject, even if they're POD.
 336     case Microsoft:
 337       return AlwaysUseTailPadding;
 338     }
 339     llvm_unreachable("bad ABI kind");
 340   }
 341
 342   friend bool operator==(const TargetCXXABI &left, const TargetCXXABI &right) {
 343     return left.getKind() == right.getKind();
 344   }
 345
 346   friend bool operator!=(const TargetCXXABI &left, const TargetCXXABI &right) {
 347     return !(left == right);
 348   }
 349 };
 350
 351 }  // end namespace clang
 352
 353 #endif