1 //===--- TargetCXXABI.h - C++ ABI Target Configuration ----------*- C++ -*-===//
3 // The LLVM Compiler Infrastructure
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
8 //===----------------------------------------------------------------------===//
11 /// \brief Defines the TargetCXXABI class, which abstracts details of the
12 /// C++ ABI that we're targeting.
14 //===----------------------------------------------------------------------===//
16 #ifndef LLVM_CLANG_BASIC_TARGETCXXABI_H
17 #define LLVM_CLANG_BASIC_TARGETCXXABI_H
19 #include "llvm/ADT/Triple.h"
20 #include "llvm/Support/ErrorHandling.h"
24 /// \brief The basic abstraction for the target C++ ABI.
27 /// \brief The basic C++ ABI 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.
33 /// It is documented here:
34 /// http://www.codesourcery.com/public/cxx-abi/
37 /// The generic ARM ABI is a modified version of the Itanium ABI
38 /// proposed by ARM for use on ARM-based platforms.
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;
50 /// It is documented here:
51 /// http://infocenter.arm.com
52 /// /help/topic/com.arm.doc.ihi0041c/IHI0041C_cppabi.pdf
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.
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.
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.
69 /// It is documented here:
70 /// http://infocenter.arm.com
71 /// /help/topic/com.arm.doc.ihi0059a/IHI0059A_cppabi64.pdf
74 /// The generic AArch64 ABI is also a modified version of the Itanium ABI,
75 /// but it has fewer divergences than the 32-bit ARM ABI.
77 /// The relevant changes from the generic ABI in this case are:
78 /// - representation of member function pointers adjusted as in ARM.
79 /// - guard variables are smaller.
82 /// The Microsoft ABI is the ABI used by Microsoft Visual Studio (and
83 /// compatible compilers).
85 /// FIXME: should this be split into Win32 and Win64 variants?
87 /// Only scattered and incomplete official documentation exists.
92 // Right now, this class is passed around as a cheap value type.
93 // If you add more members, especially non-POD members, please
94 // audit the users to pass it by reference instead.
98 /// A bogus initialization of the platform ABI.
99 TargetCXXABI() : TheKind(GenericItanium) {}
101 TargetCXXABI(Kind kind) : TheKind(kind) {}
103 void set(Kind kind) {
107 Kind getKind() const { return TheKind; }
109 /// \brief Does this ABI generally fall into the Itanium family of ABIs?
110 bool isItaniumFamily() const {
122 llvm_unreachable("bad ABI kind");
125 /// \brief Is this ABI an MSVC-compatible ABI?
126 bool isMicrosoft() const {
138 llvm_unreachable("bad ABI kind");
141 /// \brief Is the default C++ member function calling convention
142 /// the same as the default calling convention?
143 bool isMemberFunctionCCDefault() const {
144 // Right now, this is always false for Microsoft.
145 return !isMicrosoft();
148 /// Are arguments to a call destroyed left to right in the callee?
149 /// This is a fundamental language change, since it implies that objects
150 /// passed by value do *not* live to the end of the full expression.
151 /// Temporaries passed to a function taking a const reference live to the end
152 /// of the full expression as usual. Both the caller and the callee must
153 /// have access to the destructor, while only the caller needs the
154 /// destructor if this is false.
155 bool areArgsDestroyedLeftToRightInCallee() const {
156 return isMicrosoft();
159 /// \brief Does this ABI have different entrypoints for complete-object
160 /// and base-subobject constructors?
161 bool hasConstructorVariants() const {
162 return isItaniumFamily();
165 /// \brief Does this ABI allow virtual bases to be primary base classes?
166 bool hasPrimaryVBases() const {
167 return isItaniumFamily();
170 /// \brief Does this ABI use key functions? If so, class data such as the
171 /// vtable is emitted with strong linkage by the TU containing the key
173 bool hasKeyFunctions() const {
174 return isItaniumFamily();
177 /// \brief Can an out-of-line inline function serve as a key function?
179 /// This flag is only useful in ABIs where type data (for example,
180 /// v-tables and type_info objects) are emitted only after processing
181 /// the definition of a special "key" virtual function. (This is safe
182 /// because the ODR requires that every virtual function be defined
183 /// somewhere in a program.) This usually permits such data to be
184 /// emitted in only a single object file, as opposed to redundantly
185 /// in every object file that requires it.
187 /// One simple and common definition of "key function" is the first
188 /// virtual function in the class definition which is not defined there.
189 /// This rule works very well when that function has a non-inline
190 /// definition in some non-header file. Unfortunately, when that
191 /// function is defined inline, this rule requires the type data
192 /// to be emitted weakly, as if there were no key function.
194 /// The ARM ABI observes that the ODR provides an additional guarantee:
195 /// a virtual function is always ODR-used, so if it is defined inline,
196 /// that definition must appear in every translation unit that defines
197 /// the class. Therefore, there is no reason to allow such functions
198 /// to serve as key functions.
200 /// Because this changes the rules for emitting type data,
201 /// it can cause type data to be emitted with both weak and strong
202 /// linkage, which is not allowed on all platforms. Therefore,
203 /// exploiting this observation requires an ABI break and cannot be
204 /// done on a generic Itanium platform.
205 bool canKeyFunctionBeInline() const {
213 case iOS: // old iOS compilers did not follow this rule
217 llvm_unreachable("bad ABI kind");
220 /// When is record layout allowed to allocate objects in the tail
221 /// padding of a base class?
223 /// This decision cannot be changed without breaking platform ABI
224 /// compatibility, and yet it is tied to language guarantees which
225 /// the committee has so far seen fit to strengthen no less than
226 /// three separate times:
227 /// - originally, there were no restrictions at all;
228 /// - C++98 declared that objects could not be allocated in the
229 /// tail padding of a POD type;
230 /// - C++03 extended the definition of POD to include classes
231 /// containing member pointers; and
232 /// - C++11 greatly broadened the definition of POD to include
233 /// all trivial standard-layout classes.
234 /// Each of these changes technically took several existing
235 /// platforms and made them permanently non-conformant.
236 enum TailPaddingUseRules {
237 /// The tail-padding of a base class is always theoretically
238 /// available, even if it's POD. This is not strictly conforming
239 /// in any language mode.
240 AlwaysUseTailPadding,
242 /// Only allocate objects in the tail padding of a base class if
243 /// the base class is not POD according to the rules of C++ TR1.
244 /// This is non-strictly conforming in C++11 mode.
245 UseTailPaddingUnlessPOD03,
247 /// Only allocate objects in the tail padding of a base class if
248 /// the base class is not POD according to the rules of C++11.
249 UseTailPaddingUnlessPOD11
251 TailPaddingUseRules getTailPaddingUseRules() const {
253 // To preserve binary compatibility, the generic Itanium ABI has
254 // permanently locked the definition of POD to the rules of C++ TR1,
255 // and that trickles down to all the derived ABIs.
260 return UseTailPaddingUnlessPOD03;
262 // iOS on ARM64 uses the C++11 POD rules. It does not honor the
263 // Itanium exception about classes with over-large bitfields.
265 return UseTailPaddingUnlessPOD11;
267 // MSVC always allocates fields in the tail-padding of a base class
268 // subobject, even if they're POD.
270 return AlwaysUseTailPadding;
272 llvm_unreachable("bad ABI kind");
275 /// Try to parse an ABI name, returning false on error.
276 bool tryParse(llvm::StringRef name);
278 friend bool operator==(const TargetCXXABI &left, const TargetCXXABI &right) {
279 return left.getKind() == right.getKind();
282 friend bool operator!=(const TargetCXXABI &left, const TargetCXXABI &right) {
283 return !(left == right);
287 } // end namespace clang