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 /// 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 /// The basic abstraction for the target C++ ABI. 24 class TargetCXXABI { 25 public: 26 /// 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. TargetCXXABI()124 TargetCXXABI() : TheKind(GenericItanium) {} 125 TargetCXXABI(Kind kind)126 TargetCXXABI(Kind kind) : TheKind(kind) {} 127 set(Kind kind)128 void set(Kind kind) { 129 TheKind = kind; 130 } 131 getKind()132 Kind getKind() const { return TheKind; } 133 134 /// Does this ABI generally fall into the Itanium family of ABIs? isItaniumFamily()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 /// Is this ABI an MSVC-compatible ABI? isMicrosoft()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 /// 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. areMemberFunctionsAligned()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 /// Are arguments to a call destroyed left to right in the callee? 203 /// This is a fundamental language change, since it implies that objects 204 /// passed by value do *not* live to the end of the full expression. 205 /// Temporaries passed to a function taking a const reference live to the end 206 /// of the full expression as usual. Both the caller and the callee must 207 /// have access to the destructor, while only the caller needs the 208 /// destructor if this is false. areArgsDestroyedLeftToRightInCallee()209 bool areArgsDestroyedLeftToRightInCallee() const { 210 return isMicrosoft(); 211 } 212 213 /// Does this ABI have different entrypoints for complete-object 214 /// and base-subobject constructors? hasConstructorVariants()215 bool hasConstructorVariants() const { 216 return isItaniumFamily(); 217 } 218 219 /// Does this ABI allow virtual bases to be primary base classes? hasPrimaryVBases()220 bool hasPrimaryVBases() const { 221 return isItaniumFamily(); 222 } 223 224 /// Does this ABI use key functions? If so, class data such as the 225 /// vtable is emitted with strong linkage by the TU containing the key 226 /// function. hasKeyFunctions()227 bool hasKeyFunctions() const { 228 return isItaniumFamily(); 229 } 230 231 /// Can an out-of-line inline function serve as a key function? 232 /// 233 /// This flag is only useful in ABIs where type data (for example, 234 /// vtables and type_info objects) are emitted only after processing 235 /// the definition of a special "key" virtual function. (This is safe 236 /// because the ODR requires that every virtual function be defined 237 /// somewhere in a program.) This usually permits such data to be 238 /// emitted in only a single object file, as opposed to redundantly 239 /// in every object file that requires it. 240 /// 241 /// One simple and common definition of "key function" is the first 242 /// virtual function in the class definition which is not defined there. 243 /// This rule works very well when that function has a non-inline 244 /// definition in some non-header file. Unfortunately, when that 245 /// function is defined inline, this rule requires the type data 246 /// to be emitted weakly, as if there were no key function. 247 /// 248 /// The ARM ABI observes that the ODR provides an additional guarantee: 249 /// a virtual function is always ODR-used, so if it is defined inline, 250 /// that definition must appear in every translation unit that defines 251 /// the class. Therefore, there is no reason to allow such functions 252 /// to serve as key functions. 253 /// 254 /// Because this changes the rules for emitting type data, 255 /// it can cause type data to be emitted with both weak and strong 256 /// linkage, which is not allowed on all platforms. Therefore, 257 /// exploiting this observation requires an ABI break and cannot be 258 /// done on a generic Itanium platform. canKeyFunctionBeInline()259 bool canKeyFunctionBeInline() const { 260 switch (getKind()) { 261 case GenericARM: 262 case iOS64: 263 case WebAssembly: 264 case WatchOS: 265 return false; 266 267 case GenericAArch64: 268 case GenericItanium: 269 case iOS: // old iOS compilers did not follow this rule 270 case Microsoft: 271 case GenericMIPS: 272 return true; 273 } 274 llvm_unreachable("bad ABI kind"); 275 } 276 277 /// When is record layout allowed to allocate objects in the tail 278 /// padding of a base class? 279 /// 280 /// This decision cannot be changed without breaking platform ABI 281 /// compatibility, and yet it is tied to language guarantees which 282 /// the committee has so far seen fit to strengthen no less than 283 /// three separate times: 284 /// - originally, there were no restrictions at all; 285 /// - C++98 declared that objects could not be allocated in the 286 /// tail padding of a POD type; 287 /// - C++03 extended the definition of POD to include classes 288 /// containing member pointers; and 289 /// - C++11 greatly broadened the definition of POD to include 290 /// all trivial standard-layout classes. 291 /// Each of these changes technically took several existing 292 /// platforms and made them permanently non-conformant. 293 enum TailPaddingUseRules { 294 /// The tail-padding of a base class is always theoretically 295 /// available, even if it's POD. This is not strictly conforming 296 /// in any language mode. 297 AlwaysUseTailPadding, 298 299 /// Only allocate objects in the tail padding of a base class if 300 /// the base class is not POD according to the rules of C++ TR1. 301 /// This is non-strictly conforming in C++11 mode. 302 UseTailPaddingUnlessPOD03, 303 304 /// Only allocate objects in the tail padding of a base class if 305 /// the base class is not POD according to the rules of C++11. 306 UseTailPaddingUnlessPOD11 307 }; getTailPaddingUseRules()308 TailPaddingUseRules getTailPaddingUseRules() const { 309 switch (getKind()) { 310 // To preserve binary compatibility, the generic Itanium ABI has 311 // permanently locked the definition of POD to the rules of C++ TR1, 312 // and that trickles down to derived ABIs. 313 case GenericItanium: 314 case GenericAArch64: 315 case GenericARM: 316 case iOS: 317 case GenericMIPS: 318 return UseTailPaddingUnlessPOD03; 319 320 // iOS on ARM64 and WebAssembly use the C++11 POD rules. They do not honor 321 // the Itanium exception about classes with over-large bitfields. 322 case iOS64: 323 case WebAssembly: 324 case WatchOS: 325 return UseTailPaddingUnlessPOD11; 326 327 // MSVC always allocates fields in the tail-padding of a base class 328 // subobject, even if they're POD. 329 case Microsoft: 330 return AlwaysUseTailPadding; 331 } 332 llvm_unreachable("bad ABI kind"); 333 } 334 335 friend bool operator==(const TargetCXXABI &left, const TargetCXXABI &right) { 336 return left.getKind() == right.getKind(); 337 } 338 339 friend bool operator!=(const TargetCXXABI &left, const TargetCXXABI &right) { 340 return !(left == right); 341 } 342 }; 343 344 } // end namespace clang 345 346 #endif 347