1 /* Private implementation details of interface between gdb and its
4 Copyright (C) 2014-2019 Free Software Foundation, Inc.
6 This file is part of GDB.
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.
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.
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/>. */
21 #ifndef EXTENSION_PRIV_H
22 #define EXTENSION_PRIV_H
26 /* Local non-gdb includes. */
27 #include "cli/cli-script.h"
28 #include "extension.h"
30 /* High level description of an extension/scripting language.
31 An entry for each is compiled into GDB regardless of whether the support
32 is present. This is done so that we can issue meaningful errors if the
33 support is not compiled in. */
35 struct extension_language_defn
37 /* Enum of the extension language. */
38 enum extension_language language;
40 /* The name of the extension language, lowercase. E.g., python. */
43 /* The capitalized name of the extension language.
44 For python this is "Python". For gdb this is "GDB". */
45 const char *capitalized_name;
47 /* The file suffix of this extension language. E.g., ".py". */
50 /* The suffix of per-objfile scripts to auto-load.
51 E.g., When the program loads libfoo.so, look for libfoo.so-gdb.py. */
52 const char *auto_load_suffix;
54 /* We support embedding external extension language code in GDB's own
55 scripting language. We do this by having a special command that begins
56 the extension language snippet, and terminate it with "end".
57 This specifies the control type used to implement this. */
58 enum command_control_type cli_control_type;
60 /* A pointer to the "methods" to load scripts in this language,
61 or NULL if the support is not compiled into GDB. */
62 const struct extension_language_script_ops *script_ops;
64 /* Either a pointer to the "methods" of the extension language interface
65 or NULL if the support is not compiled into GDB.
66 This is also NULL for GDB's own scripting language which is relatively
67 primitive, and doesn't provide these features. */
68 const struct extension_language_ops *ops;
71 /* The interface for loading scripts from external extension languages,
72 as well as GDB's own scripting language.
73 All of these methods are required to be implemented.
75 By convention all of these functions take a pseudo-this parameter
76 as the first argument. */
78 struct extension_language_script_ops
80 /* Load a script. This is called, e.g., via the "source" command.
81 If there's an error while processing the script this function may,
82 but is not required to, throw an error. */
83 script_sourcer_func *script_sourcer;
85 /* Load a script attached to an objfile.
86 If there's an error while processing the script this function may,
87 but is not required to, throw an error. */
88 objfile_script_sourcer_func *objfile_script_sourcer;
90 /* Execute a script attached to an objfile.
91 If there's an error while processing the script this function may,
92 but is not required to, throw an error. */
93 objfile_script_executor_func *objfile_script_executor;
95 /* Return non-zero if auto-loading scripts in this extension language
97 int (*auto_load_enabled) (const struct extension_language_defn *);
100 /* The interface for making calls from GDB to an external extension
101 language. This is for non-script-loading related functionality, like
102 pretty-printing, etc. The reason these are separated out is GDB's own
103 scripting language makes use of extension_language_script_opts, but it
104 makes no use of these. There is no (current) intention to split
105 extension_language_ops up any further.
106 All of these methods are optional and may be NULL, except where
109 By convention all of these functions take a pseudo-this parameter
110 as the first argument. */
112 struct extension_language_ops
114 /* Called at the end of gdb initialization to give the extension language
115 an opportunity to finish up. This is useful for things like adding
116 new commands where one has to wait until gdb itself is initialized. */
117 void (*finish_initialization) (const struct extension_language_defn *);
119 /* Return non-zero if the extension language successfully initialized.
120 This method is required. */
121 int (*initialized) (const struct extension_language_defn *);
123 /* Process a sequence of commands embedded in GDB's own scripting language.
128 void (*eval_from_control_command) (const struct extension_language_defn *,
129 struct command_line *);
131 /* Type-printing support:
132 start_type_printers, apply_type_printers, free_type_printers.
133 These methods are optional and may be NULL, but if one of them is
134 implemented then they all must be. */
136 /* Called before printing a type. */
137 void (*start_type_printers) (const struct extension_language_defn *,
138 struct ext_lang_type_printers *);
140 /* Try to pretty-print TYPE. If successful the pretty-printed type is
141 stored in *PRETTIED_TYPE, and the caller must free it.
142 Returns EXT_LANG_RC_OK upon success, EXT_LANG_RC_NOP if the type
143 is not recognized, and EXT_LANG_RC_ERROR if an error was encountered.
144 This function has a bit of a funny name, since it actually applies
145 recognizers, but this seemed clearer given the start_type_printers
146 and free_type_printers functions. */
147 enum ext_lang_rc (*apply_type_printers)
148 (const struct extension_language_defn *,
149 const struct ext_lang_type_printers *,
150 struct type *, char **prettied_type);
152 /* Called after a type has been printed to give the type pretty-printer
153 mechanism an opportunity to clean up. */
154 void (*free_type_printers) (const struct extension_language_defn *,
155 struct ext_lang_type_printers *);
157 /* Try to pretty-print a value of type TYPE located at VAL's contents
158 buffer + EMBEDDED_OFFSET, which came from the inferior at address
159 ADDRESS + EMBEDDED_OFFSET, onto stdio stream STREAM according to
161 VAL is the whole object that came from ADDRESS.
162 Returns EXT_LANG_RC_OK upon success, EXT_LANG_RC_NOP if the value
163 is not recognized, and EXT_LANG_RC_ERROR if an error was encountered. */
164 enum ext_lang_rc (*apply_val_pretty_printer)
165 (const struct extension_language_defn *,
167 LONGEST embedded_offset, CORE_ADDR address,
168 struct ui_file *stream, int recurse,
169 struct value *val, const struct value_print_options *options,
170 const struct language_defn *language);
172 /* GDB access to the "frame filter" feature.
173 FRAME is the source frame to start frame-filter invocation. FLAGS is an
174 integer holding the flags for printing. The following elements of
175 the FRAME_FILTER_FLAGS enum denotes the make-up of FLAGS:
176 PRINT_LEVEL is a flag indicating whether to print the frame's
177 relative level in the output. PRINT_FRAME_INFO is a flag that
178 indicates whether this function should print the frame
179 information, PRINT_ARGS is a flag that indicates whether to print
180 frame arguments, and PRINT_LOCALS, likewise, with frame local
181 variables. ARGS_TYPE is an enumerator describing the argument
182 format, OUT is the output stream to print. FRAME_LOW is the
183 beginning of the slice of frames to print, and FRAME_HIGH is the
184 upper limit of the frames to count. Returns SCR_BT_ERROR on error,
185 or SCR_BT_COMPLETED on success. */
186 enum ext_lang_bt_status (*apply_frame_filter)
187 (const struct extension_language_defn *,
188 struct frame_info *frame, frame_filter_flags flags,
189 enum ext_lang_frame_args args_type,
190 struct ui_out *out, int frame_low, int frame_high);
192 /* Update values held by the extension language when OBJFILE is discarded.
193 New global types must be created for every such value, which must then be
194 updated to use the new types.
195 This function typically just iterates over all appropriate values and
196 calls preserve_one_value for each one.
197 COPIED_TYPES is used to prevent cycles / duplicates and is passed to
198 preserve_one_value. */
199 void (*preserve_values) (const struct extension_language_defn *,
200 struct objfile *objfile, htab_t copied_types);
202 /* Return non-zero if there is a stop condition for the breakpoint.
203 This is used to implement the restriction that a breakpoint may have
204 at most one condition. */
205 int (*breakpoint_has_cond) (const struct extension_language_defn *,
206 struct breakpoint *);
208 /* Return a value of enum ext_lang_bp_stop indicating if there is a stop
209 condition for the breakpoint, and if so whether the program should
210 stop. This is called when the program has stopped at the specified
212 While breakpoints can have at most one condition, this is called for
213 every extension language, even if another extension language has a
214 "stop" method: other kinds of breakpoints may be implemented using
215 this method, e.g., "finish breakpoints" in Python. */
216 enum ext_lang_bp_stop (*breakpoint_cond_says_stop)
217 (const struct extension_language_defn *, struct breakpoint *);
219 /* The next two are used to connect GDB's SIGINT handling with the
220 extension language's.
222 Terminology: If an extension language can use GDB's SIGINT handling then
223 we say the extension language has "cooperative SIGINT handling".
224 Python is an example of this.
226 These need not be implemented, but if one of them is implemented
227 then they all must be. */
229 /* Set the SIGINT indicator.
230 This is called by GDB's SIGINT handler and must be async-safe. */
231 void (*set_quit_flag) (const struct extension_language_defn *);
233 /* Return non-zero if a SIGINT has occurred.
234 This is expected to also clear the indicator. */
235 int (*check_quit_flag) (const struct extension_language_defn *);
237 /* Called before gdb prints its prompt, giving extension languages an
238 opportunity to change it with set_prompt.
239 Returns EXT_LANG_RC_OK if the prompt was changed, EXT_LANG_RC_NOP if
240 the prompt was not changed, and EXT_LANG_RC_ERROR if an error was
242 Extension languages are called in order, and once the prompt is
243 changed or an error occurs no further languages are called. */
244 enum ext_lang_rc (*before_prompt) (const struct extension_language_defn *,
245 const char *current_gdb_prompt);
247 /* Return a vector of matching xmethod workers defined in this
248 extension language. The workers service methods with name
249 METHOD_NAME on objects of type OBJ_TYPE. The vector is returned
252 This field may be NULL if the extension language does not support
254 enum ext_lang_rc (*get_matching_xmethod_workers)
255 (const struct extension_language_defn *extlang,
256 struct type *obj_type,
257 const char *method_name,
258 std::vector<xmethod_worker_up> *dm_vec);
261 /* State necessary to restore a signal handler to its previous value. */
263 struct signal_handler
265 /* Non-zero if "handler" has been set. */
268 /* The signal handler. */
269 sighandler_t handler;
272 /* State necessary to restore the currently active extension language
273 to its previous value. */
275 struct active_ext_lang_state
277 /* The previously active extension language. */
278 const struct extension_language_defn *ext_lang;
280 /* Its SIGINT handler. */
281 struct signal_handler sigint_handler;
284 extern const struct extension_language_defn *get_active_ext_lang (void);
286 extern struct active_ext_lang_state *set_active_ext_lang
287 (const struct extension_language_defn *);
289 extern void restore_active_ext_lang (struct active_ext_lang_state *previous);
291 #endif /* EXTENSION_PRIV_H */