1/* Interface between GCC C++ FE and GDB
2
3   Copyright (C) 2014-2022 Free Software Foundation, Inc.
4
5   This file is part of GCC.
6
7   This program is free software; you can redistribute it and/or modify
8   it under the terms of the GNU General Public License as published by
9   the Free Software Foundation; either version 3 of the License, or
10   (at your option) any later version.
11
12   This program is distributed in the hope that it will be useful,
13   but WITHOUT ANY WARRANTY; without even the implied warranty of
14   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
15   GNU General Public License for more details.
16
17   You should have received a copy of the GNU General Public License
18   along with this program.  If not, see <http://www.gnu.org/licenses/>.  */
19
20#ifndef GCC_CP_INTERFACE_H
21#define GCC_CP_INTERFACE_H
22
23#include "gcc-interface.h"
24
25/* This header defines the interface to the GCC API.  It must be both
26   valid C and valid C++, because it is included by both programs.  */
27
28#ifdef __cplusplus
29extern "C" {
30#endif
31
32/* Forward declaration.  */
33
34struct gcc_cp_context;
35
36/*
37 * Definitions and declarations for the C++ front end.
38 */
39
40/* Defined versions of the C++ front-end API.  */
41
42enum gcc_cp_api_version
43{
44  GCC_CP_FE_VERSION_0 = 0
45};
46
47/* Qualifiers.  */
48
49enum gcc_cp_qualifiers
50{
51  GCC_CP_QUALIFIER_CONST = 1,
52  GCC_CP_QUALIFIER_VOLATILE = 2,
53  GCC_CP_QUALIFIER_RESTRICT = 4
54};
55
56/* Ref qualifiers.  */
57
58enum gcc_cp_ref_qualifiers {
59  GCC_CP_REF_QUAL_NONE = 0,
60  GCC_CP_REF_QUAL_LVALUE = 1,
61  GCC_CP_REF_QUAL_RVALUE = 2
62};
63
64/* Opaque typedef for unbound class templates.  They are used for
65   template arguments, and defaults for template template
66   parameters.  */
67
68typedef unsigned long long gcc_utempl;
69
70/* Opaque typedef for expressions.  They are used for template
71   arguments, defaults for non-type template parameters, and defaults
72   for function arguments.  */
73
74typedef unsigned long long gcc_expr;
75
76typedef enum
77  { GCC_CP_TPARG_VALUE, GCC_CP_TPARG_CLASS,
78    GCC_CP_TPARG_TEMPL, GCC_CP_TPARG_PACK }
79gcc_cp_template_arg_kind;
80
81typedef union
82{ gcc_expr value; gcc_type type; gcc_utempl templ; gcc_type pack; }
83gcc_cp_template_arg;
84
85/* An array of template arguments.  */
86
87struct gcc_cp_template_args
88{
89  /* Number of elements.  */
90
91  int n_elements;
92
93  /* kind[i] indicates what kind of template argument type[i] is.  */
94
95  char /* gcc_cp_template_arg_kind */ *kinds;
96
97  /* The template arguments.  */
98
99  gcc_cp_template_arg *elements;
100};
101
102/* An array of (default) function arguments.  */
103
104struct gcc_cp_function_args
105{
106  /* Number of elements.  */
107
108  int n_elements;
109
110  /* The (default) values for each argument.  */
111
112  gcc_expr *elements;
113};
114
115/* This enumerates the kinds of decls that GDB can create.  */
116
117enum gcc_cp_symbol_kind
118{
119  /* A function.  */
120
121  GCC_CP_SYMBOL_FUNCTION,
122
123  /* A variable.  */
124
125  GCC_CP_SYMBOL_VARIABLE,
126
127  /* A typedef, or an alias declaration (including template ones).  */
128
129  GCC_CP_SYMBOL_TYPEDEF,
130
131  /* A label.  */
132
133  GCC_CP_SYMBOL_LABEL,
134
135  /* A class, forward declared in build_decl (to be later defined in
136     start_class_definition), or, in a template parameter list scope,
137     a declaration of a template class, closing the parameter
138     list.  */
139
140  GCC_CP_SYMBOL_CLASS,
141
142  /* A union, forward declared in build_decl (to be later defined in
143     start_class_definition).  */
144
145  GCC_CP_SYMBOL_UNION,
146
147  /* An enumeration type being introduced with start_new_enum_type.  */
148
149  GCC_CP_SYMBOL_ENUM,
150
151  /* A nonstatic data member being introduced with new_field.  */
152
153  GCC_CP_SYMBOL_FIELD,
154
155  /* A base class in a gcc_vbase_array.  */
156
157  GCC_CP_SYMBOL_BASECLASS,
158
159  /* A using declaration in new_using_decl.  */
160
161  GCC_CP_SYMBOL_USING,
162
163  /* A (lambda) closure class type.  In many regards this is just like
164     a regular class, but it's not supposed to have base classes, some
165     of the member functions that are usually implicitly-defined are
166     deleted, and it should have an operator() member function that
167     holds the lambda body.  We can't instantiate objects of lambda
168     types from the snippet, but we can interact with them in such
169     ways as passing them to functions that take their types, and
170     calling their body.  */
171
172  GCC_CP_SYMBOL_LAMBDA_CLOSURE,
173
174  /* Marker to check that we haven't exceeded GCC_CP_SYMBOL_MASK.  */
175  GCC_CP_SYMBOL_END,
176
177  GCC_CP_SYMBOL_MASK = 15,
178
179  /* When defining a class member, at least one of the
180     GCC_CP_ACCESS_MASK bits must be set; when defining a namespace-
181     or union-scoped symbol, none of them must be set.  */
182
183  GCC_CP_ACCESS_PRIVATE,
184  GCC_CP_ACCESS_PUBLIC = GCC_CP_ACCESS_PRIVATE << 1,
185  GCC_CP_ACCESS_MASK = (GCC_CP_ACCESS_PUBLIC
186			       | GCC_CP_ACCESS_PRIVATE),
187  GCC_CP_ACCESS_PROTECTED = GCC_CP_ACCESS_MASK,
188  GCC_CP_ACCESS_NONE = 0,
189
190  GCC_CP_FLAG_BASE = GCC_CP_ACCESS_PRIVATE << 2,
191
192  /* Flags to be used along with GCC_CP_SYMBOL_FUNCTION:  */
193
194  /* This flag should be set for constructors, destructors and
195     operators.  */
196  GCC_CP_FLAG_SPECIAL_FUNCTION = GCC_CP_FLAG_BASE,
197
198  /* We intentionally cannot express inline, constexpr, or virtual
199     override for functions.  We can't inline or constexpr-replace
200     without a source-level body.  The override keyword is only
201     meaningful within the definition of the containing class.  */
202
203  /* This indicates a "virtual" member function, explicitly or
204     implicitly (due to a virtual function with the same name and
205     prototype in a base class) declared as such.  */
206  GCC_CP_FLAG_VIRTUAL_FUNCTION = GCC_CP_FLAG_BASE << 1,
207
208  /* The following two flags should only be set when the flag above is
209     set.  */
210
211  /* This indicates a pure virtual member function, i.e., one that is
212     declared with "= 0", even if a body is provided in the
213     definition.  */
214  GCC_CP_FLAG_PURE_VIRTUAL_FUNCTION = GCC_CP_FLAG_BASE << 2,
215
216  /* This indicates a "final" virtual member function.  */
217  GCC_CP_FLAG_FINAL_VIRTUAL_FUNCTION = GCC_CP_FLAG_BASE << 3,
218
219  /* This indicates a special member function should have its default
220     implementation.  This either means the function declaration
221     contains the "= default" tokens, or that the member function was
222     implicitly generated by the compiler, although the latter use is
223     discouraged: just let the compiler implicitly introduce it.
224
225     A member function defaulted after its first declaration has
226     slightly different ABI implications from one implicitly generated
227     or explicitly defaulted at the declaration (and definition)
228     point.  To avoid silent (possibly harmless) violation of the one
229     definition rule, it is recommended that this flag not be used for
230     such functions, and that the address of the definition be
231     supplied instead.  */
232  GCC_CP_FLAG_DEFAULTED_FUNCTION = GCC_CP_FLAG_BASE << 4,
233
234  /* This indicates a deleted member function, i.e., one that has been
235     defined as "= delete" at its declaration point, or one that has
236     been implicitly defined as deleted (with or without an explicit
237     "= default" definition).
238
239     This should not be used for implicitly-declared member functions
240     that resolve to deleted definitions, as it may affect the
241     implicit declaration of other member functions.  */
242  GCC_CP_FLAG_DELETED_FUNCTION = GCC_CP_FLAG_BASE << 5,
243
244  /* This indicates a constructor or type-conversion operator declared
245     as "explicit".  */
246
247  GCC_CP_FLAG_EXPLICIT_FUNCTION = GCC_CP_FLAG_BASE << 6,
248
249  GCC_CP_FLAG_END_FUNCTION,
250  GCC_CP_FLAG_MASK_FUNCTION = (((GCC_CP_FLAG_END_FUNCTION - 1) << 1)
251			       - GCC_CP_FLAG_BASE),
252
253  /* Flags to be used along with GCC_CP_SYMBOL_VARIABLE:  */
254
255  /* This indicates a variable declared as "constexpr".  */
256
257  GCC_CP_FLAG_CONSTEXPR_VARIABLE = GCC_CP_FLAG_BASE,
258
259  /* This indicates a variable declared as "thread_local".  ??? What
260     should the ADDRESS be?  */
261
262  GCC_CP_FLAG_THREAD_LOCAL_VARIABLE = GCC_CP_FLAG_BASE << 1,
263
264  GCC_CP_FLAG_END_VARIABLE,
265  GCC_CP_FLAG_MASK_VARIABLE = (((GCC_CP_FLAG_END_VARIABLE - 1) << 1)
266			       - GCC_CP_FLAG_BASE),
267
268  /* Flags to be used when defining nonstatic data members of classes
269     with new_field.  */
270
271  /* Use this when no flags are present.  */
272  GCC_CP_FLAG_FIELD_NOFLAG = 0,
273
274  /* This indicates the field is declared as mutable.  */
275  GCC_CP_FLAG_FIELD_MUTABLE = GCC_CP_FLAG_BASE,
276
277  GCC_CP_FLAG_END_FIELD,
278  GCC_CP_FLAG_MASK_FIELD = (((GCC_CP_FLAG_END_FIELD - 1) << 1)
279			    - GCC_CP_FLAG_BASE),
280
281  /* Flags to be used when defining an enum with
282     start_new_enum_type.  */
283
284  /* This indicates an enum type without any flags.  */
285  GCC_CP_FLAG_ENUM_NOFLAG = 0,
286
287  /* This indicates a scoped enum type.  */
288  GCC_CP_FLAG_ENUM_SCOPED = GCC_CP_FLAG_BASE,
289
290  GCC_CP_FLAG_END_ENUM,
291  GCC_CP_FLAG_MASK_ENUM = (((GCC_CP_FLAG_END_ENUM - 1) << 1)
292			       - GCC_CP_FLAG_BASE),
293
294
295  /* Flags to be used when introducing a class or a class template
296     with build_decl.  */
297
298  /* This indicates an enum type without any flags.  */
299  GCC_CP_FLAG_CLASS_NOFLAG = 0,
300
301  /* This indicates the class is actually a struct.  This has no
302     effect whatsoever on access control in this interface, since all
303     class members must have explicit access control bits set, but it
304     may affect error messages.  */
305  GCC_CP_FLAG_CLASS_IS_STRUCT = GCC_CP_FLAG_BASE,
306
307  GCC_CP_FLAG_END_CLASS,
308  GCC_CP_FLAG_MASK_CLASS = (((GCC_CP_FLAG_END_CLASS - 1) << 1)
309			       - GCC_CP_FLAG_BASE),
310
311
312  /* Flags to be used when introducing a virtual base class in a
313     gcc_vbase_array.  */
314
315  /* This indicates an enum type without any flags.  */
316  GCC_CP_FLAG_BASECLASS_NOFLAG = 0,
317
318  /* This indicates the class is actually a struct.  This has no
319     effect whatsoever on access control in this interface, since all
320     class members must have explicit access control bits set, but it
321     may affect error messages.  */
322  GCC_CP_FLAG_BASECLASS_VIRTUAL = GCC_CP_FLAG_BASE,
323
324  GCC_CP_FLAG_END_BASECLASS,
325  GCC_CP_FLAG_MASK_BASECLASS = (((GCC_CP_FLAG_END_BASECLASS - 1) << 1)
326				- GCC_CP_FLAG_BASE),
327
328
329  GCC_CP_FLAG_MASK = (GCC_CP_FLAG_MASK_FUNCTION
330		      | GCC_CP_FLAG_MASK_VARIABLE
331		      | GCC_CP_FLAG_MASK_FIELD
332		      | GCC_CP_FLAG_MASK_ENUM
333		      | GCC_CP_FLAG_MASK_CLASS
334		      | GCC_CP_FLAG_MASK_BASECLASS
335		      )
336};
337
338
339/* An array of types used for creating lists of base classes.  */
340
341struct gcc_vbase_array
342{
343  /* Number of elements.  */
344
345  int n_elements;
346
347  /* The base classes.  */
348
349  gcc_type *elements;
350
351  /* Flags for each base class.  Used to indicate access control and
352     virtualness.  */
353
354  enum gcc_cp_symbol_kind *flags;
355};
356
357
358/* This enumerates the types of symbols that GCC might request from
359   GDB.  */
360
361enum gcc_cp_oracle_request
362{
363  /* An identifier in namespace scope -- type, variable, function,
364     namespace, template.  All namespace-scoped symbols with the
365     requested name, in any namespace (including the global
366     namespace), should be defined in response to this request.  */
367
368  GCC_CP_ORACLE_IDENTIFIER
369};
370
371/* The type of the function called by GCC to ask GDB for a symbol's
372   definition.  DATUM is an arbitrary value supplied when the oracle
373   function is registered.  CONTEXT is the GCC context in which the
374   request is being made.  REQUEST specifies what sort of symbol is
375   being requested, and IDENTIFIER is the name of the symbol.  */
376
377typedef void gcc_cp_oracle_function (void *datum,
378				     struct gcc_cp_context *context,
379				     enum gcc_cp_oracle_request request,
380				     const char *identifier);
381
382/* The type of the function called by GCC to ask GDB for a symbol's
383   address.  This should return 0 if the address is not known.  */
384
385typedef gcc_address gcc_cp_symbol_address_function (void *datum,
386						    struct gcc_cp_context *ctxt,
387						    const char *identifier);
388
389/* The type of the function called by GCC to ask GDB to enter or leave
390   the user expression scope.  */
391
392typedef void gcc_cp_enter_leave_user_expr_scope_function (void *datum,
393							  struct gcc_cp_context
394							  *context);
395
396/* The vtable used by the C front end.  */
397
398struct gcc_cp_fe_vtable
399{
400  /* The version of the C interface.  The value is one of the
401     gcc_cp_api_version constants.  */
402
403  unsigned int cp_version;
404
405  /* Set the callbacks for this context.
406
407     The binding oracle is called whenever the C++ parser needs to
408     look up a symbol.  This gives the caller a chance to lazily
409     instantiate symbols using other parts of the gcc_cp_fe_interface
410     API.  The symbol is looked up without a scope, and the oracle
411     must supply a definition for ALL namespace-scoped definitions
412     bound to the symbol.
413
414     The address oracle is called whenever the C++ parser needs to
415     look up a symbol.  This may be called for symbols not provided by
416     the symbol oracle, such as built-in functions where GCC provides
417     the declaration; other internal symbols, such as those related
418     with thunks, rtti, and virtual tables are likely to be queried
419     through this interface too.  The identifier is a mangled symbol
420     name.
421
422     DATUM is an arbitrary piece of data that is passed back verbatim
423     to the callbacks in requests.  */
424
425  void (*set_callbacks) (struct gcc_cp_context *self,
426			 gcc_cp_oracle_function *binding_oracle,
427			 gcc_cp_symbol_address_function *address_oracle,
428			 gcc_cp_enter_leave_user_expr_scope_function *enter_scope,
429			 gcc_cp_enter_leave_user_expr_scope_function *leave_scope,
430			 void *datum);
431
432#define GCC_METHOD0(R, N) \
433  R (*N) (struct gcc_cp_context *);
434#define GCC_METHOD1(R, N, A) \
435  R (*N) (struct gcc_cp_context *, A);
436#define GCC_METHOD2(R, N, A, B) \
437  R (*N) (struct gcc_cp_context *, A, B);
438#define GCC_METHOD3(R, N, A, B, C) \
439  R (*N) (struct gcc_cp_context *, A, B, C);
440#define GCC_METHOD4(R, N, A, B, C, D) \
441  R (*N) (struct gcc_cp_context *, A, B, C, D);
442#define GCC_METHOD5(R, N, A, B, C, D, E) \
443  R (*N) (struct gcc_cp_context *, A, B, C, D, E);
444#define GCC_METHOD7(R, N, A, B, C, D, E, F, G) \
445  R (*N) (struct gcc_cp_context *, A, B, C, D, E, F, G);
446
447#include "gcc-cp-fe.def"
448
449#undef GCC_METHOD0
450#undef GCC_METHOD1
451#undef GCC_METHOD2
452#undef GCC_METHOD3
453#undef GCC_METHOD4
454#undef GCC_METHOD5
455#undef GCC_METHOD7
456
457};
458
459/* The C front end object.  */
460
461struct gcc_cp_context
462{
463  /* Base class.  */
464
465  struct gcc_base_context base;
466
467  /* Our vtable.  This is a separate field because this is simpler
468     than implementing a vtable inheritance scheme in C.  */
469
470  const struct gcc_cp_fe_vtable *cp_ops;
471};
472
473/* The name of the .so that the compiler builds.  We dlopen this
474   later.  */
475
476#define GCC_CP_FE_LIBCC libcc1.so
477
478/* The compiler exports a single initialization function.  This macro
479   holds its name as a symbol.  */
480
481#define GCC_CP_FE_CONTEXT gcc_cp_fe_context
482
483/* The type of the initialization function.  The caller passes in the
484   desired base version and desired C-specific version.  If the
485   request can be satisfied, a compatible gcc_context object will be
486   returned.  Otherwise, the function returns NULL.  */
487
488typedef struct gcc_cp_context *gcc_cp_fe_context_function
489    (enum gcc_base_api_version,
490     enum gcc_cp_api_version);
491
492#ifdef __cplusplus
493}
494#endif
495
496#endif /* GCC_CP_INTERFACE_H */
497