clang  6.0.0svn
TargetCXXABI.h
Go to the documentation of this file.
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/
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
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
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.
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.
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.
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.
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.
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.
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?
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.
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.
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.
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.
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.
314  };
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:
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:
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
The generic AArch64 ABI is also a modified version of the Itanium ABI, but it has fewer divergences t...
Definition: TargetCXXABI.h:84
Only allocate objects in the tail padding of a base class if the base class is not POD according to t...
Definition: TargetCXXABI.h:309
The iOS 64-bit ABI is follows ARM's published 64-bit ABI more closely, but we don't guarantee to foll...
Definition: TargetCXXABI.h:71
The basic abstraction for the target C++ ABI.
Definition: TargetCXXABI.h:24
Kind getKind() const
Definition: TargetCXXABI.h:132
The generic Mips ABI is a modified version of the Itanium ABI.
Definition: TargetCXXABI.h:90
bool canKeyFunctionBeInline() const
Can an out-of-line inline function serve as a key function?
Definition: TargetCXXABI.h:266
bool isItaniumFamily() const
Does this ABI generally fall into the Itanium family of ABIs?
Definition: TargetCXXABI.h:135
The Microsoft ABI is the ABI used by Microsoft Visual Studio (and compatible compilers).
Definition: TargetCXXABI.h:113
bool hasConstructorVariants() const
Does this ABI have different entrypoints for complete-object and base-subobject constructors?
Definition: TargetCXXABI.h:222
The iOS ABI is a partial implementation of the ARM ABI.
Definition: TargetCXXABI.h:63
friend bool operator!=(const TargetCXXABI &left, const TargetCXXABI &right)
Definition: TargetCXXABI.h:346
friend bool operator==(const TargetCXXABI &left, const TargetCXXABI &right)
Definition: TargetCXXABI.h:342
The generic ARM ABI is a modified version of the Itanium ABI proposed by ARM for use on ARM-based pla...
Definition: TargetCXXABI.h:52
bool isMemberFunctionCCDefault() const
Is the default C++ member function calling convention the same as the default calling convention...
Definition: TargetCXXABI.h:204
bool hasKeyFunctions() const
Does this ABI use key functions? If so, class data such as the vtable is emitted with strong linkage ...
Definition: TargetCXXABI.h:234
TargetCXXABI(Kind kind)
Definition: TargetCXXABI.h:126
TargetCXXABI()
A bogus initialization of the platform ABI.
Definition: TargetCXXABI.h:124
bool hasPrimaryVBases() const
Does this ABI allow virtual bases to be primary base classes?
Definition: TargetCXXABI.h:227
WatchOS is a modernisation of the iOS ABI, which roughly means it's the iOS64 ABI ported to 32-bits...
Definition: TargetCXXABI.h:76
Only allocate objects in the tail padding of a base class if the base class is not POD according to t...
Definition: TargetCXXABI.h:313
bool areMemberFunctionsAligned() const
Are member functions differently aligned?
Definition: TargetCXXABI.h:181
The generic Itanium ABI is the standard ABI of most open-source and Unix-like platforms.
Definition: TargetCXXABI.h:34
The WebAssembly ABI is a modified version of the Itanium ABI.
Definition: TargetCXXABI.h:105
Dataflow Directional Tag Classes.
Kind
The basic C++ ABI kind.
Definition: TargetCXXABI.h:27
TailPaddingUseRules getTailPaddingUseRules() const
Definition: TargetCXXABI.h:315
bool areArgsDestroyedLeftToRightInCallee() const
Are arguments to a call destroyed left to right in the callee? This is a fundamental language change...
Definition: TargetCXXABI.h:216
TailPaddingUseRules
When is record layout allowed to allocate objects in the tail padding of a base class?
Definition: TargetCXXABI.h:300
unsigned kind
All of the diagnostics that can be emitted by the frontend.
Definition: DiagnosticIDs.h:61
The tail-padding of a base class is always theoretically available, even if it's POD.
Definition: TargetCXXABI.h:304
bool isMicrosoft() const
Is this ABI an MSVC-compatible ABI?
Definition: TargetCXXABI.h:154