include/gcc-c-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_C_INTERFACE_H
  21 #define GCC_C_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_c_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_c_api_version
  43 {
  44   GCC_C_FE_VERSION_0 = 0,
  45
  46   /* Added char_type.  Added new version of int_type and float_type,
  47      deprecated int_type_v0 and float_type_v0.  */
  48   GCC_C_FE_VERSION_1 = 1,
  49
  50   /* Added finish_record_with_alignment method.  */
  51   GCC_C_FE_VERSION_2 = 2,
  52 };
  53
  54 /* Qualifiers.  */
  55
  56 enum gcc_qualifiers
  57 {
  58   GCC_QUALIFIER_CONST = 1,
  59   GCC_QUALIFIER_VOLATILE = 2,
  60   GCC_QUALIFIER_RESTRICT = 4
  61 };
  62
  63 /* This enumerates the kinds of decls that GDB can create.  */
  64
  65 enum gcc_c_symbol_kind
  66 {
  67   /* A function.  */
  68
  69   GCC_C_SYMBOL_FUNCTION,
  70
  71   /* A variable.  */
  72
  73   GCC_C_SYMBOL_VARIABLE,
  74
  75   /* A typedef.  */
  76
  77   GCC_C_SYMBOL_TYPEDEF,
  78
  79   /* A label.  */
  80
  81   GCC_C_SYMBOL_LABEL
  82 };
  83
  84 /* This enumerates the types of symbols that GCC might request from
  85    GDB.  */
  86
  87 enum gcc_c_oracle_request
  88 {
  89   /* An ordinary symbol -- a variable, function, typedef, or enum
  90      constant.  */
  91
  92   GCC_C_ORACLE_SYMBOL,
  93
  94   /* A struct, union, or enum tag.  */
  95
  96   GCC_C_ORACLE_TAG,
  97
  98   /* A label.  */
  99
 100   GCC_C_ORACLE_LABEL
 101 };
 102
 103 /* The type of the function called by GCC to ask GDB for a symbol's
 104    definition.  DATUM is an arbitrary value supplied when the oracle
 105    function is registered.  CONTEXT is the GCC context in which the
 106    request is being made.  REQUEST specifies what sort of symbol is
 107    being requested, and IDENTIFIER is the name of the symbol.  */
 108
 109 typedef void gcc_c_oracle_function (void *datum,
 110                                     struct gcc_c_context *context,
 111                                     enum gcc_c_oracle_request request,
 112                                     const char *identifier);
 113
 114 /* The type of the function called by GCC to ask GDB for a symbol's
 115    address.  This should return 0 if the address is not known.  */
 116
 117 typedef gcc_address gcc_c_symbol_address_function (void *datum,
 118                                                    struct gcc_c_context *ctxt,
 119                                                    const char *identifier);
 120
 121 /* The vtable used by the C front end.  */
 122
 123 struct gcc_c_fe_vtable
 124 {
 125   /* The version of the C interface.  The value is one of the
 126      gcc_c_api_version constants.  */
 127
 128   unsigned int c_version;
 129
 130   /* Set the callbacks for this context.
 131
 132      The binding oracle is called whenever the C parser needs to look
 133      up a symbol.  This gives the caller a chance to lazily
 134      instantiate symbols using other parts of the gcc_c_fe_interface
 135      API.
 136
 137      The address oracle is called whenever the C parser needs to look
 138      up a symbol.  This is only called for symbols not provided by the
 139      symbol oracle -- that is, just built-in functions where GCC
 140      provides the declaration.
 141
 142      DATUM is an arbitrary piece of data that is passed back verbatim
 143      to the callbacks in requests.  */
 144
 145   void (*set_callbacks) (struct gcc_c_context *self,
 146                          gcc_c_oracle_function *binding_oracle,
 147                          gcc_c_symbol_address_function *address_oracle,
 148                          void *datum);
 149
 150 #define GCC_METHOD0(R, N) \
 151   R (*N) (struct gcc_c_context *);
 152 #define GCC_METHOD1(R, N, A) \
 153   R (*N) (struct gcc_c_context *, A);
 154 #define GCC_METHOD2(R, N, A, B) \
 155   R (*N) (struct gcc_c_context *, A, B);
 156 #define GCC_METHOD3(R, N, A, B, C) \
 157   R (*N) (struct gcc_c_context *, A, B, C);
 158 #define GCC_METHOD4(R, N, A, B, C, D) \
 159   R (*N) (struct gcc_c_context *, A, B, C, D);
 160 #define GCC_METHOD5(R, N, A, B, C, D, E) \
 161   R (*N) (struct gcc_c_context *, A, B, C, D, E);
 162 #define GCC_METHOD7(R, N, A, B, C, D, E, F, G) \
 163   R (*N) (struct gcc_c_context *, A, B, C, D, E, F, G);
 164
 165 #include "gcc-c-fe.def"
 166
 167 #undef GCC_METHOD0
 168 #undef GCC_METHOD1
 169 #undef GCC_METHOD2
 170 #undef GCC_METHOD3
 171 #undef GCC_METHOD4
 172 #undef GCC_METHOD5
 173 #undef GCC_METHOD7
 174
 175 };
 176
 177 /* The C front end object.  */
 178
 179 struct gcc_c_context
 180 {
 181   /* Base class.  */
 182
 183   struct gcc_base_context base;
 184
 185   /* Our vtable.  This is a separate field because this is simpler
 186      than implementing a vtable inheritance scheme in C.  */
 187
 188   const struct gcc_c_fe_vtable *c_ops;
 189 };
 190
 191 /* The name of the .so that the compiler builds.  We dlopen this
 192    later.  */
 193
 194 #define GCC_C_FE_LIBCC libcc1.so
 195
 196 /* The compiler exports a single initialization function.  This macro
 197    holds its name as a symbol.  */
 198
 199 #define GCC_C_FE_CONTEXT gcc_c_fe_context
 200
 201 /* The type of the initialization function.  The caller passes in the
 202    desired base version and desired C-specific version.  If the
 203    request can be satisfied, a compatible gcc_context object will be
 204    returned.  In particular, this may return a context object with a higher
 205    actual version number than was requested, provided the higher version is
 206    fully compatible.  (As of GCC_C_FE_VERSION_2, this is always true.)
 207
 208    Otherwise, the function returns NULL.  */
 209
 210 typedef struct gcc_c_context *gcc_c_fe_context_function
 211     (enum gcc_base_api_version,
 212      enum gcc_c_api_version);
 213
 214 #ifdef __cplusplus
 215 }
 216 #endif
 217
 218 #endif /* GCC_C_INTERFACE_H */