GDB (xrefs)

/tmp/gdb-8.1/gdb/extension-priv.h
Go to the documentation of this file.
1 /* Private implementation details of interface between gdb and its
2 extension languages.
3
4 Copyright (C) 2014-2018 Free Software Foundation, Inc.
5
6 This file is part of GDB.
7
8 This program is free software; you can redistribute it and/or modify
9 it under the terms of the GNU General Public License as published by
10 the Free Software Foundation; either version 3 of the License, or
11 (at your option) any later version.
12
13 This program is distributed in the hope that it will be useful,
14 but WITHOUT ANY WARRANTY; without even the implied warranty of
15 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 GNU General Public License for more details.
17
18 You should have received a copy of the GNU General Public License
19 along with this program. If not, see <http://www.gnu.org/licenses/>. */
20
21 #ifndef EXTENSION_PRIV_H
22 #define EXTENSION_PRIV_H
23
24 #include "extension.h"
25 #include <signal.h>
26 #include "cli/cli-script.h"
27
28 /* The return code for some API calls. */
29
30 enum ext_lang_rc
31 {
32 /* The operation completed successfully. */
33 EXT_LANG_RC_OK,
34
35 /* The operation was not performed (e.g., no pretty-printer). */
36 EXT_LANG_RC_NOP,
37
38 /* There was an error (e.g., Python error while printing a value).
39 When an error occurs no further extension languages are tried.
40 This is to preserve existing behaviour, and because it's convenient
41 for Python developers.
42 Note: This is different than encountering a memory error trying to read
43 a value for pretty-printing. Here we're referring to, e.g., programming
44 errors that trigger an exception in the extension language. */
45 EXT_LANG_RC_ERROR
46 };
47
48 /* High level description of an extension/scripting language.
49 An entry for each is compiled into GDB regardless of whether the support
50 is present. This is done so that we can issue meaningful errors if the
51 support is not compiled in. */
52
53 struct extension_language_defn
54 {
55 /* Enum of the extension language. */
56 enum extension_language language;
57
58 /* The name of the extension language, lowercase. E.g., python. */
59 const char *name;
60
61 /* The capitalized name of the extension language.
62 For python this is "Python". For gdb this is "GDB". */
63 const char *capitalized_name;
64
65 /* The file suffix of this extension language. E.g., ".py". */
66 const char *suffix;
67
68 /* The suffix of per-objfile scripts to auto-load.
69 E.g., When the program loads libfoo.so, look for libfoo.so-gdb.py. */
70 const char *auto_load_suffix;
71
72 /* We support embedding external extension language code in GDB's own
73 scripting language. We do this by having a special command that begins
74 the extension language snippet, and terminate it with "end".
75 This specifies the control type used to implement this. */
76 enum command_control_type cli_control_type;
77
78 /* A pointer to the "methods" to load scripts in this language,
79 or NULL if the support is not compiled into GDB. */
80 const struct extension_language_script_ops *script_ops;
81
82 /* Either a pointer to the "methods" of the extension language interface
83 or NULL if the support is not compiled into GDB.
84 This is also NULL for GDB's own scripting language which is relatively
85 primitive, and doesn't provide these features. */
86 const struct extension_language_ops *ops;
87 };
88
89 /* The interface for loading scripts from external extension languages,
90 as well as GDB's own scripting language.
91 All of these methods are required to be implemented.
92
93 By convention all of these functions take a pseudo-this parameter
94 as the first argument. */
95
96 struct extension_language_script_ops
97 {
98 /* Load a script. This is called, e.g., via the "source" command.
99 If there's an error while processing the script this function may,
100 but is not required to, throw an error. */
101 script_sourcer_func *script_sourcer;
102
103 /* Load a script attached to an objfile.
104 If there's an error while processing the script this function may,
105 but is not required to, throw an error. */
106 objfile_script_sourcer_func *objfile_script_sourcer;
107
108 /* Execute a script attached to an objfile.
109 If there's an error while processing the script this function may,
110 but is not required to, throw an error. */
111 objfile_script_executor_func *objfile_script_executor;
112
113 /* Return non-zero if auto-loading scripts in this extension language
114 is enabled. */
115 int (*auto_load_enabled) (const struct extension_language_defn *);
116 };
117
118 /* The interface for making calls from GDB to an external extension
119 language. This is for non-script-loading related functionality, like
120 pretty-printing, etc. The reason these are separated out is GDB's own
121 scripting language makes use of extension_language_script_opts, but it
122 makes no use of these. There is no (current) intention to split
123 extension_language_ops up any further.
124 All of these methods are optional and may be NULL, except where
125 otherwise indicated.
126
127 By convention all of these functions take a pseudo-this parameter
128 as the first argument. */
129
130 struct extension_language_ops
131 {
132 /* Called at the end of gdb initialization to give the extension language
133 an opportunity to finish up. This is useful for things like adding
134 new commands where one has to wait until gdb itself is initialized. */
135 void (*finish_initialization) (const struct extension_language_defn *);
136
137 /* Return non-zero if the extension language successfully initialized.
138 This method is required. */
139 int (*initialized) (const struct extension_language_defn *);
140
141 /* Process a sequence of commands embedded in GDB's own scripting language.
142 E.g.,
143 python
144 print 42
145 end */
146 void (*eval_from_control_command) (const struct extension_language_defn *,
147 struct command_line *);
148
149 /* Type-printing support:
150 start_type_printers, apply_type_printers, free_type_printers.
151 These methods are optional and may be NULL, but if one of them is
152 implemented then they all must be. */
153
154 /* Called before printing a type. */
155 void (*start_type_printers) (const struct extension_language_defn *,
156 struct ext_lang_type_printers *);
157
158 /* Try to pretty-print TYPE. If successful the pretty-printed type is
159 stored in *PRETTIED_TYPE, and the caller must free it.
160 Returns EXT_LANG_RC_OK upon success, EXT_LANG_RC_NOP if the type
161 is not recognized, and EXT_LANG_RC_ERROR if an error was encountered.
162 This function has a bit of a funny name, since it actually applies
163 recognizers, but this seemed clearer given the start_type_printers
164 and free_type_printers functions. */
165 enum ext_lang_rc (*apply_type_printers)
166 (const struct extension_language_defn *,
167 const struct ext_lang_type_printers *,
168 struct type *, char **prettied_type);
169
170 /* Called after a type has been printed to give the type pretty-printer
171 mechanism an opportunity to clean up. */
172 void (*free_type_printers) (const struct extension_language_defn *,
173 struct ext_lang_type_printers *);
174
175 /* Try to pretty-print a value of type TYPE located at VAL's contents
176 buffer + EMBEDDED_OFFSET, which came from the inferior at address
177 ADDRESS + EMBEDDED_OFFSET, onto stdio stream STREAM according to
178 OPTIONS.
179 VAL is the whole object that came from ADDRESS.
180 Returns EXT_LANG_RC_OK upon success, EXT_LANG_RC_NOP if the value
181 is not recognized, and EXT_LANG_RC_ERROR if an error was encountered. */
182 enum ext_lang_rc (*apply_val_pretty_printer)
183 (const struct extension_language_defn *,
184 struct type *type,
185 LONGEST embedded_offset, CORE_ADDR address,
186 struct ui_file *stream, int recurse,
187 struct value *val, const struct value_print_options *options,
188 const struct language_defn *language);
189
190 /* GDB access to the "frame filter" feature.
191 FRAME is the source frame to start frame-filter invocation. FLAGS is an
192 integer holding the flags for printing. The following elements of
193 the FRAME_FILTER_FLAGS enum denotes the make-up of FLAGS:
194 PRINT_LEVEL is a flag indicating whether to print the frame's
195 relative level in the output. PRINT_FRAME_INFO is a flag that
196 indicates whether this function should print the frame
197 information, PRINT_ARGS is a flag that indicates whether to print
198 frame arguments, and PRINT_LOCALS, likewise, with frame local
199 variables. ARGS_TYPE is an enumerator describing the argument
200 format, OUT is the output stream to print. FRAME_LOW is the
201 beginning of the slice of frames to print, and FRAME_HIGH is the
202 upper limit of the frames to count. Returns SCR_BT_ERROR on error,
203 or SCR_BT_COMPLETED on success. */
204 enum ext_lang_bt_status (*apply_frame_filter)
205 (const struct extension_language_defn *,
206 struct frame_info *frame, int flags, enum ext_lang_frame_args args_type,
207 struct ui_out *out, int frame_low, int frame_high);
208
209 /* Update values held by the extension language when OBJFILE is discarded.
210 New global types must be created for every such value, which must then be
211 updated to use the new types.
212 This function typically just iterates over all appropriate values and
213 calls preserve_one_value for each one.
214 COPIED_TYPES is used to prevent cycles / duplicates and is passed to
215 preserve_one_value. */
216 void (*preserve_values) (const struct extension_language_defn *,
217 struct objfile *objfile, htab_t copied_types);
218
219 /* Return non-zero if there is a stop condition for the breakpoint.
220 This is used to implement the restriction that a breakpoint may have
221 at most one condition. */
222 int (*breakpoint_has_cond) (const struct extension_language_defn *,
223 struct breakpoint *);
224
225 /* Return a value of enum ext_lang_bp_stop indicating if there is a stop
226 condition for the breakpoint, and if so whether the program should
227 stop. This is called when the program has stopped at the specified
228 breakpoint.
229 While breakpoints can have at most one condition, this is called for
230 every extension language, even if another extension language has a
231 "stop" method: other kinds of breakpoints may be implemented using
232 this method, e.g., "finish breakpoints" in Python. */
233 enum ext_lang_bp_stop (*breakpoint_cond_says_stop)
234 (const struct extension_language_defn *, struct breakpoint *);
235
236 /* The next two are used to connect GDB's SIGINT handling with the
237 extension language's.
238
239 Terminology: If an extension language can use GDB's SIGINT handling then
240 we say the extension language has "cooperative SIGINT handling".
241 Python is an example of this.
242
243 These need not be implemented, but if one of them is implemented
244 then they all must be. */
245
246 /* Set the SIGINT indicator.
247 This is called by GDB's SIGINT handler and must be async-safe. */
248 void (*set_quit_flag) (const struct extension_language_defn *);
249
250 /* Return non-zero if a SIGINT has occurred.
251 This is expected to also clear the indicator. */
252 int (*check_quit_flag) (const struct extension_language_defn *);
253
254 /* Called before gdb prints its prompt, giving extension languages an
255 opportunity to change it with set_prompt.
256 Returns EXT_LANG_RC_OK if the prompt was changed, EXT_LANG_RC_NOP if
257 the prompt was not changed, and EXT_LANG_RC_ERROR if an error was
258 encountered.
259 Extension languages are called in order, and once the prompt is
260 changed or an error occurs no further languages are called. */
261 enum ext_lang_rc (*before_prompt) (const struct extension_language_defn *,
262 const char *current_gdb_prompt);
263
264 /* xmethod support:
265 clone_xmethod_worker_data, free_xmethod_worker_data,
266 get_matching_xmethod_workers, get_xmethod_arg_types,
267 get_xmethod_return_type, invoke_xmethod.
268 These methods are optional and may be NULL, but if one of them is
269 implemented then they all must be. */
270
271 /* Clone DATA and return a new but identical xmethod worker data
272 object for this extension language. */
273 void * (*clone_xmethod_worker_data)
274 (const struct extension_language_defn *extlang, void *data);
275
276 /* Free the DATA object of this extension language. */
277 void (*free_xmethod_worker_data)
278 (const struct extension_language_defn *extlang, void *data);
279
280 /* Return a vector of matching xmethod workers defined in this
281 extension language. The workers service methods with name
282 METHOD_NAME on objects of type OBJ_TYPE. The vector is returned
283 in DM_VEC. */
284 enum ext_lang_rc (*get_matching_xmethod_workers)
285 (const struct extension_language_defn *extlang,
286 struct type *obj_type,
287 const char *method_name,
288 xmethod_worker_vec **dm_vec);
289
290 /* Given a WORKER servicing a particular method, return the types
291 of the arguments the method takes. The number of arguments is
292 returned in NARGS, and their types are returned in the array
293 ARGTYPES. */
294 enum ext_lang_rc (*get_xmethod_arg_types)
295 (const struct extension_language_defn *extlang,
296 struct xmethod_worker *worker,
297 int *nargs,
298 struct type ***arg_types);
299
300 /* Given a WORKER servicing a particular method, fetch the type of the
301 result of the method. OBJECT, ARGS, NARGS are the same as for
302 invoke_xmethod. The result type is stored in *RESULT_TYPE.
303 For backward compatibility with 7.9, which did not support getting the
304 result type, if the get_result_type operation is not provided by WORKER
305 then EXT_LANG_RC_OK is returned and NULL is returned in *RESULT_TYPE. */
306 enum ext_lang_rc (*get_xmethod_result_type)
307 (const struct extension_language_defn *extlang,
308 struct xmethod_worker *worker,
309 struct value *object, struct value **args, int nargs,
310 struct type **result_type);
311
312 /* Invoke the xmethod serviced by WORKER. The xmethod is invoked
313 on OBJECT with arguments in the array ARGS. NARGS is the length of
314 this array. Returns the value returned by the xmethod. */
315 struct value * (*invoke_xmethod)
316 (const struct extension_language_defn *extlang,
317 struct xmethod_worker *worker,
318 struct value *object,
319 struct value **args,
320 int nargs);
321 };
322
323 /* State necessary to restore a signal handler to its previous value. */
324
325 struct signal_handler
326 {
327 /* Non-zero if "handler" has been set. */
328 int handler_saved;
329
330 /* The signal handler. */
331 sighandler_t handler;
332 };
333
334 /* State necessary to restore the currently active extension language
335 to its previous value. */
336
337 struct active_ext_lang_state
338 {
339 /* The previously active extension language. */
340 const struct extension_language_defn *ext_lang;
341
342 /* Its SIGINT handler. */
343 struct signal_handler sigint_handler;
344 };
345
346 extern const struct extension_language_defn *get_active_ext_lang (void);
347
348 extern struct active_ext_lang_state *set_active_ext_lang
349 (const struct extension_language_defn *);
350
351 extern void restore_active_ext_lang (struct active_ext_lang_state *previous);
352
353 #endif /* EXTENSION_PRIV_H */
command_line
Definition: cli-script.h:51
xmethod_worker
Definition: extension.h:151
extension_language_defn::capitalized_name
const char * capitalized_name
Definition: extension-priv.h:63
extension_language_script_ops::objfile_script_sourcer
objfile_script_sourcer_func * objfile_script_sourcer
Definition: extension-priv.h:106
CORE_ADDR
bfd_vma CORE_ADDR
Definition: common-types.h:41
ext_lang_bp_stop
ext_lang_bp_stop
Definition: extension.h:129
ext_lang_rc
ext_lang_rc
Definition: extension-priv.h:30
extension_language_ops::eval_from_control_command
void(* eval_from_control_command)(const struct extension_language_defn *, struct command_line *)
Definition: extension-priv.h:146
extension_language_ops
Definition: extension-priv.h:130
extension_language_ops::breakpoint_cond_says_stop
enum ext_lang_bp_stop(* breakpoint_cond_says_stop)(const struct extension_language_defn *, struct breakpoint *)
Definition: extension-priv.h:234
objfile_script_executor_func
void objfile_script_executor_func(const struct extension_language_defn *, struct objfile *, const char *name, const char *script)
Definition: extension.h:54
frame_info
Definition: frame.c:85
extension_language_defn::suffix
const char * suffix
Definition: extension-priv.h:66
extension_language_defn::name
const char * name
Definition: extension-priv.h:59
extension_language_ops::before_prompt
enum ext_lang_rc(* before_prompt)(const struct extension_language_defn *, const char *current_gdb_prompt)
Definition: extension-priv.h:261
ui_file
Definition: ui-file.h:26
signal_handler::handler_saved
int handler_saved
Definition: extension-priv.h:328
ext_lang_bt_status
ext_lang_bt_status
Definition: extension.h:69
extension_language_defn::ops
const struct extension_language_ops * ops
Definition: extension-priv.h:86
language_defn
Definition: language.h:132
extension_language_defn::cli_control_type
enum command_control_type cli_control_type
Definition: extension-priv.h:76
flags
mach_port_t kern_return_t mach_port_t msgports mach_port_t kern_return_t pid_t pid mach_port_t kern_return_t mach_port_t task mach_port_t kern_return_t int flags
Definition: gnu-nat.c:1891
set_active_ext_lang
struct active_ext_lang_state * set_active_ext_lang(const struct extension_language_defn *)
Definition: extension.c:744
extension_language_ops::get_xmethod_result_type
enum ext_lang_rc(* get_xmethod_result_type)(const struct extension_language_defn *extlang, struct xmethod_worker *worker, struct value *object, struct value **args, int nargs, struct type **result_type)
Definition: extension-priv.h:307
extension_language
extension_language
Definition: extension.h:59
extension_language_ops::apply_type_printers
enum ext_lang_rc(* apply_type_printers)(const struct extension_language_defn *, const struct ext_lang_type_printers *, struct type *, char **prettied_type)
Definition: extension-priv.h:166
extension_language_script_ops::script_sourcer
script_sourcer_func * script_sourcer
Definition: extension-priv.h:101
signal_handler
Definition: extension-priv.h:325
value_print_options
Definition: valprint.h:25
objfile_script_sourcer_func
void objfile_script_sourcer_func(const struct extension_language_defn *, struct objfile *, FILE *stream, const char *filename)
Definition: extension.h:48
objfile::objfile
objfile(bfd *, const char *, objfile_flags)
Definition: objfiles.c:373
extension_language_ops::get_matching_xmethod_workers
enum ext_lang_rc(* get_matching_xmethod_workers)(const struct extension_language_defn *extlang, struct type *obj_type, const char *method_name, xmethod_worker_vec **dm_vec)
Definition: extension-priv.h:285
ext_lang_frame_args
ext_lang_frame_args
Definition: extension.h:108
extension_language_defn::script_ops
const struct extension_language_script_ops * script_ops
Definition: extension-priv.h:80
extension_language_defn::language
enum extension_language language
Definition: extension-priv.h:56
breakpoint
Definition: breakpoint.h:684
get_active_ext_lang
const struct extension_language_defn * get_active_ext_lang(void)
Definition: extension.c:687
cli-script.h
type
Definition: gdbtypes.h:749
type
static const char * type
Definition: language.c:113
script_sourcer_func
void script_sourcer_func(const struct extension_language_defn *, FILE *stream, const char *filename)
Definition: extension.h:41
command_control_type
command_control_type
Definition: cli-script.h:33
extension_language_ops::get_xmethod_arg_types
enum ext_lang_rc(* get_xmethod_arg_types)(const struct extension_language_defn *extlang, struct xmethod_worker *worker, int *nargs, struct type ***arg_types)
Definition: extension-priv.h:295
extension_language_ops::initialized
int(* initialized)(const struct extension_language_defn *)
Definition: extension-priv.h:139
active_ext_lang_state::sigint_handler
struct signal_handler sigint_handler
Definition: extension-priv.h:343
extension_language_ops::apply_val_pretty_printer
enum ext_lang_rc(* apply_val_pretty_printer)(const struct extension_language_defn *, struct type *type, LONGEST embedded_offset, CORE_ADDR address, struct ui_file *stream, int recurse, struct value *val, const struct value_print_options *options, const struct language_defn *language)
Definition: extension-priv.h:183
extension_language_defn
Definition: extension-priv.h:53
extension_language_defn::auto_load_suffix
const char * auto_load_suffix
Definition: extension-priv.h:70
extension_language_script_ops
Definition: extension-priv.h:96
extension_language_ops::free_xmethod_worker_data
void(* free_xmethod_worker_data)(const struct extension_language_defn *extlang, void *data)
Definition: extension-priv.h:278
extension.h
active_ext_lang_state::ext_lang
const struct extension_language_defn * ext_lang
Definition: extension-priv.h:340
value
Definition: value.c:169
ui_out
Definition: ui-out.h:77
extension_language_script_ops::objfile_script_executor
objfile_script_executor_func * objfile_script_executor
Definition: extension-priv.h:111
objfile
Definition: objfiles.h:286
ext_lang_type_printers
Definition: extension.h:143
extension_language_ops::check_quit_flag
int(* check_quit_flag)(const struct extension_language_defn *)
Definition: extension-priv.h:252
extension_language_ops::free_type_printers
void(* free_type_printers)(const struct extension_language_defn *, struct ext_lang_type_printers *)
Definition: extension-priv.h:172
extension_language_ops::apply_frame_filter
enum ext_lang_bt_status(* apply_frame_filter)(const struct extension_language_defn *, struct frame_info *frame, int flags, enum ext_lang_frame_args args_type, struct ui_out *out, int frame_low, int frame_high)
Definition: extension-priv.h:205
extension_language_ops::finish_initialization
void(* finish_initialization)(const struct extension_language_defn *)
Definition: extension-priv.h:135
signal_handler::handler
sighandler_t handler
Definition: extension-priv.h:331
language
language
Definition: defs.h:203
extension_language_script_ops::auto_load_enabled
int(* auto_load_enabled)(const struct extension_language_defn *)
Definition: extension-priv.h:115
EXT_LANG_RC_NOP
Definition: extension-priv.h:36
EXT_LANG_RC_OK
Definition: extension-priv.h:33
extension_language_ops::breakpoint_has_cond
int(* breakpoint_has_cond)(const struct extension_language_defn *, struct breakpoint *)
Definition: extension-priv.h:222
active_ext_lang_state
Definition: extension-priv.h:337
extension_language_ops::start_type_printers
void(* start_type_printers)(const struct extension_language_defn *, struct ext_lang_type_printers *)
Definition: extension-priv.h:155
restore_active_ext_lang
void restore_active_ext_lang(struct active_ext_lang_state *previous)
Definition: extension.c:775
extension_language_ops::set_quit_flag
void(* set_quit_flag)(const struct extension_language_defn *)
Definition: extension-priv.h:248
extension_language_ops::preserve_values
void(* preserve_values)(const struct extension_language_defn *, struct objfile *objfile, htab_t copied_types)
Definition: extension-priv.h:216
EXT_LANG_RC_ERROR
Definition: extension-priv.h:45
LONGEST
long long LONGEST
Definition: common-types.h:52