TargetCXXABI.h revision f3014761c955345d6e05491608e73228d014afb7
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 21namespace clang { 22 23/// \brief The basic abstraction for the target C++ ABI. 24class TargetCXXABI { 25public: 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 116private: 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 122public: 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 354