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