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