1 /* Private implementation details of interface between gdb and its 2 extension languages. 3 4 Copyright (C) 2014-2024 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 /* High level description of an extension/scripting language. 29 An entry for each is compiled into GDB regardless of whether the support 30 is present. This is done so that we can issue meaningful errors if the 31 support is not compiled in. */ 32 33 struct extension_language_defn 34 { 35 /* Enum of the extension language. */ 36 enum extension_language language; 37 38 /* The name of the extension language, lowercase. E.g., python. */ 39 const char *name; 40 41 /* The capitalized name of the extension language. 42 For python this is "Python". For gdb this is "GDB". */ 43 const char *capitalized_name; 44 45 /* The file suffix of this extension language. E.g., ".py". */ 46 const char *suffix; 47 48 /* The suffix of per-objfile scripts to auto-load. 49 E.g., When the program loads libfoo.so, look for libfoo.so-gdb.py. */ 50 const char *auto_load_suffix; 51 52 /* We support embedding external extension language code in GDB's own 53 scripting language. We do this by having a special command that begins 54 the extension language snippet, and terminate it with "end". 55 This specifies the control type used to implement this. */ 56 enum command_control_type cli_control_type; 57 58 /* A pointer to the "methods" to load scripts in this language, 59 or NULL if the support is not compiled into GDB. */ 60 const struct extension_language_script_ops *script_ops; 61 62 /* Either a pointer to the "methods" of the extension language interface 63 or NULL if the support is not compiled into GDB. 64 This is also NULL for GDB's own scripting language which is relatively 65 primitive, and doesn't provide these features. */ 66 const struct extension_language_ops *ops; 67 }; 68 69 /* The interface for loading scripts from external extension languages, 70 as well as GDB's own scripting language. 71 All of these methods are required to be implemented. 72 73 By convention all of these functions take a pseudo-this parameter 74 as the first argument. */ 75 76 struct extension_language_script_ops 77 { 78 /* Load a script. This is called, e.g., via the "source" command. 79 If there's an error while processing the script this function may, 80 but is not required to, throw an error. */ 81 script_sourcer_func *script_sourcer; 82 83 /* Load a script attached to an objfile. 84 If there's an error while processing the script this function may, 85 but is not required to, throw an error. */ 86 objfile_script_sourcer_func *objfile_script_sourcer; 87 88 /* Execute a script attached to an objfile. 89 If there's an error while processing the script this function may, 90 but is not required to, throw an error. */ 91 objfile_script_executor_func *objfile_script_executor; 92 93 /* Return non-zero if auto-loading scripts in this extension language 94 is enabled. */ 95 bool (*auto_load_enabled) (const struct extension_language_defn *); 96 }; 97 98 /* The interface for making calls from GDB to an external extension 99 language. This is for non-script-loading related functionality, like 100 pretty-printing, etc. The reason these are separated out is GDB's own 101 scripting language makes use of extension_language_script_opts, but it 102 makes no use of these. There is no (current) intention to split 103 extension_language_ops up any further. 104 All of these methods are optional and may be NULL, except where 105 otherwise indicated. 106 107 By convention all of these functions take a pseudo-this parameter 108 as the first argument. */ 109 110 struct extension_language_ops 111 { 112 /* Called after GDB has processed the early initialization settings 113 files. This is when the extension language should be initialized. By 114 the time this is called all of the earlier initialization functions 115 have already been called. */ 116 void (*initialize) (const struct extension_language_defn *); 117 118 /* Return non-zero if the extension language successfully initialized. 119 This method is required. */ 120 int (*initialized) (const struct extension_language_defn *); 121 122 /* Called just before GDB exits. This shuts down the extension 123 language. This can be NULL. */ 124 void (*shutdown) (const struct extension_language_defn *); 125 126 /* Process a sequence of commands embedded in GDB's own scripting language. 127 E.g., 128 python 129 print 42 130 end */ 131 void (*eval_from_control_command) (const struct extension_language_defn *, 132 struct command_line *); 133 134 /* Type-printing support: 135 start_type_printers, apply_type_printers, free_type_printers. 136 These methods are optional and may be NULL, but if one of them is 137 implemented then they all must be. */ 138 139 /* Called before printing a type. */ 140 void (*start_type_printers) (const struct extension_language_defn *, 141 struct ext_lang_type_printers *); 142 143 /* Try to pretty-print TYPE. If successful the pretty-printed type is 144 stored in *PRETTIED_TYPE. 145 Returns EXT_LANG_RC_OK upon success, EXT_LANG_RC_NOP if the type 146 is not recognized, and EXT_LANG_RC_ERROR if an error was encountered. 147 This function has a bit of a funny name, since it actually applies 148 recognizers, but this seemed clearer given the start_type_printers 149 and free_type_printers functions. */ 150 enum ext_lang_rc (*apply_type_printers) 151 (const struct extension_language_defn *, 152 const struct ext_lang_type_printers *, 153 struct type *, 154 gdb::unique_xmalloc_ptr<char> *prettied_type); 155 156 /* Called after a type has been printed to give the type pretty-printer 157 mechanism an opportunity to clean up. */ 158 void (*free_type_printers) (const struct extension_language_defn *, 159 struct ext_lang_type_printers *); 160 161 /* Try to pretty-print a value, onto stdio stream STREAM according 162 to OPTIONS. VAL is the object to print. Returns EXT_LANG_RC_OK 163 upon success, EXT_LANG_RC_NOP if the value is not recognized, and 164 EXT_LANG_RC_ERROR if an error was encountered. */ 165 enum ext_lang_rc (*apply_val_pretty_printer) 166 (const struct extension_language_defn *, 167 struct value *val, struct ui_file *stream, int recurse, 168 const struct value_print_options *options, 169 const struct language_defn *language); 170 171 /* GDB access to the "frame filter" feature. 172 FRAME is the source frame to start frame-filter invocation. FLAGS is an 173 integer holding the flags for printing. The following elements of 174 the FRAME_FILTER_FLAGS enum denotes the make-up of FLAGS: 175 PRINT_LEVEL is a flag indicating whether to print the frame's 176 relative level in the output. PRINT_FRAME_INFO is a flag that 177 indicates whether this function should print the frame 178 information, PRINT_ARGS is a flag that indicates whether to print 179 frame arguments, and PRINT_LOCALS, likewise, with frame local 180 variables. ARGS_TYPE is an enumerator describing the argument 181 format, OUT is the output stream to print. FRAME_LOW is the 182 beginning of the slice of frames to print, and FRAME_HIGH is the 183 upper limit of the frames to count. Returns SCR_BT_ERROR on error, 184 or SCR_BT_COMPLETED on success. */ 185 enum ext_lang_bt_status (*apply_frame_filter) 186 (const struct extension_language_defn *, 187 const frame_info_ptr &frame, frame_filter_flags flags, 188 enum ext_lang_frame_args args_type, 189 struct ui_out *out, int frame_low, int frame_high); 190 191 /* Update values held by the extension language when OBJFILE is discarded. 192 New global types must be created for every such value, which must then be 193 updated to use the new types. 194 This function typically just iterates over all appropriate values and 195 calls preserve_one_value for each one. 196 COPIED_TYPES is used to prevent cycles / duplicates and is passed to 197 preserve_one_value. */ 198 void (*preserve_values) (const struct extension_language_defn *, 199 struct objfile *objfile, htab_t copied_types); 200 201 /* Return non-zero if there is a stop condition for the breakpoint. 202 This is used to implement the restriction that a breakpoint may have 203 at most one condition. */ 204 int (*breakpoint_has_cond) (const struct extension_language_defn *, 205 struct breakpoint *); 206 207 /* Return a value of enum ext_lang_bp_stop indicating if there is a stop 208 condition for the breakpoint, and if so whether the program should 209 stop. This is called when the program has stopped at the specified 210 breakpoint. 211 While breakpoints can have at most one condition, this is called for 212 every extension language, even if another extension language has a 213 "stop" method: other kinds of breakpoints may be implemented using 214 this method, e.g., "finish breakpoints" in Python. */ 215 enum ext_lang_bp_stop (*breakpoint_cond_says_stop) 216 (const struct extension_language_defn *, struct breakpoint *); 217 218 /* The next two are used to connect GDB's SIGINT handling with the 219 extension language's. 220 221 Terminology: If an extension language can use GDB's SIGINT handling then 222 we say the extension language has "cooperative SIGINT handling". 223 Python is an example of this. 224 225 These need not be implemented, but if one of them is implemented 226 then they all must be. */ 227 228 /* Set the SIGINT indicator. 229 This is called by GDB's SIGINT handler and must be async-safe. */ 230 void (*set_quit_flag) (const struct extension_language_defn *); 231 232 /* Return true if a SIGINT has occurred. 233 This is expected to also clear the indicator. */ 234 bool (*check_quit_flag) (const struct extension_language_defn *); 235 236 /* Called before gdb prints its prompt, giving extension languages an 237 opportunity to change it with set_prompt. 238 Returns EXT_LANG_RC_OK if the prompt was changed, EXT_LANG_RC_NOP if 239 the prompt was not changed, and EXT_LANG_RC_ERROR if an error was 240 encountered. 241 Extension languages are called in order, and once the prompt is 242 changed or an error occurs no further languages are called. */ 243 enum ext_lang_rc (*before_prompt) (const struct extension_language_defn *, 244 const char *current_gdb_prompt); 245 246 /* Return a vector of matching xmethod workers defined in this 247 extension language. The workers service methods with name 248 METHOD_NAME on objects of type OBJ_TYPE. The vector is returned 249 in DM_VEC. 250 251 This field may be NULL if the extension language does not support 252 xmethods. */ 253 enum ext_lang_rc (*get_matching_xmethod_workers) 254 (const struct extension_language_defn *extlang, 255 struct type *obj_type, 256 const char *method_name, 257 std::vector<xmethod_worker_up> *dm_vec); 258 259 /* Colorize a source file. NAME is the source file's name, and 260 CONTENTS is the contents of the file. This should either return 261 colorized (using ANSI terminal escapes) version of the contents, 262 or an empty option. */ 263 std::optional<std::string> (*colorize) (const std::string &name, 264 const std::string &contents); 265 266 /* Colorize a single line of disassembler output, CONTENT. This should 267 either return colorized (using ANSI terminal escapes) version of the 268 contents, or an empty optional. */ 269 std::optional<std::string> (*colorize_disasm) (const std::string &content, 270 gdbarch *gdbarch); 271 272 /* Print a single instruction from ADDRESS in architecture GDBARCH. INFO 273 is the standard libopcodes disassembler_info structure. Bytes for the 274 instruction being printed should be read using INFO->read_memory_func 275 as the actual instruction bytes might be in a buffer. 276 277 Use INFO->fprintf_func to print the results of the disassembly, and 278 return the length of the instruction. 279 280 If no instruction can be disassembled then return an empty value and 281 other extension languages will get a chance to perform the 282 disassembly. */ 283 std::optional<int> (*print_insn) (struct gdbarch *gdbarch, 284 CORE_ADDR address, 285 struct disassemble_info *info); 286 287 /* Give extension languages a chance to deal with missing debug 288 information. OBJFILE is the file for which GDB was unable to find 289 any debug information. */ 290 ext_lang_missing_debuginfo_result 291 (*handle_missing_debuginfo) (const struct extension_language_defn *, 292 struct objfile *objfile); 293 }; 294 295 /* State necessary to restore a signal handler to its previous value. */ 296 297 struct signal_handler 298 { 299 /* Non-zero if "handler" has been set. */ 300 int handler_saved; 301 302 /* The signal handler. */ 303 sighandler_t handler; 304 }; 305 306 /* State necessary to restore the currently active extension language 307 to its previous value. */ 308 309 struct active_ext_lang_state 310 { 311 /* The previously active extension language. */ 312 const struct extension_language_defn *ext_lang; 313 314 /* Its SIGINT handler. */ 315 struct signal_handler sigint_handler; 316 }; 317 318 extern struct active_ext_lang_state *set_active_ext_lang 319 (const struct extension_language_defn *); 320 321 extern void restore_active_ext_lang (struct active_ext_lang_state *previous); 322 323 #endif /* EXTENSION_PRIV_H */ 324