1 #ifndef __TGDB_H__ 2 #define __TGDB_H__ 3 4 #ifdef HAVE_STDINT_H 5 #include <stdint.h> 6 #endif 7 8 /*! 9 * \file 10 * tgdb.h 11 * 12 * \brief 13 * This interface is intended to be the abstraction layer between a front end 14 * and the low level debugger the front end is trying to communicate with. 15 */ 16 17 #include "sys_util.h" 18 19 /* Basic interface types {{{ */ 20 21 // The client can give any of these commands to TGDB through 22 // tgdb_run_debugger_command. 23 enum tgdb_command_type { 24 TGDB_CONTINUE = 0, 25 TGDB_FINISH, 26 TGDB_NEXT, 27 TGDB_NEXTI, 28 TGDB_START, 29 TGDB_RUN, 30 TGDB_KILL, 31 TGDB_STEP, 32 TGDB_STEPI, 33 TGDB_UNTIL, 34 TGDB_UP, 35 TGDB_DOWN, 36 }; 37 38 // This gives the client the ability to add or remove breakpoints. 39 // Currently, enable/disable are not supported. 40 enum tgdb_breakpoint_action { 41 // Add a breakpoint 42 TGDB_BREAKPOINT_ADD, 43 // Add a temporary breakpoint 44 TGDB_TBREAKPOINT_ADD, 45 // Delete a breakpoint 46 TGDB_BREAKPOINT_DELETE, 47 }; 48 49 // This structure represents a breakpoint 50 struct tgdb_breakpoint { 51 // The path to the file. 52 // 53 // This will usually be absolute. If the absolute path is not 54 // available for GDB it will be a relative path 55 char *path; 56 57 // The line number where the breakpoint is set 58 int line; 59 60 // Line number corresponding to the $pc or 0 if unknown 61 uint64_t addr; 62 63 //0 if it is not enabled or 1 if it is enabled 64 int enabled; 65 }; 66 67 // This structure currently represents a file position. 68 // 69 // Either path or addr will be non-NULL. Never both. 70 // 71 // If the source location is available, path and line number will be valid. 72 // If the source information can not be determined, the addr will be 73 // available. It is possible they are both available. 74 struct tgdb_file_position { 75 // The path to the file. 76 // 77 // This will usually be absolute. If the absolute path is not 78 // available for GDB it will be a relative path. 79 // 80 // Will be NULL if the source information is not available 81 char *path; 82 83 // The line number in the file or 0 if unknown 84 int line_number; 85 86 // Line number corresponding to the $pc or 0 if unknown 87 uint64_t addr; 88 89 // Shared library where this function is defined or NULL if unknown 90 char *from; 91 92 // Function name or NULL if unknown 93 char *func; 94 }; 95 96 enum tgdb_request_type { 97 // Get a list of all the source files in the program being debugged 98 TGDB_REQUEST_INFO_SOURCES, 99 100 // Determine the current location of the debugged program. 101 // 102 // This is a filename and line number for source code. 103 TGDB_REQUEST_INFO_SOURCE_FILE, 104 105 // Get the list of existing breakpoints. 106 TGDB_REQUEST_BREAKPOINTS, 107 108 // Set which terminal to use for future runs of program being debugged. 109 // 110 // This allows tgdb to separate the output of gdb from the output 111 // of the program being debugged. 112 TGDB_REQUEST_TTY, 113 114 // Get information about the current frame. 115 // 116 // Generally useful for finding the current location of the program 117 // that is being debugged. 118 TGDB_REQUEST_INFO_FRAME, 119 120 // Query if the CLI disassemble command supports mixed source+assembly. 121 // 122 // Mixed source+assembly mode was added as the /s flag to the CLI 123 // disassemble command and as mode 4 to the MI -data-disassemble 124 // command. 125 // 126 // We query the MI command to determine if it supports mode 4, and 127 // if it does, we also know that the CLI disassemble command supports 128 // /s. 129 // 130 // The passing case, 131 // (gdb) interpreter-exec mi "-data-disassemble -s 0 -e 0 -- 4" 132 // ^done,asm_insns=[] 133 // 134 // The failing case, 135 // (gdb) interpreter-exec mi "-data-disassemble -s 0 -e 0 -- 4" 136 // ^error,msg="-data-disassemble: Mode argument must 137 // be 0, 1, 2, or 3." 138 // 139 // If the command comes back as an MI error, we assume /s is not 140 // supported. 141 // 142 // This functionality was added in gdb in commit 6ff0ba5f. 143 TGDB_REQUEST_DATA_DISASSEMBLE_MODE_QUERY, 144 145 // Run a debugger command through gdb. 146 // 147 // This is when the caller wants to run a command through gdb, 148 // next, step, finish, but without the user typing it at the 149 // console. For instance, a cgdb shortcut like F8. 150 TGDB_REQUEST_DEBUGGER_COMMAND, 151 152 // Request that a breakpoint be modified. 153 // 154 // Useful for creating, deleting and disabling breakpoints. 155 TGDB_REQUEST_MODIFY_BREAKPOINT, 156 157 // Request GDB to disassemble the function surrounding the pc of the 158 // selected frame. 159 TGDB_REQUEST_DISASSEMBLE_PC, 160 161 // Request GDB to disassemble a function. 162 TGDB_REQUEST_DISASSEMBLE_FUNC 163 }; 164 165 // This is the commands interface used between the front end and TGDB. 166 // When TGDB is responding to a request or when an event is being generated 167 // the front end will find out about it through one of these enums. 168 enum tgdb_response_type { 169 170 // All breakpoints that are set 171 TGDB_UPDATE_BREAKPOINTS, 172 173 // This tells the gui what filename/line number the debugger is on. 174 // It gets generated whenever it changes. 175 // This is a 'struct tgdb_file_position *'. 176 TGDB_UPDATE_FILE_POSITION, 177 178 // This returns a list of all the source files that make up the 179 // inferior program. 180 TGDB_UPDATE_SOURCE_FILES, 181 182 // Disassemble $pc output 183 TGDB_DISASSEMBLE_PC, 184 185 // Disassemble function output 186 TGDB_DISASSEMBLE_FUNC, 187 188 // This happens when gdb quits. 189 // You will get no more responses after this one. 190 // This is a 'struct tgdb_quit_status *' 191 TGDB_QUIT 192 }; 193 194 // A single TGDB response for the front end. 195 struct tgdb_response { 196 // This is the type of response 197 enum tgdb_response_type header; 198 199 union { 200 // header == TGDB_UPDATE_BREAKPOINTS 201 struct { 202 // This list has elements of 'struct tgdb_breakpoint *' 203 // representing each breakpoint 204 struct tgdb_breakpoint *breakpoints; 205 } update_breakpoints; 206 207 // header == TGDB_UPDATE_FILE_POSITION 208 struct { 209 struct tgdb_file_position *file_position; 210 } update_file_position; 211 212 // header == TGDB_UPDATE_SOURCE_FILES 213 struct { 214 // This list has elements of 'const char *' representing each 215 // filename. The filename may be relative or absolute. 216 char **source_files; 217 } update_source_files; 218 219 // header == TGDB_INFERIOR_EXITED 220 struct { 221 int exit_status; 222 } inferior_exited; 223 224 // header == TGDB_DISASSEMBLE_FUNC 225 struct { 226 uint64_t addr_start; 227 uint64_t addr_end; 228 int error; 229 char **disasm; 230 } disassemble_function; 231 232 // header == TGDB_QUIT 233 struct { 234 // If the GDB being used is pre new-ui, before GDB 7.12 235 // then it is unsupported, and this will be set to true. 236 // Otherwise, this will be set to false. 237 bool new_ui_unsupported; 238 } quit; 239 240 } choice; 241 }; 242 243 /* }}} */ 244 245 /* Creating and Destroying a libtgdb context. {{{*/ 246 /******************************************************************************/ 247 /** 248 * @name Creating and Destroying a libtgdb context. 249 * These functions are for createing and destroying a tgdb context. 250 */ 251 /******************************************************************************/ 252 253 /*@{*/ 254 255 /** 256 * This struct is a reference to a libtgdb instance. 257 */ 258 struct tgdb; 259 260 261 struct tgdb_callbacks { 262 /** 263 * An arbitrary pointer to associate with the callbacks. 264 */ 265 void *context; 266 267 /** 268 * Output is available for the console. 269 * 270 * @param context 271 * The context pointer 272 * 273 * @param str 274 * The console output 275 */ 276 void (*console_output_callback)(void *context, const std::string &str); 277 278 /** 279 * A command response is available for consumption. 280 * 281 * @param context 282 * The tgdb instance to operate on 283 * 284 * @param response 285 * The response to consume. This response is only valid for use 286 * during this callback function. It is freed by tgdb afterwards. 287 */ 288 void (*command_response_callback)(void *context, 289 struct tgdb_response *response); 290 }; 291 292 /** 293 * This initializes a tgdb library instance. 294 * 295 * \param callbacks 296 * Callback functions for event driven notifications 297 * 298 * @return 299 * NULL on error, a valid context on success. 300 */ 301 struct tgdb *tgdb_initialize(tgdb_callbacks callbacks); 302 303 /** 304 * This will terminate a libtgdb session. No functions should be called on 305 * the tgdb context passed into this function after this call. 306 * 307 * \param tgdb 308 * An instance of the tgdb library to operate on. 309 * 310 * @return 311 * 0 on success or -1 on error 312 */ 313 int tgdb_shutdown(struct tgdb *tgdb); 314 315 /* Close tgdb logfiles. This should happen after tgdb_shutdown() and all 316 * other shutdown which might use logfiles. Right before exit() works great. 317 */ 318 void tgdb_close_logfiles(); 319 320 /*@}*/ 321 /* }}}*/ 322 323 /* Input/Output commands {{{*/ 324 /******************************************************************************/ 325 /** 326 * @name Input/Output commands 327 * These functions are for communicating I/O with the tgdb context. 328 */ 329 /******************************************************************************/ 330 331 /*@{*/ 332 333 // Start the debugger 334 // 335 // Returns all file descriptors the client must select on. 336 // 337 // @param tgdb 338 // An instance of the tgdb library to operate on. 339 // 340 // @param debugger 341 // The path to the desired debugger to use. 342 // If this is NULL, then just "gdb" is used. 343 // 344 // @param argc 345 // The number of arguments to pass to the debugger 346 // 347 // @param argv 348 // The arguments to pass to the debugger 349 // 350 // @param gdb_win_rows 351 // The number of rows in the gdb console 352 // 353 // @param gdb_win_cols 354 // The number of columns in the gdb console 355 // 356 // @param gdb_console_fd 357 // The gdb console file descriptor 358 // 359 // @param gdb_mi_fd 360 // The gdb machine interface file descriptor 361 int tgdb_start_gdb(struct tgdb *tgdb, 362 const char *debugger, int argc, char **argv, 363 int gdb_win_rows, int gdb_win_cols, int *gdb_console_fd, 364 int *gdb_mi_fd); 365 366 /** 367 * This function does most of the dirty work in TGDB. It is capable of 368 * processing the output of the debugger, to either satisfy a previously 369 * made request, or to simply get console output for the caller to have. 370 * 371 * The data returned from this function is the console output of the 372 * debugger. 373 * 374 * \param tgdb 375 * An instance of the tgdb library to operate on. 376 * 377 * \param fd 378 * The file descriptor that has input (either the console or mi). 379 * 380 * @return 381 * 0 on sucess, or -1 on error 382 */ 383 int tgdb_process(struct tgdb *tgdb, int fd); 384 385 /** 386 * Send a character to the gdb console. 387 * 388 * \param tgdb 389 * An instance of the tgdb library to operate on. 390 * 391 * \param c 392 * The character to send to the gdb console 393 * 394 * \return 395 * 0 on sucess, or -1 on error 396 */ 397 int tgdb_send_char(struct tgdb *tgdb, char c); 398 399 /** 400 * Resize the gdb console. 401 * 402 * If tgdb_start_gdb has not been called yet, this function will be a 403 * no-op. 404 * 405 * \param tgdb 406 * An instance of the tgdb library to operate on. 407 * 408 * \param rows 409 * The number of rows in the new gdb console 410 * 411 * \param cols 412 * The number of columns in the new gdb console 413 */ 414 int tgdb_resize_console(struct tgdb *tgdb, int rows, int cols); 415 416 /*@}*/ 417 /* }}}*/ 418 419 /* Functional commands {{{*/ 420 /******************************************************************************/ 421 /** 422 * @name Functional commands 423 * These functinos are used to ask the TGDB context to perform a task. 424 */ 425 /******************************************************************************/ 426 427 /*@{*/ 428 429 /** 430 * Gets a list of source files that make up the program being debugged. 431 * 432 * \param tgdb 433 * An instance of the tgdb library to operate on. 434 */ 435 void tgdb_request_inferiors_source_files(struct tgdb *tgdb); 436 437 /** 438 * Get the current location of the inferior. 439 * 440 * \param tgdb 441 * An instance of the tgdb library to operate on. 442 */ 443 void tgdb_request_current_location(struct tgdb *tgdb); 444 445 /** 446 * Request an update of the breakpoints to the front end. 447 * 448 * @param tgdb 449 * An instance of the tgdb library to operate on. 450 */ 451 void tgdb_request_breakpoints(struct tgdb *tgdb); 452 453 /** 454 * This tells libtgdb to run a command through the debugger. 455 * 456 * \param tgdb 457 * An instance of the tgdb library to operate on. 458 * 459 * \param c 460 * This is the command that libtgdb should run through the debugger. 461 */ 462 void tgdb_request_run_debugger_command(struct tgdb *tgdb, 463 enum tgdb_command_type c); 464 465 /** 466 * Modify's a breakpoint. 467 * 468 * \param tgdb 469 * An instance of the tgdb library to operate on. 470 * 471 * \param file 472 * The file to set the breakpoint in. 473 * 474 * \param line 475 * The line in FILE to set the breakpoint in. 476 * 477 * \param b 478 * Determines what the user wants to do with the breakpoint. 479 * 480 * @return 481 * Will return as a tgdb request command on success, otherwise NULL. 482 */ 483 void tgdb_request_modify_breakpoint(struct tgdb *tgdb, 484 const char *file, int line, uint64_t addr, 485 enum tgdb_breakpoint_action b); 486 487 488 /** 489 * Used to get the disassemble of the current $pc. 490 * 491 * \param tgdb 492 * An instance of the tgdb library to operate on. 493 * 494 * \param lines 495 * The number of lines to disassemble after the pc. 496 */ 497 void tgdb_request_disassemble_pc(struct tgdb *tgdb, int lines); 498 499 /** 500 * Get disassembly for entire function. 501 * 502 * \param tgdb 503 * An instance of the tgdb library to operate on. 504 */ 505 enum disassemble_func_type { 506 DISASSEMBLE_FUNC_DISASSEMBLY, 507 DISASSEMBLE_FUNC_SOURCE_LINES, 508 DISASSEMBLE_FUNC_RAW_INSTRUCTIONS, 509 }; 510 void tgdb_request_disassemble_func(struct tgdb *tgdb, 511 enum disassemble_func_type type); 512 513 /*@}*/ 514 /* }}}*/ 515 516 /* Signal Handling Support {{{*/ 517 /******************************************************************************/ 518 /** 519 * @name Signal Handling Support 520 * These functinos are used to notify TGDB of signal received. 521 */ 522 /******************************************************************************/ 523 524 /*@{*/ 525 526 /** 527 * The front end can use this function to notify libtgdb that an 528 * asynchronous event has occurred. If signal SIGNUM is relavant 529 * to libtgdb, the appropriate processing will be done. 530 * Currently, TGDB only handles SIGINT,SIGTERM and SIGQUIT. 531 * 532 * libtgdb will remove all elements from it's queue when a SIGINT 533 * is received. 534 * 535 * \param tgdb 536 * An instance of the tgdb library to operate on. 537 * 538 * \param signum 539 * The signal number SIGNUM that has occurred. 540 * 541 * @return 542 * 0 on success or -1 on error 543 */ 544 int tgdb_signal_notification(struct tgdb *tgdb, int signum); 545 546 /*@}*/ 547 /* }}}*/ 548 549 #endif /* __TGDB_H__ */ 550