Extension Language API
[external/binutils.git] / gdb / extension-priv.h
1 /* Private implementation details of interface between gdb and its
2    extension languages.
3
4    Copyright (C) 2013 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
28 enum ext_lang_rc
29   {
30     /* The operation completed successfully.  */
31     EXT_LANG_RC_OK,
32
33     /* The operation was not performed (e.g., no pretty-printer).  */
34     EXT_LANG_RC_NOP,
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.  */
43     EXT_LANG_RC_ERROR
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
51 struct extension_language_defn
52 {
53   /* Enum of the extension language.  */
54   enum extension_language 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.  */
74   enum command_control_type cli_control_type;
75
76   /* A pointer to the "methods" to load scripts in this language,
77      or NULL if the support is not compiled into GDB.  */
78   const struct extension_language_script_ops *script_ops;
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 struct extension_language_script_ops
92 {
93   /* Load a script.  This is called, e.g., via the "source" command.
94      If there's an error while processing the script this function may,
95      but is not required to, throw an error.  */
96   script_sourcer_func *script_sourcer;
97
98   /* Load a script attached to an objfile.
99      If there's an error while processing the script this function may,
100      but is not required to, throw an error.  */
101   objfile_script_sourcer_func *objfile_script_sourcer;
102
103   /* Return non-zero if auto-loading scripts in this extension language
104      is enabled.  */
105   int (*auto_load_enabled) (const struct extension_language_defn *);
106 };
107
108 /* The interface for making calls from GDB to an external extension
109    language.  This is for non-script-loading related functionality, like
110    pretty-printing, etc.  The reason these are separated out is GDB's own
111    scripting language makes use of extension_language_script_opts, but it
112    makes no use of these.  There is no (current) intention to split
113    extension_language_ops up any further.
114    All of these methods are optional and may be NULL, except where
115    otherwise indicated.  */
116
117 struct extension_language_ops
118 {
119   /* Called at the end of gdb initialization to give the extension language
120      an opportunity to finish up.  This is useful for things like adding
121      new commands where one has to wait until gdb itself is initialized.  */
122   void (*finish_initialization) (const struct extension_language_defn *);
123
124   /* Return non-zero if the extension language successfully initialized.
125      This method is required.  */
126   int (*initialized) (const struct extension_language_defn *);
127
128   /* Process a sequence of commands embedded in GDB's own scripting language.
129      E.g.,
130      python
131      print 42
132      end  */
133   void (*eval_from_control_command) (const struct extension_language_defn *,
134                                      struct command_line *);
135
136   /* Type-printing support:
137      start_type_printers, apply_type_printers, free_type_printers.
138      These methods are optional and may be NULL, but if one of them is
139      implemented then they all must be.  */
140
141   /* Called before printing a type.  */
142   void (*start_type_printers) (const struct extension_language_defn *,
143                                struct ext_lang_type_printers *);
144
145   /* Try to pretty-print TYPE.  If successful the pretty-printed type is
146      stored in *PRETTIED_TYPE, and the caller must free it.
147      Returns EXT_LANG_RC_OK upon success, EXT_LANG_RC_NOP if the type
148      is not recognized, and EXT_LANG_RC_ERROR if an error was encountered.
149      This function has a bit of a funny name, since it actually applies
150      recognizers, but this seemed clearer given the start_type_printers
151      and free_type_printers functions.  */
152   enum ext_lang_rc (*apply_type_printers)
153     (const struct extension_language_defn *,
154      const struct ext_lang_type_printers *,
155      struct type *, char **prettied_type);
156
157   /* Called after a type has been printed to give the type pretty-printer
158      mechanism an opportunity to clean up.  */
159   void (*free_type_printers) (const struct extension_language_defn *,
160                               struct ext_lang_type_printers *);
161
162   /* Try to pretty-print a value of type TYPE located at VALADDR
163      + EMBEDDED_OFFSET, which came from the inferior at address ADDRESS
164      + EMBEDDED_OFFSET, onto stdio stream STREAM according to OPTIONS.
165      VAL is the whole object that came from ADDRESS.  VALADDR must point to
166      the head of VAL's contents buffer.
167      Returns EXT_LANG_RC_OK upon success, EXT_LANG_RC_NOP if the value
168      is not recognized, and EXT_LANG_RC_ERROR if an error was encountered.  */
169   enum ext_lang_rc (*apply_val_pretty_printer)
170     (const struct extension_language_defn *,
171      struct type *type, const gdb_byte *valaddr,
172      int embedded_offset, CORE_ADDR address,
173      struct ui_file *stream, int recurse,
174      const struct value *val, const struct value_print_options *options,
175      const struct language_defn *language);
176
177   /* GDB access to the "frame filter" feature.
178      FRAME is the source frame to start frame-filter invocation.  FLAGS is an
179      integer holding the flags for printing.  The following elements of
180      the FRAME_FILTER_FLAGS enum denotes the make-up of FLAGS:
181      PRINT_LEVEL is a flag indicating whether to print the frame's
182      relative level in the output.  PRINT_FRAME_INFO is a flag that
183      indicates whether this function should print the frame
184      information, PRINT_ARGS is a flag that indicates whether to print
185      frame arguments, and PRINT_LOCALS, likewise, with frame local
186      variables.  ARGS_TYPE is an enumerator describing the argument
187      format, OUT is the output stream to print.  FRAME_LOW is the
188      beginning of the slice of frames to print, and FRAME_HIGH is the
189      upper limit of the frames to count.  Returns SCR_BT_ERROR on error,
190      or SCR_BT_COMPLETED on success.  */
191   enum ext_lang_bt_status (*apply_frame_filter)
192     (const struct extension_language_defn *,
193      struct frame_info *frame, int flags, enum ext_lang_frame_args args_type,
194      struct ui_out *out, int frame_low, int frame_high);
195
196   /* Update values held by the extension language when OBJFILE is discarded.
197      New global types must be created for every such value, which must then be
198      updated to use the new types.
199      This function typically just iterates over all appropriate values and
200      calls preserve_one_value for each one.
201      COPIED_TYPES is used to prevent cycles / duplicates and is passed to
202      preserve_one_value.  */
203   void (*preserve_values) (const struct extension_language_defn *,
204                            struct objfile *objfile, htab_t copied_types);
205
206   /* Return non-zero if there is a stop condition for the breakpoint.
207      This is used to implement the restriction that a breakpoint may have
208      at most one condition.  */
209   int (*breakpoint_has_cond) (const struct extension_language_defn *,
210                               struct breakpoint *);
211
212   /* Return a value of enum ext_lang_bp_stop indicating if there is a stop
213      condition for the breakpoint, and if so whether the program should
214      stop.  This is called when the program has stopped at the specified
215      breakpoint.
216      While breakpoints can have at most one condition, this is called for
217      every extension language, even if another extension language has a
218      "stop" method: other kinds of breakpoints may be implemented using
219      this method, e.g., "finish breakpoints" in Python.  */
220   enum ext_lang_bp_stop (*breakpoint_cond_says_stop)
221     (const struct extension_language_defn *, struct breakpoint *);
222
223   /* The next three are used to connect GDB's SIGINT handling with the
224      extension language's.
225
226      Terminology: If an extension language can use GDB's SIGINT handling then
227      we say the extension language has "cooperative SIGINT handling".
228      Python is an example of this.
229
230      These need not be implemented, but if one of them is implemented
231      then they all must be.  */
232
233   /* Clear the SIGINT indicator.  */
234   void (*clear_quit_flag) (const struct extension_language_defn *);
235
236   /* Set the SIGINT indicator.
237      This is called by GDB's SIGINT handler and must be async-safe.  */
238   void (*set_quit_flag) (const struct extension_language_defn *);
239
240   /* Return non-zero if a SIGINT has occurred.
241      This is expected to also clear the indicator.  */
242   int (*check_quit_flag) (const struct extension_language_defn *);
243
244   /* Called before gdb prints its prompt, giving extension languages an
245      opportunity to change it with set_prompt.
246      Returns EXT_LANG_RC_OK if the prompt was changed, EXT_LANG_RC_NOP if
247      the prompt was not changed, and EXT_LANG_RC_ERROR if an error was
248      encountered.
249      Extension languages are called in order, and once the prompt is
250      changed or an error occurs no further languages are called.  */
251   enum ext_lang_rc (*before_prompt) (const struct extension_language_defn *,
252                                      const char *current_gdb_prompt);
253 };
254
255 /* State necessary to restore a signal handler to its previous value.  */
256
257 struct signal_handler
258 {
259   /* Non-zero if "handler" has been set.  */
260   int handler_saved;
261
262   /* The signal handler.  */
263   RETSIGTYPE (*handler) ();
264 };
265
266 /* State necessary to restore the currently active extension language
267    to is previous value.  */
268
269 struct active_ext_lang_state
270 {
271   /* The previously active extension language.  */
272   const struct extension_language_defn *ext_lang;
273
274   /* Its SIGINT handler.  */
275   struct signal_handler sigint_handler;
276 };
277
278 extern const struct extension_language_defn *get_active_ext_lang (void);
279
280 extern struct active_ext_lang_state *set_active_ext_lang
281   (const struct extension_language_defn *);
282
283 extern void restore_active_ext_lang (struct active_ext_lang_state *previous);
284
285 #endif /* EXTENSION_PRIV_H */