include/gcc-cp-interface.h

   1 /* Interface between GCC C++ FE and GDB
   2
   3    Copyright (C) 2014-2024 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
  29 extern "C" {
  30 #endif
  31
  32 /* Forward declaration.  */
  33
  34 struct 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
  42 enum gcc_cp_api_version
  43 {
  44   GCC_CP_FE_VERSION_0 = 0
  45 };
  46
  47 /* Qualifiers.  */
  48
  49 enum 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
  58 enum 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
  68 typedef 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
  74 typedef unsigned long long gcc_expr;
  75
  76 typedef enum
  77   { GCC_CP_TPARG_VALUE, GCC_CP_TPARG_CLASS,
  78     GCC_CP_TPARG_TEMPL, GCC_CP_TPARG_PACK }
  79 gcc_cp_template_arg_kind;
  80
  81 typedef union
  82 { gcc_expr value; gcc_type type; gcc_utempl templ; gcc_type pack; }
  83 gcc_cp_template_arg;
  84
  85 /* An array of template arguments.  */
  86
  87 struct 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
 104 struct 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
 117 enum 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
 341 struct 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
 361 enum 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
 377 typedef 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
 385 typedef 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
 392 typedef 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
 398 struct 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
 461 struct 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.  In particular, this may return a context object with a higher
 487    actual version number than was requested, provided the higher version is
 488    fully compatible.
 489
 490    Otherwise, the function returns NULL.  */
 491
 492 typedef struct gcc_cp_context *gcc_cp_fe_context_function
 493     (enum gcc_base_api_version,
 494      enum gcc_cp_api_version);
 495
 496 #ifdef __cplusplus
 497 }
 498 #endif
 499
 500 #endif /* GCC_CP_INTERFACE_H */