1 /** 2 * Copyright 2013 Robert Rossi <bob@brasko.net> 3 * 4 * This file is an amalgamation of the source files from GDBWIRE. 5 * 6 * It was created using gdbwire 1.0 and git revision 3c5983c. 7 * 8 * GDBWIRE 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 * GDBWIRE 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 GDBWIRE. If not, see <http://www.gnu.org/licenses/>. 20 * 21 * SPDX-License-Identifier: GPL-3.0-or-later 22 */ 23 24 /***** Begin file gdbwire_sys.h **********************************************/ 25 #ifndef __GDBWIRE_SYS_H__ 26 #define __GDBWIRE_SYS_H__ 27 28 /** 29 * Supporting system functions. 30 */ 31 32 #ifdef __cplusplus 33 extern "C" { 34 #endif 35 36 /** 37 * Duplicate a string. 38 * 39 * @param str 40 * The string to duplicate 41 * 42 * @return 43 * An allocated string that must be freed. 44 * Null if out of memory or str is NULL. 45 */ 46 char *gdbwire_strdup(const char *str); 47 48 #ifdef __cplusplus 49 } 50 #endif 51 52 #endif 53 /***** End of gdbwire_sys.h **************************************************/ 54 /***** Begin file gdbwire_string.h *******************************************/ 55 #ifndef __GDBWIRE_STRING_H__ 56 #define __GDBWIRE_STRING_H__ 57 58 #ifdef __cplusplus 59 extern "C" { 60 #endif 61 62 #include <stdlib.h> 63 64 /** 65 * A dynamic string representation. 66 * 67 * To create and destroy a string use gdbwire_string_create() and 68 * gdbwire_string_destroy() respectively. 69 * 70 * This string is an abstraction of a low level C string. It supports being 71 * used as a NULL terminated c string and also as an arbitrary array of 72 * bytes. You can append to this string in either of these modes using 73 * gdbwire_string_append_cstr() or gdbwire_string_append_data(). This string 74 * automatically grows as you append data to it. Please note, the size of 75 * the string will not include the NULL terminated character when using 76 * the gdbwire_string_append_cstr() function to append data. 77 * 78 * To get access to the underlying bytes associated with this string 79 * call gdbwire_string_data(). It is OK to modify the result as long as 80 * you are careful to stay in it's valid bounds. 81 * 82 * The size (or length) of the string can be accessed through the 83 * gdbwire_string_size() function. The character pointer returned from 84 * gdbwire_string_data() is valid from the index range of 0 to 85 * gdbwire_string_size() - 1. 86 */ 87 struct gdbwire_string; 88 89 /** 90 * Create a string instance. 91 * 92 * @return 93 * A valid string instance or NULL on error. 94 */ 95 struct gdbwire_string *gdbwire_string_create(void); 96 97 /** 98 * Destroy the string instance and it's resources. 99 * 100 * @param string 101 * The string to destroy. 102 */ 103 void gdbwire_string_destroy(struct gdbwire_string *string); 104 105 /** 106 * Clear the contents of a string. 107 * 108 * Sets the string back to an empty string which also changes it's 109 * size back to zero. 110 * 111 * The capacity remains unchanged. 112 * 113 * @param string 114 * The string to clear 115 */ 116 void gdbwire_string_clear(struct gdbwire_string *string); 117 118 /** 119 * Append a c string to the string instance. 120 * 121 * @param string 122 * The string instance to append the c string to. 123 * 124 * @param cstr 125 * The c string to append to the string instance. 126 * 127 * @return 128 * 0 on success or -1 on failure. 129 */ 130 int gdbwire_string_append_cstr(struct gdbwire_string *string, const char *cstr); 131 132 /** 133 * Append a sequence of bytes to the string instance. 134 * 135 * @param string 136 * The string instance to append the sequence of bytes to. 137 * 138 * @param data 139 * The sequence of bytes to append to the string instance. This may 140 * contain NUL characters. 141 * 142 * @param size 143 * The number of bytes in data to append to the string instance. 144 * 145 * @return 146 * 0 on success or -1 on failure. 147 */ 148 int gdbwire_string_append_data(struct gdbwire_string *string, 149 const char *data, size_t size); 150 151 /** 152 * Get the data associated with this string. 153 * 154 * The data could be formatted as a NULL terminated C string or 155 * as an arbitrary array of bytes. Use gdbwire_string_size() to 156 * determine the size (or length) of the result of this function. 157 * 158 * Modifying the return value of this function is acceptable as long as you 159 * stay in the string's valid bounds. 160 * 161 * @param string 162 * The string index to get the pointer data from. 163 * 164 * @return 165 * The data that has been added to this string instance or "" after 166 * creation or clear. The result is gdbwire_string_size() bytes long. 167 */ 168 char *gdbwire_string_data(struct gdbwire_string *string); 169 170 /** 171 * Determine the size (the number of bytes) this string instance represents. 172 * 173 * Please note, the result of this function will not include the NULL 174 * terminated character when using the gdbwire_string_append_cstr() function 175 * to append data. 176 * 177 * @param string 178 * The string instance to get the size for. 179 * 180 * @return 181 * The number of bytes contained in this string instance. To access these 182 * bytes see gdbwire_string_data(). Will be 0 after creation or clear. 183 */ 184 size_t gdbwire_string_size(struct gdbwire_string *string); 185 186 /** 187 * Determine the maximum capacity (number of bytes) this string may hold. 188 * 189 * The max capacity of the string is automatically increased when data 190 * is appended to this string through the gdbwire_string_append_*() 191 * family of functions. 192 * 193 * @param string 194 * The string to determine the capacity of. 195 * 196 * @return 197 * The max number of bytes this string may hold. 198 */ 199 size_t gdbwire_string_capacity(struct gdbwire_string *string); 200 201 /** 202 * Search for the first character in chars occuring in this string. 203 * 204 * @param string 205 * The string to search for the characters in chars in. 206 * 207 * @param chars 208 * A null terminated string of characters. This string is not searched 209 * for directly but instead each individually character in the string 210 * is searched for. 211 * 212 * @return 213 * The index position of the first matched character in chars. 214 * Will return gdbwire_string_size() if not found. 215 */ 216 size_t gdbwire_string_find_first_of(struct gdbwire_string *string, 217 const char *chars); 218 219 /** 220 * Erase characters from this string, reducing it's size. 221 * 222 * @param string 223 * The string to erase characters from. 224 * 225 * @param pos 226 * The index position of the first character to be erased. 227 * 228 * @param count 229 * The number of characters to erase starting at position pos. 230 * If count goes past the end of the string it is adjusted to erase 231 * until the end of the string. This allows the caller to pass in 232 * gdbwire_string_size() to erase the end of the string with out 233 * doing index arithmetic. 234 * 235 * @return 236 * On success 0 will be returned otherwise -1. The string will remain 237 * unmodified when an error occurs. Success can only occur if the entire 238 * requested range can be erased. 239 */ 240 int gdbwire_string_erase(struct gdbwire_string *string, size_t pos, 241 size_t count); 242 243 #ifdef __cplusplus 244 } 245 #endif 246 247 #endif 248 /***** End of gdbwire_string.h ***********************************************/ 249 /***** Begin file gdbwire_assert.h *******************************************/ 250 #ifndef GDBWIRE_ERROR_H 251 #define GDBWIRE_ERROR_H 252 253 /***** Include gdbwire_result.h in the middle of gdbwire_assert.h ************/ 254 /***** Begin file gdbwire_result.h *******************************************/ 255 #ifndef GDBWIRE_RESULT_H 256 #define GDBWIRE_RESULT_H 257 258 enum gdbwire_result { 259 /* The result of the operation was successful */ 260 GDBWIRE_OK, 261 262 /** 263 * An assertion failed in the calling code. 264 * 265 * Functions are encouraged to assert expressions they expect 266 * to be true. The macro GDBWIRE_ASSERT and GDBWIRE_ASSERT_ERRNO 267 * are useful for asserting expressions, and upon failure, to 268 * automatically log the assertion expression and return 269 * this result status. 270 */ 271 GDBWIRE_ASSERT, 272 273 /** 274 * An internal logic error has occurred. 275 * 276 * In general, this should be used when a function can no 277 * longer carry out it's contract and must abort. 278 * 279 * This happens, for instance, when a called function returns 280 * an error status, or when invalid input was provided, etc. 281 */ 282 GDBWIRE_LOGIC, 283 284 /** 285 * The system is out of memory. 286 * 287 * Will occur when malloc, strdup, calloc, etc fail to allocate memory. 288 */ 289 GDBWIRE_NOMEM 290 }; 291 292 #endif /* GDBWIRE_RESULT_H */ 293 /***** End of gdbwire_result.h ***********************************************/ 294 /***** Continuing where we left off in gdbwire_assert.h **********************/ 295 /***** Include gdbwire_logger.h in the middle of gdbwire_assert.h ************/ 296 /***** Begin file gdbwire_logger.h *******************************************/ 297 #ifndef __GDBWIRE_LOGGER_H__ 298 #define __GDBWIRE_LOGGER_H__ 299 300 /* #include "gdbwire_result.h" */ 301 302 #ifdef __cplusplus 303 extern "C" { 304 #endif 305 306 enum gdbwire_logger_level { 307 GDBWIRE_LOGGER_DEBUG, 308 GDBWIRE_LOGGER_INFO, 309 GDBWIRE_LOGGER_WARN, 310 GDBWIRE_LOGGER_ERROR 311 }; 312 313 /** 314 * Log a statement to the logger. 315 * 316 * This is typically not called directly. Use the below macros instead. 317 * The macros automatically supply the file, line and level arguments. 318 * 319 * @param file 320 * The filename the logger was invoked from. 321 * 322 * @param line 323 * The line number the logger was invoked from. 324 * 325 * @param level 326 * The level associated with the log message. 327 * 328 * @param fmt 329 * The format string for the message (printf formatting). 330 * 331 * @param ... 332 * Any additional format arguments. 333 */ 334 void gdbwire_logger_log(const char *file, int line, 335 enum gdbwire_logger_level level, const char *fmt, ...) 336 #ifdef __GNUC__ 337 __attribute__((__format__(__printf__, 4, 5))) 338 #endif 339 ; 340 341 /* The macros intended to be used for logging */ 342 #define gdbwire_debug(fmt, ...)(gdbwire_logger_log(__FILE__, __LINE__, \ 343 GDBWIRE_LOGGER_DEBUG, fmt, ##__VA_ARGS__)) 344 #define gdbwire_info(fmt, ...)(gdbwire_logger_log(__FILE__, __LINE__, \ 345 GDBWIRE_LOGGER_INFO, fmt, ##__VA_ARGS__)) 346 #define gdbwire_warn(fmt, ...)(gdbwire_logger_log(__FILE__, __LINE__, \ 347 GDBWIRE_LOGGER_WARN, fmt, ##__VA_ARGS__)) 348 #define gdbwire_error(fmt, ...)(gdbwire_logger_log(__FILE__, __LINE__, \ 349 GDBWIRE_LOGGER_ERROR, fmt, ##__VA_ARGS__)) 350 351 #ifdef __cplusplus 352 } 353 #endif 354 355 #endif 356 /***** End of gdbwire_logger.h ***********************************************/ 357 /***** Continuing where we left off in gdbwire_assert.h **********************/ 358 359 /** 360 * Validate that the expression evaluates to true. 361 * 362 * If the expression does not evaluate to true, log the error and 363 * return a GDBWIRE_ASSERT status code. 364 * 365 * Otherwise, if the expression does evaluate to true, do nothing. 366 * 367 * @param expr 368 * The expression to evaluate. 369 */ 370 #define GDBWIRE_ASSERT(expr) \ 371 do { \ 372 if (!(expr)) { \ 373 gdbwire_error("Assertion failure, expr[%s]", #expr); \ 374 return GDBWIRE_ASSERT; \ 375 } \ 376 } while (0) 377 378 /** 379 * Validate that the expression evaluates to true. 380 * 381 * If the expression does not evaluate to true, log the error, 382 * set the variable provided to GDBWIRE_ASSERT and goto the label 383 * provided. 384 * 385 * Otherwise, if the expression does evaluate to true, do nothing. 386 * 387 * @param expr 388 * The expression to evaluate. 389 * 390 * @param variable 391 * The result variable to assign the value GDBWIRE_ASSERT to. 392 * 393 * @param label 394 * The label to jump to if the expression evaluates to False. 395 */ 396 #define GDBWIRE_ASSERT_GOTO(expr, variable, label) \ 397 do { \ 398 if (!(expr)) { \ 399 gdbwire_error("Assertion failure, expr[%s], " \ 400 "label[%s]", #expr, #label); \ 401 variable = GDBWIRE_ASSERT; \ 402 goto label; \ 403 } \ 404 } while (0) 405 406 /** 407 * Validate that the expression evaluates to true. 408 * 409 * This particular assertion macro is used when a system library 410 * call fails and that library call has an associated errno status 411 * to describe the failure reason. 412 * 413 * If the expression does not evaluate to true, log the error, 414 * along with the errno value and message and return a GDBWIRE_ASSERT 415 * status code. 416 * 417 * Otherwise, if the expression does evaluate to true, do nothing. 418 * 419 * @param expr 420 * The expression to evaluate. 421 */ 422 #define GDBWIRE_ASSERT_ERRNO(expr) \ 423 do { \ 424 if (!(expr)) { \ 425 gdbwire_error("Assertion failure, expr[%s]," \ 426 "errno[%d], strerror[%s]", \ 427 #expr, errno, strerror(errno)); \ 428 return GDBWIRE_ASSERT; \ 429 } \ 430 } while (0) 431 432 #endif /* GDBWIRE_ERROR_H */ 433 /***** End of gdbwire_assert.h ***********************************************/ 434 /***** Begin file gdbwire_result.h *******************************************/ 435 #ifndef GDBWIRE_RESULT_H 436 #define GDBWIRE_RESULT_H 437 438 enum gdbwire_result { 439 /* The result of the operation was successful */ 440 GDBWIRE_OK, 441 442 /** 443 * An assertion failed in the calling code. 444 * 445 * Functions are encouraged to assert expressions they expect 446 * to be true. The macro GDBWIRE_ASSERT and GDBWIRE_ASSERT_ERRNO 447 * are useful for asserting expressions, and upon failure, to 448 * automatically log the assertion expression and return 449 * this result status. 450 */ 451 GDBWIRE_ASSERT, 452 453 /** 454 * An internal logic error has occurred. 455 * 456 * In general, this should be used when a function can no 457 * longer carry out it's contract and must abort. 458 * 459 * This happens, for instance, when a called function returns 460 * an error status, or when invalid input was provided, etc. 461 */ 462 GDBWIRE_LOGIC, 463 464 /** 465 * The system is out of memory. 466 * 467 * Will occur when malloc, strdup, calloc, etc fail to allocate memory. 468 */ 469 GDBWIRE_NOMEM 470 }; 471 472 #endif /* GDBWIRE_RESULT_H */ 473 /***** End of gdbwire_result.h ***********************************************/ 474 /***** Begin file gdbwire_logger.h *******************************************/ 475 #ifndef __GDBWIRE_LOGGER_H__ 476 #define __GDBWIRE_LOGGER_H__ 477 478 /* #include "gdbwire_result.h" */ 479 480 #ifdef __cplusplus 481 extern "C" { 482 #endif 483 484 enum gdbwire_logger_level { 485 GDBWIRE_LOGGER_DEBUG, 486 GDBWIRE_LOGGER_INFO, 487 GDBWIRE_LOGGER_WARN, 488 GDBWIRE_LOGGER_ERROR 489 }; 490 491 /** 492 * Log a statement to the logger. 493 * 494 * This is typically not called directly. Use the below macros instead. 495 * The macros automatically supply the file, line and level arguments. 496 * 497 * @param file 498 * The filename the logger was invoked from. 499 * 500 * @param line 501 * The line number the logger was invoked from. 502 * 503 * @param level 504 * The level associated with the log message. 505 * 506 * @param fmt 507 * The format string for the message (printf formatting). 508 * 509 * @param ... 510 * Any additional format arguments. 511 */ 512 void gdbwire_logger_log(const char *file, int line, 513 enum gdbwire_logger_level level, const char *fmt, ...); 514 515 /* The macros intended to be used for logging */ 516 #define gdbwire_debug(fmt, ...)(gdbwire_logger_log(__FILE__, __LINE__, \ 517 GDBWIRE_LOGGER_DEBUG, fmt, ##__VA_ARGS__)) 518 #define gdbwire_info(fmt, ...)(gdbwire_logger_log(__FILE__, __LINE__, \ 519 GDBWIRE_LOGGER_INFO, fmt, ##__VA_ARGS__)) 520 #define gdbwire_warn(fmt, ...)(gdbwire_logger_log(__FILE__, __LINE__, \ 521 GDBWIRE_LOGGER_WARN, fmt, ##__VA_ARGS__)) 522 #define gdbwire_error(fmt, ...)(gdbwire_logger_log(__FILE__, __LINE__, \ 523 GDBWIRE_LOGGER_ERROR, fmt, ##__VA_ARGS__)) 524 525 #ifdef __cplusplus 526 } 527 #endif 528 529 #endif 530 /***** End of gdbwire_logger.h ***********************************************/ 531 /***** Begin file gdbwire_mi_pt.h ********************************************/ 532 #ifndef GDBWIRE_MI_PT_H 533 #define GDBWIRE_MI_PT_H 534 535 #ifdef __cplusplus 536 extern "C" { 537 #endif 538 539 /** 540 * The position of a token in a GDB/MI line. 541 * 542 * Note that a string in C is zero based and the token column 543 * position is 1 based. For example, 544 * char *str = "hello world"; 545 * The "hello" token would have a start_column as 1 and an end 546 * column as 5. 547 * 548 * The start_column and end_column will be the same column number for 549 * a token of size 1. 550 */ 551 struct gdbwire_mi_position { 552 /* The starting column position of the token */ 553 int start_column; 554 /* The ending column position of the token */ 555 int end_column; 556 }; 557 558 /** The gdbwire_mi output kinds. */ 559 enum gdbwire_mi_output_kind { 560 /** 561 * The GDB/MI output contains an out of band record. 562 * 563 * The out of band record is not necessarily associated with any 564 * particular GDB/MI input command. 565 */ 566 GDBWIRE_MI_OUTPUT_OOB, 567 568 /** 569 * The GDB/MI output contains a gdbwire_mi result record. 570 * 571 * This record typically contains the result data from a request 572 * made by the client in a previous GDB/MI input command. 573 */ 574 GDBWIRE_MI_OUTPUT_RESULT, 575 576 /** 577 * The GDB/MI output represents a prompt. (ie. (gdb) ) 578 * 579 * TODO: Document when GDB is ready to receive a command. Only if 580 * the prompt is received and at *stopped? 581 */ 582 GDBWIRE_MI_OUTPUT_PROMPT, 583 584 /** 585 * A parse error occurred. 586 */ 587 GDBWIRE_MI_OUTPUT_PARSE_ERROR 588 }; 589 590 /** 591 * The GDB/MI output command. 592 * 593 * A GDB/MI output command is the main mechanism in which GDB 594 * corresponds with a front end. 595 */ 596 struct gdbwire_mi_output { 597 enum gdbwire_mi_output_kind kind; 598 599 union { 600 /** When kind == GDBWIRE_MI_OUTPUT_OOB, never NULL. */ 601 struct gdbwire_mi_oob_record *oob_record; 602 /** When kind == GDBWIRE_MI_OUTPUT_RESULT, never NULL. */ 603 struct gdbwire_mi_result_record *result_record; 604 /** When kind == GDBWIRE_MI_OUTPUT_PARSE_ERROR, never NULL. */ 605 struct { 606 /** The token the error occurred on */ 607 char *token; 608 /** The position of the token where the error occurred. */ 609 struct gdbwire_mi_position pos; 610 } error; 611 } variant; 612 613 /** 614 * The GDB/MI output line that was used to create this output instance. 615 * 616 * Each gdbwire_mi output structure is created from exactly one line of 617 * MI output from GDB. This field represents the line that created 618 * this particular output structure. 619 * 620 * This field is always available and never NULL, even for a parse error. 621 */ 622 char *line; 623 624 /** The next GDB/MI output command or NULL if none */ 625 struct gdbwire_mi_output *next; 626 }; 627 628 /** 629 * A GDB/MI token. 630 * 631 * A string made up of one or more digits. 632 * The regular expression [0-9]+ will match this types contents. 633 */ 634 typedef char *gdbwire_mi_token_t; 635 636 /** 637 * A GDB/MI output command may contain one of the following result indications. 638 */ 639 enum gdbwire_mi_result_class { 640 /** 641 * The synchronous operation was successful (^done). 642 */ 643 GDBWIRE_MI_DONE, 644 645 /** 646 * Equivalent to GDBWIRE_MI_DONE (^running). 647 * 648 * Historically, was output by GDB instead of ^done if the command 649 * resumed the target. 650 * 651 * Do not rely on or use this result class in the front end to determine 652 * the state of the target. Use the async *running output record to 653 * determine which threads have resumed running. 654 * 655 * TODO: Ensure that early versions of GDB can depend on the async 656 * *running or if front ends DO have to rely on ^running. 657 */ 658 GDBWIRE_MI_RUNNING, 659 660 /** 661 * GDB has connected to a remote target (^connected). 662 * 663 * This is in response to the -target-select command. 664 * 665 * A comment in the GDB source code says, 666 * There's no particularly good reason why target-connect results 667 * in not ^done. Should kill ^connected for MI3. 668 * 669 * With this in mind, it makes sense to assume that GDBWIRE_MI_CONNECTED 670 * and GDBWIRE_MI_DONE are equivalent. 671 */ 672 GDBWIRE_MI_CONNECTED, 673 674 /** 675 * An error has occurred (^error). 676 * 677 * This can occur if the user provides an improper command to GDB. 678 * In this case, the user will be provided the standard error output but 679 * the front end will also be provided this information independently. 680 */ 681 GDBWIRE_MI_ERROR, 682 683 /** 684 * GDB has terminated (^exit). 685 * 686 * When GDB knows it is about to exit, it provides this notification 687 * in the GDB/MI output command. However, on all other circumstances, 688 * the front end should be prepared to have GDB exit and not provide 689 * this information. 690 */ 691 GDBWIRE_MI_EXIT, 692 693 /* An unsupported result class */ 694 GDBWIRE_MI_UNSUPPORTED 695 }; 696 697 /** 698 * The GDB/MI result record in an output command. 699 * 700 * The result record represents the result data in the GDB/MI output 701 * command sent by GDB. This typically contains the content the client 702 * was requesting when it sent a GDB/MI input command to GDB. 703 */ 704 struct gdbwire_mi_result_record { 705 /** 706 * The token associated with the corresponding GDB/MI input command. 707 * 708 * The client may provide a unique string of digits at the beginning of a 709 * GDB/MI input command. For example, 710 * 0000-foo 711 * When GDB finally gets around to responding to the GDB/MI input command, 712 * it takes the token provided in the input command and puts it into the 713 * result record of the corresponding GDB/MI output command. For 714 * example, the output commmand associated with the above input command is, 715 * 0000^error,msg="Undefined MI command: foo",code="undefined-command" 716 * and the result record would have the below token field set to "0000". 717 * 718 * This is intended to allow the front end to correlate the GDB/MI input 719 * command it sent with the GDB/MI output command GDB responded with. 720 * 721 * This represents the token value the front end provided to the 722 * corresponding GDB/MI input command or NULL if no token was provided. 723 */ 724 gdbwire_mi_token_t token; 725 726 /** The result records result class. */ 727 enum gdbwire_mi_result_class result_class; 728 729 /** 730 * An optional list of results for this result record. 731 * 732 * Will be NULL if there is no results for this result record. 733 * 734 * This is typically where the result data is that the client 735 * is looking for. 736 */ 737 struct gdbwire_mi_result *result; 738 }; 739 740 /** The out of band record kinds. */ 741 enum gdbwire_mi_oob_record_kind { 742 /** 743 * An asyncronous out of band record. 744 * 745 * An asyncronous record occurs when GDB would like to update the 746 * client with information that it has not asked for. 747 * 748 * For instance, if the inferior has stopped, or a new thread has 749 * started. 750 */ 751 GDBWIRE_MI_ASYNC, 752 753 /** 754 * A stream out of band record. 755 * 756 * This is the result of normal output from the console, target or GDB. 757 */ 758 GDBWIRE_MI_STREAM 759 }; 760 761 /* This is an out of band record. */ 762 struct gdbwire_mi_oob_record { 763 /** The kind of out of band record. */ 764 enum gdbwire_mi_oob_record_kind kind; 765 766 union { 767 /** When kind == GDBWIRE_MI_ASYNC. */ 768 struct gdbwire_mi_async_record *async_record; 769 /** When kind == GDBWIRE_MI_STREAM. */ 770 struct gdbwire_mi_stream_record *stream_record; 771 } variant; 772 }; 773 774 /** The asynchronous out of band record kinds */ 775 enum gdbwire_mi_async_record_kind { 776 /** 777 * The asynchronous status record kind. 778 * 779 * Contains on-going status information about the progress of a slow 780 * operation. It can be discarded. 781 * 782 * This output is prepended by the + character. 783 */ 784 GDBWIRE_MI_STATUS, 785 786 /** 787 * The asynchronous exec record kind. 788 * 789 * Contains asynchronous state change regarding the target: 790 * (stopped, started, disappeared). 791 * 792 * This output is prepended by the * character. 793 */ 794 GDBWIRE_MI_EXEC, 795 796 /** 797 * The asyncronous notify record kind. 798 * 799 * Contains supplementary information that the client should handle 800 * (e.g., a new breakpoint information). 801 * 802 * This output is prepended by the = character. 803 */ 804 GDBWIRE_MI_NOTIFY 805 }; 806 807 /** The stream out of band record kinds */ 808 enum gdbwire_mi_stream_record_kind { 809 /** 810 * The console output. 811 * 812 * Output that should be displayed as is in the console. 813 * It is the textual response to a CLI command. 814 * 815 * This output is prepended by the ~ character. 816 */ 817 GDBWIRE_MI_CONSOLE, 818 819 /** 820 * The target output. 821 * 822 * Output produced by the target program. 823 * 824 * This output is prepended by the @ character. 825 */ 826 GDBWIRE_MI_TARGET, 827 828 /** 829 * The GDB log output. 830 * 831 * Output text coming from GDB's internals. For instance messages 832 * that should be displayed as part of an error log. 833 * 834 * This output is prepended by the & character. 835 */ 836 GDBWIRE_MI_LOG 837 }; 838 839 /** 840 * The GDB/MI asyncronous class. 841 * 842 * 843 */ 844 enum gdbwire_mi_async_class { 845 /** 846 * Loading the executable onto the remote target. 847 * 848 * This was undocumented in the GDB manual as far as GDB 7.7. 849 * 850 * This occurs if the async record is GDBWIRE_MI_STATUS as +download. 851 */ 852 GDBWIRE_MI_ASYNC_DOWNLOAD, 853 854 /** 855 * The target has stopped. 856 * 857 * This occurs if the async record is GDBWIRE_MI_EXEC as *stopped. 858 */ 859 GDBWIRE_MI_ASYNC_STOPPED, 860 861 /** 862 * The target is now running. 863 * 864 * This occurs if the async record is GDBWIRE_MI_EXEC as *running. 865 */ 866 GDBWIRE_MI_ASYNC_RUNNING, 867 868 /** 869 * Reports that a thread group was added. 870 * 871 * When a thread group is added, it generally might not be associated 872 * with a running process. 873 * 874 * This occurs if the async record is GDBWIRE_MI_NOTIFY 875 * as =thread-group-added. 876 */ 877 GDBWIRE_MI_ASYNC_THREAD_GROUP_ADDED, 878 879 /** 880 * Reports that a thread group was removed. 881 * 882 * When a thread group is removed, its id becomes invalid and cannot be 883 * used in any way. 884 * 885 * This occurs if the async record is GDBWIRE_MI_NOTIFY 886 * as =thread-group-removed. 887 */ 888 GDBWIRE_MI_ASYNC_THREAD_GROUP_REMOVED, 889 890 /** 891 * Reports that a thread group was started. 892 * 893 * A thread group became associated with a running program. 894 * 895 * This occurs if the async record is GDBWIRE_MI_NOTIFY 896 * as =thread-group-started. 897 */ 898 GDBWIRE_MI_ASYNC_THREAD_GROUP_STARTED, 899 900 /** 901 * Reports that a thread group was exited. 902 * 903 * A thread group is no longer associated with a running program. 904 * 905 * This occurs if the async record is GDBWIRE_MI_NOTIFY 906 * as =thread-group-exited. 907 */ 908 GDBWIRE_MI_ASYNC_THREAD_GROUP_EXITED, 909 910 /** 911 * Reports that a thread was created. 912 * 913 * This occurs if the async record is GDBWIRE_MI_NOTIFY 914 * as =thread-created. 915 */ 916 GDBWIRE_MI_ASYNC_THREAD_CREATED, 917 918 /** 919 * Reports that a thread was exited. 920 * 921 * This occurs if the async record is GDBWIRE_MI_NOTIFY as =thread-exited. 922 */ 923 GDBWIRE_MI_ASYNC_THREAD_EXITED, 924 925 /** 926 * Reports that a thread was selected. 927 * 928 * This occurs if the async record is GDBWIRE_MI_NOTIFY as =thread-selected. 929 */ 930 GDBWIRE_MI_ASYNC_THREAD_SELECTED, 931 932 /** 933 * Reports that a new library was loaded. 934 * 935 * This occurs if the async record is GDBWIRE_MI_NOTIFY as =library-loaded. 936 */ 937 GDBWIRE_MI_ASYNC_LIBRARY_LOADED, 938 939 /** 940 * Reports that a new library was unloaded. 941 * 942 * This occurs if the async record is GDBWIRE_MI_NOTIFY 943 * as =library-unloaded. 944 */ 945 GDBWIRE_MI_ASYNC_LIBRARY_UNLOADED, 946 947 /** 948 * Reports that a trace frame was changed. 949 * 950 * This occurs if the async record is GDBWIRE_MI_NOTIFY 951 * as =traceframe-changed. 952 */ 953 GDBWIRE_MI_ASYNC_TRACEFRAME_CHANGED, 954 955 /** 956 * Reports that a trace state variable was created. 957 * 958 * This occurs if the async record is GDBWIRE_MI_NOTIFY as =tsv-created. 959 */ 960 GDBWIRE_MI_ASYNC_TSV_CREATED, 961 962 /** 963 * Reports that a trace state variable was modified. 964 * 965 * This occurs if the async record is GDBWIRE_MI_NOTIFY as =tsv-modified. 966 */ 967 GDBWIRE_MI_ASYNC_TSV_MODIFIED, 968 969 /** 970 * Reports that a trace state variable was deleted. 971 * 972 * This occurs if the async record is GDBWIRE_MI_NOTIFY as =tsv-deleted. 973 */ 974 GDBWIRE_MI_ASYNC_TSV_DELETED, 975 976 /** 977 * Reports that a breakpoint was created. 978 * 979 * Only user-visible breakpoints are reported to the MI user. 980 * 981 * If a breakpoint is emitted in the result record of a 982 * command, then it will not also be emitted in an async record. 983 * 984 * This occurs if the async record is GDBWIRE_MI_NOTIFY 985 * as =breakpoint-created. 986 */ 987 GDBWIRE_MI_ASYNC_BREAKPOINT_CREATED, 988 989 /** 990 * Reports that a breakpoint was modified. 991 * 992 * Only user-visible breakpoints are reported to the MI user. 993 * 994 * If a breakpoint is emitted in the result record of a 995 * command, then it will not also be emitted in an async record. 996 * 997 * This occurs if the async record is GDBWIRE_MI_NOTIFY 998 * as =breakpoint-modified. 999 */ 1000 GDBWIRE_MI_ASYNC_BREAKPOINT_MODIFIED, 1001 1002 /** 1003 * Reports that a breakpoint was deleted. 1004 * 1005 * Only user-visible breakpoints are reported to the MI user. 1006 * 1007 * If a breakpoint is emitted in the result record of a 1008 * command, then it will not also be emitted in an async record. 1009 * 1010 * This occurs if the async record is GDBWIRE_MI_NOTIFY 1011 * as =breakpoint-deleted. 1012 */ 1013 GDBWIRE_MI_ASYNC_BREAKPOINT_DELETED, 1014 1015 /** 1016 * Reports that execution log recording was started on an inferior. 1017 * 1018 * This occurs if the async record is GDBWIRE_MI_NOTIF 1019 * as =record-started. 1020 */ 1021 GDBWIRE_MI_ASYNC_RECORD_STARTED, 1022 1023 /** 1024 * Reports that execution log recording was stopped on an inferior. 1025 * 1026 * This occurs if the async record is GDBWIRE_MI_NOTIFY 1027 * as =record-stopped. 1028 */ 1029 GDBWIRE_MI_ASYNC_RECORD_STOPPED, 1030 1031 /** 1032 * Reports that a parameter of the command set param is changed to value. 1033 * 1034 * For example, when the user runs a command like 'set print pretty on', 1035 * this async command will be invoked with the parameter reported as 1036 * 'print pretty' and the value as 'on'. 1037 * 1038 * This occurs if the async record is GDBWIRE_MI_NOTIFY 1039 * as =cmd-param-changed. 1040 */ 1041 GDBWIRE_MI_ASYNC_CMD_PARAM_CHANGED, 1042 1043 /** 1044 * Reports that bytes from addr to data + len were written in an inferior. 1045 * 1046 * This occurs if the async record is GDBWIRE_MI_NOTIFY 1047 * as =memory-changed. 1048 */ 1049 GDBWIRE_MI_ASYNC_MEMORY_CHANGED, 1050 1051 /* An unsupported async class */ 1052 GDBWIRE_MI_ASYNC_UNSUPPORTED 1053 }; 1054 1055 /** 1056 * The GDB/MI asyncronous record in an output command. 1057 * 1058 * An asyncronous record occurs when GDB would like to update the 1059 * client with information that it has not asked for. 1060 */ 1061 struct gdbwire_mi_async_record { 1062 /** 1063 * The result record token. 1064 * 1065 * Please note that the GDB/MI manual says that asyncronous records 1066 * do not currently populate this token on output but reserve the right 1067 * to do so. For that reason, token here should always be NULL. 1068 * 1069 * From the GDB documentation: 1070 * Note that for all async output, while the token is allowed by the 1071 * grammar and may be output by future versions of gdb for select async 1072 * output messages, it is generally omitted. Frontends should treat all 1073 * async output as reporting general changes in the state of the target 1074 * and there should be no need to associate async output to any prior 1075 * command. 1076 * 1077 * After further investigation, I determined that newer GDB's will no 1078 * longer ever output this information. Older GDB's will. The commit 1079 * that made this change in GDB is 721c02de on April 24th, 2008. 1080 * The next GDB that was released was on October 6th, 2009, version 7.0. 1081 * 1082 * Before the above mentioned commit async *stopped commands would 1083 * sometimes output the token associated with the last token provided in 1084 * a GDB/MI input command. After that change, the token is never 1085 * associated with an async output command, even though the 1086 * documentation says it might be. 1087 * 1088 * Finally, even before that change when the token was output in the 1089 * async *stopped command, the developers of GDB felt that it was not 1090 * useful and should be avoided by front ends. 1091 * 1092 * With this information, I've determined that front ends should never 1093 * use this value to determine logic. However, the value is parsed in 1094 * order to accurately handle and represent the cases where this value 1095 * occurs. 1096 * 1097 * This represents the token value the front end provided to the 1098 * corresponding GDB/MI input command or NULL if no token was provided. 1099 */ 1100 gdbwire_mi_token_t token; 1101 1102 /** The kind of asynchronous record. */ 1103 enum gdbwire_mi_async_record_kind kind; 1104 1105 /** The asynchronous output class */ 1106 enum gdbwire_mi_async_class async_class; 1107 1108 /** 1109 * An optional list of results for this async output. 1110 * 1111 * Will be NULL if there is no results. 1112 */ 1113 struct gdbwire_mi_result *result; 1114 }; 1115 1116 /** The GDB/MI result kind */ 1117 enum gdbwire_mi_result_kind { 1118 /** The result is a cstring */ 1119 GDBWIRE_MI_CSTRING, 1120 /** The result is a tuple */ 1121 GDBWIRE_MI_TUPLE, 1122 /** The result is a list */ 1123 GDBWIRE_MI_LIST 1124 }; 1125 1126 /** 1127 * A GDB/MI result list. 1128 * 1129 * This is one of the important GDB/MI data structures. GDB communicates many 1130 * of it's values to the front end through this key/value data structure. 1131 * 1132 * It is basically a list of key/value pairs, where the key is a 1133 * variable name and the value expands to a string, a tuple of results or 1134 * a list of results. 1135 * 1136 * This can be thought of as a custom json object. 1137 */ 1138 struct gdbwire_mi_result { 1139 /** The kind of result this represents. */ 1140 enum gdbwire_mi_result_kind kind; 1141 1142 /** The key being described by the result. */ 1143 char *variable; 1144 1145 union { 1146 /** When kind is GDBWIRE_MI_CSTRING */ 1147 char *cstring; 1148 1149 /** 1150 * When kind is GDBWIRE_MI_TUPLE or GDBWIRE_MI_LIST. 1151 * 1152 * If kind is GDBWIRE_MI_TUPLE, each result in the tuple should have a 1153 * valid key according to the GDB/MI specification. That is, for 1154 * each result, result->variable should not be NULL. 1155 * Note: GDBWIRE currently relaxes the above rule. It allows tuple's 1156 * with out a key in each member. For instance, {key="value"} 1157 * is what the GDB/MI specification advocates for, but some 1158 * variations of GDB emit {"value"} and so GDBWIRE allows it. 1159 * 1160 * If kind is GDBWIRE_MI_LIST, the GDB/MI specification allows 1161 * results in this list to not have keys. That is, for each result, 1162 * result->variable may be NULL. 1163 * 1164 * Will be NULL if the tuple or list is empty. 1165 */ 1166 struct gdbwire_mi_result *result; 1167 } variant; 1168 1169 /** The next result or NULL if none */ 1170 struct gdbwire_mi_result *next; 1171 }; 1172 1173 /** 1174 * An out of band GDB/MI stream record. 1175 * 1176 * A stream record is intended to provide the front end with information 1177 * from the console, the target or from GDB itself. 1178 */ 1179 struct gdbwire_mi_stream_record { 1180 /** The kind of stream record. */ 1181 enum gdbwire_mi_stream_record_kind kind; 1182 /** The buffer provided in this stream record. */ 1183 char *cstring; 1184 }; 1185 1186 void gdbwire_mi_output_free(struct gdbwire_mi_output *param); 1187 1188 struct gdbwire_mi_output *append_gdbwire_mi_output( 1189 struct gdbwire_mi_output *list, struct gdbwire_mi_output *item); 1190 1191 struct gdbwire_mi_result *append_gdbwire_mi_result( 1192 struct gdbwire_mi_result *list, struct gdbwire_mi_result *item); 1193 1194 #ifdef __cplusplus 1195 } 1196 #endif 1197 1198 #endif 1199 /***** End of gdbwire_mi_pt.h ************************************************/ 1200 /***** Begin file gdbwire_mi_pt_alloc.h **************************************/ 1201 #ifndef GDBWIRE_MI_PT_ALLOC_H 1202 #define GDBWIRE_MI_PT_ALLOC_H 1203 1204 #ifdef __cplusplus 1205 extern "C" { 1206 #endif 1207 1208 /** 1209 * Responsible for allocating and deallocating gdbwire_mi_pt objects. 1210 */ 1211 1212 /* struct gdbwire_mi_output */ 1213 struct gdbwire_mi_output *gdbwire_mi_output_alloc(void); 1214 void gdbwire_mi_output_free(struct gdbwire_mi_output *param); 1215 1216 /* struct gdbwire_mi_result_record */ 1217 struct gdbwire_mi_result_record *gdbwire_mi_result_record_alloc(void); 1218 void gdbwire_mi_result_record_free(struct gdbwire_mi_result_record *param); 1219 1220 /* struct gdbwire_mi_result */ 1221 struct gdbwire_mi_result *gdbwire_mi_result_alloc(void); 1222 void gdbwire_mi_result_free(struct gdbwire_mi_result *param); 1223 1224 /* struct gdbwire_mi_oob_record */ 1225 struct gdbwire_mi_oob_record *gdbwire_mi_oob_record_alloc(void); 1226 void gdbwire_mi_oob_record_free(struct gdbwire_mi_oob_record *param); 1227 1228 /* struct gdbwire_mi_async_record */ 1229 struct gdbwire_mi_async_record *gdbwire_mi_async_record_alloc(void); 1230 void gdbwire_mi_async_record_free(struct gdbwire_mi_async_record *param); 1231 1232 /* struct gdbwire_mi_stream_record */ 1233 struct gdbwire_mi_stream_record *gdbwire_mi_stream_record_alloc(void); 1234 void gdbwire_mi_stream_record_free(struct gdbwire_mi_stream_record *param); 1235 1236 #ifdef __cplusplus 1237 } 1238 #endif 1239 1240 #endif /* GDBWIRE_MI_PT_ALLOC_H */ 1241 /***** End of gdbwire_mi_pt_alloc.h ******************************************/ 1242 /***** Begin file gdbwire_mi_parser.h ****************************************/ 1243 #ifndef GDBWIRE_MI_PARSER_H 1244 #define GDBWIRE_MI_PARSER_H 1245 1246 #ifdef __cplusplus 1247 extern "C" { 1248 #endif 1249 1250 /* #include "gdbwire_result.h" */ 1251 /***** Include gdbwire_mi_pt.h in the middle of gdbwire_mi_parser.h **********/ 1252 /***** Begin file gdbwire_mi_pt.h ********************************************/ 1253 #ifndef GDBWIRE_MI_PT_H 1254 #define GDBWIRE_MI_PT_H 1255 1256 #ifdef __cplusplus 1257 extern "C" { 1258 #endif 1259 1260 /** 1261 * The position of a token in a GDB/MI line. 1262 * 1263 * Note that a string in C is zero based and the token column 1264 * position is 1 based. For example, 1265 * char *str = "hello world"; 1266 * The "hello" token would have a start_column as 1 and an end 1267 * column as 5. 1268 * 1269 * The start_column and end_column will be the same column number for 1270 * a token of size 1. 1271 */ 1272 struct gdbwire_mi_position { 1273 /* The starting column position of the token */ 1274 int start_column; 1275 /* The ending column position of the token */ 1276 int end_column; 1277 }; 1278 1279 /** The gdbwire_mi output kinds. */ 1280 enum gdbwire_mi_output_kind { 1281 /** 1282 * The GDB/MI output contains an out of band record. 1283 * 1284 * The out of band record is not necessarily associated with any 1285 * particular GDB/MI input command. 1286 */ 1287 GDBWIRE_MI_OUTPUT_OOB, 1288 1289 /** 1290 * The GDB/MI output contains a gdbwire_mi result record. 1291 * 1292 * This record typically contains the result data from a request 1293 * made by the client in a previous GDB/MI input command. 1294 */ 1295 GDBWIRE_MI_OUTPUT_RESULT, 1296 1297 /** 1298 * The GDB/MI output represents a prompt. (ie. (gdb) ) 1299 * 1300 * TODO: Document when GDB is ready to receive a command. Only if 1301 * the prompt is received and at *stopped? 1302 */ 1303 GDBWIRE_MI_OUTPUT_PROMPT, 1304 1305 /** 1306 * A parse error occurred. 1307 */ 1308 GDBWIRE_MI_OUTPUT_PARSE_ERROR 1309 }; 1310 1311 /** 1312 * The GDB/MI output command. 1313 * 1314 * A GDB/MI output command is the main mechanism in which GDB 1315 * corresponds with a front end. 1316 */ 1317 struct gdbwire_mi_output { 1318 enum gdbwire_mi_output_kind kind; 1319 1320 union { 1321 /** When kind == GDBWIRE_MI_OUTPUT_OOB, never NULL. */ 1322 struct gdbwire_mi_oob_record *oob_record; 1323 /** When kind == GDBWIRE_MI_OUTPUT_RESULT, never NULL. */ 1324 struct gdbwire_mi_result_record *result_record; 1325 /** When kind == GDBWIRE_MI_OUTPUT_PARSE_ERROR, never NULL. */ 1326 struct { 1327 /** The token the error occurred on */ 1328 char *token; 1329 /** The position of the token where the error occurred. */ 1330 struct gdbwire_mi_position pos; 1331 } error; 1332 } variant; 1333 1334 /** 1335 * The GDB/MI output line that was used to create this output instance. 1336 * 1337 * Each gdbwire_mi output structure is created from exactly one line of 1338 * MI output from GDB. This field represents the line that created 1339 * this particular output structure. 1340 * 1341 * This field is always available and never NULL, even for a parse error. 1342 */ 1343 char *line; 1344 1345 /** The next GDB/MI output command or NULL if none */ 1346 struct gdbwire_mi_output *next; 1347 }; 1348 1349 /** 1350 * A GDB/MI token. 1351 * 1352 * A string made up of one or more digits. 1353 * The regular expression [0-9]+ will match this types contents. 1354 */ 1355 typedef char *gdbwire_mi_token_t; 1356 1357 /** 1358 * A GDB/MI output command may contain one of the following result indications. 1359 */ 1360 enum gdbwire_mi_result_class { 1361 /** 1362 * The synchronous operation was successful (^done). 1363 */ 1364 GDBWIRE_MI_DONE, 1365 1366 /** 1367 * Equivalent to GDBWIRE_MI_DONE (^running). 1368 * 1369 * Historically, was output by GDB instead of ^done if the command 1370 * resumed the target. 1371 * 1372 * Do not rely on or use this result class in the front end to determine 1373 * the state of the target. Use the async *running output record to 1374 * determine which threads have resumed running. 1375 * 1376 * TODO: Ensure that early versions of GDB can depend on the async 1377 * *running or if front ends DO have to rely on ^running. 1378 */ 1379 GDBWIRE_MI_RUNNING, 1380 1381 /** 1382 * GDB has connected to a remote target (^connected). 1383 * 1384 * This is in response to the -target-select command. 1385 * 1386 * A comment in the GDB source code says, 1387 * There's no particularly good reason why target-connect results 1388 * in not ^done. Should kill ^connected for MI3. 1389 * 1390 * With this in mind, it makes sense to assume that GDBWIRE_MI_CONNECTED 1391 * and GDBWIRE_MI_DONE are equivalent. 1392 */ 1393 GDBWIRE_MI_CONNECTED, 1394 1395 /** 1396 * An error has occurred (^error). 1397 * 1398 * This can occur if the user provides an improper command to GDB. 1399 * In this case, the user will be provided the standard error output but 1400 * the front end will also be provided this information independently. 1401 */ 1402 GDBWIRE_MI_ERROR, 1403 1404 /** 1405 * GDB has terminated (^exit). 1406 * 1407 * When GDB knows it is about to exit, it provides this notification 1408 * in the GDB/MI output command. However, on all other circumstances, 1409 * the front end should be prepared to have GDB exit and not provide 1410 * this information. 1411 */ 1412 GDBWIRE_MI_EXIT, 1413 1414 /* An unsupported result class */ 1415 GDBWIRE_MI_UNSUPPORTED 1416 }; 1417 1418 /** 1419 * The GDB/MI result record in an output command. 1420 * 1421 * The result record represents the result data in the GDB/MI output 1422 * command sent by GDB. This typically contains the content the client 1423 * was requesting when it sent a GDB/MI input command to GDB. 1424 */ 1425 struct gdbwire_mi_result_record { 1426 /** 1427 * The token associated with the corresponding GDB/MI input command. 1428 * 1429 * The client may provide a unique string of digits at the beginning of a 1430 * GDB/MI input command. For example, 1431 * 0000-foo 1432 * When GDB finally gets around to responding to the GDB/MI input command, 1433 * it takes the token provided in the input command and puts it into the 1434 * result record of the corresponding GDB/MI output command. For 1435 * example, the output commmand associated with the above input command is, 1436 * 0000^error,msg="Undefined MI command: foo",code="undefined-command" 1437 * and the result record would have the below token field set to "0000". 1438 * 1439 * This is intended to allow the front end to correlate the GDB/MI input 1440 * command it sent with the GDB/MI output command GDB responded with. 1441 * 1442 * This represents the token value the front end provided to the 1443 * corresponding GDB/MI input command or NULL if no token was provided. 1444 */ 1445 gdbwire_mi_token_t token; 1446 1447 /** The result records result class. */ 1448 enum gdbwire_mi_result_class result_class; 1449 1450 /** 1451 * An optional list of results for this result record. 1452 * 1453 * Will be NULL if there is no results for this result record. 1454 * 1455 * This is typically where the result data is that the client 1456 * is looking for. 1457 */ 1458 struct gdbwire_mi_result *result; 1459 }; 1460 1461 /** The out of band record kinds. */ 1462 enum gdbwire_mi_oob_record_kind { 1463 /** 1464 * An asyncronous out of band record. 1465 * 1466 * An asyncronous record occurs when GDB would like to update the 1467 * client with information that it has not asked for. 1468 * 1469 * For instance, if the inferior has stopped, or a new thread has 1470 * started. 1471 */ 1472 GDBWIRE_MI_ASYNC, 1473 1474 /** 1475 * A stream out of band record. 1476 * 1477 * This is the result of normal output from the console, target or GDB. 1478 */ 1479 GDBWIRE_MI_STREAM 1480 }; 1481 1482 /* This is an out of band record. */ 1483 struct gdbwire_mi_oob_record { 1484 /** The kind of out of band record. */ 1485 enum gdbwire_mi_oob_record_kind kind; 1486 1487 union { 1488 /** When kind == GDBWIRE_MI_ASYNC. */ 1489 struct gdbwire_mi_async_record *async_record; 1490 /** When kind == GDBWIRE_MI_STREAM. */ 1491 struct gdbwire_mi_stream_record *stream_record; 1492 } variant; 1493 }; 1494 1495 /** The asynchronous out of band record kinds */ 1496 enum gdbwire_mi_async_record_kind { 1497 /** 1498 * The asynchronous status record kind. 1499 * 1500 * Contains on-going status information about the progress of a slow 1501 * operation. It can be discarded. 1502 * 1503 * This output is prepended by the + character. 1504 */ 1505 GDBWIRE_MI_STATUS, 1506 1507 /** 1508 * The asynchronous exec record kind. 1509 * 1510 * Contains asynchronous state change regarding the target: 1511 * (stopped, started, disappeared). 1512 * 1513 * This output is prepended by the * character. 1514 */ 1515 GDBWIRE_MI_EXEC, 1516 1517 /** 1518 * The asyncronous notify record kind. 1519 * 1520 * Contains supplementary information that the client should handle 1521 * (e.g., a new breakpoint information). 1522 * 1523 * This output is prepended by the = character. 1524 */ 1525 GDBWIRE_MI_NOTIFY 1526 }; 1527 1528 /** The stream out of band record kinds */ 1529 enum gdbwire_mi_stream_record_kind { 1530 /** 1531 * The console output. 1532 * 1533 * Output that should be displayed as is in the console. 1534 * It is the textual response to a CLI command. 1535 * 1536 * This output is prepended by the ~ character. 1537 */ 1538 GDBWIRE_MI_CONSOLE, 1539 1540 /** 1541 * The target output. 1542 * 1543 * Output produced by the target program. 1544 * 1545 * This output is prepended by the @ character. 1546 */ 1547 GDBWIRE_MI_TARGET, 1548 1549 /** 1550 * The GDB log output. 1551 * 1552 * Output text coming from GDB's internals. For instance messages 1553 * that should be displayed as part of an error log. 1554 * 1555 * This output is prepended by the & character. 1556 */ 1557 GDBWIRE_MI_LOG 1558 }; 1559 1560 /** 1561 * The GDB/MI asyncronous class. 1562 * 1563 * 1564 */ 1565 enum gdbwire_mi_async_class { 1566 /** 1567 * Loading the executable onto the remote target. 1568 * 1569 * This was undocumented in the GDB manual as far as GDB 7.7. 1570 * 1571 * This occurs if the async record is GDBWIRE_MI_STATUS as +download. 1572 */ 1573 GDBWIRE_MI_ASYNC_DOWNLOAD, 1574 1575 /** 1576 * The target has stopped. 1577 * 1578 * This occurs if the async record is GDBWIRE_MI_EXEC as *stopped. 1579 */ 1580 GDBWIRE_MI_ASYNC_STOPPED, 1581 1582 /** 1583 * The target is now running. 1584 * 1585 * This occurs if the async record is GDBWIRE_MI_EXEC as *running. 1586 */ 1587 GDBWIRE_MI_ASYNC_RUNNING, 1588 1589 /** 1590 * Reports that a thread group was added. 1591 * 1592 * When a thread group is added, it generally might not be associated 1593 * with a running process. 1594 * 1595 * This occurs if the async record is GDBWIRE_MI_NOTIFY 1596 * as =thread-group-added. 1597 */ 1598 GDBWIRE_MI_ASYNC_THREAD_GROUP_ADDED, 1599 1600 /** 1601 * Reports that a thread group was removed. 1602 * 1603 * When a thread group is removed, its id becomes invalid and cannot be 1604 * used in any way. 1605 * 1606 * This occurs if the async record is GDBWIRE_MI_NOTIFY 1607 * as =thread-group-removed. 1608 */ 1609 GDBWIRE_MI_ASYNC_THREAD_GROUP_REMOVED, 1610 1611 /** 1612 * Reports that a thread group was started. 1613 * 1614 * A thread group became associated with a running program. 1615 * 1616 * This occurs if the async record is GDBWIRE_MI_NOTIFY 1617 * as =thread-group-started. 1618 */ 1619 GDBWIRE_MI_ASYNC_THREAD_GROUP_STARTED, 1620 1621 /** 1622 * Reports that a thread group was exited. 1623 * 1624 * A thread group is no longer associated with a running program. 1625 * 1626 * This occurs if the async record is GDBWIRE_MI_NOTIFY 1627 * as =thread-group-exited. 1628 */ 1629 GDBWIRE_MI_ASYNC_THREAD_GROUP_EXITED, 1630 1631 /** 1632 * Reports that a thread was created. 1633 * 1634 * This occurs if the async record is GDBWIRE_MI_NOTIFY 1635 * as =thread-created. 1636 */ 1637 GDBWIRE_MI_ASYNC_THREAD_CREATED, 1638 1639 /** 1640 * Reports that a thread was exited. 1641 * 1642 * This occurs if the async record is GDBWIRE_MI_NOTIFY as =thread-exited. 1643 */ 1644 GDBWIRE_MI_ASYNC_THREAD_EXITED, 1645 1646 /** 1647 * Reports that a thread was selected. 1648 * 1649 * This occurs if the async record is GDBWIRE_MI_NOTIFY as =thread-selected. 1650 */ 1651 GDBWIRE_MI_ASYNC_THREAD_SELECTED, 1652 1653 /** 1654 * Reports that a new library was loaded. 1655 * 1656 * This occurs if the async record is GDBWIRE_MI_NOTIFY as =library-loaded. 1657 */ 1658 GDBWIRE_MI_ASYNC_LIBRARY_LOADED, 1659 1660 /** 1661 * Reports that a new library was unloaded. 1662 * 1663 * This occurs if the async record is GDBWIRE_MI_NOTIFY 1664 * as =library-unloaded. 1665 */ 1666 GDBWIRE_MI_ASYNC_LIBRARY_UNLOADED, 1667 1668 /** 1669 * Reports that a trace frame was changed. 1670 * 1671 * This occurs if the async record is GDBWIRE_MI_NOTIFY 1672 * as =traceframe-changed. 1673 */ 1674 GDBWIRE_MI_ASYNC_TRACEFRAME_CHANGED, 1675 1676 /** 1677 * Reports that a trace state variable was created. 1678 * 1679 * This occurs if the async record is GDBWIRE_MI_NOTIFY as =tsv-created. 1680 */ 1681 GDBWIRE_MI_ASYNC_TSV_CREATED, 1682 1683 /** 1684 * Reports that a trace state variable was modified. 1685 * 1686 * This occurs if the async record is GDBWIRE_MI_NOTIFY as =tsv-modified. 1687 */ 1688 GDBWIRE_MI_ASYNC_TSV_MODIFIED, 1689 1690 /** 1691 * Reports that a trace state variable was deleted. 1692 * 1693 * This occurs if the async record is GDBWIRE_MI_NOTIFY as =tsv-deleted. 1694 */ 1695 GDBWIRE_MI_ASYNC_TSV_DELETED, 1696 1697 /** 1698 * Reports that a breakpoint was created. 1699 * 1700 * Only user-visible breakpoints are reported to the MI user. 1701 * 1702 * If a breakpoint is emitted in the result record of a 1703 * command, then it will not also be emitted in an async record. 1704 * 1705 * This occurs if the async record is GDBWIRE_MI_NOTIFY 1706 * as =breakpoint-created. 1707 */ 1708 GDBWIRE_MI_ASYNC_BREAKPOINT_CREATED, 1709 1710 /** 1711 * Reports that a breakpoint was modified. 1712 * 1713 * Only user-visible breakpoints are reported to the MI user. 1714 * 1715 * If a breakpoint is emitted in the result record of a 1716 * command, then it will not also be emitted in an async record. 1717 * 1718 * This occurs if the async record is GDBWIRE_MI_NOTIFY 1719 * as =breakpoint-modified. 1720 */ 1721 GDBWIRE_MI_ASYNC_BREAKPOINT_MODIFIED, 1722 1723 /** 1724 * Reports that a breakpoint was deleted. 1725 * 1726 * Only user-visible breakpoints are reported to the MI user. 1727 * 1728 * If a breakpoint is emitted in the result record of a 1729 * command, then it will not also be emitted in an async record. 1730 * 1731 * This occurs if the async record is GDBWIRE_MI_NOTIFY 1732 * as =breakpoint-deleted. 1733 */ 1734 GDBWIRE_MI_ASYNC_BREAKPOINT_DELETED, 1735 1736 /** 1737 * Reports that execution log recording was started on an inferior. 1738 * 1739 * This occurs if the async record is GDBWIRE_MI_NOTIF 1740 * as =record-started. 1741 */ 1742 GDBWIRE_MI_ASYNC_RECORD_STARTED, 1743 1744 /** 1745 * Reports that execution log recording was stopped on an inferior. 1746 * 1747 * This occurs if the async record is GDBWIRE_MI_NOTIFY 1748 * as =record-stopped. 1749 */ 1750 GDBWIRE_MI_ASYNC_RECORD_STOPPED, 1751 1752 /** 1753 * Reports that a parameter of the command set param is changed to value. 1754 * 1755 * For example, when the user runs a command like 'set print pretty on', 1756 * this async command will be invoked with the parameter reported as 1757 * 'print pretty' and the value as 'on'. 1758 * 1759 * This occurs if the async record is GDBWIRE_MI_NOTIFY 1760 * as =cmd-param-changed. 1761 */ 1762 GDBWIRE_MI_ASYNC_CMD_PARAM_CHANGED, 1763 1764 /** 1765 * Reports that bytes from addr to data + len were written in an inferior. 1766 * 1767 * This occurs if the async record is GDBWIRE_MI_NOTIFY 1768 * as =memory-changed. 1769 */ 1770 GDBWIRE_MI_ASYNC_MEMORY_CHANGED, 1771 1772 /* An unsupported async class */ 1773 GDBWIRE_MI_ASYNC_UNSUPPORTED 1774 }; 1775 1776 /** 1777 * The GDB/MI asyncronous record in an output command. 1778 * 1779 * An asyncronous record occurs when GDB would like to update the 1780 * client with information that it has not asked for. 1781 */ 1782 struct gdbwire_mi_async_record { 1783 /** 1784 * The result record token. 1785 * 1786 * Please note that the GDB/MI manual says that asyncronous records 1787 * do not currently populate this token on output but reserve the right 1788 * to do so. For that reason, token here should always be NULL. 1789 * 1790 * From the GDB documentation: 1791 * Note that for all async output, while the token is allowed by the 1792 * grammar and may be output by future versions of gdb for select async 1793 * output messages, it is generally omitted. Frontends should treat all 1794 * async output as reporting general changes in the state of the target 1795 * and there should be no need to associate async output to any prior 1796 * command. 1797 * 1798 * After further investigation, I determined that newer GDB's will no 1799 * longer ever output this information. Older GDB's will. The commit 1800 * that made this change in GDB is 721c02de on April 24th, 2008. 1801 * The next GDB that was released was on October 6th, 2009, version 7.0. 1802 * 1803 * Before the above mentioned commit async *stopped commands would 1804 * sometimes output the token associated with the last token provided in 1805 * a GDB/MI input command. After that change, the token is never 1806 * associated with an async output command, even though the 1807 * documentation says it might be. 1808 * 1809 * Finally, even before that change when the token was output in the 1810 * async *stopped command, the developers of GDB felt that it was not 1811 * useful and should be avoided by front ends. 1812 * 1813 * With this information, I've determined that front ends should never 1814 * use this value to determine logic. However, the value is parsed in 1815 * order to accurately handle and represent the cases where this value 1816 * occurs. 1817 * 1818 * This represents the token value the front end provided to the 1819 * corresponding GDB/MI input command or NULL if no token was provided. 1820 */ 1821 gdbwire_mi_token_t token; 1822 1823 /** The kind of asynchronous record. */ 1824 enum gdbwire_mi_async_record_kind kind; 1825 1826 /** The asynchronous output class */ 1827 enum gdbwire_mi_async_class async_class; 1828 1829 /** 1830 * An optional list of results for this async output. 1831 * 1832 * Will be NULL if there is no results. 1833 */ 1834 struct gdbwire_mi_result *result; 1835 }; 1836 1837 /** The GDB/MI result kind */ 1838 enum gdbwire_mi_result_kind { 1839 /** The result is a cstring */ 1840 GDBWIRE_MI_CSTRING, 1841 /** The result is a tuple */ 1842 GDBWIRE_MI_TUPLE, 1843 /** The result is a list */ 1844 GDBWIRE_MI_LIST 1845 }; 1846 1847 /** 1848 * A GDB/MI result list. 1849 * 1850 * This is one of the important GDB/MI data structures. GDB communicates many 1851 * of it's values to the front end through this key/value data structure. 1852 * 1853 * It is basically a list of key/value pairs, where the key is a 1854 * variable name and the value expands to a string, a tuple of results or 1855 * a list of results. 1856 * 1857 * This can be thought of as a custom json object. 1858 */ 1859 struct gdbwire_mi_result { 1860 /** The kind of result this represents. */ 1861 enum gdbwire_mi_result_kind kind; 1862 1863 /** The key being described by the result. */ 1864 char *variable; 1865 1866 union { 1867 /** When kind is GDBWIRE_MI_CSTRING */ 1868 char *cstring; 1869 1870 /** 1871 * When kind is GDBWIRE_MI_TUPLE or GDBWIRE_MI_LIST. 1872 * 1873 * If kind is GDBWIRE_MI_TUPLE, each result in the tuple should have a 1874 * valid key according to the GDB/MI specification. That is, for 1875 * each result, result->variable should not be NULL. 1876 * Note: GDBWIRE currently relaxes the above rule. It allows tuple's 1877 * with out a key in each member. For instance, {key="value"} 1878 * is what the GDB/MI specification advocates for, but some 1879 * variations of GDB emit {"value"} and so GDBWIRE allows it. 1880 * 1881 * If kind is GDBWIRE_MI_LIST, the GDB/MI specification allows 1882 * results in this list to not have keys. That is, for each result, 1883 * result->variable may be NULL. 1884 * 1885 * Will be NULL if the tuple or list is empty. 1886 */ 1887 struct gdbwire_mi_result *result; 1888 } variant; 1889 1890 /** The next result or NULL if none */ 1891 struct gdbwire_mi_result *next; 1892 }; 1893 1894 /** 1895 * An out of band GDB/MI stream record. 1896 * 1897 * A stream record is intended to provide the front end with information 1898 * from the console, the target or from GDB itself. 1899 */ 1900 struct gdbwire_mi_stream_record { 1901 /** The kind of stream record. */ 1902 enum gdbwire_mi_stream_record_kind kind; 1903 /** The buffer provided in this stream record. */ 1904 char *cstring; 1905 }; 1906 1907 void gdbwire_mi_output_free(struct gdbwire_mi_output *param); 1908 1909 struct gdbwire_mi_output *append_gdbwire_mi_output( 1910 struct gdbwire_mi_output *list, struct gdbwire_mi_output *item); 1911 1912 struct gdbwire_mi_result *append_gdbwire_mi_result( 1913 struct gdbwire_mi_result *list, struct gdbwire_mi_result *item); 1914 1915 #ifdef __cplusplus 1916 } 1917 #endif 1918 1919 #endif 1920 /***** End of gdbwire_mi_pt.h ************************************************/ 1921 /***** Continuing where we left off in gdbwire_mi_parser.h *******************/ 1922 1923 /* The opaque GDB/MI parser context */ 1924 struct gdbwire_mi_parser; 1925 1926 /** 1927 * The primary mechanism to alert users of GDB/MI notifications. 1928 * 1929 * The flow is like this: 1930 * - create a parser context (gdbwire_mi_parser_create) 1931 * - push onto the parser arbitrary amounts of data (gdbwire_mi_parser_push) 1932 * - receive callbacks from inside gdbwire_mi_parser_push when 1933 * it discovers callbacks the user will find interesting 1934 * - destroy the parser (gdbwire_mi_parser_destroy) 1935 */ 1936 struct gdbwire_mi_parser_callbacks { 1937 /** 1938 * An arbitrary pointer to associate with the callbacks. 1939 * 1940 * If the calling api is C++ it is useful to make this an instance 1941 * of an object you want to bind to the callback functions below. 1942 */ 1943 void *context; 1944 1945 /** 1946 * A GDB/MI output command is available. 1947 * 1948 * @param context 1949 * The context pointer above. 1950 * 1951 * @param output 1952 * The gdbwire_mi output command. This output command is now owned by the 1953 * function being invoked and should be destroyed when necessary. 1954 */ 1955 void (*gdbwire_mi_output_callback)(void *context, 1956 struct gdbwire_mi_output *output); 1957 }; 1958 1959 /** 1960 * Create a GDB/MI parser context. 1961 * 1962 * @param callbacks 1963 * The callback functions to invoke upon discovery of parse data. 1964 * 1965 * @return 1966 * A new GDB/MI parser instance or NULL on error. 1967 */ 1968 struct gdbwire_mi_parser *gdbwire_mi_parser_create( 1969 struct gdbwire_mi_parser_callbacks callbacks); 1970 1971 /** 1972 * Destroy a gdbwire_mi_parser context. 1973 * 1974 * This function will do nothing if parser is NULL. 1975 * 1976 * @param parser 1977 * The instance the parser to destroy 1978 */ 1979 void gdbwire_mi_parser_destroy(struct gdbwire_mi_parser *parser); 1980 1981 /** 1982 * Push a null terminated string onto the parser. 1983 * 1984 * During this function, if a gdbwire_mi output command is discovered by 1985 * the parser (or any other useful GDB/MI notification), it will invoke 1986 * the appropriate callbacks assigned during parser creation. 1987 * 1988 * @param parser 1989 * The gdbwire_mi parser context to operate on. 1990 * 1991 * @param data 1992 * The parse data to push onto the parser. 1993 * 1994 * @return 1995 * GDBWIRE_OK on success or appropriate error result on failure. 1996 */ 1997 enum gdbwire_result gdbwire_mi_parser_push(struct gdbwire_mi_parser *parser, 1998 const char *data); 1999 2000 /** 2001 * Push some parse data onto the parser. 2002 * 2003 * See gdbwire_mi_parser_push for details on function behavior. 2004 * 2005 * @param parser 2006 * The gdbwire_mi parser context to operate on. 2007 * 2008 * @param data 2009 * The parse data to push onto the parser. 2010 * 2011 * @param size 2012 * The size of the data to push onto the parser. 2013 * 2014 * @return 2015 * GDBWIRE_OK on success or appropriate error result on failure. 2016 */ 2017 enum gdbwire_result gdbwire_mi_parser_push_data( 2018 struct gdbwire_mi_parser *parser, const char *data, size_t size); 2019 2020 #ifdef __cplusplus 2021 } 2022 #endif 2023 2024 #endif 2025 /***** End of gdbwire_mi_parser.h ********************************************/ 2026 /***** Begin file gdbwire_mi_command.h ***************************************/ 2027 #ifndef GDBWIRE_MI_COMMAND_H 2028 #define GDBWIRE_MI_COMMAND_H 2029 2030 #ifdef __cplusplus 2031 extern "C" { 2032 #endif 2033 2034 /* #include "gdbwire_result.h" */ 2035 /* #include "gdbwire_mi_pt.h" */ 2036 2037 /** 2038 * An enumeration representing the supported GDB/MI commands. 2039 */ 2040 enum gdbwire_mi_command_kind { 2041 /* -break-info */ 2042 GDBWIRE_MI_BREAK_INFO, 2043 2044 /* -stack-info-frame */ 2045 GDBWIRE_MI_STACK_INFO_FRAME, 2046 2047 /* -file-list-exec-source-file */ 2048 GDBWIRE_MI_FILE_LIST_EXEC_SOURCE_FILE, 2049 /* -file-list-exec-source-files */ 2050 GDBWIRE_MI_FILE_LIST_EXEC_SOURCE_FILES 2051 }; 2052 2053 /** A linked list of source files. */ 2054 struct gdbwire_mi_source_file { 2055 /** A relative path to a file, never NULL */ 2056 char *file; 2057 /**An absolute path to a file, NULL if unavailable */ 2058 char *fullname; 2059 /** The next file name or NULL if no more. */ 2060 struct gdbwire_mi_source_file *next; 2061 }; 2062 2063 /** The disposition of a breakpoint. What to do after hitting it. */ 2064 enum gdbwire_mi_breakpoint_disp_kind { 2065 GDBWIRE_MI_BP_DISP_DELETE, /** Delete on next hit */ 2066 GDBWIRE_MI_BP_DISP_DELETE_NEXT_STOP, /** Delete on next stop, hit or not */ 2067 GDBWIRE_MI_BP_DISP_DISABLE, /** Disable on next hit */ 2068 GDBWIRE_MI_BP_DISP_KEEP, /** Leave the breakpoint in place */ 2069 GDBWIRE_MI_BP_DISP_UNKNOWN /** When GDB doesn't specify */ 2070 }; 2071 2072 /** 2073 * A linked list of breakpoints. 2074 * 2075 * A breakpoint is a breakpoint, a tracepoint, a watchpoing or a 2076 * catchpoint. The GDB breakpoint model is quite sophisticated. 2077 * This structure can be extended when necessary. 2078 */ 2079 struct gdbwire_mi_breakpoint { 2080 /** 2081 * The breakpoint number. 2082 * 2083 * An integer, however, for a breakpoint that represents one location of 2084 * a multiple location breakpoint, this will be a dotted pair, like ‘1.2’. 2085 * 2086 * Never NULL. 2087 */ 2088 char *number; 2089 2090 /** 2091 * Determines if this is a multiple location breakpoint. 2092 * 2093 * True for a multi-location breakpoint, false otherwise. 2094 * 2095 * It is possible that a breakpoint corresponds to several locations in 2096 * your program. For example, several functions may have the same name. 2097 * For the following source code, 2098 * int foo(int p) { return p; } 2099 * double foo(double p) { return p; } 2100 * int main() { int i = 1; double d = 2.3; return foo(i) + foo(d); } 2101 * If the user sets a breakpoint at foo by typing, 2102 * b foo 2103 * Then gdb will create 3 breakpoints. The multiple location breakpoint, 2104 * which is the parent of the two breakpoints created for each foo 2105 * function. Here is the output of gdb from the CLI perspective, 2106 * Num Type Disp Enb Address What 2107 * 1 breakpoint keep y <MULTIPLE> 2108 * 1.1 y 0x4004dd in foo(int) at main.cpp:1 2109 * 1.2 y 0x4004eb in foo(double) at main.cpp:2 2110 * 2111 * However, if the user created a breakpoint for main by typing, 2112 * b main 2113 * Then gdb will only create a single breakpoint which would look like, 2114 * 1 breakpoint keep y 0x4004fa in main() at main.cpp:3 2115 * 2116 * When this is true, the address field will be "<MULTIPLE>" and 2117 * the field multi_breakpoints will represent the breakpoints that this 2118 * multiple location breakpoint has created. 2119 */ 2120 unsigned char multi:1; 2121 2122 /** 2123 * True for breakpoints of a multi-location breakpoint, otherwise false. 2124 * 2125 * For the example above, 1.1 and 1.2 would have this field set true. 2126 * 2127 * When this is true, the field multi_breakpoint will represent 2128 * the multiple location breakpoint that has created this breakpoint. 2129 */ 2130 unsigned char from_multi:1; 2131 2132 /** 2133 * The breakpoint type. 2134 * 2135 * Typically "breakpoint", "watchpoint" or "catchpoint", but can be 2136 * a variety of different values. In gdb, see breakpoint.c:bptype_string 2137 * to see all the different possibilities. 2138 * 2139 * This will be NULL for breakpoints of a multiple location breakpoint. 2140 * In this circumstance, check the multi_breakpoint field for the 2141 * multiple location breakpoint type field. 2142 */ 2143 char *type; 2144 2145 /** 2146 * The type of the catchpoint or NULL if not a catch point. 2147 * 2148 * This field is only valid when the breakpoint is a catchpoint. 2149 * Unfortuntely, gdb says the "type" of the breakpoint in the type field 2150 * is "breakpoint" not "catchpoint". So if this field is non-NULL, it is 2151 * safe to assume that this breakpoint represents at catch point. 2152 */ 2153 char *catch_type; 2154 2155 /** 2156 * The breakpoint disposition. 2157 * 2158 * For multiple location breakpoints, this will be 2159 * GDBWIRE_MI_BP_DISP_UNKNOWN. In this circumstance, check the 2160 * multi_breakpoint field for the multiple location breakpoint 2161 * disposition field. 2162 */ 2163 enum gdbwire_mi_breakpoint_disp_kind disposition; 2164 2165 /** True if enabled or False if disabled. */ 2166 unsigned char enabled:1; 2167 2168 /** 2169 * The address of the breakpoint. 2170 * 2171 * This may be 2172 * - a hexidecimal number, representing the address 2173 * - the string ‘<PENDING>’ for a pending breakpoint 2174 * - the string ‘<MULTIPLE>’ for a breakpoint with multiple locations 2175 * 2176 * This field will be NULL if no address can be determined. 2177 * For example, a watchpoint does not have an address. 2178 */ 2179 char *address; 2180 2181 /** 2182 * The name of the function or NULL if unknown. 2183 */ 2184 char *func_name; 2185 2186 /** 2187 * A relative path to the file the breakpoint is in or NULL if unknown. 2188 */ 2189 char *file; 2190 2191 /** 2192 * An absolute path to the file the breakpoint is in or NULL if unknown. 2193 */ 2194 char *fullname; 2195 2196 /** 2197 * The line number the breakpoint is at or 0 if unkonwn. 2198 */ 2199 unsigned long line; 2200 2201 /** 2202 * The number of times this breakpoint has been hit. 2203 * 2204 * For breakpoints of multi-location breakpoints, this will be 0. 2205 * Look at the multi-location breakpoint field instead. 2206 */ 2207 unsigned long times; 2208 2209 /** 2210 * The location of the breakpoint as originally specified by the user. 2211 * 2212 * This may be NULL for instance, for breakpoints for multi-breakpoints. 2213 */ 2214 char *original_location; 2215 2216 /** 2217 * True for a pending breakpoint, otherwise false. 2218 * 2219 * When this is true, the address field will be "<PENDING>". 2220 */ 2221 unsigned char pending:1; 2222 2223 /** 2224 * The breakpoints for a multi-location breakpoint. 2225 * 2226 * If multi is true, this will be the breakpoints associated with the 2227 * multiple location breakpoint. Otherwise will be NULL. 2228 */ 2229 struct gdbwire_mi_breakpoint *multi_breakpoints; 2230 2231 /** 2232 * A pointer to the multi location breakpoint that created this breakpoint. 2233 * 2234 * When the field from_multi is true, this will be a pointer to the 2235 * multi-location breakpoint that created this breakpoint. Otherwise NULL. 2236 * 2237 * For the example above in the multi field, breakpoints 1.1 and 1.2 2238 * would have this field pointing to the breakpoint 1. 2239 */ 2240 struct gdbwire_mi_breakpoint *multi_breakpoint; 2241 2242 2243 /** The next breakpoint or NULL if no more. */ 2244 struct gdbwire_mi_breakpoint *next; 2245 }; 2246 2247 struct gdbwire_mi_stack_frame { 2248 /** 2249 * The frame number. 2250 * 2251 * Where 0 is the topmost frame, i.e., the innermost function. 2252 * 2253 * Always present. 2254 */ 2255 unsigned level; 2256 2257 /** 2258 * The address ($pc value) of the frame. 2259 * 2260 * May be NULL if GDB can not determine the frame address. 2261 */ 2262 char *address; 2263 2264 /** 2265 * The function name for the frame. May be NULL if unknown. 2266 */ 2267 char *func; 2268 2269 /** 2270 * The file name for the frame. May be NULL if unknown. 2271 */ 2272 char *file; 2273 2274 /** 2275 * The fullname name for the frame. May be NULL if unknown. 2276 */ 2277 char *fullname; 2278 2279 /** 2280 * Line number corresponding to the $pc. Maybe be 0 if unknown. 2281 */ 2282 int line; 2283 2284 /** 2285 * The shared library where this function is defined. 2286 * 2287 * This is only given if the frame's function is not known. 2288 * May be NULL if unknown. 2289 */ 2290 char *from; 2291 }; 2292 2293 /** 2294 * Represents a GDB/MI command. 2295 */ 2296 struct gdbwire_mi_command { 2297 /** 2298 * The kind of mi command this represents. 2299 */ 2300 enum gdbwire_mi_command_kind kind; 2301 2302 union { 2303 /** When kind == GDBWIRE_MI_BREAK_INFO */ 2304 struct { 2305 /** The list of breakpoints, NULL if none exist. */ 2306 struct gdbwire_mi_breakpoint *breakpoints; 2307 } break_info; 2308 2309 /** When kind == GDBWIRE_MI_STACK_INFO_FRAME */ 2310 struct { 2311 struct gdbwire_mi_stack_frame *frame; 2312 } stack_info_frame; 2313 2314 /** When kind == GDBWIRE_MI_FILE_LIST_EXEC_SOURCE_FILE */ 2315 struct { 2316 /** 2317 * The line number the inferior is currently executing at. 2318 */ 2319 int line; 2320 2321 /** 2322 * The filename the inferior is currently executing at. 2323 * 2324 * This is usually a relative path. 2325 */ 2326 char *file; 2327 2328 /** 2329 * The filename the inferior is currently executing at. 2330 * 2331 * This is an absolute path. 2332 * 2333 * This command was addd in 2004, however, it was possible 2334 * at the time that only the "file" field would be put out and 2335 * the "fullname" field would be omitted. In 2012, in git commit, 2336 * f35a17b5, gdb was changed to always omit the "fullname" field. 2337 */ 2338 char *fullname; 2339 2340 /** 2341 * Determines if the file includes preprocessor macro information. 2342 * 2343 * This command was added in 2004. However, the macro-info 2344 * field was added to the output in 2008 in git commit 17784837. 2345 * 2346 * Only check this field if macro_info_exists is true. 2347 */ 2348 char macro_info:1; 2349 2350 /** True if macro-info field was in mi output, otherwise false */ 2351 char macro_info_exists:1; 2352 } file_list_exec_source_file; 2353 2354 /** When kind == GDBWIRE_MI_FILE_LIST_EXEC_SOURCE_FILES */ 2355 struct { 2356 /** 2357 * A list of files that make up the inferior. 2358 * 2359 * When there are no files (if the gdb does not have an inferior 2360 * loaded) than files will be NULL. 2361 * 2362 * This command was addd in 2004, however, it was possible 2363 * at the time that only the "file" field would be put out and 2364 * the "fullname" field would be omitted. In 2012, in git commit, 2365 * f35a17b5, gdb was changed to always omit the "fullname" field. 2366 */ 2367 struct gdbwire_mi_source_file *files; 2368 } file_list_exec_source_files; 2369 2370 } variant; 2371 }; 2372 2373 /** 2374 * Get a gdbwire MI command from the result record. 2375 * 2376 * @param kind 2377 * The kind of command the result record is associated with. 2378 * 2379 * @param result_record 2380 * The result record to turn into a command. 2381 * 2382 * @param out_mi_command 2383 * Will return an allocated gdbwire mi command if GDBWIRE_OK is returned 2384 * from this function. You should free this memory with 2385 * gdbwire_mi_command_free when you are done with it. 2386 * 2387 * @return 2388 * The result of this function. 2389 */ 2390 enum gdbwire_result gdbwire_get_mi_command( 2391 enum gdbwire_mi_command_kind kind, 2392 struct gdbwire_mi_result_record *result_record, 2393 struct gdbwire_mi_command **out_mi_command); 2394 2395 /** 2396 * Free the gdbwire mi command. 2397 * 2398 * @param mi_command 2399 * The mi command to free. 2400 */ 2401 void gdbwire_mi_command_free(struct gdbwire_mi_command *mi_command); 2402 2403 #ifdef __cplusplus 2404 } 2405 #endif 2406 2407 #endif 2408 /***** End of gdbwire_mi_command.h *******************************************/ 2409 /***** Begin file gdbwire_mi_grammar.h ***************************************/ 2410 /* A Bison parser, made by GNU Bison 3.0.4. */ 2411 2412 /* Bison interface for Yacc-like parsers in C 2413 2414 Copyright 1984, 1989-1990, 2000-2015 Free Software Foundation, Inc. 2415 2416 This program is free software: you can redistribute it and/or modify 2417 it under the terms of the GNU General Public License as published by 2418 the Free Software Foundation, either version 3 of the License, or 2419 (at your option) any later version. 2420 2421 This program is distributed in the hope that it will be useful, 2422 but WITHOUT ANY WARRANTY; without even the implied warranty of 2423 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 2424 GNU General Public License for more details. 2425 2426 You should have received a copy of the GNU General Public License 2427 along with this program. If not, see <http://www.gnu.org/licenses/>. */ 2428 2429 /* As a special exception, you may create a larger work that contains 2430 part or all of the Bison parser skeleton and distribute that work 2431 under terms of your choice, so long as that work isn't itself a 2432 parser generator using the skeleton or a modified version thereof 2433 as a parser skeleton. Alternatively, if you modify or redistribute 2434 the parser skeleton itself, you may (at your option) remove this 2435 special exception, which will cause the skeleton and the resulting 2436 Bison output files to be licensed under the GNU General Public 2437 License without this special exception. 2438 2439 This special exception was added by the Free Software Foundation in 2440 version 2.2 of Bison. */ 2441 2442 #ifndef YY_GDBWIRE_MI_SRC_GDBWIRE_MI_GRAMMAR_H_INCLUDED 2443 # define YY_GDBWIRE_MI_SRC_GDBWIRE_MI_GRAMMAR_H_INCLUDED 2444 /* Debug traces. */ 2445 #ifndef YYDEBUG 2446 # define YYDEBUG 0 2447 #endif 2448 #if YYDEBUG 2449 extern int gdbwire_mi_debug; 2450 #endif 2451 /* "%code requires" blocks. */ 2452 2453 2454 /* An opaque pointer. */ 2455 #ifndef YY_TYPEDEF_YY_SCANNER_T 2456 #define YY_TYPEDEF_YY_SCANNER_T 2457 typedef void *yyscan_t; 2458 #endif 2459 2460 struct gdbwire_mi_output; 2461 2462 2463 /* Token type. */ 2464 #ifndef YYTOKENTYPE 2465 # define YYTOKENTYPE 2466 enum yytokentype 2467 { 2468 OPEN_BRACE = 258, 2469 CLOSED_BRACE = 259, 2470 OPEN_PAREN = 260, 2471 CLOSED_PAREN = 261, 2472 ADD_OP = 262, 2473 MULT_OP = 263, 2474 EQUAL_SIGN = 264, 2475 TILDA = 265, 2476 AT_SYMBOL = 266, 2477 AMPERSAND = 267, 2478 OPEN_BRACKET = 268, 2479 CLOSED_BRACKET = 269, 2480 NEWLINE = 270, 2481 INTEGER_LITERAL = 271, 2482 STRING_LITERAL = 272, 2483 CSTRING = 273, 2484 COMMA = 274, 2485 CARROT = 275 2486 }; 2487 #endif 2488 /* Tokens. */ 2489 #define OPEN_BRACE 258 2490 #define CLOSED_BRACE 259 2491 #define OPEN_PAREN 260 2492 #define CLOSED_PAREN 261 2493 #define ADD_OP 262 2494 #define MULT_OP 263 2495 #define EQUAL_SIGN 264 2496 #define TILDA 265 2497 #define AT_SYMBOL 266 2498 #define AMPERSAND 267 2499 #define OPEN_BRACKET 268 2500 #define CLOSED_BRACKET 269 2501 #define NEWLINE 270 2502 #define INTEGER_LITERAL 271 2503 #define STRING_LITERAL 272 2504 #define CSTRING 273 2505 #define COMMA 274 2506 #define CARROT 275 2507 2508 /* Value type. */ 2509 #if ! defined YYSTYPE && ! defined YYSTYPE_IS_DECLARED 2510 2511 union YYSTYPE 2512 { 2513 2514 struct gdbwire_mi_output *u_output; 2515 struct gdbwire_mi_oob_record *u_oob_record; 2516 struct gdbwire_mi_result_record *u_result_record; 2517 int u_result_class; 2518 int u_async_record_kind; 2519 struct gdbwire_mi_result_list *u_result_list; 2520 struct gdbwire_mi_result *u_result; 2521 char *u_token; 2522 struct gdbwire_mi_async_record *u_async_record; 2523 struct gdbwire_mi_stream_record *u_stream_record; 2524 int u_async_class; 2525 char *u_variable; 2526 char *u_cstring; 2527 struct gdbwire_mi_result *u_tuple; 2528 struct gdbwire_mi_result *u_list; 2529 int u_stream_record_kind; 2530 2531 }; 2532 2533 typedef union YYSTYPE YYSTYPE; 2534 # define YYSTYPE_IS_TRIVIAL 1 2535 # define YYSTYPE_IS_DECLARED 1 2536 #endif 2537 2538 2539 2540 #ifndef YYPUSH_MORE_DEFINED 2541 # define YYPUSH_MORE_DEFINED 2542 enum { YYPUSH_MORE = 4 }; 2543 #endif 2544 2545 typedef struct gdbwire_mi_pstate gdbwire_mi_pstate; 2546 2547 int gdbwire_mi_push_parse (gdbwire_mi_pstate *ps, int pushed_char, YYSTYPE const *pushed_val, yyscan_t yyscanner, struct gdbwire_mi_output **gdbwire_mi_output); 2548 2549 gdbwire_mi_pstate * gdbwire_mi_pstate_new (void); 2550 void gdbwire_mi_pstate_delete (gdbwire_mi_pstate *ps); 2551 2552 #endif /* !YY_GDBWIRE_MI_SRC_GDBWIRE_MI_GRAMMAR_H_INCLUDED */ 2553 /***** End of gdbwire_mi_grammar.h *******************************************/ 2554 /***** Begin file gdbwire.h **************************************************/ 2555 /** 2556 * Copyright 2013 Robert Rossi <bob@brasko.net> 2557 * 2558 * This file is part of GDBWIRE. 2559 * 2560 * GDBWIRE is free software: you can redistribute it and/or modify 2561 * it under the terms of the GNU General Public License as published by 2562 * the Free Software Foundation, either version 3 of the License, or 2563 * (at your option) any later version. 2564 * 2565 * GDBWIRE is distributed in the hope that it will be useful, 2566 * but WITHOUT ANY WARRANTY; without even the implied warranty of 2567 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 2568 * GNU General Public License for more details. 2569 * 2570 * You should have received a copy of the GNU General Public License 2571 * along with GDBWIRE. If not, see <http://www.gnu.org/licenses/>. 2572 */ 2573 2574 #ifndef GDBWIRE_H 2575 #define GDBWIRE_H 2576 2577 #ifdef __cplusplus 2578 extern "C" { 2579 #endif 2580 2581 #include <stdlib.h> 2582 /* #include "gdbwire_result.h" */ 2583 /* #include "gdbwire_mi_pt.h" */ 2584 /***** Include gdbwire_mi_command.h in the middle of gdbwire.h ***************/ 2585 /***** Begin file gdbwire_mi_command.h ***************************************/ 2586 #ifndef GDBWIRE_MI_COMMAND_H 2587 #define GDBWIRE_MI_COMMAND_H 2588 2589 #ifdef __cplusplus 2590 extern "C" { 2591 #endif 2592 2593 /* #include "gdbwire_result.h" */ 2594 /* #include "gdbwire_mi_pt.h" */ 2595 2596 /** 2597 * An enumeration representing the supported GDB/MI commands. 2598 */ 2599 enum gdbwire_mi_command_kind { 2600 /* -break-info */ 2601 GDBWIRE_MI_BREAK_INFO, 2602 2603 /* -stack-info-frame */ 2604 GDBWIRE_MI_STACK_INFO_FRAME, 2605 2606 /* -file-list-exec-source-file */ 2607 GDBWIRE_MI_FILE_LIST_EXEC_SOURCE_FILE, 2608 /* -file-list-exec-source-files */ 2609 GDBWIRE_MI_FILE_LIST_EXEC_SOURCE_FILES 2610 }; 2611 2612 /** A linked list of source files. */ 2613 struct gdbwire_mi_source_file { 2614 /** A relative path to a file, never NULL */ 2615 char *file; 2616 /**An absolute path to a file, NULL if unavailable */ 2617 char *fullname; 2618 /** The next file name or NULL if no more. */ 2619 struct gdbwire_mi_source_file *next; 2620 }; 2621 2622 /** The disposition of a breakpoint. What to do after hitting it. */ 2623 enum gdbwire_mi_breakpoint_disp_kind { 2624 GDBWIRE_MI_BP_DISP_DELETE, /** Delete on next hit */ 2625 GDBWIRE_MI_BP_DISP_DELETE_NEXT_STOP, /** Delete on next stop, hit or not */ 2626 GDBWIRE_MI_BP_DISP_DISABLE, /** Disable on next hit */ 2627 GDBWIRE_MI_BP_DISP_KEEP, /** Leave the breakpoint in place */ 2628 GDBWIRE_MI_BP_DISP_UNKNOWN /** When GDB doesn't specify */ 2629 }; 2630 2631 /** 2632 * A linked list of breakpoints. 2633 * 2634 * A breakpoint is a breakpoint, a tracepoint, a watchpoing or a 2635 * catchpoint. The GDB breakpoint model is quite sophisticated. 2636 * This structure can be extended when necessary. 2637 */ 2638 struct gdbwire_mi_breakpoint { 2639 /** 2640 * The breakpoint number. 2641 * 2642 * An integer, however, for a breakpoint that represents one location of 2643 * a multiple location breakpoint, this will be a dotted pair, like ‘1.2’. 2644 * 2645 * Never NULL. 2646 */ 2647 char *number; 2648 2649 /** 2650 * Determines if this is a multiple location breakpoint. 2651 * 2652 * True for a multi-location breakpoint, false otherwise. 2653 * 2654 * It is possible that a breakpoint corresponds to several locations in 2655 * your program. For example, several functions may have the same name. 2656 * For the following source code, 2657 * int foo(int p) { return p; } 2658 * double foo(double p) { return p; } 2659 * int main() { int i = 1; double d = 2.3; return foo(i) + foo(d); } 2660 * If the user sets a breakpoint at foo by typing, 2661 * b foo 2662 * Then gdb will create 3 breakpoints. The multiple location breakpoint, 2663 * which is the parent of the two breakpoints created for each foo 2664 * function. Here is the output of gdb from the CLI perspective, 2665 * Num Type Disp Enb Address What 2666 * 1 breakpoint keep y <MULTIPLE> 2667 * 1.1 y 0x4004dd in foo(int) at main.cpp:1 2668 * 1.2 y 0x4004eb in foo(double) at main.cpp:2 2669 * 2670 * However, if the user created a breakpoint for main by typing, 2671 * b main 2672 * Then gdb will only create a single breakpoint which would look like, 2673 * 1 breakpoint keep y 0x4004fa in main() at main.cpp:3 2674 * 2675 * When this is true, the address field will be "<MULTIPLE>" and 2676 * the field multi_breakpoints will represent the breakpoints that this 2677 * multiple location breakpoint has created. 2678 */ 2679 unsigned char multi:1; 2680 2681 /** 2682 * True for breakpoints of a multi-location breakpoint, otherwise false. 2683 * 2684 * For the example above, 1.1 and 1.2 would have this field set true. 2685 * 2686 * When this is true, the field multi_breakpoint will represent 2687 * the multiple location breakpoint that has created this breakpoint. 2688 */ 2689 unsigned char from_multi:1; 2690 2691 /** 2692 * The breakpoint type. 2693 * 2694 * Typically "breakpoint", "watchpoint" or "catchpoint", but can be 2695 * a variety of different values. In gdb, see breakpoint.c:bptype_string 2696 * to see all the different possibilities. 2697 * 2698 * This will be NULL for breakpoints of a multiple location breakpoint. 2699 * In this circumstance, check the multi_breakpoint field for the 2700 * multiple location breakpoint type field. 2701 */ 2702 char *type; 2703 2704 /** 2705 * The type of the catchpoint or NULL if not a catch point. 2706 * 2707 * This field is only valid when the breakpoint is a catchpoint. 2708 * Unfortuntely, gdb says the "type" of the breakpoint in the type field 2709 * is "breakpoint" not "catchpoint". So if this field is non-NULL, it is 2710 * safe to assume that this breakpoint represents at catch point. 2711 */ 2712 char *catch_type; 2713 2714 /** 2715 * The breakpoint disposition. 2716 * 2717 * For multiple location breakpoints, this will be 2718 * GDBWIRE_MI_BP_DISP_UNKNOWN. In this circumstance, check the 2719 * multi_breakpoint field for the multiple location breakpoint 2720 * disposition field. 2721 */ 2722 enum gdbwire_mi_breakpoint_disp_kind disposition; 2723 2724 /** True if enabled or False if disabled. */ 2725 unsigned char enabled:1; 2726 2727 /** 2728 * The address of the breakpoint. 2729 * 2730 * This may be 2731 * - a hexidecimal number, representing the address 2732 * - the string ‘<PENDING>’ for a pending breakpoint 2733 * - the string ‘<MULTIPLE>’ for a breakpoint with multiple locations 2734 * 2735 * This field will be NULL if no address can be determined. 2736 * For example, a watchpoint does not have an address. 2737 */ 2738 char *address; 2739 2740 /** 2741 * The name of the function or NULL if unknown. 2742 */ 2743 char *func_name; 2744 2745 /** 2746 * A relative path to the file the breakpoint is in or NULL if unknown. 2747 */ 2748 char *file; 2749 2750 /** 2751 * An absolute path to the file the breakpoint is in or NULL if unknown. 2752 */ 2753 char *fullname; 2754 2755 /** 2756 * The line number the breakpoint is at or 0 if unkonwn. 2757 */ 2758 unsigned long line; 2759 2760 /** 2761 * The number of times this breakpoint has been hit. 2762 * 2763 * For breakpoints of multi-location breakpoints, this will be 0. 2764 * Look at the multi-location breakpoint field instead. 2765 */ 2766 unsigned long times; 2767 2768 /** 2769 * The location of the breakpoint as originally specified by the user. 2770 * 2771 * This may be NULL for instance, for breakpoints for multi-breakpoints. 2772 */ 2773 char *original_location; 2774 2775 /** 2776 * True for a pending breakpoint, otherwise false. 2777 * 2778 * When this is true, the address field will be "<PENDING>". 2779 */ 2780 unsigned char pending:1; 2781 2782 /** 2783 * The breakpoints for a multi-location breakpoint. 2784 * 2785 * If multi is true, this will be the breakpoints associated with the 2786 * multiple location breakpoint. Otherwise will be NULL. 2787 */ 2788 struct gdbwire_mi_breakpoint *multi_breakpoints; 2789 2790 /** 2791 * A pointer to the multi location breakpoint that created this breakpoint. 2792 * 2793 * When the field from_multi is true, this will be a pointer to the 2794 * multi-location breakpoint that created this breakpoint. Otherwise NULL. 2795 * 2796 * For the example above in the multi field, breakpoints 1.1 and 1.2 2797 * would have this field pointing to the breakpoint 1. 2798 */ 2799 struct gdbwire_mi_breakpoint *multi_breakpoint; 2800 2801 2802 /** The next breakpoint or NULL if no more. */ 2803 struct gdbwire_mi_breakpoint *next; 2804 }; 2805 2806 struct gdbwire_mi_stack_frame { 2807 /** 2808 * The frame number. 2809 * 2810 * Where 0 is the topmost frame, i.e., the innermost function. 2811 * 2812 * Always present. 2813 */ 2814 unsigned level; 2815 2816 /** 2817 * The address ($pc value) of the frame. 2818 * 2819 * May be NULL if GDB can not determine the frame address. 2820 */ 2821 char *address; 2822 2823 /** 2824 * The function name for the frame. May be NULL if unknown. 2825 */ 2826 char *func; 2827 2828 /** 2829 * The file name for the frame. May be NULL if unknown. 2830 */ 2831 char *file; 2832 2833 /** 2834 * The fullname name for the frame. May be NULL if unknown. 2835 */ 2836 char *fullname; 2837 2838 /** 2839 * Line number corresponding to the $pc. Maybe be 0 if unknown. 2840 */ 2841 int line; 2842 2843 /** 2844 * The shared library where this function is defined. 2845 * 2846 * This is only given if the frame's function is not known. 2847 * May be NULL if unknown. 2848 */ 2849 char *from; 2850 }; 2851 2852 /** 2853 * Represents a GDB/MI command. 2854 */ 2855 struct gdbwire_mi_command { 2856 /** 2857 * The kind of mi command this represents. 2858 */ 2859 enum gdbwire_mi_command_kind kind; 2860 2861 union { 2862 /** When kind == GDBWIRE_MI_BREAK_INFO */ 2863 struct { 2864 /** The list of breakpoints, NULL if none exist. */ 2865 struct gdbwire_mi_breakpoint *breakpoints; 2866 } break_info; 2867 2868 /** When kind == GDBWIRE_MI_STACK_INFO_FRAME */ 2869 struct { 2870 struct gdbwire_mi_stack_frame *frame; 2871 } stack_info_frame; 2872 2873 /** When kind == GDBWIRE_MI_FILE_LIST_EXEC_SOURCE_FILE */ 2874 struct { 2875 /** 2876 * The line number the inferior is currently executing at. 2877 */ 2878 int line; 2879 2880 /** 2881 * The filename the inferior is currently executing at. 2882 * 2883 * This is usually a relative path. 2884 */ 2885 char *file; 2886 2887 /** 2888 * The filename the inferior is currently executing at. 2889 * 2890 * This is an absolute path. 2891 * 2892 * This command was addd in 2004, however, it was possible 2893 * at the time that only the "file" field would be put out and 2894 * the "fullname" field would be omitted. In 2012, in git commit, 2895 * f35a17b5, gdb was changed to always omit the "fullname" field. 2896 */ 2897 char *fullname; 2898 2899 /** 2900 * Determines if the file includes preprocessor macro information. 2901 * 2902 * This command was added in 2004. However, the macro-info 2903 * field was added to the output in 2008 in git commit 17784837. 2904 * 2905 * Only check this field if macro_info_exists is true. 2906 */ 2907 char macro_info:1; 2908 2909 /** True if macro-info field was in mi output, otherwise false */ 2910 char macro_info_exists:1; 2911 } file_list_exec_source_file; 2912 2913 /** When kind == GDBWIRE_MI_FILE_LIST_EXEC_SOURCE_FILES */ 2914 struct { 2915 /** 2916 * A list of files that make up the inferior. 2917 * 2918 * When there are no files (if the gdb does not have an inferior 2919 * loaded) than files will be NULL. 2920 * 2921 * This command was addd in 2004, however, it was possible 2922 * at the time that only the "file" field would be put out and 2923 * the "fullname" field would be omitted. In 2012, in git commit, 2924 * f35a17b5, gdb was changed to always omit the "fullname" field. 2925 */ 2926 struct gdbwire_mi_source_file *files; 2927 } file_list_exec_source_files; 2928 2929 } variant; 2930 }; 2931 2932 /** 2933 * Get a gdbwire MI command from the result record. 2934 * 2935 * @param kind 2936 * The kind of command the result record is associated with. 2937 * 2938 * @param result_record 2939 * The result record to turn into a command. 2940 * 2941 * @param out_mi_command 2942 * Will return an allocated gdbwire mi command if GDBWIRE_OK is returned 2943 * from this function. You should free this memory with 2944 * gdbwire_mi_command_free when you are done with it. 2945 * 2946 * @return 2947 * The result of this function. 2948 */ 2949 enum gdbwire_result gdbwire_get_mi_command( 2950 enum gdbwire_mi_command_kind kind, 2951 struct gdbwire_mi_result_record *result_record, 2952 struct gdbwire_mi_command **out_mi_command); 2953 2954 /** 2955 * Free the gdbwire mi command. 2956 * 2957 * @param mi_command 2958 * The mi command to free. 2959 */ 2960 void gdbwire_mi_command_free(struct gdbwire_mi_command *mi_command); 2961 2962 #ifdef __cplusplus 2963 } 2964 #endif 2965 2966 #endif 2967 /***** End of gdbwire_mi_command.h *******************************************/ 2968 /***** Continuing where we left off in gdbwire.h *****************************/ 2969 2970 /* The opaque gdbwire context */ 2971 struct gdbwire; 2972 2973 /** 2974 * The primary mechanism for gdbwire to send events to the caller. 2975 * 2976 * The flow is like this: 2977 * - create a gdbwire instance 2978 * - loop: 2979 * - call gdbwire functions to send commands to gdb 2980 * - receive callback events with results when they become available 2981 * - destroy the instance 2982 */ 2983 struct gdbwire_callbacks { 2984 /** 2985 * An arbitrary pointer to associate with the events. 2986 * 2987 * This pointer will be passed back to the caller in each event. 2988 */ 2989 void *context; 2990 2991 /** 2992 * A console, target or log output event has occured. 2993 * 2994 * @param context 2995 * The context pointer above. 2996 * 2997 * @param stream_record 2998 * The stream record to display to the user. 2999 */ 3000 void (*gdbwire_stream_record_fn)(void *context, 3001 struct gdbwire_mi_stream_record *stream_record); 3002 3003 /** 3004 * An asynchronous output event. 3005 * 3006 * @param context 3007 * The context pointer above. 3008 * 3009 * @param async_record 3010 * The asychronous record output by GDB. 3011 */ 3012 void (*gdbwire_async_record_fn)(void *context, 3013 struct gdbwire_mi_async_record *async_record); 3014 3015 /** 3016 * A result output event. 3017 * 3018 * @param context 3019 * The context pointer above. 3020 * 3021 * @param result_record 3022 * The result record output by GDB. 3023 */ 3024 void (*gdbwire_result_record_fn)(void *context, 3025 struct gdbwire_mi_result_record *result_record); 3026 3027 /** 3028 * A prompt output event. 3029 * 3030 * @param context 3031 * The context pointer above. 3032 * 3033 * @param prompt 3034 * The prompt output to display to the user. 3035 */ 3036 void (*gdbwire_prompt_fn)(void *context, const char *prompt); 3037 3038 /** 3039 * A gdbwire parse error occurred. 3040 * 3041 * If you receive this callback, that means the gdbwire parser 3042 * failed to parse some gdb/mi coming out of gdb. 3043 * Please send the parameters received in this callback to the 3044 * gdbwire develpment team. 3045 * 3046 * @param context 3047 * The context pointer above. 3048 * 3049 * @param mi 3050 * The mi string that gdbwire could not parse. 3051 * 3052 * @param token 3053 * The token the error occurred on. 3054 * 3055 * @param position 3056 * The position of the token the error occurred on. 3057 */ 3058 void (*gdbwire_parse_error_fn)(void *context, const char *mi, 3059 const char *token, struct gdbwire_mi_position position); 3060 }; 3061 3062 /** 3063 * Create a gdbwire context. 3064 * 3065 * Each gdbwire structure is capable of talking to a single gdb instance. 3066 * 3067 * @param callbacks 3068 * The callback functions for when events should be sent. Be sure to 3069 * initialize all of the callback functions. If a callback event is 3070 * initialized to NULL, it will not be called. 3071 * 3072 * @return 3073 * A new gdbwire instance or NULL on error. 3074 */ 3075 struct gdbwire *gdbwire_create(struct gdbwire_callbacks callbacks); 3076 3077 /** 3078 * Destroy a gdbwire context. 3079 * 3080 * This function will do nothing if the instance is NULL. 3081 * 3082 * @param gdbwire 3083 * The instance of gdbwire to destroy 3084 */ 3085 void gdbwire_destroy(struct gdbwire *wire); 3086 3087 /** 3088 * Push some GDB output characters to gdbwire for processing. 3089 * 3090 * Currently, the calling application is responsible for reading the 3091 * output of GDB and sending it to gdbwire. This may change in the future. 3092 * Call this function with output from GDB when it is available. 3093 * 3094 * During this function, callback events may be invoked to alert the 3095 * caller of useful gdbwire_mi events. 3096 * 3097 * @param wire 3098 * The gdbwire context to operate on. 3099 * 3100 * @param data 3101 * The data to push to gdbwire for interpretation. 3102 * 3103 * @param size 3104 * The size of the data to push to gdbwire. 3105 * 3106 * @return 3107 * GDBWIRE_OK on success or appropriate error result on failure. 3108 */ 3109 enum gdbwire_result gdbwire_push_data(struct gdbwire *wire, const char *data, 3110 size_t size); 3111 3112 /** 3113 * Handle an interpreter-exec command. 3114 * 3115 * Typically, a front end would start gdb with the MI interface and create 3116 * a corresponding gdbwire instance. The front end would feed the gdbwire 3117 * instance all of the MI output. In this scenario, gdbwire triggers 3118 * callbacks when interesting events occur. 3119 * 3120 * Some GDB front ends use the annotate interface with gdb, and will 3121 * transition to using MI through the use of the interpreter-exec command. 3122 * In this scenario, the front end will send GDB a single interpreter-exec 3123 * command and will want to interpret the output of only that command. 3124 * For this use case, a gdbwire instance is not necessary for the front end, 3125 * nor any of the callbacks associated with that instance. 3126 * 3127 * This function provides a way for a front end to interpret the output 3128 * of a single interpreter-exec command with out the need for creating 3129 * a gdbwire instance or any gdbwire callbacks. 3130 * 3131 * @param interpreter_exec_output 3132 * The MI output from GDB for the interpreter exec command. 3133 * 3134 * @param kind 3135 * The interpreter-exec command kind. 3136 * 3137 * @param out_mi_command 3138 * Will return an allocated gdbwire mi command if GDBWIRE_OK is returned 3139 * from this function. You should free this memory with 3140 * gdbwire_mi_command_free when you are done with it. 3141 * 3142 * @return 3143 * The result of this function. 3144 */ 3145 enum gdbwire_result gdbwire_interpreter_exec( 3146 const char *interpreter_exec_output, 3147 enum gdbwire_mi_command_kind kind, 3148 struct gdbwire_mi_command **out_mi_command); 3149 3150 #ifdef __cplusplus 3151 } 3152 #endif 3153 3154 #endif 3155 /***** End of gdbwire.h ******************************************************/ 3156