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