1This is gdbint.info, produced by makeinfo version 4.6 from 2./gdbint.texinfo. 3 4INFO-DIR-SECTION Software development 5START-INFO-DIR-ENTRY 6* Gdb-Internals: (gdbint). The GNU debugger's internals. 7END-INFO-DIR-ENTRY 8 9 This file documents the internals of the GNU debugger GDB. 10Copyright 111990,1991,1992,1993,1994,1996,1998,1999,2000,2001,2002,2003,2004 12Free Software Foundation, Inc. Contributed by Cygnus Solutions. 13Written by John Gilmore. Second Edition by Stan Shebs. 14 15 Permission is granted to copy, distribute and/or modify this document 16under the terms of the GNU Free Documentation License, Version 1.1 or 17any later version published by the Free Software Foundation; with no 18Invariant Sections, with no Front-Cover Texts, and with no Back-Cover 19Texts. A copy of the license is included in the section entitled "GNU 20Free Documentation License". 21 22 23File: gdbint.info, Node: Top, Next: Requirements, Up: (dir) 24 25Scope of this Document 26********************** 27 28This document documents the internals of the GNU debugger, GDB. It 29includes description of GDB's key algorithms and operations, as well as 30the mechanisms that adapt GDB to specific hosts and targets. 31 32* Menu: 33 34* Requirements:: 35* Overall Structure:: 36* Algorithms:: 37* User Interface:: 38* libgdb:: 39* Symbol Handling:: 40* Language Support:: 41* Host Definition:: 42* Target Architecture Definition:: 43* Target Vector Definition:: 44* Native Debugging:: 45* Support Libraries:: 46* Coding:: 47* Porting GDB:: 48* Releasing GDB:: 49* Testsuite:: 50* Hints:: 51 52* GDB Observers:: GDB Currently available observers 53* GNU Free Documentation License:: The license for this documentation 54* Index:: 55 56 57File: gdbint.info, Node: Requirements, Next: Overall Structure, Prev: Top, Up: Top 58 59Requirements 60************ 61 62Before diving into the internals, you should understand the formal 63requirements and other expectations for GDB. Although some of these 64may seem obvious, there have been proposals for GDB that have run 65counter to these requirements. 66 67 First of all, GDB is a debugger. It's not designed to be a front 68panel for embedded systems. It's not a text editor. It's not a shell. 69It's not a programming environment. 70 71 GDB is an interactive tool. Although a batch mode is available, 72GDB's primary role is to interact with a human programmer. 73 74 GDB should be responsive to the user. A programmer hot on the trail 75of a nasty bug, and operating under a looming deadline, is going to be 76very impatient of everything, including the response time to debugger 77commands. 78 79 GDB should be relatively permissive, such as for expressions. While 80the compiler should be picky (or have the option to be made picky), 81since source code lives for a long time usually, the programmer doing 82debugging shouldn't be spending time figuring out to mollify the 83debugger. 84 85 GDB will be called upon to deal with really large programs. 86Executable sizes of 50 to 100 megabytes occur regularly, and we've 87heard reports of programs approaching 1 gigabyte in size. 88 89 GDB should be able to run everywhere. No other debugger is 90available for even half as many configurations as GDB supports. 91 92 93File: gdbint.info, Node: Overall Structure, Next: Algorithms, Prev: Requirements, Up: Top 94 95Overall Structure 96***************** 97 98GDB consists of three major subsystems: user interface, symbol handling 99(the "symbol side"), and target system handling (the "target side"). 100 101 The user interface consists of several actual interfaces, plus 102supporting code. 103 104 The symbol side consists of object file readers, debugging info 105interpreters, symbol table management, source language expression 106parsing, type and value printing. 107 108 The target side consists of execution control, stack frame analysis, 109and physical target manipulation. 110 111 The target side/symbol side division is not formal, and there are a 112number of exceptions. For instance, core file support involves symbolic 113elements (the basic core file reader is in BFD) and target elements (it 114supplies the contents of memory and the values of registers). Instead, 115this division is useful for understanding how the minor subsystems 116should fit together. 117 118The Symbol Side 119=============== 120 121The symbolic side of GDB can be thought of as "everything you can do in 122GDB without having a live program running". For instance, you can look 123at the types of variables, and evaluate many kinds of expressions. 124 125The Target Side 126=============== 127 128The target side of GDB is the "bits and bytes manipulator". Although 129it may make reference to symbolic info here and there, most of the 130target side will run with only a stripped executable available--or even 131no executable at all, in remote debugging cases. 132 133 Operations such as disassembly, stack frame crawls, and register 134display, are able to work with no symbolic info at all. In some cases, 135such as disassembly, GDB will use symbolic info to present addresses 136relative to symbols rather than as raw numbers, but it will work either 137way. 138 139Configurations 140============== 141 142"Host" refers to attributes of the system where GDB runs. "Target" 143refers to the system where the program being debugged executes. In 144most cases they are the same machine, in which case a third type of 145"Native" attributes come into play. 146 147 Defines and include files needed to build on the host are host 148support. Examples are tty support, system defined types, host byte 149order, host float format. 150 151 Defines and information needed to handle the target format are target 152dependent. Examples are the stack frame format, instruction set, 153breakpoint instruction, registers, and how to set up and tear down the 154stack to call a function. 155 156 Information that is only needed when the host and target are the 157same, is native dependent. One example is Unix child process support; 158if the host and target are not the same, doing a fork to start the 159target process is a bad idea. The various macros needed for finding the 160registers in the `upage', running `ptrace', and such are all in the 161native-dependent files. 162 163 Another example of native-dependent code is support for features that 164are really part of the target environment, but which require `#include' 165files that are only available on the host system. Core file handling 166and `setjmp' handling are two common cases. 167 168 When you want to make GDB work "native" on a particular machine, you 169have to include all three kinds of information. 170 171 172File: gdbint.info, Node: Algorithms, Next: User Interface, Prev: Overall Structure, Up: Top 173 174Algorithms 175********** 176 177GDB uses a number of debugging-specific algorithms. They are often not 178very complicated, but get lost in the thicket of special cases and 179real-world issues. This chapter describes the basic algorithms and 180mentions some of the specific target definitions that they use. 181 182Frames 183====== 184 185A frame is a construct that GDB uses to keep track of calling and 186called functions. 187 188 `FRAME_FP' in the machine description has no meaning to the 189machine-independent part of GDB, except that it is used when setting up 190a new frame from scratch, as follows: 191 192 create_new_frame (read_register (DEPRECATED_FP_REGNUM), read_pc ())); 193 194 Other than that, all the meaning imparted to `DEPRECATED_FP_REGNUM' 195is imparted by the machine-dependent code. So, `DEPRECATED_FP_REGNUM' 196can have any value that is convenient for the code that creates new 197frames. (`create_new_frame' calls `DEPRECATED_INIT_EXTRA_FRAME_INFO' 198if it is defined; that is where you should use the 199`DEPRECATED_FP_REGNUM' value, if your frames are nonstandard.) 200 201 Given a GDB frame, define `DEPRECATED_FRAME_CHAIN' to determine the 202address of the calling function's frame. This will be used to create a 203new GDB frame struct, and then `DEPRECATED_INIT_EXTRA_FRAME_INFO' and 204`DEPRECATED_INIT_FRAME_PC' will be called for the new frame. 205 206Breakpoint Handling 207=================== 208 209In general, a breakpoint is a user-designated location in the program 210where the user wants to regain control if program execution ever reaches 211that location. 212 213 There are two main ways to implement breakpoints; either as 214"hardware" breakpoints or as "software" breakpoints. 215 216 Hardware breakpoints are sometimes available as a builtin debugging 217features with some chips. Typically these work by having dedicated 218register into which the breakpoint address may be stored. If the PC 219(shorthand for "program counter") ever matches a value in a breakpoint 220registers, the CPU raises an exception and reports it to GDB. 221 222 Another possibility is when an emulator is in use; many emulators 223include circuitry that watches the address lines coming out from the 224processor, and force it to stop if the address matches a breakpoint's 225address. 226 227 A third possibility is that the target already has the ability to do 228breakpoints somehow; for instance, a ROM monitor may do its own 229software breakpoints. So although these are not literally "hardware 230breakpoints", from GDB's point of view they work the same; GDB need not 231do anything more than set the breakpoint and wait for something to 232happen. 233 234 Since they depend on hardware resources, hardware breakpoints may be 235limited in number; when the user asks for more, GDB will start trying 236to set software breakpoints. (On some architectures, notably the 23732-bit x86 platforms, GDB cannot always know whether there's enough 238hardware resources to insert all the hardware breakpoints and 239watchpoints. On those platforms, GDB prints an error message only when 240the program being debugged is continued.) 241 242 Software breakpoints require GDB to do somewhat more work. The 243basic theory is that GDB will replace a program instruction with a 244trap, illegal divide, or some other instruction that will cause an 245exception, and then when it's encountered, GDB will take the exception 246and stop the program. When the user says to continue, GDB will restore 247the original instruction, single-step, re-insert the trap, and continue 248on. 249 250 Since it literally overwrites the program being tested, the program 251area must be writable, so this technique won't work on programs in ROM. 252It can also distort the behavior of programs that examine themselves, 253although such a situation would be highly unusual. 254 255 Also, the software breakpoint instruction should be the smallest 256size of instruction, so it doesn't overwrite an instruction that might 257be a jump target, and cause disaster when the program jumps into the 258middle of the breakpoint instruction. (Strictly speaking, the 259breakpoint must be no larger than the smallest interval between 260instructions that may be jump targets; perhaps there is an architecture 261where only even-numbered instructions may jumped to.) Note that it's 262possible for an instruction set not to have any instructions usable for 263a software breakpoint, although in practice only the ARC has failed to 264define such an instruction. 265 266 The basic definition of the software breakpoint is the macro 267`BREAKPOINT'. 268 269 Basic breakpoint object handling is in `breakpoint.c'. However, 270much of the interesting breakpoint action is in `infrun.c'. 271 272Single Stepping 273=============== 274 275Signal Handling 276=============== 277 278Thread Handling 279=============== 280 281Inferior Function Calls 282======================= 283 284Longjmp Support 285=============== 286 287GDB has support for figuring out that the target is doing a `longjmp' 288and for stopping at the target of the jump, if we are stepping. This 289is done with a few specialized internal breakpoints, which are visible 290in the output of the `maint info breakpoint' command. 291 292 To make this work, you need to define a macro called 293`GET_LONGJMP_TARGET', which will examine the `jmp_buf' structure and 294extract the longjmp target address. Since `jmp_buf' is target 295specific, you will need to define it in the appropriate `tm-TARGET.h' 296file. Look in `tm-sun4os4.h' and `sparc-tdep.c' for examples of how to 297do this. 298 299Watchpoints 300=========== 301 302Watchpoints are a special kind of breakpoints (*note breakpoints: 303Algorithms.) which break when data is accessed rather than when some 304instruction is executed. When you have data which changes without your 305knowing what code does that, watchpoints are the silver bullet to hunt 306down and kill such bugs. 307 308 Watchpoints can be either hardware-assisted or not; the latter type 309is known as "software watchpoints." GDB always uses hardware-assisted 310watchpoints if they are available, and falls back on software 311watchpoints otherwise. Typical situations where GDB will use software 312watchpoints are: 313 314 * The watched memory region is too large for the underlying hardware 315 watchpoint support. For example, each x86 debug register can 316 watch up to 4 bytes of memory, so trying to watch data structures 317 whose size is more than 16 bytes will cause GDB to use software 318 watchpoints. 319 320 * The value of the expression to be watched depends on data held in 321 registers (as opposed to memory). 322 323 * Too many different watchpoints requested. (On some architectures, 324 this situation is impossible to detect until the debugged program 325 is resumed.) Note that x86 debug registers are used both for 326 hardware breakpoints and for watchpoints, so setting too many 327 hardware breakpoints might cause watchpoint insertion to fail. 328 329 * No hardware-assisted watchpoints provided by the target 330 implementation. 331 332 Software watchpoints are very slow, since GDB needs to single-step 333the program being debugged and test the value of the watched 334expression(s) after each instruction. The rest of this section is 335mostly irrelevant for software watchpoints. 336 337 GDB uses several macros and primitives to support hardware 338watchpoints: 339 340`TARGET_HAS_HARDWARE_WATCHPOINTS' 341 If defined, the target supports hardware watchpoints. 342 343`TARGET_CAN_USE_HARDWARE_WATCHPOINT (TYPE, COUNT, OTHER)' 344 Return the number of hardware watchpoints of type TYPE that are 345 possible to be set. The value is positive if COUNT watchpoints of 346 this type can be set, zero if setting watchpoints of this type is 347 not supported, and negative if COUNT is more than the maximum 348 number of watchpoints of type TYPE that can be set. OTHER is 349 non-zero if other types of watchpoints are currently enabled (there 350 are architectures which cannot set watchpoints of different types 351 at the same time). 352 353`TARGET_REGION_OK_FOR_HW_WATCHPOINT (ADDR, LEN)' 354 Return non-zero if hardware watchpoints can be used to watch a 355 region whose address is ADDR and whose length in bytes is LEN. 356 357`TARGET_REGION_SIZE_OK_FOR_HW_WATCHPOINT (SIZE)' 358 Return non-zero if hardware watchpoints can be used to watch a 359 region whose size is SIZE. GDB only uses this macro as a 360 fall-back, in case `TARGET_REGION_OK_FOR_HW_WATCHPOINT' is not 361 defined. 362 363`TARGET_DISABLE_HW_WATCHPOINTS (PID)' 364 Disables watchpoints in the process identified by PID. This is 365 used, e.g., on HP-UX which provides operations to disable and 366 enable the page-level memory protection that implements hardware 367 watchpoints on that platform. 368 369`TARGET_ENABLE_HW_WATCHPOINTS (PID)' 370 Enables watchpoints in the process identified by PID. This is 371 used, e.g., on HP-UX which provides operations to disable and 372 enable the page-level memory protection that implements hardware 373 watchpoints on that platform. 374 375`target_insert_watchpoint (ADDR, LEN, TYPE)' 376`target_remove_watchpoint (ADDR, LEN, TYPE)' 377 Insert or remove a hardware watchpoint starting at ADDR, for LEN 378 bytes. TYPE is the watchpoint type, one of the possible values of 379 the enumerated data type `target_hw_bp_type', defined by 380 `breakpoint.h' as follows: 381 382 enum target_hw_bp_type 383 { 384 hw_write = 0, /* Common (write) HW watchpoint */ 385 hw_read = 1, /* Read HW watchpoint */ 386 hw_access = 2, /* Access (read or write) HW watchpoint */ 387 hw_execute = 3 /* Execute HW breakpoint */ 388 }; 389 390 These two macros should return 0 for success, non-zero for failure. 391 392`target_remove_hw_breakpoint (ADDR, SHADOW)' 393`target_insert_hw_breakpoint (ADDR, SHADOW)' 394 Insert or remove a hardware-assisted breakpoint at address ADDR. 395 Returns zero for success, non-zero for failure. SHADOW is the 396 real contents of the byte where the breakpoint has been inserted; 397 it is generally not valid when hardware breakpoints are used, but 398 since no other code touches these values, the implementations of 399 the above two macros can use them for their internal purposes. 400 401`target_stopped_data_address ()' 402 If the inferior has some watchpoint that triggered, return the 403 address associated with that watchpoint. Otherwise, return zero. 404 405`HAVE_STEPPABLE_WATCHPOINT' 406 If defined to a non-zero value, it is not necessary to disable a 407 watchpoint to step over it. 408 409`HAVE_NONSTEPPABLE_WATCHPOINT' 410 If defined to a non-zero value, GDB should disable a watchpoint to 411 step the inferior over it. 412 413`HAVE_CONTINUABLE_WATCHPOINT' 414 If defined to a non-zero value, it is possible to continue the 415 inferior after a watchpoint has been hit. 416 417`CANNOT_STEP_HW_WATCHPOINTS' 418 If this is defined to a non-zero value, GDB will remove all 419 watchpoints before stepping the inferior. 420 421`STOPPED_BY_WATCHPOINT (WAIT_STATUS)' 422 Return non-zero if stopped by a watchpoint. WAIT_STATUS is of the 423 type `struct target_waitstatus', defined by `target.h'. 424 425x86 Watchpoints 426--------------- 427 428The 32-bit Intel x86 (a.k.a. ia32) processors feature special debug 429registers designed to facilitate debugging. GDB provides a generic 430library of functions that x86-based ports can use to implement support 431for watchpoints and hardware-assisted breakpoints. This subsection 432documents the x86 watchpoint facilities in GDB. 433 434 To use the generic x86 watchpoint support, a port should do the 435following: 436 437 * Define the macro `I386_USE_GENERIC_WATCHPOINTS' somewhere in the 438 target-dependent headers. 439 440 * Include the `config/i386/nm-i386.h' header file _after_ defining 441 `I386_USE_GENERIC_WATCHPOINTS'. 442 443 * Add `i386-nat.o' to the value of the Make variable `NATDEPFILES' 444 (*note NATDEPFILES: Native Debugging.) or `TDEPFILES' (*note 445 TDEPFILES: Target Architecture Definition.). 446 447 * Provide implementations for the `I386_DR_LOW_*' macros described 448 below. Typically, each macro should call a target-specific 449 function which does the real work. 450 451 The x86 watchpoint support works by maintaining mirror images of the 452debug registers. Values are copied between the mirror images and the 453real debug registers via a set of macros which each target needs to 454provide: 455 456`I386_DR_LOW_SET_CONTROL (VAL)' 457 Set the Debug Control (DR7) register to the value VAL. 458 459`I386_DR_LOW_SET_ADDR (IDX, ADDR)' 460 Put the address ADDR into the debug register number IDX. 461 462`I386_DR_LOW_RESET_ADDR (IDX)' 463 Reset (i.e. zero out) the address stored in the debug register 464 number IDX. 465 466`I386_DR_LOW_GET_STATUS' 467 Return the value of the Debug Status (DR6) register. This value is 468 used immediately after it is returned by `I386_DR_LOW_GET_STATUS', 469 so as to support per-thread status register values. 470 471 For each one of the 4 debug registers (whose indices are from 0 to 3) 472that store addresses, a reference count is maintained by GDB, to allow 473sharing of debug registers by several watchpoints. This allows users 474to define several watchpoints that watch the same expression, but with 475different conditions and/or commands, without wasting debug registers 476which are in short supply. GDB maintains the reference counts 477internally, targets don't have to do anything to use this feature. 478 479 The x86 debug registers can each watch a region that is 1, 2, or 4 480bytes long. The ia32 architecture requires that each watched region be 481appropriately aligned: 2-byte region on 2-byte boundary, 4-byte region 482on 4-byte boundary. However, the x86 watchpoint support in GDB can 483watch unaligned regions and regions larger than 4 bytes (up to 16 484bytes) by allocating several debug registers to watch a single region. 485This allocation of several registers per a watched region is also done 486automatically without target code intervention. 487 488 The generic x86 watchpoint support provides the following API for the 489GDB's application code: 490 491`i386_region_ok_for_watchpoint (ADDR, LEN)' 492 The macro `TARGET_REGION_OK_FOR_HW_WATCHPOINT' is set to call this 493 function. It counts the number of debug registers required to 494 watch a given region, and returns a non-zero value if that number 495 is less than 4, the number of debug registers available to x86 496 processors. 497 498`i386_stopped_data_address (void)' 499 The macros `STOPPED_BY_WATCHPOINT' and 500 `target_stopped_data_address' are set to call this function. The 501 argument passed to `STOPPED_BY_WATCHPOINT' is ignored. This 502 function examines the breakpoint condition bits in the DR6 Debug 503 Status register, as returned by the `I386_DR_LOW_GET_STATUS' 504 macro, and returns the address associated with the first bit that 505 is set in DR6. 506 507`i386_insert_watchpoint (ADDR, LEN, TYPE)' 508`i386_remove_watchpoint (ADDR, LEN, TYPE)' 509 Insert or remove a watchpoint. The macros 510 `target_insert_watchpoint' and `target_remove_watchpoint' are set 511 to call these functions. `i386_insert_watchpoint' first looks for 512 a debug register which is already set to watch the same region for 513 the same access types; if found, it just increments the reference 514 count of that debug register, thus implementing debug register 515 sharing between watchpoints. If no such register is found, the 516 function looks for a vacant debug register, sets its mirrored 517 value to ADDR, sets the mirrored value of DR7 Debug Control 518 register as appropriate for the LEN and TYPE parameters, and then 519 passes the new values of the debug register and DR7 to the 520 inferior by calling `I386_DR_LOW_SET_ADDR' and 521 `I386_DR_LOW_SET_CONTROL'. If more than one debug register is 522 required to cover the given region, the above process is repeated 523 for each debug register. 524 525 `i386_remove_watchpoint' does the opposite: it resets the address 526 in the mirrored value of the debug register and its read/write and 527 length bits in the mirrored value of DR7, then passes these new 528 values to the inferior via `I386_DR_LOW_RESET_ADDR' and 529 `I386_DR_LOW_SET_CONTROL'. If a register is shared by several 530 watchpoints, each time a `i386_remove_watchpoint' is called, it 531 decrements the reference count, and only calls 532 `I386_DR_LOW_RESET_ADDR' and `I386_DR_LOW_SET_CONTROL' when the 533 count goes to zero. 534 535`i386_insert_hw_breakpoint (ADDR, SHADOW' 536`i386_remove_hw_breakpoint (ADDR, SHADOW)' 537 These functions insert and remove hardware-assisted breakpoints. 538 The macros `target_insert_hw_breakpoint' and 539 `target_remove_hw_breakpoint' are set to call these functions. 540 These functions work like `i386_insert_watchpoint' and 541 `i386_remove_watchpoint', respectively, except that they set up 542 the debug registers to watch instruction execution, and each 543 hardware-assisted breakpoint always requires exactly one debug 544 register. 545 546`i386_stopped_by_hwbp (void)' 547 This function returns non-zero if the inferior has some watchpoint 548 or hardware breakpoint that triggered. It works like 549 `i386_stopped_data_address', except that it doesn't return the 550 address whose watchpoint triggered. 551 552`i386_cleanup_dregs (void)' 553 This function clears all the reference counts, addresses, and 554 control bits in the mirror images of the debug registers. It 555 doesn't affect the actual debug registers in the inferior process. 556 557*Notes:* 558 1. x86 processors support setting watchpoints on I/O reads or writes. 559 However, since no target supports this (as of March 2001), and 560 since `enum target_hw_bp_type' doesn't even have an enumeration 561 for I/O watchpoints, this feature is not yet available to GDB 562 running on x86. 563 564 2. x86 processors can enable watchpoints locally, for the current task 565 only, or globally, for all the tasks. For each debug register, 566 there's a bit in the DR7 Debug Control register that determines 567 whether the associated address is watched locally or globally. The 568 current implementation of x86 watchpoint support in GDB always 569 sets watchpoints to be locally enabled, since global watchpoints 570 might interfere with the underlying OS and are probably 571 unavailable in many platforms. 572 573Observing changes in GDB internals 574================================== 575 576In order to function properly, several modules need to be notified when 577some changes occur in the GDB internals. Traditionally, these modules 578have relied on several paradigms, the most common ones being hooks and 579gdb-events. Unfortunately, none of these paradigms was versatile 580enough to become the standard notification mechanism in GDB. The fact 581that they only supported one "client" was also a strong limitation. 582 583 A new paradigm, based on the Observer pattern of the `Design 584Patterns' book, has therefore been implemented. The goal was to provide 585a new interface overcoming the issues with the notification mechanisms 586previously available. This new interface needed to be strongly typed, 587easy to extend, and versatile enough to be used as the standard 588interface when adding new notifications. 589 590 See *Note GDB Observers:: for a brief description of the observers 591currently implemented in GDB. The rationale for the current 592implementation is also briefly discussed. 593 594 595File: gdbint.info, Node: User Interface, Next: libgdb, Prev: Algorithms, Up: Top 596 597User Interface 598************** 599 600GDB has several user interfaces. Although the command-line interface 601is the most common and most familiar, there are others. 602 603Command Interpreter 604=================== 605 606The command interpreter in GDB is fairly simple. It is designed to 607allow for the set of commands to be augmented dynamically, and also has 608a recursive subcommand capability, where the first argument to a 609command may itself direct a lookup on a different command list. 610 611 For instance, the `set' command just starts a lookup on the 612`setlist' command list, while `set thread' recurses to the 613`set_thread_cmd_list'. 614 615 To add commands in general, use `add_cmd'. `add_com' adds to the 616main command list, and should be used for those commands. The usual 617place to add commands is in the `_initialize_XYZ' routines at the ends 618of most source files. 619 620 To add paired `set' and `show' commands, use `add_setshow_cmd' or 621`add_setshow_cmd_full'. The former is a slightly simpler interface 622which is useful when you don't need to further modify the new command 623structures, while the latter returns the new command structures for 624manipulation. 625 626 Before removing commands from the command set it is a good idea to 627deprecate them for some time. Use `deprecate_cmd' on commands or 628aliases to set the deprecated flag. `deprecate_cmd' takes a `struct 629cmd_list_element' as it's first argument. You can use the return value 630from `add_com' or `add_cmd' to deprecate the command immediately after 631it is created. 632 633 The first time a command is used the user will be warned and offered 634a replacement (if one exists). Note that the replacement string passed 635to `deprecate_cmd' should be the full name of the command, i.e. the 636entire string the user should type at the command line. 637 638UI-Independent Output--the `ui_out' Functions 639============================================= 640 641The `ui_out' functions present an abstraction level for the GDB output 642code. They hide the specifics of different user interfaces supported 643by GDB, and thus free the programmer from the need to write several 644versions of the same code, one each for every UI, to produce output. 645 646Overview and Terminology 647------------------------ 648 649In general, execution of each GDB command produces some sort of output, 650and can even generate an input request. 651 652 Output can be generated for the following purposes: 653 654 * to display a _result_ of an operation; 655 656 * to convey _info_ or produce side-effects of a requested operation; 657 658 * to provide a _notification_ of an asynchronous event (including 659 progress indication of a prolonged asynchronous operation); 660 661 * to display _error messages_ (including warnings); 662 663 * to show _debug data_; 664 665 * to _query_ or prompt a user for input (a special case). 666 667This section mainly concentrates on how to build result output, 668although some of it also applies to other kinds of output. 669 670 Generation of output that displays the results of an operation 671involves one or more of the following: 672 673 * output of the actual data 674 675 * formatting the output as appropriate for console output, to make it 676 easily readable by humans 677 678 * machine oriented formatting-a more terse formatting to allow for 679 easy parsing by programs which read GDB's output 680 681 * annotation, whose purpose is to help legacy GUIs to identify 682 interesting parts in the output 683 684 The `ui_out' routines take care of the first three aspects. 685Annotations are provided by separate annotation routines. Note that use 686of annotations for an interface between a GUI and GDB is deprecated. 687 688 Output can be in the form of a single item, which we call a "field"; 689a "list" consisting of identical fields; a "tuple" consisting of 690non-identical fields; or a "table", which is a tuple consisting of a 691header and a body. In a BNF-like form: 692 693`<table> ==>' 694 `<header> <body>' 695 696`<header> ==>' 697 `{ <column> }' 698 699`<column> ==>' 700 `<width> <alignment> <title>' 701 702`<body> ==>' 703 `{<row>}' 704 705General Conventions 706------------------- 707 708Most `ui_out' routines are of type `void', the exceptions are 709`ui_out_stream_new' (which returns a pointer to the newly created 710object) and the `make_cleanup' routines. 711 712 The first parameter is always the `ui_out' vector object, a pointer 713to a `struct ui_out'. 714 715 The FORMAT parameter is like in `printf' family of functions. When 716it is present, there must also be a variable list of arguments 717sufficient used to satisfy the `%' specifiers in the supplied format. 718 719 When a character string argument is not used in a `ui_out' function 720call, a `NULL' pointer has to be supplied instead. 721 722Table, Tuple and List Functions 723------------------------------- 724 725This section introduces `ui_out' routines for building lists, tuples 726and tables. The routines to output the actual data items (fields) are 727presented in the next section. 728 729 To recap: A "tuple" is a sequence of "fields", each field containing 730information about an object; a "list" is a sequence of fields where 731each field describes an identical object. 732 733 Use the "table" functions when your output consists of a list of 734rows (tuples) and the console output should include a heading. Use this 735even when you are listing just one object but you still want the header. 736 737 Tables can not be nested. Tuples and lists can be nested up to a 738maximum of five levels. 739 740 The overall structure of the table output code is something like 741this: 742 743 ui_out_table_begin 744 ui_out_table_header 745 ... 746 ui_out_table_body 747 ui_out_tuple_begin 748 ui_out_field_* 749 ... 750 ui_out_tuple_end 751 ... 752 ui_out_table_end 753 754 Here is the description of table-, tuple- and list-related `ui_out' 755functions: 756 757 - Function: void ui_out_table_begin (struct ui_out *UIOUT, int 758 NBROFCOLS, int NR_ROWS, const char *TBLID) 759 The function `ui_out_table_begin' marks the beginning of the output 760 of a table. It should always be called before any other `ui_out' 761 function for a given table. NBROFCOLS is the number of columns in 762 the table. NR_ROWS is the number of rows in the table. TBLID is 763 an optional string identifying the table. The string pointed to 764 by TBLID is copied by the implementation of `ui_out_table_begin', 765 so the application can free the string if it was `malloc'ed. 766 767 The companion function `ui_out_table_end', described below, marks 768 the end of the table's output. 769 770 - Function: void ui_out_table_header (struct ui_out *UIOUT, int WIDTH, 771 enum ui_align ALIGNMENT, const char *COLHDR) 772 `ui_out_table_header' provides the header information for a single 773 table column. You call this function several times, one each for 774 every column of the table, after `ui_out_table_begin', but before 775 `ui_out_table_body'. 776 777 The value of WIDTH gives the column width in characters. The 778 value of ALIGNMENT is one of `left', `center', and `right', and it 779 specifies how to align the header: left-justify, center, or 780 right-justify it. COLHDR points to a string that specifies the 781 column header; the implementation copies that string, so column 782 header strings in `malloc'ed storage can be freed after the call. 783 784 - Function: void ui_out_table_body (struct ui_out *UIOUT) 785 This function delimits the table header from the table body. 786 787 - Function: void ui_out_table_end (struct ui_out *UIOUT) 788 This function signals the end of a table's output. It should be 789 called after the table body has been produced by the list and 790 field output functions. 791 792 There should be exactly one call to `ui_out_table_end' for each 793 call to `ui_out_table_begin', otherwise the `ui_out' functions 794 will signal an internal error. 795 796 The output of the tuples that represent the table rows must follow 797the call to `ui_out_table_body' and precede the call to 798`ui_out_table_end'. You build a tuple by calling `ui_out_tuple_begin' 799and `ui_out_tuple_end', with suitable calls to functions which actually 800output fields between them. 801 802 - Function: void ui_out_tuple_begin (struct ui_out *UIOUT, const char 803 *ID) 804 This function marks the beginning of a tuple output. ID points to 805 an optional string that identifies the tuple; it is copied by the 806 implementation, and so strings in `malloc'ed storage can be freed 807 after the call. 808 809 - Function: void ui_out_tuple_end (struct ui_out *UIOUT) 810 This function signals an end of a tuple output. There should be 811 exactly one call to `ui_out_tuple_end' for each call to 812 `ui_out_tuple_begin', otherwise an internal GDB error will be 813 signaled. 814 815 - Function: struct cleanup *make_cleanup_ui_out_tuple_begin_end 816 (struct ui_out *UIOUT, const char *ID) 817 This function first opens the tuple and then establishes a cleanup 818 (*note Cleanups: Coding.) to close the tuple. It provides a 819 convenient and correct implementation of the non-portable(1) code 820 sequence: 821 struct cleanup *old_cleanup; 822 ui_out_tuple_begin (uiout, "..."); 823 old_cleanup = make_cleanup ((void(*)(void *)) ui_out_tuple_end, 824 uiout); 825 826 - Function: void ui_out_list_begin (struct ui_out *UIOUT, const char 827 *ID) 828 This function marks the beginning of a list output. ID points to 829 an optional string that identifies the list; it is copied by the 830 implementation, and so strings in `malloc'ed storage can be freed 831 after the call. 832 833 - Function: void ui_out_list_end (struct ui_out *UIOUT) 834 This function signals an end of a list output. There should be 835 exactly one call to `ui_out_list_end' for each call to 836 `ui_out_list_begin', otherwise an internal GDB error will be 837 signaled. 838 839 - Function: struct cleanup *make_cleanup_ui_out_list_begin_end (struct 840 ui_out *UIOUT, const char *ID) 841 Similar to `make_cleanup_ui_out_tuple_begin_end', this function 842 opens a list and then establishes cleanup (*note Cleanups: Coding.) 843 that will close the list.list. 844 845Item Output Functions 846--------------------- 847 848The functions described below produce output for the actual data items, 849or fields, which contain information about the object. 850 851 Choose the appropriate function accordingly to your particular needs. 852 853 - Function: void ui_out_field_fmt (struct ui_out *UIOUT, char 854 *FLDNAME, char *FORMAT, ...) 855 This is the most general output function. It produces the 856 representation of the data in the variable-length argument list 857 according to formatting specifications in FORMAT, a `printf'-like 858 format string. The optional argument FLDNAME supplies the name of 859 the field. The data items themselves are supplied as additional 860 arguments after FORMAT. 861 862 This generic function should be used only when it is not possible 863 to use one of the specialized versions (see below). 864 865 - Function: void ui_out_field_int (struct ui_out *UIOUT, const char 866 *FLDNAME, int VALUE) 867 This function outputs a value of an `int' variable. It uses the 868 `"%d"' output conversion specification. FLDNAME specifies the 869 name of the field. 870 871 - Function: void ui_out_field_fmt_int (struct ui_out *UIOUT, int 872 WIDTH, enum ui_align ALIGNMENT, const char *FLDNAME, int 873 VALUE) 874 This function outputs a value of an `int' variable. It differs 875 from `ui_out_field_int' in that the caller specifies the desired 876 WIDTH and ALIGNMENT of the output. FLDNAME specifies the name of 877 the field. 878 879 - Function: void ui_out_field_core_addr (struct ui_out *UIOUT, const 880 char *FLDNAME, CORE_ADDR ADDRESS) 881 This function outputs an address. 882 883 - Function: void ui_out_field_string (struct ui_out *UIOUT, const char 884 *FLDNAME, const char *STRING) 885 This function outputs a string using the `"%s"' conversion 886 specification. 887 888 Sometimes, there's a need to compose your output piece by piece using 889functions that operate on a stream, such as `value_print' or 890`fprintf_symbol_filtered'. These functions accept an argument of the 891type `struct ui_file *', a pointer to a `ui_file' object used to store 892the data stream used for the output. When you use one of these 893functions, you need a way to pass their results stored in a `ui_file' 894object to the `ui_out' functions. To this end, you first create a 895`ui_stream' object by calling `ui_out_stream_new', pass the `stream' 896member of that `ui_stream' object to `value_print' and similar 897functions, and finally call `ui_out_field_stream' to output the field 898you constructed. When the `ui_stream' object is no longer needed, you 899should destroy it and free its memory by calling `ui_out_stream_delete'. 900 901 - Function: struct ui_stream *ui_out_stream_new (struct ui_out *UIOUT) 902 This function creates a new `ui_stream' object which uses the same 903 output methods as the `ui_out' object whose pointer is passed in 904 UIOUT. It returns a pointer to the newly created `ui_stream' 905 object. 906 907 - Function: void ui_out_stream_delete (struct ui_stream *STREAMBUF) 908 This functions destroys a `ui_stream' object specified by 909 STREAMBUF. 910 911 - Function: void ui_out_field_stream (struct ui_out *UIOUT, const char 912 *FIELDNAME, struct ui_stream *STREAMBUF) 913 This function consumes all the data accumulated in 914 `streambuf->stream' and outputs it like `ui_out_field_string' 915 does. After a call to `ui_out_field_stream', the accumulated data 916 no longer exists, but the stream is still valid and may be used 917 for producing more fields. 918 919 *Important:* If there is any chance that your code could bail out 920before completing output generation and reaching the point where 921`ui_out_stream_delete' is called, it is necessary to set up a cleanup, 922to avoid leaking memory and other resources. Here's a skeleton code to 923do that: 924 925 struct ui_stream *mybuf = ui_out_stream_new (uiout); 926 struct cleanup *old = make_cleanup (ui_out_stream_delete, mybuf); 927 ... 928 do_cleanups (old); 929 930 If the function already has the old cleanup chain set (for other 931kinds of cleanups), you just have to add your cleanup to it: 932 933 mybuf = ui_out_stream_new (uiout); 934 make_cleanup (ui_out_stream_delete, mybuf); 935 936 Note that with cleanups in place, you should not call 937`ui_out_stream_delete' directly, or you would attempt to free the same 938buffer twice. 939 940Utility Output Functions 941------------------------ 942 943 - Function: void ui_out_field_skip (struct ui_out *UIOUT, const char 944 *FLDNAME) 945 This function skips a field in a table. Use it if you have to 946 leave an empty field without disrupting the table alignment. The 947 argument FLDNAME specifies a name for the (missing) filed. 948 949 - Function: void ui_out_text (struct ui_out *UIOUT, const char *STRING) 950 This function outputs the text in STRING in a way that makes it 951 easy to be read by humans. For example, the console 952 implementation of this method filters the text through a built-in 953 pager, to prevent it from scrolling off the visible portion of the 954 screen. 955 956 Use this function for printing relatively long chunks of text 957 around the actual field data: the text it produces is not aligned 958 according to the table's format. Use `ui_out_field_string' to 959 output a string field, and use `ui_out_message', described below, 960 to output short messages. 961 962 - Function: void ui_out_spaces (struct ui_out *UIOUT, int NSPACES) 963 This function outputs NSPACES spaces. It is handy to align the 964 text produced by `ui_out_text' with the rest of the table or list. 965 966 - Function: void ui_out_message (struct ui_out *UIOUT, int VERBOSITY, 967 const char *FORMAT, ...) 968 This function produces a formatted message, provided that the 969 current verbosity level is at least as large as given by 970 VERBOSITY. The current verbosity level is specified by the user 971 with the `set verbositylevel' command.(2) 972 973 - Function: void ui_out_wrap_hint (struct ui_out *UIOUT, char *INDENT) 974 This function gives the console output filter (a paging filter) a 975 hint of where to break lines which are too long. Ignored for all 976 other output consumers. INDENT, if non-`NULL', is the string to 977 be printed to indent the wrapped text on the next line; it must 978 remain accessible until the next call to `ui_out_wrap_hint', or 979 until an explicit newline is produced by one of the other 980 functions. If INDENT is `NULL', the wrapped text will not be 981 indented. 982 983 - Function: void ui_out_flush (struct ui_out *UIOUT) 984 This function flushes whatever output has been accumulated so far, 985 if the UI buffers output. 986 987Examples of Use of `ui_out' functions 988------------------------------------- 989 990This section gives some practical examples of using the `ui_out' 991functions to generalize the old console-oriented code in GDB. The 992examples all come from functions defined on the `breakpoints.c' file. 993 994 This example, from the `breakpoint_1' function, shows how to produce 995a table. 996 997 The original code was: 998 999 if (!found_a_breakpoint++) 1000 { 1001 annotate_breakpoints_headers (); 1002 1003 annotate_field (0); 1004 printf_filtered ("Num "); 1005 annotate_field (1); 1006 printf_filtered ("Type "); 1007 annotate_field (2); 1008 printf_filtered ("Disp "); 1009 annotate_field (3); 1010 printf_filtered ("Enb "); 1011 if (addressprint) 1012 { 1013 annotate_field (4); 1014 printf_filtered ("Address "); 1015 } 1016 annotate_field (5); 1017 printf_filtered ("What\n"); 1018 1019 annotate_breakpoints_table (); 1020 } 1021 1022 Here's the new version: 1023 1024 nr_printable_breakpoints = ...; 1025 1026 if (addressprint) 1027 ui_out_table_begin (ui, 6, nr_printable_breakpoints, "BreakpointTable"); 1028 else 1029 ui_out_table_begin (ui, 5, nr_printable_breakpoints, "BreakpointTable"); 1030 1031 if (nr_printable_breakpoints > 0) 1032 annotate_breakpoints_headers (); 1033 if (nr_printable_breakpoints > 0) 1034 annotate_field (0); 1035 ui_out_table_header (uiout, 3, ui_left, "number", "Num"); /* 1 */ 1036 if (nr_printable_breakpoints > 0) 1037 annotate_field (1); 1038 ui_out_table_header (uiout, 14, ui_left, "type", "Type"); /* 2 */ 1039 if (nr_printable_breakpoints > 0) 1040 annotate_field (2); 1041 ui_out_table_header (uiout, 4, ui_left, "disp", "Disp"); /* 3 */ 1042 if (nr_printable_breakpoints > 0) 1043 annotate_field (3); 1044 ui_out_table_header (uiout, 3, ui_left, "enabled", "Enb"); /* 4 */ 1045 if (addressprint) 1046 { 1047 if (nr_printable_breakpoints > 0) 1048 annotate_field (4); 1049 if (TARGET_ADDR_BIT <= 32) 1050 ui_out_table_header (uiout, 10, ui_left, "addr", "Address");/* 5 */ 1051 else 1052 ui_out_table_header (uiout, 18, ui_left, "addr", "Address");/* 5 */ 1053 } 1054 if (nr_printable_breakpoints > 0) 1055 annotate_field (5); 1056 ui_out_table_header (uiout, 40, ui_noalign, "what", "What"); /* 6 */ 1057 ui_out_table_body (uiout); 1058 if (nr_printable_breakpoints > 0) 1059 annotate_breakpoints_table (); 1060 1061 This example, from the `print_one_breakpoint' function, shows how to 1062produce the actual data for the table whose structure was defined in 1063the above example. The original code was: 1064 1065 annotate_record (); 1066 annotate_field (0); 1067 printf_filtered ("%-3d ", b->number); 1068 annotate_field (1); 1069 if ((int)b->type > (sizeof(bptypes)/sizeof(bptypes[0])) 1070 || ((int) b->type != bptypes[(int) b->type].type)) 1071 internal_error ("bptypes table does not describe type #%d.", 1072 (int)b->type); 1073 printf_filtered ("%-14s ", bptypes[(int)b->type].description); 1074 annotate_field (2); 1075 printf_filtered ("%-4s ", bpdisps[(int)b->disposition]); 1076 annotate_field (3); 1077 printf_filtered ("%-3c ", bpenables[(int)b->enable]); 1078 ... 1079 1080 This is the new version: 1081 1082 annotate_record (); 1083 ui_out_tuple_begin (uiout, "bkpt"); 1084 annotate_field (0); 1085 ui_out_field_int (uiout, "number", b->number); 1086 annotate_field (1); 1087 if (((int) b->type > (sizeof (bptypes) / sizeof (bptypes[0]))) 1088 || ((int) b->type != bptypes[(int) b->type].type)) 1089 internal_error ("bptypes table does not describe type #%d.", 1090 (int) b->type); 1091 ui_out_field_string (uiout, "type", bptypes[(int)b->type].description); 1092 annotate_field (2); 1093 ui_out_field_string (uiout, "disp", bpdisps[(int)b->disposition]); 1094 annotate_field (3); 1095 ui_out_field_fmt (uiout, "enabled", "%c", bpenables[(int)b->enable]); 1096 ... 1097 1098 This example, also from `print_one_breakpoint', shows how to produce 1099a complicated output field using the `print_expression' functions which 1100requires a stream to be passed. It also shows how to automate stream 1101destruction with cleanups. The original code was: 1102 1103 annotate_field (5); 1104 print_expression (b->exp, gdb_stdout); 1105 1106 The new version is: 1107 1108 struct ui_stream *stb = ui_out_stream_new (uiout); 1109 struct cleanup *old_chain = make_cleanup_ui_out_stream_delete (stb); 1110 ... 1111 annotate_field (5); 1112 print_expression (b->exp, stb->stream); 1113 ui_out_field_stream (uiout, "what", local_stream); 1114 1115 This example, also from `print_one_breakpoint', shows how to use 1116`ui_out_text' and `ui_out_field_string'. The original code was: 1117 1118 annotate_field (5); 1119 if (b->dll_pathname == NULL) 1120 printf_filtered ("<any library> "); 1121 else 1122 printf_filtered ("library \"%s\" ", b->dll_pathname); 1123 1124 It became: 1125 1126 annotate_field (5); 1127 if (b->dll_pathname == NULL) 1128 { 1129 ui_out_field_string (uiout, "what", "<any library>"); 1130 ui_out_spaces (uiout, 1); 1131 } 1132 else 1133 { 1134 ui_out_text (uiout, "library \""); 1135 ui_out_field_string (uiout, "what", b->dll_pathname); 1136 ui_out_text (uiout, "\" "); 1137 } 1138 1139 The following example from `print_one_breakpoint' shows how to use 1140`ui_out_field_int' and `ui_out_spaces'. The original code was: 1141 1142 annotate_field (5); 1143 if (b->forked_inferior_pid != 0) 1144 printf_filtered ("process %d ", b->forked_inferior_pid); 1145 1146 It became: 1147 1148 annotate_field (5); 1149 if (b->forked_inferior_pid != 0) 1150 { 1151 ui_out_text (uiout, "process "); 1152 ui_out_field_int (uiout, "what", b->forked_inferior_pid); 1153 ui_out_spaces (uiout, 1); 1154 } 1155 1156 Here's an example of using `ui_out_field_string'. The original code 1157was: 1158 1159 annotate_field (5); 1160 if (b->exec_pathname != NULL) 1161 printf_filtered ("program \"%s\" ", b->exec_pathname); 1162 1163 It became: 1164 1165 annotate_field (5); 1166 if (b->exec_pathname != NULL) 1167 { 1168 ui_out_text (uiout, "program \""); 1169 ui_out_field_string (uiout, "what", b->exec_pathname); 1170 ui_out_text (uiout, "\" "); 1171 } 1172 1173 Finally, here's an example of printing an address. The original 1174code: 1175 1176 annotate_field (4); 1177 printf_filtered ("%s ", 1178 local_hex_string_custom ((unsigned long) b->address, "08l")); 1179 1180 It became: 1181 1182 annotate_field (4); 1183 ui_out_field_core_addr (uiout, "Address", b->address); 1184 1185Console Printing 1186================ 1187 1188TUI 1189=== 1190 1191---------- Footnotes ---------- 1192 1193 (1) The function cast is not portable ISO C. 1194 1195 (2) As of this writing (April 2001), setting verbosity level is not 1196yet implemented, and is always returned as zero. So calling 1197`ui_out_message' with a VERBOSITY argument more than zero will cause 1198the message to never be printed. 1199 1200 1201File: gdbint.info, Node: libgdb, Next: Symbol Handling, Prev: User Interface, Up: Top 1202 1203libgdb 1204****** 1205 1206libgdb 1.0 1207========== 1208 1209`libgdb' 1.0 was an abortive project of years ago. The theory was to 1210provide an API to GDB's functionality. 1211 1212libgdb 2.0 1213========== 1214 1215`libgdb' 2.0 is an ongoing effort to update GDB so that is better able 1216to support graphical and other environments. 1217 1218 Since `libgdb' development is on-going, its architecture is still 1219evolving. The following components have so far been identified: 1220 1221 * Observer - `gdb-events.h'. 1222 1223 * Builder - `ui-out.h' 1224 1225 * Event Loop - `event-loop.h' 1226 1227 * Library - `gdb.h' 1228 1229 The model that ties these components together is described below. 1230 1231The `libgdb' Model 1232================== 1233 1234A client of `libgdb' interacts with the library in two ways. 1235 1236 * As an observer (using `gdb-events') receiving notifications from 1237 `libgdb' of any internal state changes (break point changes, run 1238 state, etc). 1239 1240 * As a client querying `libgdb' (using the `ui-out' builder) to 1241 obtain various status values from GDB. 1242 1243 Since `libgdb' could have multiple clients (e.g. a GUI supporting 1244the existing GDB CLI), those clients must co-operate when controlling 1245`libgdb'. In particular, a client must ensure that `libgdb' is idle 1246(i.e. no other client is using `libgdb') before responding to a 1247`gdb-event' by making a query. 1248 1249CLI support 1250=========== 1251 1252At present GDB's CLI is very much entangled in with the core of 1253`libgdb'. Consequently, a client wishing to include the CLI in their 1254interface needs to carefully co-ordinate its own and the CLI's 1255requirements. 1256 1257 It is suggested that the client set `libgdb' up to be bi-modal 1258(alternate between CLI and client query modes). The notes below sketch 1259out the theory: 1260 1261 * The client registers itself as an observer of `libgdb'. 1262 1263 * The client create and install `cli-out' builder using its own 1264 versions of the `ui-file' `gdb_stderr', `gdb_stdtarg' and 1265 `gdb_stdout' streams. 1266 1267 * The client creates a separate custom `ui-out' builder that is only 1268 used while making direct queries to `libgdb'. 1269 1270 When the client receives input intended for the CLI, it simply 1271passes it along. Since the `cli-out' builder is installed by default, 1272all the CLI output in response to that command is routed (pronounced 1273rooted) through to the client controlled `gdb_stdout' et. al. streams. 1274At the same time, the client is kept abreast of internal changes by 1275virtue of being a `libgdb' observer. 1276 1277 The only restriction on the client is that it must wait until 1278`libgdb' becomes idle before initiating any queries (using the client's 1279custom builder). 1280 1281`libgdb' components 1282=================== 1283 1284Observer - `gdb-events.h' 1285------------------------- 1286 1287`gdb-events' provides the client with a very raw mechanism that can be 1288used to implement an observer. At present it only allows for one 1289observer and that observer must, internally, handle the need to delay 1290the processing of any event notifications until after `libgdb' has 1291finished the current command. 1292 1293Builder - `ui-out.h' 1294-------------------- 1295 1296`ui-out' provides the infrastructure necessary for a client to create a 1297builder. That builder is then passed down to `libgdb' when doing any 1298queries. 1299 1300Event Loop - `event-loop.h' 1301--------------------------- 1302 1303`event-loop', currently non-re-entrant, provides a simple event loop. 1304A client would need to either plug its self into this loop or, 1305implement a new event-loop that GDB would use. 1306 1307 The event-loop will eventually be made re-entrant. This is so that 1308GDB can better handle the problem of some commands blocking instead of 1309returning. 1310 1311Library - `gdb.h' 1312----------------- 1313 1314`libgdb' is the most obvious component of this system. It provides the 1315query interface. Each function is parameterized by a `ui-out' builder. 1316The result of the query is constructed using that builder before the 1317query function returns. 1318 1319 1320File: gdbint.info, Node: Symbol Handling, Next: Language Support, Prev: libgdb, Up: Top 1321 1322Symbol Handling 1323*************** 1324 1325Symbols are a key part of GDB's operation. Symbols include variables, 1326functions, and types. 1327 1328Symbol Reading 1329============== 1330 1331GDB reads symbols from "symbol files". The usual symbol file is the 1332file containing the program which GDB is debugging. GDB can be 1333directed to use a different file for symbols (with the `symbol-file' 1334command), and it can also read more symbols via the `add-file' and 1335`load' commands, or while reading symbols from shared libraries. 1336 1337 Symbol files are initially opened by code in `symfile.c' using the 1338BFD library (*note Support Libraries::). BFD identifies the type of 1339the file by examining its header. `find_sym_fns' then uses this 1340identification to locate a set of symbol-reading functions. 1341 1342 Symbol-reading modules identify themselves to GDB by calling 1343`add_symtab_fns' during their module initialization. The argument to 1344`add_symtab_fns' is a `struct sym_fns' which contains the name (or name 1345prefix) of the symbol format, the length of the prefix, and pointers to 1346four functions. These functions are called at various times to process 1347symbol files whose identification matches the specified prefix. 1348 1349 The functions supplied by each module are: 1350 1351`XYZ_symfile_init(struct sym_fns *sf)' 1352 Called from `symbol_file_add' when we are about to read a new 1353 symbol file. This function should clean up any internal state 1354 (possibly resulting from half-read previous files, for example) 1355 and prepare to read a new symbol file. Note that the symbol file 1356 which we are reading might be a new "main" symbol file, or might 1357 be a secondary symbol file whose symbols are being added to the 1358 existing symbol table. 1359 1360 The argument to `XYZ_symfile_init' is a newly allocated `struct 1361 sym_fns' whose `bfd' field contains the BFD for the new symbol 1362 file being read. Its `private' field has been zeroed, and can be 1363 modified as desired. Typically, a struct of private information 1364 will be `malloc''d, and a pointer to it will be placed in the 1365 `private' field. 1366 1367 There is no result from `XYZ_symfile_init', but it can call 1368 `error' if it detects an unavoidable problem. 1369 1370`XYZ_new_init()' 1371 Called from `symbol_file_add' when discarding existing symbols. 1372 This function needs only handle the symbol-reading module's 1373 internal state; the symbol table data structures visible to the 1374 rest of GDB will be discarded by `symbol_file_add'. It has no 1375 arguments and no result. It may be called after 1376 `XYZ_symfile_init', if a new symbol table is being read, or may be 1377 called alone if all symbols are simply being discarded. 1378 1379`XYZ_symfile_read(struct sym_fns *sf, CORE_ADDR addr, int mainline)' 1380 Called from `symbol_file_add' to actually read the symbols from a 1381 symbol-file into a set of psymtabs or symtabs. 1382 1383 `sf' points to the `struct sym_fns' originally passed to 1384 `XYZ_sym_init' for possible initialization. `addr' is the offset 1385 between the file's specified start address and its true address in 1386 memory. `mainline' is 1 if this is the main symbol table being 1387 read, and 0 if a secondary symbol file (e.g. shared library or 1388 dynamically loaded file) is being read. 1389 1390 In addition, if a symbol-reading module creates psymtabs when 1391XYZ_symfile_read is called, these psymtabs will contain a pointer to a 1392function `XYZ_psymtab_to_symtab', which can be called from any point in 1393the GDB symbol-handling code. 1394 1395`XYZ_psymtab_to_symtab (struct partial_symtab *pst)' 1396 Called from `psymtab_to_symtab' (or the `PSYMTAB_TO_SYMTAB' macro) 1397 if the psymtab has not already been read in and had its 1398 `pst->symtab' pointer set. The argument is the psymtab to be 1399 fleshed-out into a symtab. Upon return, `pst->readin' should have 1400 been set to 1, and `pst->symtab' should contain a pointer to the 1401 new corresponding symtab, or zero if there were no symbols in that 1402 part of the symbol file. 1403 1404Partial Symbol Tables 1405===================== 1406 1407GDB has three types of symbol tables: 1408 1409 * Full symbol tables ("symtabs"). These contain the main 1410 information about symbols and addresses. 1411 1412 * Partial symbol tables ("psymtabs"). These contain enough 1413 information to know when to read the corresponding part of the full 1414 symbol table. 1415 1416 * Minimal symbol tables ("msymtabs"). These contain information 1417 gleaned from non-debugging symbols. 1418 1419 This section describes partial symbol tables. 1420 1421 A psymtab is constructed by doing a very quick pass over an 1422executable file's debugging information. Small amounts of information 1423are extracted--enough to identify which parts of the symbol table will 1424need to be re-read and fully digested later, when the user needs the 1425information. The speed of this pass causes GDB to start up very 1426quickly. Later, as the detailed rereading occurs, it occurs in small 1427pieces, at various times, and the delay therefrom is mostly invisible to 1428the user. 1429 1430 The symbols that show up in a file's psymtab should be, roughly, 1431those visible to the debugger's user when the program is not running 1432code from that file. These include external symbols and types, static 1433symbols and types, and `enum' values declared at file scope. 1434 1435 The psymtab also contains the range of instruction addresses that the 1436full symbol table would represent. 1437 1438 The idea is that there are only two ways for the user (or much of the 1439code in the debugger) to reference a symbol: 1440 1441 * By its address (e.g. execution stops at some address which is 1442 inside a function in this file). The address will be noticed to 1443 be in the range of this psymtab, and the full symtab will be read 1444 in. `find_pc_function', `find_pc_line', and other `find_pc_...' 1445 functions handle this. 1446 1447 * By its name (e.g. the user asks to print a variable, or set a 1448 breakpoint on a function). Global names and file-scope names will 1449 be found in the psymtab, which will cause the symtab to be pulled 1450 in. Local names will have to be qualified by a global name, or a 1451 file-scope name, in which case we will have already read in the 1452 symtab as we evaluated the qualifier. Or, a local symbol can be 1453 referenced when we are "in" a local scope, in which case the first 1454 case applies. `lookup_symbol' does most of the work here. 1455 1456 The only reason that psymtabs exist is to cause a symtab to be read 1457in at the right moment. Any symbol that can be elided from a psymtab, 1458while still causing that to happen, should not appear in it. Since 1459psymtabs don't have the idea of scope, you can't put local symbols in 1460them anyway. Psymtabs don't have the idea of the type of a symbol, 1461either, so types need not appear, unless they will be referenced by 1462name. 1463 1464 It is a bug for GDB to behave one way when only a psymtab has been 1465read, and another way if the corresponding symtab has been read in. 1466Such bugs are typically caused by a psymtab that does not contain all 1467the visible symbols, or which has the wrong instruction address ranges. 1468 1469 The psymtab for a particular section of a symbol file (objfile) 1470could be thrown away after the symtab has been read in. The symtab 1471should always be searched before the psymtab, so the psymtab will never 1472be used (in a bug-free environment). Currently, psymtabs are allocated 1473on an obstack, and all the psymbols themselves are allocated in a pair 1474of large arrays on an obstack, so there is little to be gained by 1475trying to free them unless you want to do a lot more work. 1476 1477Types 1478===== 1479 1480Fundamental Types (e.g., `FT_VOID', `FT_BOOLEAN'). 1481-------------------------------------------------- 1482 1483These are the fundamental types that GDB uses internally. Fundamental 1484types from the various debugging formats (stabs, ELF, etc) are mapped 1485into one of these. They are basically a union of all fundamental types 1486that GDB knows about for all the languages that GDB knows about. 1487 1488Type Codes (e.g., `TYPE_CODE_PTR', `TYPE_CODE_ARRAY'). 1489------------------------------------------------------ 1490 1491Each time GDB builds an internal type, it marks it with one of these 1492types. The type may be a fundamental type, such as `TYPE_CODE_INT', or 1493a derived type, such as `TYPE_CODE_PTR' which is a pointer to another 1494type. Typically, several `FT_*' types map to one `TYPE_CODE_*' type, 1495and are distinguished by other members of the type struct, such as 1496whether the type is signed or unsigned, and how many bits it uses. 1497 1498Builtin Types (e.g., `builtin_type_void', `builtin_type_char'). 1499--------------------------------------------------------------- 1500 1501These are instances of type structs that roughly correspond to 1502fundamental types and are created as global types for GDB to use for 1503various ugly historical reasons. We eventually want to eliminate 1504these. Note for example that `builtin_type_int' initialized in 1505`gdbtypes.c' is basically the same as a `TYPE_CODE_INT' type that is 1506initialized in `c-lang.c' for an `FT_INTEGER' fundamental type. The 1507difference is that the `builtin_type' is not associated with any 1508particular objfile, and only one instance exists, while `c-lang.c' 1509builds as many `TYPE_CODE_INT' types as needed, with each one 1510associated with some particular objfile. 1511 1512Object File Formats 1513=================== 1514 1515a.out 1516----- 1517 1518The `a.out' format is the original file format for Unix. It consists 1519of three sections: `text', `data', and `bss', which are for program 1520code, initialized data, and uninitialized data, respectively. 1521 1522 The `a.out' format is so simple that it doesn't have any reserved 1523place for debugging information. (Hey, the original Unix hackers used 1524`adb', which is a machine-language debugger!) The only debugging 1525format for `a.out' is stabs, which is encoded as a set of normal 1526symbols with distinctive attributes. 1527 1528 The basic `a.out' reader is in `dbxread.c'. 1529 1530COFF 1531---- 1532 1533The COFF format was introduced with System V Release 3 (SVR3) Unix. 1534COFF files may have multiple sections, each prefixed by a header. The 1535number of sections is limited. 1536 1537 The COFF specification includes support for debugging. Although this 1538was a step forward, the debugging information was woefully limited. For 1539instance, it was not possible to represent code that came from an 1540included file. 1541 1542 The COFF reader is in `coffread.c'. 1543 1544ECOFF 1545----- 1546 1547ECOFF is an extended COFF originally introduced for Mips and Alpha 1548workstations. 1549 1550 The basic ECOFF reader is in `mipsread.c'. 1551 1552XCOFF 1553----- 1554 1555The IBM RS/6000 running AIX uses an object file format called XCOFF. 1556The COFF sections, symbols, and line numbers are used, but debugging 1557symbols are `dbx'-style stabs whose strings are located in the `.debug' 1558section (rather than the string table). For more information, see 1559*Note Top: (stabs)Top. 1560 1561 The shared library scheme has a clean interface for figuring out what 1562shared libraries are in use, but the catch is that everything which 1563refers to addresses (symbol tables and breakpoints at least) needs to be 1564relocated for both shared libraries and the main executable. At least 1565using the standard mechanism this can only be done once the program has 1566been run (or the core file has been read). 1567 1568PE 1569-- 1570 1571Windows 95 and NT use the PE ("Portable Executable") format for their 1572executables. PE is basically COFF with additional headers. 1573 1574 While BFD includes special PE support, GDB needs only the basic COFF 1575reader. 1576 1577ELF 1578--- 1579 1580The ELF format came with System V Release 4 (SVR4) Unix. ELF is similar 1581to COFF in being organized into a number of sections, but it removes 1582many of COFF's limitations. 1583 1584 The basic ELF reader is in `elfread.c'. 1585 1586SOM 1587--- 1588 1589SOM is HP's object file and debug format (not to be confused with IBM's 1590SOM, which is a cross-language ABI). 1591 1592 The SOM reader is in `hpread.c'. 1593 1594Other File Formats 1595------------------ 1596 1597Other file formats that have been supported by GDB include Netware 1598Loadable Modules (`nlmread.c'). 1599 1600Debugging File Formats 1601====================== 1602 1603This section describes characteristics of debugging information that 1604are independent of the object file format. 1605 1606stabs 1607----- 1608 1609`stabs' started out as special symbols within the `a.out' format. 1610Since then, it has been encapsulated into other file formats, such as 1611COFF and ELF. 1612 1613 While `dbxread.c' does some of the basic stab processing, including 1614for encapsulated versions, `stabsread.c' does the real work. 1615 1616COFF 1617---- 1618 1619The basic COFF definition includes debugging information. The level of 1620support is minimal and non-extensible, and is not often used. 1621 1622Mips debug (Third Eye) 1623---------------------- 1624 1625ECOFF includes a definition of a special debug format. 1626 1627 The file `mdebugread.c' implements reading for this format. 1628 1629DWARF 1 1630------- 1631 1632DWARF 1 is a debugging format that was originally designed to be used 1633with ELF in SVR4 systems. 1634 1635 The DWARF 1 reader is in `dwarfread.c'. 1636 1637DWARF 2 1638------- 1639 1640DWARF 2 is an improved but incompatible version of DWARF 1. 1641 1642 The DWARF 2 reader is in `dwarf2read.c'. 1643 1644SOM 1645--- 1646 1647Like COFF, the SOM definition includes debugging information. 1648 1649Adding a New Symbol Reader to GDB 1650================================= 1651 1652If you are using an existing object file format (`a.out', COFF, ELF, 1653etc), there is probably little to be done. 1654 1655 If you need to add a new object file format, you must first add it to 1656BFD. This is beyond the scope of this document. 1657 1658 You must then arrange for the BFD code to provide access to the 1659debugging symbols. Generally GDB will have to call swapping routines 1660from BFD and a few other BFD internal routines to locate the debugging 1661information. As much as possible, GDB should not depend on the BFD 1662internal data structures. 1663 1664 For some targets (e.g., COFF), there is a special transfer vector 1665used to call swapping routines, since the external data structures on 1666various platforms have different sizes and layouts. Specialized 1667routines that will only ever be implemented by one object file format 1668may be called directly. This interface should be described in a file 1669`bfd/libXYZ.h', which is included by GDB. 1670 1671 1672File: gdbint.info, Node: Language Support, Next: Host Definition, Prev: Symbol Handling, Up: Top 1673 1674Language Support 1675**************** 1676 1677GDB's language support is mainly driven by the symbol reader, although 1678it is possible for the user to set the source language manually. 1679 1680 GDB chooses the source language by looking at the extension of the 1681file recorded in the debug info; `.c' means C, `.f' means Fortran, etc. 1682It may also use a special-purpose language identifier if the debug 1683format supports it, like with DWARF. 1684 1685Adding a Source Language to GDB 1686=============================== 1687 1688To add other languages to GDB's expression parser, follow the following 1689steps: 1690 1691_Create the expression parser._ 1692 This should reside in a file `LANG-exp.y'. Routines for building 1693 parsed expressions into a `union exp_element' list are in 1694 `parse.c'. 1695 1696 Since we can't depend upon everyone having Bison, and YACC produces 1697 parsers that define a bunch of global names, the following lines 1698 *must* be included at the top of the YACC parser, to prevent the 1699 various parsers from defining the same global names: 1700 1701 #define yyparse LANG_parse 1702 #define yylex LANG_lex 1703 #define yyerror LANG_error 1704 #define yylval LANG_lval 1705 #define yychar LANG_char 1706 #define yydebug LANG_debug 1707 #define yypact LANG_pact 1708 #define yyr1 LANG_r1 1709 #define yyr2 LANG_r2 1710 #define yydef LANG_def 1711 #define yychk LANG_chk 1712 #define yypgo LANG_pgo 1713 #define yyact LANG_act 1714 #define yyexca LANG_exca 1715 #define yyerrflag LANG_errflag 1716 #define yynerrs LANG_nerrs 1717 1718 At the bottom of your parser, define a `struct language_defn' and 1719 initialize it with the right values for your language. Define an 1720 `initialize_LANG' routine and have it call 1721 `add_language(LANG_language_defn)' to tell the rest of GDB that 1722 your language exists. You'll need some other supporting variables 1723 and functions, which will be used via pointers from your 1724 `LANG_language_defn'. See the declaration of `struct 1725 language_defn' in `language.h', and the other `*-exp.y' files, for 1726 more information. 1727 1728_Add any evaluation routines, if necessary_ 1729 If you need new opcodes (that represent the operations of the 1730 language), add them to the enumerated type in `expression.h'. Add 1731 support code for these operations in the `evaluate_subexp' function 1732 defined in the file `eval.c'. Add cases for new opcodes in two 1733 functions from `parse.c': `prefixify_subexp' and 1734 `length_of_subexp'. These compute the number of `exp_element's 1735 that a given operation takes up. 1736 1737_Update some existing code_ 1738 Add an enumerated identifier for your language to the enumerated 1739 type `enum language' in `defs.h'. 1740 1741 Update the routines in `language.c' so your language is included. 1742 These routines include type predicates and such, which (in some 1743 cases) are language dependent. If your language does not appear 1744 in the switch statement, an error is reported. 1745 1746 Also included in `language.c' is the code that updates the variable 1747 `current_language', and the routines that translate the 1748 `language_LANG' enumerated identifier into a printable string. 1749 1750 Update the function `_initialize_language' to include your 1751 language. This function picks the default language upon startup, 1752 so is dependent upon which languages that GDB is built for. 1753 1754 Update `allocate_symtab' in `symfile.c' and/or symbol-reading code 1755 so that the language of each symtab (source file) is set properly. 1756 This is used to determine the language to use at each stack frame 1757 level. Currently, the language is set based upon the extension of 1758 the source file. If the language can be better inferred from the 1759 symbol information, please set the language of the symtab in the 1760 symbol-reading code. 1761 1762 Add helper code to `print_subexp' (in `expprint.c') to handle any 1763 new expression opcodes you have added to `expression.h'. Also, 1764 add the printed representations of your operators to 1765 `op_print_tab'. 1766 1767_Add a place of call_ 1768 Add a call to `LANG_parse()' and `LANG_error' in `parse_exp_1' 1769 (defined in `parse.c'). 1770 1771_Use macros to trim code_ 1772 The user has the option of building GDB for some or all of the 1773 languages. If the user decides to build GDB for the language 1774 LANG, then every file dependent on `language.h' will have the 1775 macro `_LANG_LANG' defined in it. Use `#ifdef's to leave out 1776 large routines that the user won't need if he or she is not using 1777 your language. 1778 1779 Note that you do not need to do this in your YACC parser, since if 1780 GDB is not build for LANG, then `LANG-exp.tab.o' (the compiled 1781 form of your parser) is not linked into GDB at all. 1782 1783 See the file `configure.in' for how GDB is configured for 1784 different languages. 1785 1786_Edit `Makefile.in'_ 1787 Add dependencies in `Makefile.in'. Make sure you update the macro 1788 variables such as `HFILES' and `OBJS', otherwise your code may not 1789 get linked in, or, worse yet, it may not get `tar'red into the 1790 distribution! 1791 1792 1793File: gdbint.info, Node: Host Definition, Next: Target Architecture Definition, Prev: Language Support, Up: Top 1794 1795Host Definition 1796*************** 1797 1798With the advent of Autoconf, it's rarely necessary to have host 1799definition machinery anymore. The following information is provided, 1800mainly, as an historical reference. 1801 1802Adding a New Host 1803================= 1804 1805GDB's host configuration support normally happens via Autoconf. New 1806host-specific definitions should not be needed. Older hosts GDB still 1807use the host-specific definitions and files listed below, but these 1808mostly exist for historical reasons, and will eventually disappear. 1809 1810`gdb/config/ARCH/XYZ.mh' 1811 This file once contained both host and native configuration 1812 information (*note Native Debugging::) for the machine XYZ. The 1813 host configuration information is now handed by Autoconf. 1814 1815 Host configuration information included a definition of 1816 `XM_FILE=xm-XYZ.h' and possibly definitions for `CC', 1817 `SYSV_DEFINE', `XM_CFLAGS', `XM_ADD_FILES', `XM_CLIBS', 1818 `XM_CDEPS', etc.; see `Makefile.in'. 1819 1820 New host only configurations do not need this file. 1821 1822`gdb/config/ARCH/xm-XYZ.h' 1823 This file once contained definitions and includes required when 1824 hosting gdb on machine XYZ. Those definitions and includes are now 1825 handled by Autoconf. 1826 1827 New host and native configurations do not need this file. 1828 1829 _Maintainer's note: Some hosts continue to use the `xm-xyz.h' file 1830 to define the macros HOST_FLOAT_FORMAT, HOST_DOUBLE_FORMAT and 1831 HOST_LONG_DOUBLE_FORMAT. That code also needs to be replaced with 1832 either an Autoconf or run-time test._ 1833 1834 1835Generic Host Support Files 1836-------------------------- 1837 1838There are some "generic" versions of routines that can be used by 1839various systems. These can be customized in various ways by macros 1840defined in your `xm-XYZ.h' file. If these routines work for the XYZ 1841host, you can just include the generic file's name (with `.o', not 1842`.c') in `XDEPFILES'. 1843 1844 Otherwise, if your machine needs custom support routines, you will 1845need to write routines that perform the same functions as the generic 1846file. Put them into `XYZ-xdep.c', and put `XYZ-xdep.o' into 1847`XDEPFILES'. 1848 1849`ser-unix.c' 1850 This contains serial line support for Unix systems. This is always 1851 included, via the makefile variable `SER_HARDWIRE'; override this 1852 variable in the `.mh' file to avoid it. 1853 1854`ser-go32.c' 1855 This contains serial line support for 32-bit programs running 1856 under DOS, using the DJGPP (a.k.a. GO32) execution environment. 1857 1858`ser-tcp.c' 1859 This contains generic TCP support using sockets. 1860 1861Host Conditionals 1862================= 1863 1864When GDB is configured and compiled, various macros are defined or left 1865undefined, to control compilation based on the attributes of the host 1866system. These macros and their meanings (or if the meaning is not 1867documented here, then one of the source files where they are used is 1868indicated) are: 1869 1870`GDBINIT_FILENAME' 1871 The default name of GDB's initialization file (normally 1872 `.gdbinit'). 1873 1874`NO_STD_REGS' 1875 This macro is deprecated. 1876 1877`NO_SYS_FILE' 1878 Define this if your system does not have a `<sys/file.h>'. 1879 1880`SIGWINCH_HANDLER' 1881 If your host defines `SIGWINCH', you can define this to be the name 1882 of a function to be called if `SIGWINCH' is received. 1883 1884`SIGWINCH_HANDLER_BODY' 1885 Define this to expand into code that will define the function 1886 named by the expansion of `SIGWINCH_HANDLER'. 1887 1888`ALIGN_STACK_ON_STARTUP' 1889 Define this if your system is of a sort that will crash in 1890 `tgetent' if the stack happens not to be longword-aligned when 1891 `main' is called. This is a rare situation, but is known to occur 1892 on several different types of systems. 1893 1894`CRLF_SOURCE_FILES' 1895 Define this if host files use `\r\n' rather than `\n' as a line 1896 terminator. This will cause source file listings to omit `\r' 1897 characters when printing and it will allow `\r\n' line endings of 1898 files which are "sourced" by gdb. It must be possible to open 1899 files in binary mode using `O_BINARY' or, for fopen, `"rb"'. 1900 1901`DEFAULT_PROMPT' 1902 The default value of the prompt string (normally `"(gdb) "'). 1903 1904`DEV_TTY' 1905 The name of the generic TTY device, defaults to `"/dev/tty"'. 1906 1907`FCLOSE_PROVIDED' 1908 Define this if the system declares `fclose' in the headers included 1909 in `defs.h'. This isn't needed unless your compiler is unusually 1910 anal. 1911 1912`FOPEN_RB' 1913 Define this if binary files are opened the same way as text files. 1914 1915`GETENV_PROVIDED' 1916 Define this if the system declares `getenv' in its headers included 1917 in `defs.h'. This isn't needed unless your compiler is unusually 1918 anal. 1919 1920`HAVE_MMAP' 1921 In some cases, use the system call `mmap' for reading symbol 1922 tables. For some machines this allows for sharing and quick 1923 updates. 1924 1925`HAVE_TERMIO' 1926 Define this if the host system has `termio.h'. 1927 1928`INT_MAX' 1929`INT_MIN' 1930`LONG_MAX' 1931`UINT_MAX' 1932`ULONG_MAX' 1933 Values for host-side constants. 1934 1935`ISATTY' 1936 Substitute for isatty, if not available. 1937 1938`LONGEST' 1939 This is the longest integer type available on the host. If not 1940 defined, it will default to `long long' or `long', depending on 1941 `CC_HAS_LONG_LONG'. 1942 1943`CC_HAS_LONG_LONG' 1944 Define this if the host C compiler supports `long long'. This is 1945 set by the `configure' script. 1946 1947`PRINTF_HAS_LONG_LONG' 1948 Define this if the host can handle printing of long long integers 1949 via the printf format conversion specifier `ll'. This is set by 1950 the `configure' script. 1951 1952`HAVE_LONG_DOUBLE' 1953 Define this if the host C compiler supports `long double'. This is 1954 set by the `configure' script. 1955 1956`PRINTF_HAS_LONG_DOUBLE' 1957 Define this if the host can handle printing of long double 1958 float-point numbers via the printf format conversion specifier 1959 `Lg'. This is set by the `configure' script. 1960 1961`SCANF_HAS_LONG_DOUBLE' 1962 Define this if the host can handle the parsing of long double 1963 float-point numbers via the scanf format conversion specifier 1964 `Lg'. This is set by the `configure' script. 1965 1966`LSEEK_NOT_LINEAR' 1967 Define this if `lseek (n)' does not necessarily move to byte number 1968 `n' in the file. This is only used when reading source files. It 1969 is normally faster to define `CRLF_SOURCE_FILES' when possible. 1970 1971`L_SET' 1972 This macro is used as the argument to `lseek' (or, most commonly, 1973 `bfd_seek'). FIXME, should be replaced by SEEK_SET instead, which 1974 is the POSIX equivalent. 1975 1976`NORETURN' 1977 If defined, this should be one or more tokens, such as `volatile', 1978 that can be used in both the declaration and definition of 1979 functions to indicate that they never return. The default is 1980 already set correctly if compiling with GCC. This will almost 1981 never need to be defined. 1982 1983`ATTR_NORETURN' 1984 If defined, this should be one or more tokens, such as 1985 `__attribute__ ((noreturn))', that can be used in the declarations 1986 of functions to indicate that they never return. The default is 1987 already set correctly if compiling with GCC. This will almost 1988 never need to be defined. 1989 1990`SEEK_CUR' 1991`SEEK_SET' 1992 Define these to appropriate value for the system `lseek', if not 1993 already defined. 1994 1995`STOP_SIGNAL' 1996 This is the signal for stopping GDB. Defaults to `SIGTSTP'. 1997 (Only redefined for the Convex.) 1998 1999`USE_O_NOCTTY' 2000 Define this if the interior's tty should be opened with the 2001 `O_NOCTTY' flag. (FIXME: This should be a native-only flag, but 2002 `inflow.c' is always linked in.) 2003 2004`USG' 2005 Means that System V (prior to SVR4) include files are in use. 2006 (FIXME: This symbol is abused in `infrun.c', `regex.c', and 2007 `utils.c' for other things, at the moment.) 2008 2009`lint' 2010 Define this to help placate `lint' in some situations. 2011 2012`volatile' 2013 Define this to override the defaults of `__volatile__' or `/**/'. 2014 2015 2016File: gdbint.info, Node: Target Architecture Definition, Next: Target Vector Definition, Prev: Host Definition, Up: Top 2017 2018Target Architecture Definition 2019****************************** 2020 2021GDB's target architecture defines what sort of machine-language 2022programs GDB can work with, and how it works with them. 2023 2024 The target architecture object is implemented as the C structure 2025`struct gdbarch *'. The structure, and its methods, are generated 2026using the Bourne shell script `gdbarch.sh'. 2027 2028Operating System ABI Variant Handling 2029===================================== 2030 2031GDB provides a mechanism for handling variations in OS ABIs. An OS ABI 2032variant may have influence over any number of variables in the target 2033architecture definition. There are two major components in the OS ABI 2034mechanism: sniffers and handlers. 2035 2036 A "sniffer" examines a file matching a BFD architecture/flavour pair 2037(the architecture may be wildcarded) in an attempt to determine the OS 2038ABI of that file. Sniffers with a wildcarded architecture are 2039considered to be "generic", while sniffers for a specific architecture 2040are considered to be "specific". A match from a specific sniffer 2041overrides a match from a generic sniffer. Multiple sniffers for an 2042architecture/flavour may exist, in order to differentiate between two 2043different operating systems which use the same basic file format. The 2044OS ABI framework provides a generic sniffer for ELF-format files which 2045examines the `EI_OSABI' field of the ELF header, as well as note 2046sections known to be used by several operating systems. 2047 2048 A "handler" is used to fine-tune the `gdbarch' structure for the 2049selected OS ABI. There may be only one handler for a given OS ABI for 2050each BFD architecture. 2051 2052 The following OS ABI variants are defined in `osabi.h': 2053 2054`GDB_OSABI_UNKNOWN' 2055 The ABI of the inferior is unknown. The default `gdbarch' 2056 settings for the architecture will be used. 2057 2058`GDB_OSABI_SVR4' 2059 UNIX System V Release 4 2060 2061`GDB_OSABI_HURD' 2062 GNU using the Hurd kernel 2063 2064`GDB_OSABI_SOLARIS' 2065 Sun Solaris 2066 2067`GDB_OSABI_OSF1' 2068 OSF/1, including Digital UNIX and Compaq Tru64 UNIX 2069 2070`GDB_OSABI_LINUX' 2071 GNU using the Linux kernel 2072 2073`GDB_OSABI_FREEBSD_AOUT' 2074 FreeBSD using the a.out executable format 2075 2076`GDB_OSABI_FREEBSD_ELF' 2077 FreeBSD using the ELF executable format 2078 2079`GDB_OSABI_NETBSD_AOUT' 2080 NetBSD using the a.out executable format 2081 2082`GDB_OSABI_NETBSD_ELF' 2083 NetBSD using the ELF executable format 2084 2085`GDB_OSABI_WINCE' 2086 Windows CE 2087 2088`GDB_OSABI_GO32' 2089 DJGPP 2090 2091`GDB_OSABI_NETWARE' 2092 Novell NetWare 2093 2094`GDB_OSABI_ARM_EABI_V1' 2095 ARM Embedded ABI version 1 2096 2097`GDB_OSABI_ARM_EABI_V2' 2098 ARM Embedded ABI version 2 2099 2100`GDB_OSABI_ARM_APCS' 2101 Generic ARM Procedure Call Standard 2102 2103 2104 Here are the functions that make up the OS ABI framework: 2105 2106 - Function: const char *gdbarch_osabi_name (enum gdb_osabi OSABI) 2107 Return the name of the OS ABI corresponding to OSABI. 2108 2109 - Function: void gdbarch_register_osabi (enum bfd_architecture ARCH, 2110 unsigned long MACHINE, enum gdb_osabi OSABI, void 2111 (*INIT_OSABI)(struct gdbarch_info INFO, struct gdbarch 2112 *GDBARCH)) 2113 Register the OS ABI handler specified by INIT_OSABI for the 2114 architecture, machine type and OS ABI specified by ARCH, MACHINE 2115 and OSABI. In most cases, a value of zero for the machine type, 2116 which implies the architecture's default machine type, will 2117 suffice. 2118 2119 - Function: void gdbarch_register_osabi_sniffer (enum bfd_architecture 2120 ARCH, enum bfd_flavour FLAVOUR, enum gdb_osabi (*SNIFFER)(bfd 2121 *ABFD)) 2122 Register the OS ABI file sniffer specified by SNIFFER for the BFD 2123 architecture/flavour pair specified by ARCH and FLAVOUR. If ARCH 2124 is `bfd_arch_unknown', the sniffer is considered to be generic, 2125 and is allowed to examine FLAVOUR-flavoured files for any 2126 architecture. 2127 2128 - Function: enum gdb_osabi gdbarch_lookup_osabi (bfd *ABFD) 2129 Examine the file described by ABFD to determine its OS ABI. The 2130 value `GDB_OSABI_UNKNOWN' is returned if the OS ABI cannot be 2131 determined. 2132 2133 - Function: void gdbarch_init_osabi (struct gdbarch info INFO, struct 2134 gdbarch *GDBARCH, enum gdb_osabi OSABI) 2135 Invoke the OS ABI handler corresponding to OSABI to fine-tune the 2136 `gdbarch' structure specified by GDBARCH. If a handler 2137 corresponding to OSABI has not been registered for GDBARCH's 2138 architecture, a warning will be issued and the debugging session 2139 will continue with the defaults already established for GDBARCH. 2140 2141Registers and Memory 2142==================== 2143 2144GDB's model of the target machine is rather simple. GDB assumes the 2145machine includes a bank of registers and a block of memory. Each 2146register may have a different size. 2147 2148 GDB does not have a magical way to match up with the compiler's idea 2149of which registers are which; however, it is critical that they do 2150match up accurately. The only way to make this work is to get accurate 2151information about the order that the compiler uses, and to reflect that 2152in the `REGISTER_NAME' and related macros. 2153 2154 GDB can handle big-endian, little-endian, and bi-endian 2155architectures. 2156 2157Pointers Are Not Always Addresses 2158================================= 2159 2160On almost all 32-bit architectures, the representation of a pointer is 2161indistinguishable from the representation of some fixed-length number 2162whose value is the byte address of the object pointed to. On such 2163machines, the words "pointer" and "address" can be used interchangeably. 2164However, architectures with smaller word sizes are often cramped for 2165address space, so they may choose a pointer representation that breaks 2166this identity, and allows a larger code address space. 2167 2168 For example, the Renesas D10V is a 16-bit VLIW processor whose 2169instructions are 32 bits long(1). If the D10V used ordinary byte 2170addresses to refer to code locations, then the processor would only be 2171able to address 64kb of instructions. However, since instructions must 2172be aligned on four-byte boundaries, the low two bits of any valid 2173instruction's byte address are always zero--byte addresses waste two 2174bits. So instead of byte addresses, the D10V uses word addresses--byte 2175addresses shifted right two bits--to refer to code. Thus, the D10V can 2176use 16-bit words to address 256kb of code space. 2177 2178 However, this means that code pointers and data pointers have 2179different forms on the D10V. The 16-bit word `0xC020' refers to byte 2180address `0xC020' when used as a data address, but refers to byte address 2181`0x30080' when used as a code address. 2182 2183 (The D10V also uses separate code and data address spaces, which also 2184affects the correspondence between pointers and addresses, but we're 2185going to ignore that here; this example is already too long.) 2186 2187 To cope with architectures like this--the D10V is not the only 2188one!--GDB tries to distinguish between "addresses", which are byte 2189numbers, and "pointers", which are the target's representation of an 2190address of a particular type of data. In the example above, `0xC020' 2191is the pointer, which refers to one of the addresses `0xC020' or 2192`0x30080', depending on the type imposed upon it. GDB provides 2193functions for turning a pointer into an address and vice versa, in the 2194appropriate way for the current architecture. 2195 2196 Unfortunately, since addresses and pointers are identical on almost 2197all processors, this distinction tends to bit-rot pretty quickly. Thus, 2198each time you port GDB to an architecture which does distinguish 2199between pointers and addresses, you'll probably need to clean up some 2200architecture-independent code. 2201 2202 Here are functions which convert between pointers and addresses: 2203 2204 - Function: CORE_ADDR extract_typed_address (void *BUF, struct type 2205 *TYPE) 2206 Treat the bytes at BUF as a pointer or reference of type TYPE, and 2207 return the address it represents, in a manner appropriate for the 2208 current architecture. This yields an address GDB can use to read 2209 target memory, disassemble, etc. Note that BUF refers to a buffer 2210 in GDB's memory, not the inferior's. 2211 2212 For example, if the current architecture is the Intel x86, this 2213 function extracts a little-endian integer of the appropriate 2214 length from BUF and returns it. However, if the current 2215 architecture is the D10V, this function will return a 16-bit 2216 integer extracted from BUF, multiplied by four if TYPE is a 2217 pointer to a function. 2218 2219 If TYPE is not a pointer or reference type, then this function 2220 will signal an internal error. 2221 2222 - Function: CORE_ADDR store_typed_address (void *BUF, struct type 2223 *TYPE, CORE_ADDR ADDR) 2224 Store the address ADDR in BUF, in the proper format for a pointer 2225 of type TYPE in the current architecture. Note that BUF refers to 2226 a buffer in GDB's memory, not the inferior's. 2227 2228 For example, if the current architecture is the Intel x86, this 2229 function stores ADDR unmodified as a little-endian integer of the 2230 appropriate length in BUF. However, if the current architecture 2231 is the D10V, this function divides ADDR by four if TYPE is a 2232 pointer to a function, and then stores it in BUF. 2233 2234 If TYPE is not a pointer or reference type, then this function 2235 will signal an internal error. 2236 2237 - Function: CORE_ADDR value_as_address (struct value *VAL) 2238 Assuming that VAL is a pointer, return the address it represents, 2239 as appropriate for the current architecture. 2240 2241 This function actually works on integral values, as well as 2242 pointers. For pointers, it performs architecture-specific 2243 conversions as described above for `extract_typed_address'. 2244 2245 - Function: CORE_ADDR value_from_pointer (struct type *TYPE, CORE_ADDR 2246 ADDR) 2247 Create and return a value representing a pointer of type TYPE to 2248 the address ADDR, as appropriate for the current architecture. 2249 This function performs architecture-specific conversions as 2250 described above for `store_typed_address'. 2251 2252 Here are some macros which architectures can define to indicate the 2253relationship between pointers and addresses. These have default 2254definitions, appropriate for architectures on which all pointers are 2255simple unsigned byte addresses. 2256 2257 - Target Macro: CORE_ADDR POINTER_TO_ADDRESS (struct type *TYPE, char 2258 *BUF) 2259 Assume that BUF holds a pointer of type TYPE, in the appropriate 2260 format for the current architecture. Return the byte address the 2261 pointer refers to. 2262 2263 This function may safely assume that TYPE is either a pointer or a 2264 C++ reference type. 2265 2266 - Target Macro: void ADDRESS_TO_POINTER (struct type *TYPE, char *BUF, 2267 CORE_ADDR ADDR) 2268 Store in BUF a pointer of type TYPE representing the address ADDR, 2269 in the appropriate format for the current architecture. 2270 2271 This function may safely assume that TYPE is either a pointer or a 2272 C++ reference type. 2273 2274Address Classes 2275=============== 2276 2277Sometimes information about different kinds of addresses is available 2278via the debug information. For example, some programming environments 2279define addresses of several different sizes. If the debug information 2280distinguishes these kinds of address classes through either the size 2281info (e.g, `DW_AT_byte_size' in DWARF 2) or through an explicit address 2282class attribute (e.g, `DW_AT_address_class' in DWARF 2), the following 2283macros should be defined in order to disambiguate these types within 2284GDB as well as provide the added information to a GDB user when 2285printing type expressions. 2286 2287 - Target Macro: int ADDRESS_CLASS_TYPE_FLAGS (int BYTE_SIZE, int 2288 DWARF2_ADDR_CLASS) 2289 Returns the type flags needed to construct a pointer type whose 2290 size is BYTE_SIZE and whose address class is DWARF2_ADDR_CLASS. 2291 This function is normally called from within a symbol reader. See 2292 `dwarf2read.c'. 2293 2294 - Target Macro: char *ADDRESS_CLASS_TYPE_FLAGS_TO_NAME (int TYPE_FLAGS) 2295 Given the type flags representing an address class qualifier, 2296 return its name. 2297 2298 - Target Macro: int ADDRESS_CLASS_NAME_to_TYPE_FLAGS (int NAME, int 2299 *vartype_flags_ptr) 2300 Given an address qualifier name, set the `int' refererenced by 2301 TYPE_FLAGS_PTR to the type flags for that address class qualifier. 2302 2303 Since the need for address classes is rather rare, none of the 2304address class macros defined by default. Predicate macros are provided 2305to detect when they are defined. 2306 2307 Consider a hypothetical architecture in which addresses are normally 230832-bits wide, but 16-bit addresses are also supported. Furthermore, 2309suppose that the DWARF 2 information for this architecture simply uses 2310a `DW_AT_byte_size' value of 2 to indicate the use of one of these 2311"short" pointers. The following functions could be defined to 2312implement the address class macros: 2313 2314 somearch_address_class_type_flags (int byte_size, 2315 int dwarf2_addr_class) 2316 { 2317 if (byte_size == 2) 2318 return TYPE_FLAG_ADDRESS_CLASS_1; 2319 else 2320 return 0; 2321 } 2322 2323 static char * 2324 somearch_address_class_type_flags_to_name (int type_flags) 2325 { 2326 if (type_flags & TYPE_FLAG_ADDRESS_CLASS_1) 2327 return "short"; 2328 else 2329 return NULL; 2330 } 2331 2332 int 2333 somearch_address_class_name_to_type_flags (char *name, 2334 int *type_flags_ptr) 2335 { 2336 if (strcmp (name, "short") == 0) 2337 { 2338 *type_flags_ptr = TYPE_FLAG_ADDRESS_CLASS_1; 2339 return 1; 2340 } 2341 else 2342 return 0; 2343 } 2344 2345 The qualifier `@short' is used in GDB's type expressions to indicate 2346the presence of one of these "short" pointers. E.g, if the debug 2347information indicates that `short_ptr_var' is one of these short 2348pointers, GDB might show the following behavior: 2349 2350 (gdb) ptype short_ptr_var 2351 type = int * @short 2352 2353Raw and Virtual Register Representations 2354======================================== 2355 2356_Maintainer note: This section is pretty much obsolete. The 2357functionality described here has largely been replaced by 2358pseudo-registers and the mechanisms described in *Note Using Different 2359Register and Memory Data Representations: Target Architecture 2360Definition. See also Bug Tracking Database 2361(http://www.gnu.org/software/gdb/bugs/) and ARI Index 2362(http://sources.redhat.com/gdb/current/ari/) for more up-to-date 2363information._ 2364 2365 Some architectures use one representation for a value when it lives 2366in a register, but use a different representation when it lives in 2367memory. In GDB's terminology, the "raw" representation is the one used 2368in the target registers, and the "virtual" representation is the one 2369used in memory, and within GDB `struct value' objects. 2370 2371 _Maintainer note: Notice that the same mechanism is being used to 2372both convert a register to a `struct value' and alternative register 2373forms._ 2374 2375 For almost all data types on almost all architectures, the virtual 2376and raw representations are identical, and no special handling is 2377needed. However, they do occasionally differ. For example: 2378 2379 * The x86 architecture supports an 80-bit `long double' type. 2380 However, when we store those values in memory, they occupy twelve 2381 bytes: the floating-point number occupies the first ten, and the 2382 final two bytes are unused. This keeps the values aligned on 2383 four-byte boundaries, allowing more efficient access. Thus, the 2384 x86 80-bit floating-point type is the raw representation, and the 2385 twelve-byte loosely-packed arrangement is the virtual 2386 representation. 2387 2388 * Some 64-bit MIPS targets present 32-bit registers to GDB as 64-bit 2389 registers, with garbage in their upper bits. GDB ignores the top 2390 32 bits. Thus, the 64-bit form, with garbage in the upper 32 2391 bits, is the raw representation, and the trimmed 32-bit 2392 representation is the virtual representation. 2393 2394 In general, the raw representation is determined by the 2395architecture, or GDB's interface to the architecture, while the virtual 2396representation can be chosen for GDB's convenience. GDB's register 2397file, `registers', holds the register contents in raw format, and the 2398GDB remote protocol transmits register values in raw format. 2399 2400 Your architecture may define the following macros to request 2401conversions between the raw and virtual format: 2402 2403 - Target Macro: int REGISTER_CONVERTIBLE (int REG) 2404 Return non-zero if register number REG's value needs different raw 2405 and virtual formats. 2406 2407 You should not use `REGISTER_CONVERT_TO_VIRTUAL' for a register 2408 unless this macro returns a non-zero value for that register. 2409 2410 - Target Macro: int DEPRECATED_REGISTER_RAW_SIZE (int REG) 2411 The size of register number REG's raw value. This is the number 2412 of bytes the register will occupy in `registers', or in a GDB 2413 remote protocol packet. 2414 2415 - Target Macro: int DEPRECATED_REGISTER_VIRTUAL_SIZE (int REG) 2416 The size of register number REG's value, in its virtual format. 2417 This is the size a `struct value''s buffer will have, holding that 2418 register's value. 2419 2420 - Target Macro: struct type *DEPRECATED_REGISTER_VIRTUAL_TYPE (int REG) 2421 This is the type of the virtual representation of register number 2422 REG. Note that there is no need for a macro giving a type for the 2423 register's raw form; once the register's value has been obtained, 2424 GDB always uses the virtual form. 2425 2426 - Target Macro: void REGISTER_CONVERT_TO_VIRTUAL (int REG, struct type 2427 *TYPE, char *FROM, char *TO) 2428 Convert the value of register number REG to TYPE, which should 2429 always be `DEPRECATED_REGISTER_VIRTUAL_TYPE (REG)'. The buffer at 2430 FROM holds the register's value in raw format; the macro should 2431 convert the value to virtual format, and place it at TO. 2432 2433 Note that `REGISTER_CONVERT_TO_VIRTUAL' and 2434 `REGISTER_CONVERT_TO_RAW' take their REG and TYPE arguments in 2435 different orders. 2436 2437 You should only use `REGISTER_CONVERT_TO_VIRTUAL' with registers 2438 for which the `REGISTER_CONVERTIBLE' macro returns a non-zero 2439 value. 2440 2441 - Target Macro: void REGISTER_CONVERT_TO_RAW (struct type *TYPE, int 2442 REG, char *FROM, char *TO) 2443 Convert the value of register number REG to TYPE, which should 2444 always be `DEPRECATED_REGISTER_VIRTUAL_TYPE (REG)'. The buffer at 2445 FROM holds the register's value in raw format; the macro should 2446 convert the value to virtual format, and place it at TO. 2447 2448 Note that REGISTER_CONVERT_TO_VIRTUAL and REGISTER_CONVERT_TO_RAW 2449 take their REG and TYPE arguments in different orders. 2450 2451Using Different Register and Memory Data Representations 2452======================================================== 2453 2454_Maintainer's note: The way GDB manipulates registers is undergoing 2455significant change. Many of the macros and functions refered to in this 2456section are likely to be subject to further revision. See A.R. Index 2457(http://sources.redhat.com/gdb/current/ari/) and Bug Tracking Database 2458(http://www.gnu.org/software/gdb/bugs) for further information. 2459cagney/2002-05-06._ 2460 2461 Some architectures can represent a data object in a register using a 2462form that is different to the objects more normal memory representation. 2463For example: 2464 2465 * The Alpha architecture can represent 32 bit integer values in 2466 floating-point registers. 2467 2468 * The x86 architecture supports 80-bit floating-point registers. The 2469 `long double' data type occupies 96 bits in memory but only 80 bits 2470 when stored in a register. 2471 2472 2473 In general, the register representation of a data type is determined 2474by the architecture, or GDB's interface to the architecture, while the 2475memory representation is determined by the Application Binary Interface. 2476 2477 For almost all data types on almost all architectures, the two 2478representations are identical, and no special handling is needed. 2479However, they do occasionally differ. Your architecture may define the 2480following macros to request conversions between the register and memory 2481representations of a data type: 2482 2483 - Target Macro: int CONVERT_REGISTER_P (int REG) 2484 Return non-zero if the representation of a data value stored in 2485 this register may be different to the representation of that same 2486 data value when stored in memory. 2487 2488 When non-zero, the macros `REGISTER_TO_VALUE' and 2489 `VALUE_TO_REGISTER' are used to perform any necessary conversion. 2490 2491 - Target Macro: void REGISTER_TO_VALUE (int REG, struct type *TYPE, 2492 char *FROM, char *TO) 2493 Convert the value of register number REG to a data object of type 2494 TYPE. The buffer at FROM holds the register's value in raw 2495 format; the converted value should be placed in the buffer at TO. 2496 2497 Note that `REGISTER_TO_VALUE' and `VALUE_TO_REGISTER' take their 2498 REG and TYPE arguments in different orders. 2499 2500 You should only use `REGISTER_TO_VALUE' with registers for which 2501 the `CONVERT_REGISTER_P' macro returns a non-zero value. 2502 2503 - Target Macro: void VALUE_TO_REGISTER (struct type *TYPE, int REG, 2504 char *FROM, char *TO) 2505 Convert a data value of type TYPE to register number REG' raw 2506 format. 2507 2508 Note that `REGISTER_TO_VALUE' and `VALUE_TO_REGISTER' take their 2509 REG and TYPE arguments in different orders. 2510 2511 You should only use `VALUE_TO_REGISTER' with registers for which 2512 the `CONVERT_REGISTER_P' macro returns a non-zero value. 2513 2514 - Target Macro: void REGISTER_CONVERT_TO_TYPE (int REGNUM, struct type 2515 *TYPE, char *BUF) 2516 See `mips-tdep.c'. It does not do what you want. 2517 2518Frame Interpretation 2519==================== 2520 2521Inferior Call Setup 2522=================== 2523 2524Compiler Characteristics 2525======================== 2526 2527Target Conditionals 2528=================== 2529 2530This section describes the macros that you can use to define the target 2531machine. 2532 2533`ADDR_BITS_REMOVE (addr)' 2534 If a raw machine instruction address includes any bits that are not 2535 really part of the address, then define this macro to expand into 2536 an expression that zeroes those bits in ADDR. This is only used 2537 for addresses of instructions, and even then not in all contexts. 2538 2539 For example, the two low-order bits of the PC on the 2540 Hewlett-Packard PA 2.0 architecture contain the privilege level of 2541 the corresponding instruction. Since instructions must always be 2542 aligned on four-byte boundaries, the processor masks out these 2543 bits to generate the actual address of the instruction. 2544 ADDR_BITS_REMOVE should filter out these bits with an expression 2545 such as `((addr) & ~3)'. 2546 2547`ADDRESS_CLASS_NAME_TO_TYPE_FLAGS (NAME, TYPE_FLAGS_PTR)' 2548 If NAME is a valid address class qualifier name, set the `int' 2549 referenced by TYPE_FLAGS_PTR to the mask representing the qualifier 2550 and return 1. If NAME is not a valid address class qualifier name, 2551 return 0. 2552 2553 The value for TYPE_FLAGS_PTR should be one of 2554 `TYPE_FLAG_ADDRESS_CLASS_1', `TYPE_FLAG_ADDRESS_CLASS_2', or 2555 possibly some combination of these values or'd together. *Note 2556 Address Classes: Target Architecture Definition. 2557 2558`ADDRESS_CLASS_NAME_TO_TYPE_FLAGS_P ()' 2559 Predicate which indicates whether 2560 `ADDRESS_CLASS_NAME_TO_TYPE_FLAGS' has been defined. 2561 2562`ADDRESS_CLASS_TYPE_FLAGS (BYTE_SIZE, DWARF2_ADDR_CLASS)' 2563 Given a pointers byte size (as described by the debug information) 2564 and the possible `DW_AT_address_class' value, return the type flags 2565 used by GDB to represent this address class. The value returned 2566 should be one of `TYPE_FLAG_ADDRESS_CLASS_1', 2567 `TYPE_FLAG_ADDRESS_CLASS_2', or possibly some combination of these 2568 values or'd together. *Note Address Classes: Target Architecture 2569 Definition. 2570 2571`ADDRESS_CLASS_TYPE_FLAGS_P ()' 2572 Predicate which indicates whether `ADDRESS_CLASS_TYPE_FLAGS' has 2573 been defined. 2574 2575`ADDRESS_CLASS_TYPE_FLAGS_TO_NAME (TYPE_FLAGS)' 2576 Return the name of the address class qualifier associated with the 2577 type flags given by TYPE_FLAGS. 2578 2579`ADDRESS_CLASS_TYPE_FLAGS_TO_NAME_P ()' 2580 Predicate which indicates whether 2581 `ADDRESS_CLASS_TYPE_FLAGS_TO_NAME' has been defined. *Note 2582 Address Classes: Target Architecture Definition. 2583 2584`ADDRESS_TO_POINTER (TYPE, BUF, ADDR)' 2585 Store in BUF a pointer of type TYPE representing the address ADDR, 2586 in the appropriate format for the current architecture. This 2587 macro may safely assume that TYPE is either a pointer or a C++ 2588 reference type. *Note Pointers Are Not Always Addresses: Target 2589 Architecture Definition. 2590 2591`BELIEVE_PCC_PROMOTION' 2592 Define if the compiler promotes a `short' or `char' parameter to 2593 an `int', but still reports the parameter as its original type, 2594 rather than the promoted type. 2595 2596`BITS_BIG_ENDIAN' 2597 Define this if the numbering of bits in the targets does *not* 2598 match the endianness of the target byte order. A value of 1 means 2599 that the bits are numbered in a big-endian bit order, 0 means 2600 little-endian. 2601 2602`BREAKPOINT' 2603 This is the character array initializer for the bit pattern to put 2604 into memory where a breakpoint is set. Although it's common to 2605 use a trap instruction for a breakpoint, it's not required; for 2606 instance, the bit pattern could be an invalid instruction. The 2607 breakpoint must be no longer than the shortest instruction of the 2608 architecture. 2609 2610 `BREAKPOINT' has been deprecated in favor of `BREAKPOINT_FROM_PC'. 2611 2612`BIG_BREAKPOINT' 2613`LITTLE_BREAKPOINT' 2614 Similar to BREAKPOINT, but used for bi-endian targets. 2615 2616 `BIG_BREAKPOINT' and `LITTLE_BREAKPOINT' have been deprecated in 2617 favor of `BREAKPOINT_FROM_PC'. 2618 2619`DEPRECATED_REMOTE_BREAKPOINT' 2620`DEPRECATED_LITTLE_REMOTE_BREAKPOINT' 2621`DEPRECATED_BIG_REMOTE_BREAKPOINT' 2622 Specify the breakpoint instruction sequence for a remote target. 2623 `DEPRECATED_REMOTE_BREAKPOINT', `DEPRECATED_BIG_REMOTE_BREAKPOINT' 2624 and `DEPRECATED_LITTLE_REMOTE_BREAKPOINT' have been deprecated in 2625 favor of `BREAKPOINT_FROM_PC' (*note BREAKPOINT_FROM_PC::). 2626 2627`BREAKPOINT_FROM_PC (PCPTR, LENPTR)' 2628 Use the program counter to determine the contents and size of a 2629 breakpoint instruction. It returns a pointer to a string of bytes 2630 that encode a breakpoint instruction, stores the length of the 2631 string to `*LENPTR', and adjusts the program counter (if 2632 necessary) to point to the actual memory location where the 2633 breakpoint should be inserted. 2634 2635 Although it is common to use a trap instruction for a breakpoint, 2636 it's not required; for instance, the bit pattern could be an 2637 invalid instruction. The breakpoint must be no longer than the 2638 shortest instruction of the architecture. 2639 2640 Replaces all the other BREAKPOINT macros. 2641 2642`MEMORY_INSERT_BREAKPOINT (ADDR, CONTENTS_CACHE)' 2643`MEMORY_REMOVE_BREAKPOINT (ADDR, CONTENTS_CACHE)' 2644 Insert or remove memory based breakpoints. Reasonable defaults 2645 (`default_memory_insert_breakpoint' and 2646 `default_memory_remove_breakpoint' respectively) have been 2647 provided so that it is not necessary to define these for most 2648 architectures. Architectures which may want to define 2649 `MEMORY_INSERT_BREAKPOINT' and `MEMORY_REMOVE_BREAKPOINT' will 2650 likely have instructions that are oddly sized or are not stored in 2651 a conventional manner. 2652 2653 It may also be desirable (from an efficiency standpoint) to define 2654 custom breakpoint insertion and removal routines if 2655 `BREAKPOINT_FROM_PC' needs to read the target's memory for some 2656 reason. 2657 2658`ADJUST_BREAKPOINT_ADDRESS (ADDRESS)' 2659 Given an address at which a breakpoint is desired, return a 2660 breakpoint address adjusted to account for architectural 2661 constraints on breakpoint placement. This method is not needed by 2662 most targets. 2663 2664 The FR-V target (see `frv-tdep.c') requires this method. The FR-V 2665 is a VLIW architecture in which a number of RISC-like instructions 2666 are grouped (packed) together into an aggregate instruction or 2667 instruction bundle. When the processor executes one of these 2668 bundles, the component instructions are executed in parallel. 2669 2670 In the course of optimization, the compiler may group instructions 2671 from distinct source statements into the same bundle. The line 2672 number information associated with one of the latter statements 2673 will likely refer to some instruction other than the first one in 2674 the bundle. So, if the user attempts to place a breakpoint on one 2675 of these latter statements, GDB must be careful to _not_ place the 2676 break instruction on any instruction other than the first one in 2677 the bundle. (Remember though that the instructions within a 2678 bundle execute in parallel, so the _first_ instruction is the 2679 instruction at the lowest address and has nothing to do with 2680 execution order.) 2681 2682 The FR-V's `ADJUST_BREAKPOINT_ADDRESS' method will adjust a 2683 breakpoint's address by scanning backwards for the beginning of 2684 the bundle, returning the address of the bundle. 2685 2686 Since the adjustment of a breakpoint may significantly alter a 2687 user's expectation, GDB prints a warning when an adjusted 2688 breakpoint is initially set and each time that that breakpoint is 2689 hit. 2690 2691`CALL_DUMMY_LOCATION' 2692 See the file `inferior.h'. 2693 2694 This method has been replaced by `push_dummy_code' (*note 2695 push_dummy_code::). 2696 2697`CANNOT_FETCH_REGISTER (REGNO)' 2698 A C expression that should be nonzero if REGNO cannot be fetched 2699 from an inferior process. This is only relevant if 2700 `FETCH_INFERIOR_REGISTERS' is not defined. 2701 2702`CANNOT_STORE_REGISTER (REGNO)' 2703 A C expression that should be nonzero if REGNO should not be 2704 written to the target. This is often the case for program 2705 counters, status words, and other special registers. If this is 2706 not defined, GDB will assume that all registers may be written. 2707 2708`int CONVERT_REGISTER_P(REGNUM)' 2709 Return non-zero if register REGNUM can represent data values in a 2710 non-standard form. *Note Using Different Register and Memory Data 2711 Representations: Target Architecture Definition. 2712 2713`DECR_PC_AFTER_BREAK' 2714 Define this to be the amount by which to decrement the PC after the 2715 program encounters a breakpoint. This is often the number of 2716 bytes in `BREAKPOINT', though not always. For most targets this 2717 value will be 0. 2718 2719`DISABLE_UNSETTABLE_BREAK (ADDR)' 2720 If defined, this should evaluate to 1 if ADDR is in a shared 2721 library in which breakpoints cannot be set and so should be 2722 disabled. 2723 2724`PRINT_FLOAT_INFO()' 2725 If defined, then the `info float' command will print information 2726 about the processor's floating point unit. 2727 2728`print_registers_info (GDBARCH, FRAME, REGNUM, ALL)' 2729 If defined, pretty print the value of the register REGNUM for the 2730 specified FRAME. If the value of REGNUM is -1, pretty print 2731 either all registers (ALL is non zero) or a select subset of 2732 registers (ALL is zero). 2733 2734 The default method prints one register per line, and if ALL is 2735 zero omits floating-point registers. 2736 2737`PRINT_VECTOR_INFO()' 2738 If defined, then the `info vector' command will call this function 2739 to print information about the processor's vector unit. 2740 2741 By default, the `info vector' command will print all vector 2742 registers (the register's type having the vector attribute). 2743 2744`DWARF_REG_TO_REGNUM' 2745 Convert DWARF register number into GDB regnum. If not defined, no 2746 conversion will be performed. 2747 2748`DWARF2_REG_TO_REGNUM' 2749 Convert DWARF2 register number into GDB regnum. If not defined, 2750 no conversion will be performed. 2751 2752`ECOFF_REG_TO_REGNUM' 2753 Convert ECOFF register number into GDB regnum. If not defined, no 2754 conversion will be performed. 2755 2756`END_OF_TEXT_DEFAULT' 2757 This is an expression that should designate the end of the text 2758 section. 2759 2760`EXTRACT_RETURN_VALUE(TYPE, REGBUF, VALBUF)' 2761 Define this to extract a function's return value of type TYPE from 2762 the raw register state REGBUF and copy that, in virtual format, 2763 into VALBUF. 2764 2765 This method has been deprecated in favour of `gdbarch_return_value' 2766 (*note gdbarch_return_value::). 2767 2768`DEPRECATED_EXTRACT_STRUCT_VALUE_ADDRESS(REGBUF)' 2769 When defined, extract from the array REGBUF (containing the raw 2770 register state) the `CORE_ADDR' at which a function should return 2771 its structure value. 2772 2773 *Note gdbarch_return_value::. 2774 2775`DEPRECATED_EXTRACT_STRUCT_VALUE_ADDRESS_P()' 2776 Predicate for `DEPRECATED_EXTRACT_STRUCT_VALUE_ADDRESS'. 2777 2778`DEPRECATED_FP_REGNUM' 2779 If the virtual frame pointer is kept in a register, then define 2780 this macro to be the number (greater than or equal to zero) of 2781 that register. 2782 2783 This should only need to be defined if `DEPRECATED_TARGET_READ_FP' 2784 is not defined. 2785 2786`DEPRECATED_FRAMELESS_FUNCTION_INVOCATION(FI)' 2787 Define this to an expression that returns 1 if the function 2788 invocation represented by FI does not have a stack frame 2789 associated with it. Otherwise return 0. 2790 2791`frame_align (ADDRESS)' 2792 Define this to adjust ADDRESS so that it meets the alignment 2793 requirements for the start of a new stack frame. A stack frame's 2794 alignment requirements are typically stronger than a target 2795 processors stack alignment requirements (*note 2796 DEPRECATED_STACK_ALIGN::). 2797 2798 This function is used to ensure that, when creating a dummy frame, 2799 both the initial stack pointer and (if needed) the address of the 2800 return value are correctly aligned. 2801 2802 Unlike `DEPRECATED_STACK_ALIGN', this function always adjusts the 2803 address in the direction of stack growth. 2804 2805 By default, no frame based stack alignment is performed. 2806 2807`int frame_red_zone_size' 2808 The number of bytes, beyond the innermost-stack-address, reserved 2809 by the ABI. A function is permitted to use this scratch area 2810 (instead of allocating extra stack space). 2811 2812 When performing an inferior function call, to ensure that it does 2813 not modify this area, GDB adjusts the innermost-stack-address by 2814 FRAME_RED_ZONE_SIZE bytes before pushing parameters onto the stack. 2815 2816 By default, zero bytes are allocated. The value must be aligned 2817 (*note frame_align::). 2818 2819 The AMD64 (nee x86-64) ABI documentation refers to the _red zone_ 2820 when describing this scratch area. 2821 2822`DEPRECATED_FRAME_CHAIN(FRAME)' 2823 Given FRAME, return a pointer to the calling frame. 2824 2825`DEPRECATED_FRAME_CHAIN_VALID(CHAIN, THISFRAME)' 2826 Define this to be an expression that returns zero if the given 2827 frame is an outermost frame, with no caller, and nonzero 2828 otherwise. Most normal situations can be handled without defining 2829 this macro, including `NULL' chain pointers, dummy frames, and 2830 frames whose PC values are inside the startup file (e.g. 2831 `crt0.o'), inside `main', or inside `_start'. 2832 2833`DEPRECATED_FRAME_INIT_SAVED_REGS(FRAME)' 2834 See `frame.h'. Determines the address of all registers in the 2835 current stack frame storing each in `frame->saved_regs'. Space for 2836 `frame->saved_regs' shall be allocated by 2837 `DEPRECATED_FRAME_INIT_SAVED_REGS' using `frame_saved_regs_zalloc'. 2838 2839 `FRAME_FIND_SAVED_REGS' is deprecated. 2840 2841`FRAME_NUM_ARGS (FI)' 2842 For the frame described by FI return the number of arguments that 2843 are being passed. If the number of arguments is not known, return 2844 `-1'. 2845 2846`DEPRECATED_FRAME_SAVED_PC(FRAME)' 2847 Given FRAME, return the pc saved there. This is the return 2848 address. 2849 2850 This method is deprecated. *Note unwind_pc::. 2851 2852`CORE_ADDR unwind_pc (struct frame_info *THIS_FRAME)' 2853 Return the instruction address, in THIS_FRAME's caller, at which 2854 execution will resume after THIS_FRAME returns. This is commonly 2855 refered to as the return address. 2856 2857 The implementation, which must be frame agnostic (work with any 2858 frame), is typically no more than: 2859 2860 ULONGEST pc; 2861 frame_unwind_unsigned_register (this_frame, D10V_PC_REGNUM, &pc); 2862 return d10v_make_iaddr (pc); 2863 2864 *Note DEPRECATED_FRAME_SAVED_PC::, which this method replaces. 2865 2866`CORE_ADDR unwind_sp (struct frame_info *THIS_FRAME)' 2867 Return the frame's inner most stack address. This is commonly 2868 refered to as the frame's "stack pointer". 2869 2870 The implementation, which must be frame agnostic (work with any 2871 frame), is typically no more than: 2872 2873 ULONGEST sp; 2874 frame_unwind_unsigned_register (this_frame, D10V_SP_REGNUM, &sp); 2875 return d10v_make_daddr (sp); 2876 2877 *Note TARGET_READ_SP::, which this method replaces. 2878 2879`FUNCTION_EPILOGUE_SIZE' 2880 For some COFF targets, the `x_sym.x_misc.x_fsize' field of the 2881 function end symbol is 0. For such targets, you must define 2882 `FUNCTION_EPILOGUE_SIZE' to expand into the standard size of a 2883 function's epilogue. 2884 2885`DEPRECATED_FUNCTION_START_OFFSET' 2886 An integer, giving the offset in bytes from a function's address 2887 (as used in the values of symbols, function pointers, etc.), and 2888 the function's first genuine instruction. 2889 2890 This is zero on almost all machines: the function's address is 2891 usually the address of its first instruction. However, on the 2892 VAX, for example, each function starts with two bytes containing a 2893 bitmask indicating which registers to save upon entry to the 2894 function. The VAX `call' instructions check this value, and save 2895 the appropriate registers automatically. Thus, since the offset 2896 from the function's address to its first instruction is two bytes, 2897 `DEPRECATED_FUNCTION_START_OFFSET' would be 2 on the VAX. 2898 2899`GCC_COMPILED_FLAG_SYMBOL' 2900`GCC2_COMPILED_FLAG_SYMBOL' 2901 If defined, these are the names of the symbols that GDB will look 2902 for to detect that GCC compiled the file. The default symbols are 2903 `gcc_compiled.' and `gcc2_compiled.', respectively. (Currently 2904 only defined for the Delta 68.) 2905 2906`GDB_MULTI_ARCH' 2907 If defined and non-zero, enables support for multiple architectures 2908 within GDB. 2909 2910 This support can be enabled at two levels. At level one, only 2911 definitions for previously undefined macros are provided; at level 2912 two, a multi-arch definition of all architecture dependent macros 2913 will be defined. 2914 2915`GDB_TARGET_IS_HPPA' 2916 This determines whether horrible kludge code in `dbxread.c' and 2917 `partial-stab.h' is used to mangle multiple-symbol-table files from 2918 HPPA's. This should all be ripped out, and a scheme like 2919 `elfread.c' used instead. 2920 2921`GET_LONGJMP_TARGET' 2922 For most machines, this is a target-dependent parameter. On the 2923 DECstation and the Iris, this is a native-dependent parameter, 2924 since the header file `setjmp.h' is needed to define it. 2925 2926 This macro determines the target PC address that `longjmp' will 2927 jump to, assuming that we have just stopped at a `longjmp' 2928 breakpoint. It takes a `CORE_ADDR *' as argument, and stores the 2929 target PC value through this pointer. It examines the current 2930 state of the machine as needed. 2931 2932`DEPRECATED_GET_SAVED_REGISTER' 2933 Define this if you need to supply your own definition for the 2934 function `DEPRECATED_GET_SAVED_REGISTER'. 2935 2936`DEPRECATED_IBM6000_TARGET' 2937 Shows that we are configured for an IBM RS/6000 system. This 2938 conditional should be eliminated (FIXME) and replaced by 2939 feature-specific macros. It was introduced in a haste and we are 2940 repenting at leisure. 2941 2942`I386_USE_GENERIC_WATCHPOINTS' 2943 An x86-based target can define this to use the generic x86 2944 watchpoint support; see *Note I386_USE_GENERIC_WATCHPOINTS: 2945 Algorithms. 2946 2947`SYMBOLS_CAN_START_WITH_DOLLAR' 2948 Some systems have routines whose names start with `$'. Giving this 2949 macro a non-zero value tells GDB's expression parser to check for 2950 such routines when parsing tokens that begin with `$'. 2951 2952 On HP-UX, certain system routines (millicode) have names beginning 2953 with `$' or `$$'. For example, `$$dyncall' is a millicode routine 2954 that handles inter-space procedure calls on PA-RISC. 2955 2956`DEPRECATED_INIT_EXTRA_FRAME_INFO (FROMLEAF, FRAME)' 2957 If additional information about the frame is required this should 2958 be stored in `frame->extra_info'. Space for `frame->extra_info' 2959 is allocated using `frame_extra_info_zalloc'. 2960 2961`DEPRECATED_INIT_FRAME_PC (FROMLEAF, PREV)' 2962 This is a C statement that sets the pc of the frame pointed to by 2963 PREV. [By default...] 2964 2965`INNER_THAN (LHS, RHS)' 2966 Returns non-zero if stack address LHS is inner than (nearer to the 2967 stack top) stack address RHS. Define this as `lhs < rhs' if the 2968 target's stack grows downward in memory, or `lhs > rsh' if the 2969 stack grows upward. 2970 2971`gdbarch_in_function_epilogue_p (GDBARCH, PC)' 2972 Returns non-zero if the given PC is in the epilogue of a function. 2973 The epilogue of a function is defined as the part of a function 2974 where the stack frame of the function already has been destroyed 2975 up to the final `return from function call' instruction. 2976 2977`DEPRECATED_SIGTRAMP_START (PC)' 2978`DEPRECATED_SIGTRAMP_END (PC)' 2979 Define these to be the start and end address of the `sigtramp' for 2980 the given PC. On machines where the address is just a compile time 2981 constant, the macro expansion will typically just ignore the 2982 supplied PC. 2983 2984`IN_SOLIB_CALL_TRAMPOLINE (PC, NAME)' 2985 Define this to evaluate to nonzero if the program is stopped in the 2986 trampoline that connects to a shared library. 2987 2988`IN_SOLIB_RETURN_TRAMPOLINE (PC, NAME)' 2989 Define this to evaluate to nonzero if the program is stopped in the 2990 trampoline that returns from a shared library. 2991 2992`IN_SOLIB_DYNSYM_RESOLVE_CODE (PC)' 2993 Define this to evaluate to nonzero if the program is stopped in the 2994 dynamic linker. 2995 2996`SKIP_SOLIB_RESOLVER (PC)' 2997 Define this to evaluate to the (nonzero) address at which execution 2998 should continue to get past the dynamic linker's symbol resolution 2999 function. A zero value indicates that it is not important or 3000 necessary to set a breakpoint to get through the dynamic linker 3001 and that single stepping will suffice. 3002 3003`INTEGER_TO_ADDRESS (TYPE, BUF)' 3004 Define this when the architecture needs to handle non-pointer to 3005 address conversions specially. Converts that value to an address 3006 according to the current architectures conventions. 3007 3008 _Pragmatics: When the user copies a well defined expression from 3009 their source code and passes it, as a parameter, to GDB's `print' 3010 command, they should get the same value as would have been 3011 computed by the target program. Any deviation from this rule can 3012 cause major confusion and annoyance, and needs to be justified 3013 carefully. In other words, GDB doesn't really have the freedom to 3014 do these conversions in clever and useful ways. It has, however, 3015 been pointed out that users aren't complaining about how GDB casts 3016 integers to pointers; they are complaining that they can't take an 3017 address from a disassembly listing and give it to `x/i'. Adding 3018 an architecture method like `INTEGER_TO_ADDRESS' certainly makes 3019 it possible for GDB to "get it right" in all circumstances._ 3020 3021 *Note Pointers Are Not Always Addresses: Target Architecture 3022 Definition. 3023 3024`NO_HIF_SUPPORT' 3025 (Specific to the a29k.) 3026 3027`POINTER_TO_ADDRESS (TYPE, BUF)' 3028 Assume that BUF holds a pointer of type TYPE, in the appropriate 3029 format for the current architecture. Return the byte address the 3030 pointer refers to. *Note Pointers Are Not Always Addresses: 3031 Target Architecture Definition. 3032 3033`REGISTER_CONVERTIBLE (REG)' 3034 Return non-zero if REG uses different raw and virtual formats. 3035 *Note Raw and Virtual Register Representations: Target 3036 Architecture Definition. 3037 3038`REGISTER_TO_VALUE(REGNUM, TYPE, FROM, TO)' 3039 Convert the raw contents of register REGNUM into a value of type 3040 TYPE. *Note Using Different Register and Memory Data 3041 Representations: Target Architecture Definition. 3042 3043`DEPRECATED_REGISTER_RAW_SIZE (REG)' 3044 Return the raw size of REG; defaults to the size of the register's 3045 virtual type. *Note Raw and Virtual Register Representations: 3046 Target Architecture Definition. 3047 3048`register_reggroup_p (GDBARCH, REGNUM, REGGROUP)' 3049 Return non-zero if register REGNUM is a member of the register 3050 group REGGROUP. 3051 3052 By default, registers are grouped as follows: 3053 3054 `float_reggroup' 3055 Any register with a valid name and a floating-point type. 3056 3057 `vector_reggroup' 3058 Any register with a valid name and a vector type. 3059 3060 `general_reggroup' 3061 Any register with a valid name and a type other than vector or 3062 floating-point. `float_reggroup'. 3063 3064 `save_reggroup' 3065 `restore_reggroup' 3066 `all_reggroup' 3067 Any register with a valid name. 3068 3069`DEPRECATED_REGISTER_VIRTUAL_SIZE (REG)' 3070 Return the virtual size of REG; defaults to the size of the 3071 register's virtual type. Return the virtual size of REG. *Note 3072 Raw and Virtual Register Representations: Target Architecture 3073 Definition. 3074 3075`DEPRECATED_REGISTER_VIRTUAL_TYPE (REG)' 3076 Return the virtual type of REG. *Note Raw and Virtual Register 3077 Representations: Target Architecture Definition. 3078 3079`struct type *register_type (GDBARCH, REG)' 3080 If defined, return the type of register REG. This function 3081 superseeds `DEPRECATED_REGISTER_VIRTUAL_TYPE'. *Note Raw and 3082 Virtual Register Representations: Target Architecture Definition. 3083 3084`REGISTER_CONVERT_TO_VIRTUAL(REG, TYPE, FROM, TO)' 3085 Convert the value of register REG from its raw form to its virtual 3086 form. *Note Raw and Virtual Register Representations: Target 3087 Architecture Definition. 3088 3089`REGISTER_CONVERT_TO_RAW(TYPE, REG, FROM, TO)' 3090 Convert the value of register REG from its virtual form to its raw 3091 form. *Note Raw and Virtual Register Representations: Target 3092 Architecture Definition. 3093 3094`const struct regset *regset_from_core_section (struct gdbarch * GDBARCH, const char * SECT_NAME, size_t SECT_SIZE)' 3095 Return the appropriate register set for a core file section with 3096 name SECT_NAME and size SECT_SIZE. 3097 3098`SOFTWARE_SINGLE_STEP_P()' 3099 Define this as 1 if the target does not have a hardware single-step 3100 mechanism. The macro `SOFTWARE_SINGLE_STEP' must also be defined. 3101 3102`SOFTWARE_SINGLE_STEP(SIGNAL, INSERT_BREAPOINTS_P)' 3103 A function that inserts or removes (depending on 3104 INSERT_BREAPOINTS_P) breakpoints at each possible destinations of 3105 the next instruction. See `sparc-tdep.c' and `rs6000-tdep.c' for 3106 examples. 3107 3108`SOFUN_ADDRESS_MAYBE_MISSING' 3109 Somebody clever observed that, the more actual addresses you have 3110 in the debug information, the more time the linker has to spend 3111 relocating them. So whenever there's some other way the debugger 3112 could find the address it needs, you should omit it from the debug 3113 info, to make linking faster. 3114 3115 `SOFUN_ADDRESS_MAYBE_MISSING' indicates that a particular set of 3116 hacks of this sort are in use, affecting `N_SO' and `N_FUN' 3117 entries in stabs-format debugging information. `N_SO' stabs mark 3118 the beginning and ending addresses of compilation units in the text 3119 segment. `N_FUN' stabs mark the starts and ends of functions. 3120 3121 `SOFUN_ADDRESS_MAYBE_MISSING' means two things: 3122 3123 * `N_FUN' stabs have an address of zero. Instead, you should 3124 find the addresses where the function starts by taking the 3125 function name from the stab, and then looking that up in the 3126 minsyms (the linker/assembler symbol table). In other words, 3127 the stab has the name, and the linker/assembler symbol table 3128 is the only place that carries the address. 3129 3130 * `N_SO' stabs have an address of zero, too. You just look at 3131 the `N_FUN' stabs that appear before and after the `N_SO' 3132 stab, and guess the starting and ending addresses of the 3133 compilation unit from them. 3134 3135`PC_LOAD_SEGMENT' 3136 If defined, print information about the load segment for the 3137 program counter. (Defined only for the RS/6000.) 3138 3139`PC_REGNUM' 3140 If the program counter is kept in a register, then define this 3141 macro to be the number (greater than or equal to zero) of that 3142 register. 3143 3144 This should only need to be defined if `TARGET_READ_PC' and 3145 `TARGET_WRITE_PC' are not defined. 3146 3147`PARM_BOUNDARY' 3148 If non-zero, round arguments to a boundary of this many bits before 3149 pushing them on the stack. 3150 3151`stabs_argument_has_addr (GDBARCH, TYPE)' 3152 Define this to return nonzero if a function argument of type TYPE 3153 is passed by reference instead of value. 3154 3155 This method replaces `DEPRECATED_REG_STRUCT_HAS_ADDR' (*note 3156 DEPRECATED_REG_STRUCT_HAS_ADDR::). 3157 3158`PROCESS_LINENUMBER_HOOK' 3159 A hook defined for XCOFF reading. 3160 3161`PROLOGUE_FIRSTLINE_OVERLAP' 3162 (Only used in unsupported Convex configuration.) 3163 3164`PS_REGNUM' 3165 If defined, this is the number of the processor status register. 3166 (This definition is only used in generic code when parsing "$ps".) 3167 3168`DEPRECATED_POP_FRAME' 3169 If defined, used by `frame_pop' to remove a stack frame. This 3170 method has been superseeded by generic code. 3171 3172`push_dummy_call (GDBARCH, FUNCTION, REGCACHE, PC_ADDR, NARGS, ARGS, SP, STRUCT_RETURN, STRUCT_ADDR)' 3173 Define this to push the dummy frame's call to the inferior 3174 function onto the stack. In addition to pushing NARGS, the code 3175 should push STRUCT_ADDR (when STRUCT_RETURN), and the return 3176 address (BP_ADDR). 3177 3178 FUNCTION is a pointer to a `struct value'; on architectures that 3179 use function descriptors, this contains the function descriptor 3180 value. 3181 3182 Returns the updated top-of-stack pointer. 3183 3184 This method replaces `DEPRECATED_PUSH_ARGUMENTS'. 3185 3186`CORE_ADDR push_dummy_code (GDBARCH, SP, FUNADDR, USING_GCC, ARGS, NARGS, VALUE_TYPE, REAL_PC, BP_ADDR)' 3187 Given a stack based call dummy, push the instruction sequence 3188 (including space for a breakpoint) to which the called function 3189 should return. 3190 3191 Set BP_ADDR to the address at which the breakpoint instruction 3192 should be inserted, REAL_PC to the resume address when starting 3193 the call sequence, and return the updated inner-most stack address. 3194 3195 By default, the stack is grown sufficient to hold a frame-aligned 3196 (*note frame_align::) breakpoint, BP_ADDR is set to the address 3197 reserved for that breakpoint, and REAL_PC set to FUNADDR. 3198 3199 This method replaces `CALL_DUMMY_LOCATION', 3200 `DEPRECATED_REGISTER_SIZE'. 3201 3202`DEPRECATED_REGISTER_BYTES' 3203 The total amount of space needed to store GDB's copy of the 3204 machine's register state. 3205 3206 This is no longer needed. GDB instead computes the size of the 3207 register buffer at run-time. 3208 3209`REGISTER_NAME(I)' 3210 Return the name of register I as a string. May return `NULL' or 3211 `NUL' to indicate that register I is not valid. 3212 3213`DEPRECATED_REG_STRUCT_HAS_ADDR (GCC_P, TYPE)' 3214 Define this to return 1 if the given type will be passed by 3215 pointer rather than directly. 3216 3217 This method has been replaced by `stabs_argument_has_addr' (*note 3218 stabs_argument_has_addr::). 3219 3220`SAVE_DUMMY_FRAME_TOS (SP)' 3221 Used in `call_function_by_hand' to notify the target dependent 3222 code of the top-of-stack value that will be passed to the the 3223 inferior code. This is the value of the `SP' after both the dummy 3224 frame and space for parameters/results have been allocated on the 3225 stack. *Note unwind_dummy_id::. 3226 3227`SDB_REG_TO_REGNUM' 3228 Define this to convert sdb register numbers into GDB regnums. If 3229 not defined, no conversion will be done. 3230 3231`enum return_value_convention gdbarch_return_value (struct gdbarch *GDBARCH, struct type *VALTYPE, struct regcache *REGCACHE, void *READBUF, const void *WRITEBUF)' 3232 Given a function with a return-value of type RETTYPE, return which 3233 return-value convention that function would use. 3234 3235 GDB currently recognizes two function return-value conventions: 3236 `RETURN_VALUE_REGISTER_CONVENTION' where the return value is found 3237 in registers; and `RETURN_VALUE_STRUCT_CONVENTION' where the return 3238 value is found in memory and the address of that memory location is 3239 passed in as the function's first parameter. 3240 3241 If the register convention is being used, and WRITEBUF is 3242 non-`NULL', also copy the return-value in WRITEBUF into REGCACHE. 3243 3244 If the register convention is being used, and READBUF is 3245 non-`NULL', also copy the return value from REGCACHE into READBUF 3246 (REGCACHE contains a copy of the registers from the just returned 3247 function). 3248 3249 *Note DEPRECATED_EXTRACT_STRUCT_VALUE_ADDRESS::, for a description 3250 of how return-values that use the struct convention are handled. 3251 3252 _Maintainer note: This method replaces separate predicate, extract, 3253 store methods. By having only one method, the logic needed to 3254 determine the return-value convention need only be implemented in 3255 one place. If GDB were written in an OO language, this method 3256 would instead return an object that knew how to perform the 3257 register return-value extract and store._ 3258 3259 _Maintainer note: This method does not take a GCC_P parameter, and 3260 such a parameter should not be added. If an architecture that 3261 requires per-compiler or per-function information be identified, 3262 then the replacement of RETTYPE with `struct value' FUNCTION 3263 should be persued._ 3264 3265 _Maintainer note: The REGCACHE parameter limits this methods to 3266 the inner most frame. While replacing REGCACHE with a `struct 3267 frame_info' FRAME parameter would remove that limitation there has 3268 yet to be a demonstrated need for such a change._ 3269 3270`SKIP_PERMANENT_BREAKPOINT' 3271 Advance the inferior's PC past a permanent breakpoint. GDB 3272 normally steps over a breakpoint by removing it, stepping one 3273 instruction, and re-inserting the breakpoint. However, permanent 3274 breakpoints are hardwired into the inferior, and can't be removed, 3275 so this strategy doesn't work. Calling 3276 `SKIP_PERMANENT_BREAKPOINT' adjusts the processor's state so that 3277 execution will resume just after the breakpoint. This macro does 3278 the right thing even when the breakpoint is in the delay slot of a 3279 branch or jump. 3280 3281`SKIP_PROLOGUE (PC)' 3282 A C expression that returns the address of the "real" code beyond 3283 the function entry prologue found at PC. 3284 3285`SKIP_TRAMPOLINE_CODE (PC)' 3286 If the target machine has trampoline code that sits between 3287 callers and the functions being called, then define this macro to 3288 return a new PC that is at the start of the real function. 3289 3290`SP_REGNUM' 3291 If the stack-pointer is kept in a register, then define this macro 3292 to be the number (greater than or equal to zero) of that register, 3293 or -1 if there is no such register. 3294 3295`STAB_REG_TO_REGNUM' 3296 Define this to convert stab register numbers (as gotten from `r' 3297 declarations) into GDB regnums. If not defined, no conversion 3298 will be done. 3299 3300`DEPRECATED_STACK_ALIGN (ADDR)' 3301 Define this to increase ADDR so that it meets the alignment 3302 requirements for the processor's stack. 3303 3304 Unlike *Note frame_align::, this function always adjusts ADDR 3305 upwards. 3306 3307 By default, no stack alignment is performed. 3308 3309`STEP_SKIPS_DELAY (ADDR)' 3310 Define this to return true if the address is of an instruction 3311 with a delay slot. If a breakpoint has been placed in the 3312 instruction's delay slot, GDB will single-step over that 3313 instruction before resuming normally. Currently only defined for 3314 the Mips. 3315 3316`STORE_RETURN_VALUE (TYPE, REGCACHE, VALBUF)' 3317 A C expression that writes the function return value, found in 3318 VALBUF, into the REGCACHE. TYPE is the type of the value that is 3319 to be returned. 3320 3321 This method has been deprecated in favour of `gdbarch_return_value' 3322 (*note gdbarch_return_value::). 3323 3324`SYMBOL_RELOADING_DEFAULT' 3325 The default value of the "symbol-reloading" variable. (Never 3326 defined in current sources.) 3327 3328`TARGET_CHAR_BIT' 3329 Number of bits in a char; defaults to 8. 3330 3331`TARGET_CHAR_SIGNED' 3332 Non-zero if `char' is normally signed on this architecture; zero if 3333 it should be unsigned. 3334 3335 The ISO C standard requires the compiler to treat `char' as 3336 equivalent to either `signed char' or `unsigned char'; any 3337 character in the standard execution set is supposed to be positive. 3338 Most compilers treat `char' as signed, but `char' is unsigned on 3339 the IBM S/390, RS6000, and PowerPC targets. 3340 3341`TARGET_COMPLEX_BIT' 3342 Number of bits in a complex number; defaults to `2 * 3343 TARGET_FLOAT_BIT'. 3344 3345 At present this macro is not used. 3346 3347`TARGET_DOUBLE_BIT' 3348 Number of bits in a double float; defaults to `8 * 3349 TARGET_CHAR_BIT'. 3350 3351`TARGET_DOUBLE_COMPLEX_BIT' 3352 Number of bits in a double complex; defaults to `2 * 3353 TARGET_DOUBLE_BIT'. 3354 3355 At present this macro is not used. 3356 3357`TARGET_FLOAT_BIT' 3358 Number of bits in a float; defaults to `4 * TARGET_CHAR_BIT'. 3359 3360`TARGET_INT_BIT' 3361 Number of bits in an integer; defaults to `4 * TARGET_CHAR_BIT'. 3362 3363`TARGET_LONG_BIT' 3364 Number of bits in a long integer; defaults to `4 * 3365 TARGET_CHAR_BIT'. 3366 3367`TARGET_LONG_DOUBLE_BIT' 3368 Number of bits in a long double float; defaults to `2 * 3369 TARGET_DOUBLE_BIT'. 3370 3371`TARGET_LONG_LONG_BIT' 3372 Number of bits in a long long integer; defaults to `2 * 3373 TARGET_LONG_BIT'. 3374 3375`TARGET_PTR_BIT' 3376 Number of bits in a pointer; defaults to `TARGET_INT_BIT'. 3377 3378`TARGET_SHORT_BIT' 3379 Number of bits in a short integer; defaults to `2 * 3380 TARGET_CHAR_BIT'. 3381 3382`TARGET_READ_PC' 3383`TARGET_WRITE_PC (VAL, PID)' 3384`TARGET_READ_SP' 3385`TARGET_READ_FP' 3386 These change the behavior of `read_pc', `write_pc', `read_sp' and 3387 `deprecated_read_fp'. For most targets, these may be left 3388 undefined. GDB will call the read and write register functions 3389 with the relevant `_REGNUM' argument. 3390 3391 These macros are useful when a target keeps one of these registers 3392 in a hard to get at place; for example, part in a segment register 3393 and part in an ordinary register. 3394 3395 *Note unwind_sp::, which replaces `TARGET_READ_SP'. 3396 3397`TARGET_VIRTUAL_FRAME_POINTER(PC, REGP, OFFSETP)' 3398 Returns a `(register, offset)' pair representing the virtual frame 3399 pointer in use at the code address PC. If virtual frame pointers 3400 are not used, a default definition simply returns 3401 `DEPRECATED_FP_REGNUM', with an offset of zero. 3402 3403`TARGET_HAS_HARDWARE_WATCHPOINTS' 3404 If non-zero, the target has support for hardware-assisted 3405 watchpoints. *Note watchpoints: Algorithms, for more details and 3406 other related macros. 3407 3408`TARGET_PRINT_INSN (ADDR, INFO)' 3409 This is the function used by GDB to print an assembly instruction. 3410 It prints the instruction at address ADDR in debugged memory and 3411 returns the length of the instruction, in bytes. If a target 3412 doesn't define its own printing routine, it defaults to an 3413 accessor function for the global pointer 3414 `deprecated_tm_print_insn'. This usually points to a function in 3415 the `opcodes' library (*note Opcodes: Support Libraries.). INFO 3416 is a structure (of type `disassemble_info') defined in 3417 `include/dis-asm.h' used to pass information to the instruction 3418 decoding routine. 3419 3420`struct frame_id unwind_dummy_id (struct frame_info *FRAME)' 3421 Given FRAME return a `struct frame_id' that uniquely identifies an 3422 inferior function call's dummy frame. The value returned must 3423 match the dummy frame stack value previously saved using 3424 `SAVE_DUMMY_FRAME_TOS'. *Note SAVE_DUMMY_FRAME_TOS::. 3425 3426`DEPRECATED_USE_STRUCT_CONVENTION (GCC_P, TYPE)' 3427 If defined, this must be an expression that is nonzero if a value 3428 of the given TYPE being returned from a function must have space 3429 allocated for it on the stack. GCC_P is true if the function 3430 being considered is known to have been compiled by GCC; this is 3431 helpful for systems where GCC is known to use different calling 3432 convention than other compilers. 3433 3434 This method has been deprecated in favour of `gdbarch_return_value' 3435 (*note gdbarch_return_value::). 3436 3437`VALUE_TO_REGISTER(TYPE, REGNUM, FROM, TO)' 3438 Convert a value of type TYPE into the raw contents of register 3439 REGNUM's. *Note Using Different Register and Memory Data 3440 Representations: Target Architecture Definition. 3441 3442`VARIABLES_INSIDE_BLOCK (DESC, GCC_P)' 3443 For dbx-style debugging information, if the compiler puts variable 3444 declarations inside LBRAC/RBRAC blocks, this should be defined to 3445 be nonzero. DESC is the value of `n_desc' from the `N_RBRAC' 3446 symbol, and GCC_P is true if GDB has noticed the presence of 3447 either the `GCC_COMPILED_SYMBOL' or the `GCC2_COMPILED_SYMBOL'. 3448 By default, this is 0. 3449 3450`OS9K_VARIABLES_INSIDE_BLOCK (DESC, GCC_P)' 3451 Similarly, for OS/9000. Defaults to 1. 3452 3453 Motorola M68K target conditionals. 3454 3455`BPT_VECTOR' 3456 Define this to be the 4-bit location of the breakpoint trap 3457 vector. If not defined, it will default to `0xf'. 3458 3459`REMOTE_BPT_VECTOR' 3460 Defaults to `1'. 3461 3462`NAME_OF_MALLOC' 3463 A string containing the name of the function to call in order to 3464 allocate some memory in the inferior. The default value is 3465 "malloc". 3466 3467 3468Adding a New Target 3469=================== 3470 3471The following files add a target to GDB: 3472 3473`gdb/config/ARCH/TTT.mt' 3474 Contains a Makefile fragment specific to this target. Specifies 3475 what object files are needed for target TTT, by defining 3476 `TDEPFILES=...' and `TDEPLIBS=...'. Also specifies the header 3477 file which describes TTT, by defining `TM_FILE= tm-TTT.h'. 3478 3479 You can also define `TM_CFLAGS', `TM_CLIBS', `TM_CDEPS', but these 3480 are now deprecated, replaced by autoconf, and may go away in 3481 future versions of GDB. 3482 3483`gdb/TTT-tdep.c' 3484 Contains any miscellaneous code required for this target machine. 3485 On some machines it doesn't exist at all. Sometimes the macros in 3486 `tm-TTT.h' become very complicated, so they are implemented as 3487 functions here instead, and the macro is simply defined to call the 3488 function. This is vastly preferable, since it is easier to 3489 understand and debug. 3490 3491`gdb/ARCH-tdep.c' 3492`gdb/ARCH-tdep.h' 3493 This often exists to describe the basic layout of the target 3494 machine's processor chip (registers, stack, etc.). If used, it is 3495 included by `TTT-tdep.h'. It can be shared among many targets 3496 that use the same processor. 3497 3498`gdb/config/ARCH/tm-TTT.h' 3499 (`tm.h' is a link to this file, created by `configure'). Contains 3500 macro definitions about the target machine's registers, stack frame 3501 format and instructions. 3502 3503 New targets do not need this file and should not create it. 3504 3505`gdb/config/ARCH/tm-ARCH.h' 3506 This often exists to describe the basic layout of the target 3507 machine's processor chip (registers, stack, etc.). If used, it is 3508 included by `tm-TTT.h'. It can be shared among many targets that 3509 use the same processor. 3510 3511 New targets do not need this file and should not create it. 3512 3513 3514 If you are adding a new operating system for an existing CPU chip, 3515add a `config/tm-OS.h' file that describes the operating system 3516facilities that are unusual (extra symbol table info; the breakpoint 3517instruction needed; etc.). Then write a `ARCH/tm-OS.h' that just 3518`#include's `tm-ARCH.h' and `config/tm-OS.h'. 3519 3520Converting an existing Target Architecture to Multi-arch 3521======================================================== 3522 3523This section describes the current accepted best practice for converting 3524an existing target architecture to the multi-arch framework. 3525 3526 The process consists of generating, testing, posting and committing a 3527sequence of patches. Each patch must contain a single change, for 3528instance: 3529 3530 * Directly convert a group of functions into macros (the conversion 3531 does not change the behavior of any of the functions). 3532 3533 * Replace a non-multi-arch with a multi-arch mechanism (e.g., 3534 `FRAME_INFO'). 3535 3536 * Enable multi-arch level one. 3537 3538 * Delete one or more files. 3539 3540 3541There isn't a size limit on a patch, however, a developer is strongly 3542encouraged to keep the patch size down. 3543 3544 Since each patch is well defined, and since each change has been 3545tested and shows no regressions, the patches are considered _fairly_ 3546obvious. Such patches, when submitted by developers listed in the 3547`MAINTAINERS' file, do not need approval. Occasional steps in the 3548process may be more complicated and less clear. The developer is 3549expected to use their judgment and is encouraged to seek advice as 3550needed. 3551 3552Preparation 3553----------- 3554 3555The first step is to establish control. Build (with `-Werror' enabled) 3556and test the target so that there is a baseline against which the 3557debugger can be compared. 3558 3559 At no stage can the test results regress or GDB stop compiling with 3560`-Werror'. 3561 3562Add the multi-arch initialization code 3563-------------------------------------- 3564 3565The objective of this step is to establish the basic multi-arch 3566framework. It involves 3567 3568 * The addition of a `ARCH_gdbarch_init' function(2) that creates the 3569 architecture: 3570 static struct gdbarch * 3571 d10v_gdbarch_init (info, arches) 3572 struct gdbarch_info info; 3573 struct gdbarch_list *arches; 3574 { 3575 struct gdbarch *gdbarch; 3576 /* there is only one d10v architecture */ 3577 if (arches != NULL) 3578 return arches->gdbarch; 3579 gdbarch = gdbarch_alloc (&info, NULL); 3580 return gdbarch; 3581 } 3582 3583 __ 3584 3585 * A per-architecture dump function to print any architecture specific 3586 information: 3587 static void 3588 mips_dump_tdep (struct gdbarch *current_gdbarch, 3589 struct ui_file *file) 3590 { 3591 ... code to print architecture specific info ... 3592 } 3593 3594 * A change to `_initialize_ARCH_tdep' to register this new 3595 architecture: 3596 void 3597 _initialize_mips_tdep (void) 3598 { 3599 gdbarch_register (bfd_arch_mips, mips_gdbarch_init, 3600 mips_dump_tdep); 3601 3602 * Add the macro `GDB_MULTI_ARCH', defined as 0 (zero), to the file 3603 `config/ARCH/tm-ARCH.h'. 3604 3605 3606Update multi-arch incompatible mechanisms 3607----------------------------------------- 3608 3609Some mechanisms do not work with multi-arch. They include: 3610 3611`FRAME_FIND_SAVED_REGS' 3612 Replaced with `DEPRECATED_FRAME_INIT_SAVED_REGS' 3613 3614At this stage you could also consider converting the macros into 3615functions. 3616 3617Prepare for multi-arch level to one 3618----------------------------------- 3619 3620Temporally set `GDB_MULTI_ARCH' to `GDB_MULTI_ARCH_PARTIAL' and then 3621build and start GDB (the change should not be committed). GDB may not 3622build, and once built, it may die with an internal error listing the 3623architecture methods that must be provided. 3624 3625 Fix any build problems (patch(es)). 3626 3627 Convert all the architecture methods listed, which are only macros, 3628into functions (patch(es)). 3629 3630 Update `ARCH_gdbarch_init' to set all the missing architecture 3631methods and wrap the corresponding macros in `#if !GDB_MULTI_ARCH' 3632(patch(es)). 3633 3634Set multi-arch level one 3635------------------------ 3636 3637Change the value of `GDB_MULTI_ARCH' to GDB_MULTI_ARCH_PARTIAL (a 3638single patch). 3639 3640 Any problems with throwing "the switch" should have been fixed 3641already. 3642 3643Convert remaining macros 3644------------------------ 3645 3646Suggest converting macros into functions (and setting the corresponding 3647architecture method) in small batches. 3648 3649Set multi-arch level to two 3650--------------------------- 3651 3652This should go smoothly. 3653 3654Delete the TM file 3655------------------ 3656 3657The `tm-ARCH.h' can be deleted. `ARCH.mt' and `configure.in' updated. 3658 3659 ---------- Footnotes ---------- 3660 3661 (1) Some D10V instructions are actually pairs of 16-bit 3662sub-instructions. However, since you can't jump into the middle of 3663such a pair, code addresses can only refer to full 32 bit instructions, 3664which is what matters in this explanation. 3665 3666 (2) The above is from the original example and uses K&R C. GDB has 3667since converted to ISO C but lets ignore that. 3668 3669 3670File: gdbint.info, Node: Target Vector Definition, Next: Native Debugging, Prev: Target Architecture Definition, Up: Top 3671 3672Target Vector Definition 3673************************ 3674 3675The target vector defines the interface between GDB's abstract handling 3676of target systems, and the nitty-gritty code that actually exercises 3677control over a process or a serial port. GDB includes some 30-40 3678different target vectors; however, each configuration of GDB includes 3679only a few of them. 3680 3681File Targets 3682============ 3683 3684Both executables and core files have target vectors. 3685 3686Standard Protocol and Remote Stubs 3687================================== 3688 3689GDB's file `remote.c' talks a serial protocol to code that runs in the 3690target system. GDB provides several sample "stubs" that can be 3691integrated into target programs or operating systems for this purpose; 3692they are named `*-stub.c'. 3693 3694 The GDB user's manual describes how to put such a stub into your 3695target code. What follows is a discussion of integrating the SPARC 3696stub into a complicated operating system (rather than a simple 3697program), by Stu Grossman, the author of this stub. 3698 3699 The trap handling code in the stub assumes the following upon entry 3700to `trap_low': 3701 3702 1. %l1 and %l2 contain pc and npc respectively at the time of the 3703 trap; 3704 3705 2. traps are disabled; 3706 3707 3. you are in the correct trap window. 3708 3709 As long as your trap handler can guarantee those conditions, then 3710there is no reason why you shouldn't be able to "share" traps with the 3711stub. The stub has no requirement that it be jumped to directly from 3712the hardware trap vector. That is why it calls `exceptionHandler()', 3713which is provided by the external environment. For instance, this could 3714set up the hardware traps to actually execute code which calls the stub 3715first, and then transfers to its own trap handler. 3716 3717 For the most point, there probably won't be much of an issue with 3718"sharing" traps, as the traps we use are usually not used by the kernel, 3719and often indicate unrecoverable error conditions. Anyway, this is all 3720controlled by a table, and is trivial to modify. The most important 3721trap for us is for `ta 1'. Without that, we can't single step or do 3722breakpoints. Everything else is unnecessary for the proper operation 3723of the debugger/stub. 3724 3725 From reading the stub, it's probably not obvious how breakpoints 3726work. They are simply done by deposit/examine operations from GDB. 3727 3728ROM Monitor Interface 3729===================== 3730 3731Custom Protocols 3732================ 3733 3734Transport Layer 3735=============== 3736 3737Builtin Simulator 3738================= 3739 3740 3741File: gdbint.info, Node: Native Debugging, Next: Support Libraries, Prev: Target Vector Definition, Up: Top 3742 3743Native Debugging 3744**************** 3745 3746Several files control GDB's configuration for native support: 3747 3748`gdb/config/ARCH/XYZ.mh' 3749 Specifies Makefile fragments needed by a _native_ configuration on 3750 machine XYZ. In particular, this lists the required 3751 native-dependent object files, by defining `NATDEPFILES=...'. 3752 Also specifies the header file which describes native support on 3753 XYZ, by defining `NAT_FILE= nm-XYZ.h'. You can also define 3754 `NAT_CFLAGS', `NAT_ADD_FILES', `NAT_CLIBS', `NAT_CDEPS', etc.; see 3755 `Makefile.in'. 3756 3757 _Maintainer's note: The `.mh' suffix is because this file 3758 originally contained `Makefile' fragments for hosting GDB on 3759 machine XYZ. While the file is no longer used for this purpose, 3760 the `.mh' suffix remains. Perhaps someone will eventually rename 3761 these fragments so that they have a `.mn' suffix._ 3762 3763`gdb/config/ARCH/nm-XYZ.h' 3764 (`nm.h' is a link to this file, created by `configure'). Contains 3765 C macro definitions describing the native system environment, such 3766 as child process control and core file support. 3767 3768`gdb/XYZ-nat.c' 3769 Contains any miscellaneous C code required for this native support 3770 of this machine. On some machines it doesn't exist at all. 3771 3772 There are some "generic" versions of routines that can be used by 3773various systems. These can be customized in various ways by macros 3774defined in your `nm-XYZ.h' file. If these routines work for the XYZ 3775host, you can just include the generic file's name (with `.o', not 3776`.c') in `NATDEPFILES'. 3777 3778 Otherwise, if your machine needs custom support routines, you will 3779need to write routines that perform the same functions as the generic 3780file. Put them into `XYZ-nat.c', and put `XYZ-nat.o' into 3781`NATDEPFILES'. 3782 3783`inftarg.c' 3784 This contains the _target_ops vector_ that supports Unix child 3785 processes on systems which use ptrace and wait to control the 3786 child. 3787 3788`procfs.c' 3789 This contains the _target_ops vector_ that supports Unix child 3790 processes on systems which use /proc to control the child. 3791 3792`fork-child.c' 3793 This does the low-level grunge that uses Unix system calls to do a 3794 "fork and exec" to start up a child process. 3795 3796`infptrace.c' 3797 This is the low level interface to inferior processes for systems 3798 using the Unix `ptrace' call in a vanilla way. 3799 3800Native core file Support 3801======================== 3802 3803`core-aout.c::fetch_core_registers()' 3804 Support for reading registers out of a core file. This routine 3805 calls `register_addr()', see below. Now that BFD is used to read 3806 core files, virtually all machines should use `core-aout.c', and 3807 should just provide `fetch_core_registers' in `XYZ-nat.c' (or 3808 `REGISTER_U_ADDR' in `nm-XYZ.h'). 3809 3810`core-aout.c::register_addr()' 3811 If your `nm-XYZ.h' file defines the macro `REGISTER_U_ADDR(addr, 3812 blockend, regno)', it should be defined to set `addr' to the 3813 offset within the `user' struct of GDB register number `regno'. 3814 `blockend' is the offset within the "upage" of `u.u_ar0'. If 3815 `REGISTER_U_ADDR' is defined, `core-aout.c' will define the 3816 `register_addr()' function and use the macro in it. If you do not 3817 define `REGISTER_U_ADDR', but you are using the standard 3818 `fetch_core_registers()', you will need to define your own version 3819 of `register_addr()', put it into your `XYZ-nat.c' file, and be 3820 sure `XYZ-nat.o' is in the `NATDEPFILES' list. If you have your 3821 own `fetch_core_registers()', you may not need a separate 3822 `register_addr()'. Many custom `fetch_core_registers()' 3823 implementations simply locate the registers themselves. 3824 3825 When making GDB run native on a new operating system, to make it 3826possible to debug core files, you will need to either write specific 3827code for parsing your OS's core files, or customize `bfd/trad-core.c'. 3828First, use whatever `#include' files your machine uses to define the 3829struct of registers that is accessible (possibly in the u-area) in a 3830core file (rather than `machine/reg.h'), and an include file that 3831defines whatever header exists on a core file (e.g. the u-area or a 3832`struct core'). Then modify `trad_unix_core_file_p' to use these 3833values to set up the section information for the data segment, stack 3834segment, any other segments in the core file (perhaps shared library 3835contents or control information), "registers" segment, and if there are 3836two discontiguous sets of registers (e.g. integer and float), the 3837"reg2" segment. This section information basically delimits areas in 3838the core file in a standard way, which the section-reading routines in 3839BFD know how to seek around in. 3840 3841 Then back in GDB, you need a matching routine called 3842`fetch_core_registers'. If you can use the generic one, it's in 3843`core-aout.c'; if not, it's in your `XYZ-nat.c' file. It will be 3844passed a char pointer to the entire "registers" segment, its length, 3845and a zero; or a char pointer to the entire "regs2" segment, its 3846length, and a 2. The routine should suck out the supplied register 3847values and install them into GDB's "registers" array. 3848 3849 If your system uses `/proc' to control processes, and uses ELF 3850format core files, then you may be able to use the same routines for 3851reading the registers out of processes and out of core files. 3852 3853ptrace 3854====== 3855 3856/proc 3857===== 3858 3859win32 3860===== 3861 3862shared libraries 3863================ 3864 3865Native Conditionals 3866=================== 3867 3868When GDB is configured and compiled, various macros are defined or left 3869undefined, to control compilation when the host and target systems are 3870the same. These macros should be defined (or left undefined) in 3871`nm-SYSTEM.h'. 3872 3873`CHILD_PREPARE_TO_STORE' 3874 If the machine stores all registers at once in the child process, 3875 then define this to ensure that all values are correct. This 3876 usually entails a read from the child. 3877 3878 [Note that this is incorrectly defined in `xm-SYSTEM.h' files 3879 currently.] 3880 3881`FETCH_INFERIOR_REGISTERS' 3882 Define this if the native-dependent code will provide its own 3883 routines `fetch_inferior_registers' and `store_inferior_registers' 3884 in `HOST-nat.c'. If this symbol is _not_ defined, and 3885 `infptrace.c' is included in this configuration, the default 3886 routines in `infptrace.c' are used for these functions. 3887 3888`FILES_INFO_HOOK' 3889 (Only defined for Convex.) 3890 3891`FP0_REGNUM' 3892 This macro is normally defined to be the number of the first 3893 floating point register, if the machine has such registers. As 3894 such, it would appear only in target-specific code. However, 3895 `/proc' support uses this to decide whether floats are in use on 3896 this target. 3897 3898`GET_LONGJMP_TARGET' 3899 For most machines, this is a target-dependent parameter. On the 3900 DECstation and the Iris, this is a native-dependent parameter, 3901 since `setjmp.h' is needed to define it. 3902 3903 This macro determines the target PC address that `longjmp' will 3904 jump to, assuming that we have just stopped at a longjmp 3905 breakpoint. It takes a `CORE_ADDR *' as argument, and stores the 3906 target PC value through this pointer. It examines the current 3907 state of the machine as needed. 3908 3909`I386_USE_GENERIC_WATCHPOINTS' 3910 An x86-based machine can define this to use the generic x86 3911 watchpoint support; see *Note I386_USE_GENERIC_WATCHPOINTS: 3912 Algorithms. 3913 3914`KERNEL_U_ADDR' 3915 Define this to the address of the `u' structure (the "user 3916 struct", also known as the "u-page") in kernel virtual memory. 3917 GDB needs to know this so that it can subtract this address from 3918 absolute addresses in the upage, that are obtained via ptrace or 3919 from core files. On systems that don't need this value, set it to 3920 zero. 3921 3922`KERNEL_U_ADDR_BSD' 3923 Define this to cause GDB to determine the address of `u' at 3924 runtime, by using Berkeley-style `nlist' on the kernel's image in 3925 the root directory. 3926 3927`KERNEL_U_ADDR_HPUX' 3928 Define this to cause GDB to determine the address of `u' at 3929 runtime, by using HP-style `nlist' on the kernel's image in the 3930 root directory. 3931 3932`ONE_PROCESS_WRITETEXT' 3933 Define this to be able to, when a breakpoint insertion fails, warn 3934 the user that another process may be running with the same 3935 executable. 3936 3937`PROC_NAME_FMT' 3938 Defines the format for the name of a `/proc' device. Should be 3939 defined in `nm.h' _only_ in order to override the default 3940 definition in `procfs.c'. 3941 3942`PTRACE_FP_BUG' 3943 See `mach386-xdep.c'. 3944 3945`PTRACE_ARG3_TYPE' 3946 The type of the third argument to the `ptrace' system call, if it 3947 exists and is different from `int'. 3948 3949`REGISTER_U_ADDR' 3950 Defines the offset of the registers in the "u area". 3951 3952`SHELL_COMMAND_CONCAT' 3953 If defined, is a string to prefix on the shell command used to 3954 start the inferior. 3955 3956`SHELL_FILE' 3957 If defined, this is the name of the shell to use to run the 3958 inferior. Defaults to `"/bin/sh"'. 3959 3960`SOLIB_ADD (FILENAME, FROM_TTY, TARG, READSYMS)' 3961 Define this to expand into an expression that will cause the 3962 symbols in FILENAME to be added to GDB's symbol table. If READSYMS 3963 is zero symbols are not read but any necessary low level 3964 processing for FILENAME is still done. 3965 3966`SOLIB_CREATE_INFERIOR_HOOK' 3967 Define this to expand into any shared-library-relocation code that 3968 you want to be run just after the child process has been forked. 3969 3970`START_INFERIOR_TRAPS_EXPECTED' 3971 When starting an inferior, GDB normally expects to trap twice; 3972 once when the shell execs, and once when the program itself execs. 3973 If the actual number of traps is something other than 2, then 3974 define this macro to expand into the number expected. 3975 3976`SVR4_SHARED_LIBS' 3977 Define this to indicate that SVR4-style shared libraries are in 3978 use. 3979 3980`USE_PROC_FS' 3981 This determines whether small routines in `*-tdep.c', which 3982 translate register values between GDB's internal representation 3983 and the `/proc' representation, are compiled. 3984 3985`U_REGS_OFFSET' 3986 This is the offset of the registers in the upage. It need only be 3987 defined if the generic ptrace register access routines in 3988 `infptrace.c' are being used (that is, `infptrace.c' is configured 3989 in, and `FETCH_INFERIOR_REGISTERS' is not defined). If the 3990 default value from `infptrace.c' is good enough, leave it 3991 undefined. 3992 3993 The default value means that u.u_ar0 _points to_ the location of 3994 the registers. I'm guessing that `#define U_REGS_OFFSET 0' means 3995 that `u.u_ar0' _is_ the location of the registers. 3996 3997`CLEAR_SOLIB' 3998 See `objfiles.c'. 3999 4000`DEBUG_PTRACE' 4001 Define this to debug `ptrace' calls. 4002 4003 4004File: gdbint.info, Node: Support Libraries, Next: Coding, Prev: Native Debugging, Up: Top 4005 4006Support Libraries 4007***************** 4008 4009BFD 4010=== 4011 4012BFD provides support for GDB in several ways: 4013 4014_identifying executable and core files_ 4015 BFD will identify a variety of file types, including a.out, coff, 4016 and several variants thereof, as well as several kinds of core 4017 files. 4018 4019_access to sections of files_ 4020 BFD parses the file headers to determine the names, virtual 4021 addresses, sizes, and file locations of all the various named 4022 sections in files (such as the text section or the data section). 4023 GDB simply calls BFD to read or write section X at byte offset Y 4024 for length Z. 4025 4026_specialized core file support_ 4027 BFD provides routines to determine the failing command name stored 4028 in a core file, the signal with which the program failed, and 4029 whether a core file matches (i.e. could be a core dump of) a 4030 particular executable file. 4031 4032_locating the symbol information_ 4033 GDB uses an internal interface of BFD to determine where to find 4034 the symbol information in an executable file or symbol-file. GDB 4035 itself handles the reading of symbols, since BFD does not 4036 "understand" debug symbols, but GDB uses BFD's cached information 4037 to find the symbols, string table, etc. 4038 4039opcodes 4040======= 4041 4042The opcodes library provides GDB's disassembler. (It's a separate 4043library because it's also used in binutils, for `objdump'). 4044 4045readline 4046======== 4047 4048mmalloc 4049======= 4050 4051libiberty 4052========= 4053 4054The `libiberty' library provides a set of functions and features that 4055integrate and improve on functionality found in modern operating 4056systems. Broadly speaking, such features can be divided into three 4057groups: supplemental functions (functions that may be missing in some 4058environments and operating systems), replacement functions (providing a 4059uniform and easier to use interface for commonly used standard 4060functions), and extensions (which provide additional functionality 4061beyond standard functions). 4062 4063 GDB uses various features provided by the `libiberty' library, for 4064instance the C++ demangler, the IEEE floating format support functions, 4065the input options parser `getopt', the `obstack' extension, and other 4066functions. 4067 4068`obstacks' in GDB 4069----------------- 4070 4071The obstack mechanism provides a convenient way to allocate and free 4072chunks of memory. Each obstack is a pool of memory that is managed 4073like a stack. Objects (of any nature, size and alignment) are 4074allocated and freed in a LIFO fashion on an obstack (see `libiberty''s 4075documenatation for a more detailed explanation of `obstacks'). 4076 4077 The most noticeable use of the `obstacks' in GDB is in object files. 4078There is an obstack associated with each internal representation of an 4079object file. Lots of things get allocated on these `obstacks': 4080dictionary entries, blocks, blockvectors, symbols, minimal symbols, 4081types, vectors of fundamental types, class fields of types, object 4082files section lists, object files section offets lists, line tables, 4083symbol tables, partial symbol tables, string tables, symbol table 4084private data, macros tables, debug information sections and entries, 4085import and export lists (som), unwind information (hppa), dwarf2 4086location expressions data. Plus various strings such as directory 4087names strings, debug format strings, names of types. 4088 4089 An essential and convenient property of all data on `obstacks' is 4090that memory for it gets allocated (with `obstack_alloc') at various 4091times during a debugging sesssion, but it is released all at once using 4092the `obstack_free' function. The `obstack_free' function takes a 4093pointer to where in the stack it must start the deletion from (much 4094like the cleanup chains have a pointer to where to start the cleanups). 4095Because of the stack like structure of the `obstacks', this allows to 4096free only a top portion of the obstack. There are a few instances in 4097GDB where such thing happens. Calls to `obstack_free' are done after 4098some local data is allocated to the obstack. Only the local data is 4099deleted from the obstack. Of course this assumes that nothing between 4100the `obstack_alloc' and the `obstack_free' allocates anything else on 4101the same obstack. For this reason it is best and safest to use 4102temporary `obstacks'. 4103 4104 Releasing the whole obstack is also not safe per se. It is safe only 4105under the condition that we know the `obstacks' memory is no longer 4106needed. In GDB we get rid of the `obstacks' only when we get rid of 4107the whole objfile(s), for instance upon reading a new symbol file. 4108 4109gnu-regex 4110========= 4111 4112Regex conditionals. 4113 4114`C_ALLOCA' 4115 4116`NFAILURES' 4117 4118`RE_NREGS' 4119 4120`SIGN_EXTEND_CHAR' 4121 4122`SWITCH_ENUM_BUG' 4123 4124`SYNTAX_TABLE' 4125 4126`Sword' 4127 4128`sparc' 4129 4130include 4131======= 4132 4133 4134File: gdbint.info, Node: Coding, Next: Porting GDB, Prev: Support Libraries, Up: Top 4135 4136Coding 4137****** 4138 4139This chapter covers topics that are lower-level than the major 4140algorithms of GDB. 4141 4142Cleanups 4143======== 4144 4145Cleanups are a structured way to deal with things that need to be done 4146later. 4147 4148 When your code does something (e.g., `xmalloc' some memory, or 4149`open' a file) that needs to be undone later (e.g., `xfree' the memory 4150or `close' the file), it can make a cleanup. The cleanup will be done 4151at some future point: when the command is finished and control returns 4152to the top level; when an error occurs and the stack is unwound; or 4153when your code decides it's time to explicitly perform cleanups. 4154Alternatively you can elect to discard the cleanups you created. 4155 4156 Syntax: 4157 4158`struct cleanup *OLD_CHAIN;' 4159 Declare a variable which will hold a cleanup chain handle. 4160 4161`OLD_CHAIN = make_cleanup (FUNCTION, ARG);' 4162 Make a cleanup which will cause FUNCTION to be called with ARG (a 4163 `char *') later. The result, OLD_CHAIN, is a handle that can 4164 later be passed to `do_cleanups' or `discard_cleanups'. Unless 4165 you are going to call `do_cleanups' or `discard_cleanups', you can 4166 ignore the result from `make_cleanup'. 4167 4168`do_cleanups (OLD_CHAIN);' 4169 Do all cleanups added to the chain since the corresponding 4170 `make_cleanup' call was made. 4171 4172`discard_cleanups (OLD_CHAIN);' 4173 Same as `do_cleanups' except that it just removes the cleanups from 4174 the chain and does not call the specified functions. 4175 4176 Cleanups are implemented as a chain. The handle returned by 4177`make_cleanups' includes the cleanup passed to the call and any later 4178cleanups appended to the chain (but not yet discarded or performed). 4179E.g.: 4180 4181 make_cleanup (a, 0); 4182 { 4183 struct cleanup *old = make_cleanup (b, 0); 4184 make_cleanup (c, 0) 4185 ... 4186 do_cleanups (old); 4187 } 4188 4189will call `c()' and `b()' but will not call `a()'. The cleanup that 4190calls `a()' will remain in the cleanup chain, and will be done later 4191unless otherwise discarded. 4192 4193 Your function should explicitly do or discard the cleanups it 4194creates. Failing to do this leads to non-deterministic behavior since 4195the caller will arbitrarily do or discard your functions cleanups. 4196This need leads to two common cleanup styles. 4197 4198 The first style is try/finally. Before it exits, your code-block 4199calls `do_cleanups' with the old cleanup chain and thus ensures that 4200your code-block's cleanups are always performed. For instance, the 4201following code-segment avoids a memory leak problem (even when `error' 4202is called and a forced stack unwind occurs) by ensuring that the 4203`xfree' will always be called: 4204 4205 struct cleanup *old = make_cleanup (null_cleanup, 0); 4206 data = xmalloc (sizeof blah); 4207 make_cleanup (xfree, data); 4208 ... blah blah ... 4209 do_cleanups (old); 4210 4211 The second style is try/except. Before it exits, your code-block 4212calls `discard_cleanups' with the old cleanup chain and thus ensures 4213that any created cleanups are not performed. For instance, the 4214following code segment, ensures that the file will be closed but only 4215if there is an error: 4216 4217 FILE *file = fopen ("afile", "r"); 4218 struct cleanup *old = make_cleanup (close_file, file); 4219 ... blah blah ... 4220 discard_cleanups (old); 4221 return file; 4222 4223 Some functions, e.g. `fputs_filtered()' or `error()', specify that 4224they "should not be called when cleanups are not in place". This means 4225that any actions you need to reverse in the case of an error or 4226interruption must be on the cleanup chain before you call these 4227functions, since they might never return to your code (they `longjmp' 4228instead). 4229 4230Per-architecture module data 4231============================ 4232 4233The multi-arch framework includes a mechanism for adding module 4234specific per-architecture data-pointers to the `struct gdbarch' 4235architecture object. 4236 4237 A module registers one or more per-architecture data-pointers using: 4238 4239 - Function: struct gdbarch_data *gdbarch_data_register_pre_init 4240 (gdbarch_data_pre_init_ftype *PRE_INIT) 4241 PRE_INIT is used to, on-demand, allocate an initial value for a 4242 per-architecture data-pointer using the architecture's obstack 4243 (passed in as a parameter). Since PRE_INIT can be called during 4244 architecture creation, it is not parameterized with the 4245 architecture. and must not call modules that use per-architecture 4246 data. 4247 4248 - Function: struct gdbarch_data *gdbarch_data_register_post_init 4249 (gdbarch_data_post_init_ftype *POST_INIT) 4250 POST_INIT is used to obtain an initial value for a 4251 per-architecture data-pointer _after_. Since POST_INIT is always 4252 called after architecture creation, it both receives the fully 4253 initialized architecture and is free to call modules that use 4254 per-architecture data (care needs to be taken to ensure that those 4255 other modules do not try to call back to this module as that will 4256 create in cycles in the initialization call graph). 4257 4258 These functions return a `struct gdbarch_data' that is used to 4259identify the per-architecture data-pointer added for that module. 4260 4261 The per-architecture data-pointer is accessed using the function: 4262 4263 - Function: void *gdbarch_data (struct gdbarch *GDBARCH, struct 4264 gdbarch_data *DATA_HANDLE) 4265 Given the architecture ARCH and module data handle DATA_HANDLE 4266 (returned by `gdbarch_data_register_pre_init' or 4267 `gdbarch_data_register_post_init'), this function returns the 4268 current value of the per-architecture data-pointer. If the data 4269 pointer is `NULL', it is first initialized by calling the 4270 corresponding PRE_INIT or POST_INIT method. 4271 4272 The examples below assume the following definitions: 4273 4274 struct nozel { int total; }; 4275 static struct gdbarch_data *nozel_handle; 4276 4277 A module can extend the architecture vector, adding additional 4278per-architecture data, using the PRE_INIT method. The module's 4279per-architecture data is then initialized during architecture creation. 4280 4281 In the below, the module's per-architecture _nozel_ is added. An 4282architecture can specify its nozel by calling `set_gdbarch_nozel' from 4283`gdbarch_init'. 4284 4285 static void * 4286 nozel_pre_init (struct obstack *obstack) 4287 { 4288 struct nozel *data = OBSTACK_ZALLOC (obstack, struct nozel); 4289 return data; 4290 } 4291 4292 extern void 4293 set_gdbarch_nozel (struct gdbarch *gdbarch, int total) 4294 { 4295 struct nozel *data = gdbarch_data (gdbarch, nozel_handle); 4296 data->total = nozel; 4297 } 4298 4299 A module can on-demand create architecture dependant data structures 4300using `post_init'. 4301 4302 In the below, the nozel's total is computed on-demand by 4303`nozel_post_init' using information obtained from the architecture. 4304 4305 static void * 4306 nozel_post_init (struct gdbarch *gdbarch) 4307 { 4308 struct nozel *data = GDBARCH_OBSTACK_ZALLOC (gdbarch, struct nozel); 4309 nozel->total = gdbarch... (gdbarch); 4310 return data; 4311 } 4312 4313 extern int 4314 nozel_total (struct gdbarch *gdbarch) 4315 { 4316 struct nozel *data = gdbarch_data (gdbarch, nozel_handle); 4317 return data->total; 4318 } 4319 4320Wrapping Output Lines 4321===================== 4322 4323Output that goes through `printf_filtered' or `fputs_filtered' or 4324`fputs_demangled' needs only to have calls to `wrap_here' added in 4325places that would be good breaking points. The utility routines will 4326take care of actually wrapping if the line width is exceeded. 4327 4328 The argument to `wrap_here' is an indentation string which is 4329printed _only_ if the line breaks there. This argument is saved away 4330and used later. It must remain valid until the next call to 4331`wrap_here' or until a newline has been printed through the 4332`*_filtered' functions. Don't pass in a local variable and then return! 4333 4334 It is usually best to call `wrap_here' after printing a comma or 4335space. If you call it before printing a space, make sure that your 4336indentation properly accounts for the leading space that will print if 4337the line wraps there. 4338 4339 Any function or set of functions that produce filtered output must 4340finish by printing a newline, to flush the wrap buffer, before switching 4341to unfiltered (`printf') output. Symbol reading routines that print 4342warnings are a good example. 4343 4344GDB Coding Standards 4345==================== 4346 4347GDB follows the GNU coding standards, as described in 4348`etc/standards.texi'. This file is also available for anonymous FTP 4349from GNU archive sites. GDB takes a strict interpretation of the 4350standard; in general, when the GNU standard recommends a practice but 4351does not require it, GDB requires it. 4352 4353 GDB follows an additional set of coding standards specific to GDB, 4354as described in the following sections. 4355 4356ISO C 4357----- 4358 4359GDB assumes an ISO/IEC 9899:1990 (a.k.a. ISO C90) compliant compiler. 4360 4361 GDB does not assume an ISO C or POSIX compliant C library. 4362 4363Memory Management 4364----------------- 4365 4366GDB does not use the functions `malloc', `realloc', `calloc', `free' 4367and `asprintf'. 4368 4369 GDB uses the functions `xmalloc', `xrealloc' and `xcalloc' when 4370allocating memory. Unlike `malloc' et.al. these functions do not 4371return when the memory pool is empty. Instead, they unwind the stack 4372using cleanups. These functions return `NULL' when requested to 4373allocate a chunk of memory of size zero. 4374 4375 _Pragmatics: By using these functions, the need to check every 4376memory allocation is removed. These functions provide portable 4377behavior._ 4378 4379 GDB does not use the function `free'. 4380 4381 GDB uses the function `xfree' to return memory to the memory pool. 4382Consistent with ISO-C, this function ignores a request to free a `NULL' 4383pointer. 4384 4385 _Pragmatics: On some systems `free' fails when passed a `NULL' 4386pointer._ 4387 4388 GDB can use the non-portable function `alloca' for the allocation of 4389small temporary values (such as strings). 4390 4391 _Pragmatics: This function is very non-portable. Some systems 4392restrict the memory being allocated to no more than a few kilobytes._ 4393 4394 GDB uses the string function `xstrdup' and the print function 4395`xstrprintf'. 4396 4397 _Pragmatics: `asprintf' and `strdup' can fail. Print functions such 4398as `sprintf' are very prone to buffer overflow errors._ 4399 4400Compiler Warnings 4401----------------- 4402 4403With few exceptions, developers should include the configuration option 4404`--enable-gdb-build-warnings=,-Werror' when building GDB. The 4405exceptions are listed in the file `gdb/MAINTAINERS'. 4406 4407 This option causes GDB (when built using GCC) to be compiled with a 4408carefully selected list of compiler warning flags. Any warnings from 4409those flags being treated as errors. 4410 4411 The current list of warning flags includes: 4412 4413`-Wimplicit' 4414 Since GDB coding standard requires all functions to be declared 4415 using a prototype, the flag has the side effect of ensuring that 4416 prototyped functions are always visible with out resorting to 4417 `-Wstrict-prototypes'. 4418 4419`-Wreturn-type' 4420 Such code often appears to work except on instruction set 4421 architectures that use register windows. 4422 4423`-Wcomment' 4424 4425`-Wtrigraphs' 4426 4427`-Wformat' 4428`-Wformat-nonliteral' 4429 Since GDB uses the `format printf' attribute on all `printf' like 4430 functions these check not just `printf' calls but also calls to 4431 functions such as `fprintf_unfiltered'. 4432 4433`-Wparentheses' 4434 This warning includes uses of the assignment operator within an 4435 `if' statement. 4436 4437`-Wpointer-arith' 4438 4439`-Wuninitialized' 4440 4441`-Wunused-label' 4442 This warning has the additional benefit of detecting the absence 4443 of the `case' reserved word in a switch statement: 4444 enum { FD_SCHEDULED, NOTHING_SCHEDULED } sched; 4445 ... 4446 switch (sched) 4447 { 4448 case FD_SCHEDULED: 4449 ...; 4450 break; 4451 NOTHING_SCHEDULED: 4452 ...; 4453 break; 4454 } 4455 4456`-Wunused-function' 4457 4458 _Pragmatics: Due to the way that GDB is implemented most functions 4459have unused parameters. Consequently the warning `-Wunused-parameter' 4460is precluded from the list. The macro `ATTRIBUTE_UNUSED' is not used 4461as it leads to false negatives -- it is not an error to have 4462`ATTRIBUTE_UNUSED' on a parameter that is being used. The options 4463`-Wall' and `-Wunused' are also precluded because they both include 4464`-Wunused-parameter'._ 4465 4466 _Pragmatics: GDB has not simply accepted the warnings enabled by 4467`-Wall -Werror -W...'. Instead it is selecting warnings when and where 4468their benefits can be demonstrated._ 4469 4470Formatting 4471---------- 4472 4473The standard GNU recommendations for formatting must be followed 4474strictly. 4475 4476 A function declaration should not have its name in column zero. A 4477function definition should have its name in column zero. 4478 4479 /* Declaration */ 4480 static void foo (void); 4481 /* Definition */ 4482 void 4483 foo (void) 4484 { 4485 } 4486 4487 _Pragmatics: This simplifies scripting. Function definitions can be 4488found using `^function-name'._ 4489 4490 There must be a space between a function or macro name and the 4491opening parenthesis of its argument list (except for macro definitions, 4492as required by C). There must not be a space after an open 4493paren/bracket or before a close paren/bracket. 4494 4495 While additional whitespace is generally helpful for reading, do not 4496use more than one blank line to separate blocks, and avoid adding 4497whitespace after the end of a program line (as of 1/99, some 600 lines 4498had whitespace after the semicolon). Excess whitespace causes 4499difficulties for `diff' and `patch' utilities. 4500 4501 Pointers are declared using the traditional K&R C style: 4502 4503 void *foo; 4504 4505and not: 4506 4507 void * foo; 4508 void* foo; 4509 4510Comments 4511-------- 4512 4513The standard GNU requirements on comments must be followed strictly. 4514 4515 Block comments must appear in the following form, with no `/*'- or 4516`*/'-only lines, and no leading `*': 4517 4518 /* Wait for control to return from inferior to debugger. If inferior 4519 gets a signal, we may decide to start it up again instead of 4520 returning. That is why there is a loop in this function. When 4521 this function actually returns it means the inferior should be left 4522 stopped and GDB should read more commands. */ 4523 4524 (Note that this format is encouraged by Emacs; tabbing for a 4525multi-line comment works correctly, and `M-q' fills the block 4526consistently.) 4527 4528 Put a blank line between the block comments preceding function or 4529variable definitions, and the definition itself. 4530 4531 In general, put function-body comments on lines by themselves, rather 4532than trying to fit them into the 20 characters left at the end of a 4533line, since either the comment or the code will inevitably get longer 4534than will fit, and then somebody will have to move it anyhow. 4535 4536C Usage 4537------- 4538 4539Code must not depend on the sizes of C data types, the format of the 4540host's floating point numbers, the alignment of anything, or the order 4541of evaluation of expressions. 4542 4543 Use functions freely. There are only a handful of compute-bound 4544areas in GDB that might be affected by the overhead of a function call, 4545mainly in symbol reading. Most of GDB's performance is limited by the 4546target interface (whether serial line or system call). 4547 4548 However, use functions with moderation. A thousand one-line 4549functions are just as hard to understand as a single thousand-line 4550function. 4551 4552 _Macros are bad, M'kay._ (But if you have to use a macro, make sure 4553that the macro arguments are protected with parentheses.) 4554 4555 Declarations like `struct foo *' should be used in preference to 4556declarations like `typedef struct foo { ... } *foo_ptr'. 4557 4558Function Prototypes 4559------------------- 4560 4561Prototypes must be used when both _declaring_ and _defining_ a 4562function. Prototypes for GDB functions must include both the argument 4563type and name, with the name matching that used in the actual function 4564definition. 4565 4566 All external functions should have a declaration in a header file 4567that callers include, except for `_initialize_*' functions, which must 4568be external so that `init.c' construction works, but shouldn't be 4569visible to random source files. 4570 4571 Where a source file needs a forward declaration of a static function, 4572that declaration must appear in a block near the top of the source file. 4573 4574Internal Error Recovery 4575----------------------- 4576 4577During its execution, GDB can encounter two types of errors. User 4578errors and internal errors. User errors include not only a user 4579entering an incorrect command but also problems arising from corrupt 4580object files and system errors when interacting with the target. 4581Internal errors include situations where GDB has detected, at run time, 4582a corrupt or erroneous situation. 4583 4584 When reporting an internal error, GDB uses `internal_error' and 4585`gdb_assert'. 4586 4587 GDB must not call `abort' or `assert'. 4588 4589 _Pragmatics: There is no `internal_warning' function. Either the 4590code detected a user error, recovered from it and issued a `warning' or 4591the code failed to correctly recover from the user error and issued an 4592`internal_error'._ 4593 4594File Names 4595---------- 4596 4597Any file used when building the core of GDB must be in lower case. Any 4598file used when building the core of GDB must be 8.3 unique. These 4599requirements apply to both source and generated files. 4600 4601 _Pragmatics: The core of GDB must be buildable on many platforms 4602including DJGPP and MacOS/HFS. Every time an unfriendly file is 4603introduced to the build process both `Makefile.in' and `configure.in' 4604need to be modified accordingly. Compare the convoluted conversion 4605process needed to transform `COPYING' into `copying.c' with the 4606conversion needed to transform `version.in' into `version.c'._ 4607 4608 Any file non 8.3 compliant file (that is not used when building the 4609core of GDB) must be added to `gdb/config/djgpp/fnchange.lst'. 4610 4611 _Pragmatics: This is clearly a compromise._ 4612 4613 When GDB has a local version of a system header file (ex `string.h') 4614the file name based on the POSIX header prefixed with `gdb_' 4615(`gdb_string.h'). These headers should be relatively independent: they 4616should use only macros defined by `configure', the compiler, or the 4617host; they should include only system headers; they should refer only 4618to system types. They may be shared between multiple programs, e.g. 4619GDB and GDBSERVER. 4620 4621 For other files `-' is used as the separator. 4622 4623Include Files 4624------------- 4625 4626A `.c' file should include `defs.h' first. 4627 4628 A `.c' file should directly include the `.h' file of every 4629declaration and/or definition it directly refers to. It cannot rely on 4630indirect inclusion. 4631 4632 A `.h' file should directly include the `.h' file of every 4633declaration and/or definition it directly refers to. It cannot rely on 4634indirect inclusion. Exception: The file `defs.h' does not need to be 4635directly included. 4636 4637 An external declaration should only appear in one include file. 4638 4639 An external declaration should never appear in a `.c' file. 4640Exception: a declaration for the `_initialize' function that pacifies 4641`-Wmissing-declaration'. 4642 4643 A `typedef' definition should only appear in one include file. 4644 4645 An opaque `struct' declaration can appear in multiple `.h' files. 4646Where possible, a `.h' file should use an opaque `struct' declaration 4647instead of an include. 4648 4649 All `.h' files should be wrapped in: 4650 4651 #ifndef INCLUDE_FILE_NAME_H 4652 #define INCLUDE_FILE_NAME_H 4653 header body 4654 #endif 4655 4656Clean Design and Portable Implementation 4657---------------------------------------- 4658 4659In addition to getting the syntax right, there's the little question of 4660semantics. Some things are done in certain ways in GDB because long 4661experience has shown that the more obvious ways caused various kinds of 4662trouble. 4663 4664 You can't assume the byte order of anything that comes from a target 4665(including VALUEs, object files, and instructions). Such things must 4666be byte-swapped using `SWAP_TARGET_AND_HOST' in GDB, or one of the swap 4667routines defined in `bfd.h', such as `bfd_get_32'. 4668 4669 You can't assume that you know what interface is being used to talk 4670to the target system. All references to the target must go through the 4671current `target_ops' vector. 4672 4673 You can't assume that the host and target machines are the same 4674machine (except in the "native" support modules). In particular, you 4675can't assume that the target machine's header files will be available 4676on the host machine. Target code must bring along its own header files 4677- written from scratch or explicitly donated by their owner, to avoid 4678copyright problems. 4679 4680 Insertion of new `#ifdef''s will be frowned upon. It's much better 4681to write the code portably than to conditionalize it for various 4682systems. 4683 4684 New `#ifdef''s which test for specific compilers or manufacturers or 4685operating systems are unacceptable. All `#ifdef''s should test for 4686features. The information about which configurations contain which 4687features should be segregated into the configuration files. Experience 4688has proven far too often that a feature unique to one particular system 4689often creeps into other systems; and that a conditional based on some 4690predefined macro for your current system will become worthless over 4691time, as new versions of your system come out that behave differently 4692with regard to this feature. 4693 4694 Adding code that handles specific architectures, operating systems, 4695target interfaces, or hosts, is not acceptable in generic code. 4696 4697 One particularly notorious area where system dependencies tend to 4698creep in is handling of file names. The mainline GDB code assumes 4699Posix semantics of file names: absolute file names begin with a forward 4700slash `/', slashes are used to separate leading directories, 4701case-sensitive file names. These assumptions are not necessarily true 4702on non-Posix systems such as MS-Windows. To avoid system-dependent 4703code where you need to take apart or construct a file name, use the 4704following portable macros: 4705 4706`HAVE_DOS_BASED_FILE_SYSTEM' 4707 This preprocessing symbol is defined to a non-zero value on hosts 4708 whose filesystems belong to the MS-DOS/MS-Windows family. Use this 4709 symbol to write conditional code which should only be compiled for 4710 such hosts. 4711 4712`IS_DIR_SEPARATOR (C)' 4713 Evaluates to a non-zero value if C is a directory separator 4714 character. On Unix and GNU/Linux systems, only a slash `/' is 4715 such a character, but on Windows, both `/' and `\' will pass. 4716 4717`IS_ABSOLUTE_PATH (FILE)' 4718 Evaluates to a non-zero value if FILE is an absolute file name. 4719 For Unix and GNU/Linux hosts, a name which begins with a slash `/' 4720 is absolute. On DOS and Windows, `d:/foo' and `x:\bar' are also 4721 absolute file names. 4722 4723`FILENAME_CMP (F1, F2)' 4724 Calls a function which compares file names F1 and F2 as 4725 appropriate for the underlying host filesystem. For Posix systems, 4726 this simply calls `strcmp'; on case-insensitive filesystems it 4727 will call `strcasecmp' instead. 4728 4729`DIRNAME_SEPARATOR' 4730 Evaluates to a character which separates directories in 4731 `PATH'-style lists, typically held in environment variables. This 4732 character is `:' on Unix, `;' on DOS and Windows. 4733 4734`SLASH_STRING' 4735 This evaluates to a constant string you should use to produce an 4736 absolute filename from leading directories and the file's basename. 4737 `SLASH_STRING' is `"/"' on most systems, but might be `"\\"' for 4738 some Windows-based ports. 4739 4740 In addition to using these macros, be sure to use portable library 4741functions whenever possible. For example, to extract a directory or a 4742basename part from a file name, use the `dirname' and `basename' 4743library functions (available in `libiberty' for platforms which don't 4744provide them), instead of searching for a slash with `strrchr'. 4745 4746 Another way to generalize GDB along a particular interface is with an 4747attribute struct. For example, GDB has been generalized to handle 4748multiple kinds of remote interfaces--not by `#ifdef's everywhere, but 4749by defining the `target_ops' structure and having a current target (as 4750well as a stack of targets below it, for memory references). Whenever 4751something needs to be done that depends on which remote interface we are 4752using, a flag in the current target_ops structure is tested (e.g., 4753`target_has_stack'), or a function is called through a pointer in the 4754current target_ops structure. In this way, when a new remote interface 4755is added, only one module needs to be touched--the one that actually 4756implements the new remote interface. Other examples of 4757attribute-structs are BFD access to multiple kinds of object file 4758formats, or GDB's access to multiple source languages. 4759 4760 Please avoid duplicating code. For example, in GDB 3.x all the code 4761interfacing between `ptrace' and the rest of GDB was duplicated in 4762`*-dep.c', and so changing something was very painful. In GDB 4.x, 4763these have all been consolidated into `infptrace.c'. `infptrace.c' can 4764deal with variations between systems the same way any system-independent 4765file would (hooks, `#if defined', etc.), and machines which are 4766radically different don't need to use `infptrace.c' at all. 4767 4768 All debugging code must be controllable using the `set debug MODULE' 4769command. Do not use `printf' to print trace messages. Use 4770`fprintf_unfiltered(gdb_stdlog, ...'. Do not use `#ifdef DEBUG'. 4771 4772 4773File: gdbint.info, Node: Porting GDB, Next: Releasing GDB, Prev: Coding, Up: Top 4774 4775Porting GDB 4776*********** 4777 4778Most of the work in making GDB compile on a new machine is in 4779specifying the configuration of the machine. This is done in a 4780dizzying variety of header files and configuration scripts, which we 4781hope to make more sensible soon. Let's say your new host is called an 4782XYZ (e.g., `sun4'), and its full three-part configuration name is 4783`ARCH-XVEND-XOS' (e.g., `sparc-sun-sunos4'). In particular: 4784 4785 * In the top level directory, edit `config.sub' and add ARCH, XVEND, 4786 and XOS to the lists of supported architectures, vendors, and 4787 operating systems near the bottom of the file. Also, add XYZ as 4788 an alias that maps to `ARCH-XVEND-XOS'. You can test your changes 4789 by running 4790 4791 ./config.sub XYZ 4792 4793 and 4794 4795 ./config.sub `ARCH-XVEND-XOS' 4796 4797 which should both respond with `ARCH-XVEND-XOS' and no error 4798 messages. 4799 4800 You need to port BFD, if that hasn't been done already. Porting 4801 BFD is beyond the scope of this manual. 4802 4803 * To configure GDB itself, edit `gdb/configure.host' to recognize 4804 your system and set `gdb_host' to XYZ, and (unless your desired 4805 target is already available) also edit `gdb/configure.tgt', 4806 setting `gdb_target' to something appropriate (for instance, XYZ). 4807 4808 _Maintainer's note: Work in progress. The file 4809 `gdb/configure.host' originally needed to be modified when either a 4810 new native target or a new host machine was being added to GDB. 4811 Recent changes have removed this requirement. The file now only 4812 needs to be modified when adding a new native configuration. This 4813 will likely changed again in the future._ 4814 4815 * Finally, you'll need to specify and define GDB's host-, native-, 4816 and target-dependent `.h' and `.c' files used for your 4817 configuration. 4818 4819 4820File: gdbint.info, Node: Releasing GDB, Next: Testsuite, Prev: Porting GDB, Up: Top 4821 4822Releasing GDB 4823************* 4824 4825Versions and Branches 4826===================== 4827 4828Version Identifiers 4829------------------- 4830 4831GDB's version is determined by the file `gdb/version.in'. 4832 4833 GDB's mainline uses ISO dates to differentiate between versions. 4834The CVS repository uses YYYY-MM-DD-cvs while the corresponding snapshot 4835uses YYYYMMDD. 4836 4837 GDB's release branch uses a slightly more complicated scheme. When 4838the branch is first cut, the mainline version identifier is prefixed 4839with the MAJOR.MINOR from of the previous release series but with .90 4840appended. As draft releases are drawn from the branch, the minor minor 4841number (.90) is incremented. Once the first release (M.N) has been 4842made, the version prefix is updated to M.N.0.90 (dot zero, dot ninety). 4843Follow on releases have an incremented minor minor version number (.0). 4844 4845 Using 5.1 (previous) and 5.2 (current), the example below 4846illustrates a typical sequence of version identifiers: 4847 48485.1.1 4849 final release from previous branch 4850 48512002-03-03-cvs 4852 main-line the day the branch is cut 4853 48545.1.90-2002-03-03-cvs 4855 corresponding branch version 4856 48575.1.91 4858 first draft release candidate 4859 48605.1.91-2002-03-17-cvs 4861 updated branch version 4862 48635.1.92 4864 second draft release candidate 4865 48665.1.92-2002-03-31-cvs 4867 updated branch version 4868 48695.1.93 4870 final release candidate (see below) 4871 48725.2 4873 official release 4874 48755.2.0.90-2002-04-07-cvs 4876 updated CVS branch version 4877 48785.2.1 4879 second official release 4880 4881 Notes: 4882 4883 * Minor minor minor draft release candidates such as 5.2.0.91 have 4884 been omitted from the example. Such release candidates are, 4885 typically, never made. 4886 4887 * For 5.1.93 the bziped tar ball `gdb-5.1.93.tar.bz2' is just the 4888 official `gdb-5.2.tar' renamed and compressed. 4889 4890 To avoid version conflicts, vendors are expected to modify the file 4891`gdb/version.in' to include a vendor unique alphabetic identifier (an 4892official GDB release never uses alphabetic characters in its version 4893identifer). 4894 4895 Since GDB does not make minor minor minor releases (e.g., 5.1.0.1) 4896the conflict between that and a minor minor draft release identifier 4897(e.g., 5.1.0.90) is avoided. 4898 4899Branches 4900-------- 4901 4902GDB draws a release series (5.2, 5.2.1, ...) from a single release 4903branch (gdb_5_2-branch). Since minor minor minor releases (5.1.0.1) 4904are not made, the need to branch the release branch is avoided (it also 4905turns out that the effort required for such a a branch and release is 4906significantly greater than the effort needed to create a new release 4907from the head of the release branch). 4908 4909 Releases 5.0 and 5.1 used branch and release tags of the form: 4910 4911 gdb_N_M-YYYY-MM-DD-branchpoint 4912 gdb_N_M-YYYY-MM-DD-branch 4913 gdb_M_N-YYYY-MM-DD-release 4914 4915 Release 5.2 is trialing the branch and release tags: 4916 4917 gdb_N_M-YYYY-MM-DD-branchpoint 4918 gdb_N_M-branch 4919 gdb_M_N-YYYY-MM-DD-release 4920 4921 _Pragmatics: The branchpoint and release tags need to identify when 4922a branch and release are made. The branch tag, denoting the head of the 4923branch, does not have this criteria._ 4924 4925Branch Commit Policy 4926==================== 4927 4928The branch commit policy is pretty slack. GDB releases 5.0, 5.1 and 49295.2 all used the below: 4930 4931 * The `gdb/MAINTAINERS' file still holds. 4932 4933 * Don't fix something on the branch unless/until it is also fixed in 4934 the trunk. If this isn't possible, mentioning it in the 4935 `gdb/PROBLEMS' file is better than committing a hack. 4936 4937 * When considering a patch for the branch, suggested criteria 4938 include: Does it fix a build? Does it fix the sequence `break 4939 main; run' when debugging a static binary? 4940 4941 * The further a change is from the core of GDB, the less likely the 4942 change will worry anyone (e.g., target specific code). 4943 4944 * Only post a proposal to change the core of GDB after you've sent 4945 individual bribes to all the people listed in the `MAINTAINERS' 4946 file ;-) 4947 4948 _Pragmatics: Provided updates are restricted to non-core 4949functionality there is little chance that a broken change will be fatal. 4950This means that changes such as adding a new architectures or (within 4951reason) support for a new host are considered acceptable._ 4952 4953Obsoleting code 4954=============== 4955 4956Before anything else, poke the other developers (and around the source 4957code) to see if there is anything that can be removed from GDB (an old 4958target, an unused file). 4959 4960 Obsolete code is identified by adding an `OBSOLETE' prefix to every 4961line. Doing this means that it is easy to identify something that has 4962been obsoleted when greping through the sources. 4963 4964 The process is done in stages -- this is mainly to ensure that the 4965wider GDB community has a reasonable opportunity to respond. Remember, 4966everything on the Internet takes a week. 4967 4968 1. Post the proposal on the GDB mailing list <gdb@sources.redhat.com> 4969 Creating a bug report to track the task's state, is also highly 4970 recommended. 4971 4972 2. Wait a week or so. 4973 4974 3. Post the proposal on the GDB Announcement mailing list 4975 <gdb-announce@sources.redhat.com>. 4976 4977 4. Wait a week or so. 4978 4979 5. Go through and edit all relevant files and lines so that they are 4980 prefixed with the word `OBSOLETE'. 4981 4982 6. Wait until the next GDB version, containing this obsolete code, 4983 has been released. 4984 4985 7. Remove the obsolete code. 4986 4987_Maintainer note: While removing old code is regrettable it is 4988hopefully better for GDB's long term development. Firstly it helps the 4989developers by removing code that is either no longer relevant or simply 4990wrong. Secondly since it removes any history associated with the file 4991(effectively clearing the slate) the developer has a much freer hand 4992when it comes to fixing broken files._ 4993 4994Before the Branch 4995================= 4996 4997The most important objective at this stage is to find and fix simple 4998changes that become a pain to track once the branch is created. For 4999instance, configuration problems that stop GDB from even building. If 5000you can't get the problem fixed, document it in the `gdb/PROBLEMS' file. 5001 5002Prompt for `gdb/NEWS' 5003--------------------- 5004 5005People always forget. Send a post reminding them but also if you know 5006something interesting happened add it yourself. The `schedule' script 5007will mention this in its e-mail. 5008 5009Review `gdb/README' 5010------------------- 5011 5012Grab one of the nightly snapshots and then walk through the 5013`gdb/README' looking for anything that can be improved. The `schedule' 5014script will mention this in its e-mail. 5015 5016Refresh any imported files. 5017--------------------------- 5018 5019A number of files are taken from external repositories. They include: 5020 5021 * `texinfo/texinfo.tex' 5022 5023 * `config.guess' et. al. (see the top-level `MAINTAINERS' file) 5024 5025 * `etc/standards.texi', `etc/make-stds.texi' 5026 5027Check the ARI 5028------------- 5029 5030A.R.I. is an `awk' script (Awk Regression Index ;-) that checks for a 5031number of errors and coding conventions. The checks include things 5032like using `malloc' instead of `xmalloc' and file naming problems. 5033There shouldn't be any regressions. 5034 5035Review the bug data base 5036------------------------ 5037 5038Close anything obviously fixed. 5039 5040Check all cross targets build 5041----------------------------- 5042 5043The targets are listed in `gdb/MAINTAINERS'. 5044 5045Cut the Branch 5046============== 5047 5048Create the branch 5049----------------- 5050 5051 $ u=5.1 5052 $ v=5.2 5053 $ V=`echo $v | sed 's/\./_/g'` 5054 $ D=`date -u +%Y-%m-%d` 5055 $ echo $u $V $D 5056 5.1 5_2 2002-03-03 5057 $ echo cvs -f -d :ext:sources.redhat.com:/cvs/src rtag \ 5058 -D $D-gmt gdb_$V-$D-branchpoint insight+dejagnu 5059 cvs -f -d :ext:sources.redhat.com:/cvs/src rtag 5060 -D 2002-03-03-gmt gdb_5_2-2002-03-03-branchpoint insight+dejagnu 5061 $ ^echo ^^ 5062 ... 5063 $ echo cvs -f -d :ext:sources.redhat.com:/cvs/src rtag \ 5064 -b -r gdb_$V-$D-branchpoint gdb_$V-branch insight+dejagnu 5065 cvs -f -d :ext:sources.redhat.com:/cvs/src rtag \ 5066 -b -r gdb_5_2-2002-03-03-branchpoint gdb_5_2-branch insight+dejagnu 5067 $ ^echo ^^ 5068 ... 5069 $ 5070 5071 * by using `-D YYYY-MM-DD-gmt' the branch is forced to an exact 5072 date/time. 5073 5074 * the trunk is first taged so that the branch point can easily be 5075 found 5076 5077 * Insight (which includes GDB) and dejagnu are all tagged at the 5078 same time 5079 5080 * `version.in' gets bumped to avoid version number conflicts 5081 5082 * the reading of `.cvsrc' is disabled using `-f' 5083 5084Update `version.in' 5085------------------- 5086 5087 $ u=5.1 5088 $ v=5.2 5089 $ V=`echo $v | sed 's/\./_/g'` 5090 $ echo $u $v$V 5091 5.1 5_2 5092 $ cd /tmp 5093 $ echo cvs -f -d :ext:sources.redhat.com:/cvs/src co \ 5094 -r gdb_$V-branch src/gdb/version.in 5095 cvs -f -d :ext:sources.redhat.com:/cvs/src co 5096 -r gdb_5_2-branch src/gdb/version.in 5097 $ ^echo ^^ 5098 U src/gdb/version.in 5099 $ cd src/gdb 5100 $ echo $u.90-0000-00-00-cvs > version.in 5101 $ cat version.in 5102 5.1.90-0000-00-00-cvs 5103 $ cvs -f commit version.in 5104 5105 * `0000-00-00' is used as a date to pump prime the version.in update 5106 mechanism 5107 5108 * `.90' and the previous branch version are used as fairly arbitrary 5109 initial branch version number 5110 5111Update the web and news pages 5112----------------------------- 5113 5114Something? 5115 5116Tweak cron to track the new branch 5117---------------------------------- 5118 5119The file `gdbadmin/cron/crontab' contains gdbadmin's cron table. This 5120file needs to be updated so that: 5121 5122 * a daily timestamp is added to the file `version.in' 5123 5124 * the new branch is included in the snapshot process 5125 5126See the file `gdbadmin/cron/README' for how to install the updated cron 5127table. 5128 5129 The file `gdbadmin/ss/README' should also be reviewed to reflect any 5130changes. That file is copied to both the branch/ and current/ snapshot 5131directories. 5132 5133Update the NEWS and README files 5134-------------------------------- 5135 5136The `NEWS' file needs to be updated so that on the branch it refers to 5137_changes in the current release_ while on the trunk it also refers to 5138_changes since the current release_. 5139 5140 The `README' file needs to be updated so that it refers to the 5141current release. 5142 5143Post the branch info 5144-------------------- 5145 5146Send an announcement to the mailing lists: 5147 5148 * GDB Announcement mailing list <gdb-announce@sources.redhat.com> 5149 5150 * GDB Discsussion mailing list <gdb@sources.redhat.com> and GDB 5151 Discsussion mailing list <gdb-testers@sources.redhat.com> 5152 5153 _Pragmatics: The branch creation is sent to the announce list to 5154ensure that people people not subscribed to the higher volume discussion 5155list are alerted._ 5156 5157 The announcement should include: 5158 5159 * the branch tag 5160 5161 * how to check out the branch using CVS 5162 5163 * the date/number of weeks until the release 5164 5165 * the branch commit policy still holds. 5166 5167Stabilize the branch 5168==================== 5169 5170Something goes here. 5171 5172Create a Release 5173================ 5174 5175The process of creating and then making available a release is broken 5176down into a number of stages. The first part addresses the technical 5177process of creating a releasable tar ball. The later stages address the 5178process of releasing that tar ball. 5179 5180 When making a release candidate just the first section is needed. 5181 5182Create a release candidate 5183-------------------------- 5184 5185The objective at this stage is to create a set of tar balls that can be 5186made available as a formal release (or as a less formal release 5187candidate). 5188 5189Freeze the branch 5190................. 5191 5192Send out an e-mail notifying everyone that the branch is frozen to 5193<gdb-patches@sources.redhat.com>. 5194 5195Establish a few defaults. 5196......................... 5197 5198 $ b=gdb_5_2-branch 5199 $ v=5.2 5200 $ t=/sourceware/snapshot-tmp/gdbadmin-tmp 5201 $ echo $t/$b/$v 5202 /sourceware/snapshot-tmp/gdbadmin-tmp/gdb_5_2-branch/5.2 5203 $ mkdir -p $t/$b/$v 5204 $ cd $t/$b/$v 5205 $ pwd 5206 /sourceware/snapshot-tmp/gdbadmin-tmp/gdb_5_2-branch/5.2 5207 $ which autoconf 5208 /home/gdbadmin/bin/autoconf 5209 $ 5210 5211Notes: 5212 5213 * Check the `autoconf' version carefully. You want to be using the 5214 version taken from the `binutils' snapshot directory, which can be 5215 found at `ftp://sources.redhat.com/pub/binutils/'. It is very 5216 unlikely that a system installed version of `autoconf' (e.g., 5217 `/usr/bin/autoconf') is correct. 5218 5219Check out the relevant modules: 5220............................... 5221 5222 $ for m in gdb insight dejagnu 5223 do 5224 ( mkdir -p $m && cd $m && cvs -q -f -d /cvs/src co -P -r $b $m ) 5225 done 5226 $ 5227 5228Note: 5229 5230 * The reading of `.cvsrc' is disabled (`-f') so that there isn't any 5231 confusion between what is written here and what your local `cvs' 5232 really does. 5233 5234Update relevant files. 5235...................... 5236 5237`gdb/NEWS' 5238 Major releases get their comments added as part of the mainline. 5239 Minor releases should probably mention any significant bugs that 5240 were fixed. 5241 5242 Don't forget to include the `ChangeLog' entry. 5243 5244 $ emacs gdb/src/gdb/NEWS 5245 ... 5246 c-x 4 a 5247 ... 5248 c-x c-s c-x c-c 5249 $ cp gdb/src/gdb/NEWS insight/src/gdb/NEWS 5250 $ cp gdb/src/gdb/ChangeLog insight/src/gdb/ChangeLog 5251 5252`gdb/README' 5253 You'll need to update: 5254 5255 * the version 5256 5257 * the update date 5258 5259 * who did it 5260 5261 $ emacs gdb/src/gdb/README 5262 ... 5263 c-x 4 a 5264 ... 5265 c-x c-s c-x c-c 5266 $ cp gdb/src/gdb/README insight/src/gdb/README 5267 $ cp gdb/src/gdb/ChangeLog insight/src/gdb/ChangeLog 5268 5269 _Maintainer note: Hopefully the `README' file was reviewed before 5270 the initial branch was cut so just a simple substitute is needed 5271 to get it updated._ 5272 5273 _Maintainer note: Other projects generate `README' and `INSTALL' 5274 from the core documentation. This might be worth pursuing._ 5275 5276`gdb/version.in' 5277 $ echo $v > gdb/src/gdb/version.in 5278 $ cat gdb/src/gdb/version.in 5279 5.2 5280 $ emacs gdb/src/gdb/version.in 5281 ... 5282 c-x 4 a 5283 ... Bump to version ... 5284 c-x c-s c-x c-c 5285 $ cp gdb/src/gdb/version.in insight/src/gdb/version.in 5286 $ cp gdb/src/gdb/ChangeLog insight/src/gdb/ChangeLog 5287 5288`dejagnu/src/dejagnu/configure.in' 5289 Dejagnu is more complicated. The version number is a parameter to 5290 `AM_INIT_AUTOMAKE'. Tweak it to read something like gdb-5.1.91. 5291 5292 Don't forget to re-generate `configure'. 5293 5294 Don't forget to include a `ChangeLog' entry. 5295 5296 $ emacs dejagnu/src/dejagnu/configure.in 5297 ... 5298 c-x 4 a 5299 ... 5300 c-x c-s c-x c-c 5301 $ ( cd dejagnu/src/dejagnu && autoconf ) 5302 5303 5304Do the dirty work 5305................. 5306 5307This is identical to the process used to create the daily snapshot. 5308 5309 $ for m in gdb insight 5310 do 5311 ( cd $m/src && gmake -f src-release $m.tar ) 5312 done 5313 $ ( m=dejagnu; cd $m/src && gmake -f src-release $m.tar.bz2 ) 5314 5315 If the top level source directory does not have `src-release' (GDB 5316version 5.3.1 or earlier), try these commands instead: 5317 5318 $ for m in gdb insight 5319 do 5320 ( cd $m/src && gmake -f Makefile.in $m.tar ) 5321 done 5322 $ ( m=dejagnu; cd $m/src && gmake -f Makefile.in $m.tar.bz2 ) 5323 5324Check the source files 5325...................... 5326 5327You're looking for files that have mysteriously disappeared. 5328`distclean' has the habit of deleting files it shouldn't. Watch out 5329for the `version.in' update `cronjob'. 5330 5331 $ ( cd gdb/src && cvs -f -q -n update ) 5332 M djunpack.bat 5333 ? gdb-5.1.91.tar 5334 ? proto-toplev 5335 ... lots of generated files ... 5336 M gdb/ChangeLog 5337 M gdb/NEWS 5338 M gdb/README 5339 M gdb/version.in 5340 ... lots of generated files ... 5341 $ 5342 5343_Don't worry about the `gdb.info-??' or `gdb/p-exp.tab.c'. They were 5344generated (and yes `gdb.info-1' was also generated only something 5345strange with CVS means that they didn't get supressed). Fixing it 5346would be nice though._ 5347 5348Create compressed versions of the release 5349......................................... 5350 5351 $ cp */src/*.tar . 5352 $ cp */src/*.bz2 . 5353 $ ls -F 5354 dejagnu/ dejagnu-gdb-5.2.tar.bz2 gdb/ gdb-5.2.tar insight/ insight-5.2.tar 5355 $ for m in gdb insight 5356 do 5357 bzip2 -v -9 -c $m-$v.tar > $m-$v.tar.bz2 5358 gzip -v -9 -c $m-$v.tar > $m-$v.tar.gz 5359 done 5360 $ 5361 5362Note: 5363 5364 * A pipe such as `bunzip2 < xxx.bz2 | gzip -9 > xxx.gz' is not since, 5365 in that mode, `gzip' does not know the name of the file and, hence, 5366 can not include it in the compressed file. This is also why the 5367 release process runs `tar' and `bzip2' as separate passes. 5368 5369Sanity check the tar ball 5370------------------------- 5371 5372Pick a popular machine (Solaris/PPC?) and try the build on that. 5373 5374 $ bunzip2 < gdb-5.2.tar.bz2 | tar xpf - 5375 $ cd gdb-5.2 5376 $ ./configure 5377 $ make 5378 ... 5379 $ ./gdb/gdb ./gdb/gdb 5380 GNU gdb 5.2 5381 ... 5382 (gdb) b main 5383 Breakpoint 1 at 0x80732bc: file main.c, line 734. 5384 (gdb) run 5385 Starting program: /tmp/gdb-5.2/gdb/gdb 5386 5387 Breakpoint 1, main (argc=1, argv=0xbffff8b4) at main.c:734 5388 734 catch_errors (captured_main, &args, "", RETURN_MASK_ALL); 5389 (gdb) print args 5390 $1 = {argc = 136426532, argv = 0x821b7f0} 5391 (gdb) 5392 5393Make a release candidate available 5394---------------------------------- 5395 5396If this is a release candidate then the only remaining steps are: 5397 5398 1. Commit `version.in' and `ChangeLog' 5399 5400 2. Tweak `version.in' (and `ChangeLog' to read L.M.N-0000-00-00-cvs 5401 so that the version update process can restart. 5402 5403 3. Make the release candidate available in 5404 `ftp://sources.redhat.com/pub/gdb/snapshots/branch' 5405 5406 4. Notify the relevant mailing lists ( <gdb@sources.redhat.com> and 5407 <gdb-testers@sources.redhat.com> that the candidate is available. 5408 5409Make a formal release available 5410------------------------------- 5411 5412(And you thought all that was required was to post an e-mail.) 5413 5414Install on sware 5415................ 5416 5417Copy the new files to both the release and the old release directory: 5418 5419 $ cp *.bz2 *.gz ~ftp/pub/gdb/old-releases/ 5420 $ cp *.bz2 *.gz ~ftp/pub/gdb/releases 5421 5422Clean up the releases directory so that only the most recent releases 5423are available (e.g. keep 5.2 and 5.2.1 but remove 5.1): 5424 5425 $ cd ~ftp/pub/gdb/releases 5426 $ rm ... 5427 5428Update the file `README' and `.message' in the releases directory: 5429 5430 $ vi README 5431 ... 5432 $ rm -f .message 5433 $ ln README .message 5434 5435Update the web pages. 5436..................... 5437 5438`htdocs/download/ANNOUNCEMENT' 5439 This file, which is posted as the official announcement, includes: 5440 * General announcement 5441 5442 * News. If making an M.N.1 release, retain the news from 5443 earlier M.N release. 5444 5445 * Errata 5446 5447`htdocs/index.html' 5448`htdocs/news/index.html' 5449`htdocs/download/index.html' 5450 These files include: 5451 * announcement of the most recent release 5452 5453 * news entry (remember to update both the top level and the 5454 news directory). 5455 These pages also need to be regenerate using `index.sh'. 5456 5457`download/onlinedocs/' 5458 You need to find the magic command that is used to generate the 5459 online docs from the `.tar.bz2'. The best way is to look in the 5460 output from one of the nightly `cron' jobs and then just edit 5461 accordingly. Something like: 5462 5463 $ ~/ss/update-web-docs \ 5464 ~ftp/pub/gdb/releases/gdb-5.2.tar.bz2 \ 5465 $PWD/www \ 5466 /www/sourceware/htdocs/gdb/download/onlinedocs \ 5467 gdb 5468 5469`download/ari/' 5470 Just like the online documentation. Something like: 5471 5472 $ /bin/sh ~/ss/update-web-ari \ 5473 ~ftp/pub/gdb/releases/gdb-5.2.tar.bz2 \ 5474 $PWD/www \ 5475 /www/sourceware/htdocs/gdb/download/ari \ 5476 gdb 5477 5478 5479Shadow the pages onto gnu 5480......................... 5481 5482Something goes here. 5483 5484Install the GDB tar ball on GNU 5485............................... 5486 5487At the time of writing, the GNU machine was `gnudist.gnu.org' in 5488`~ftp/gnu/gdb'. 5489 5490Make the `ANNOUNCEMENT' 5491....................... 5492 5493Post the `ANNOUNCEMENT' file you created above to: 5494 5495 * GDB Announcement mailing list <gdb-announce@sources.redhat.com> 5496 5497 * General GNU Announcement list <info-gnu@gnu.org> (but delay it a 5498 day or so to let things get out) 5499 5500 * GDB Bug Report mailing list <bug-gdb@gnu.org> 5501 5502Cleanup 5503------- 5504 5505The release is out but you're still not finished. 5506 5507Commit outstanding changes 5508.......................... 5509 5510In particular you'll need to commit any changes to: 5511 5512 * `gdb/ChangeLog' 5513 5514 * `gdb/version.in' 5515 5516 * `gdb/NEWS' 5517 5518 * `gdb/README' 5519 5520Tag the release 5521............... 5522 5523Something like: 5524 5525 $ d=`date -u +%Y-%m-%d` 5526 $ echo $d 5527 2002-01-24 5528 $ ( cd insight/src/gdb && cvs -f -q update ) 5529 $ ( cd insight/src && cvs -f -q tag gdb_5_2-$d-release ) 5530 5531 Insight is used since that contains more of the release than GDB 5532(`dejagnu' doesn't get tagged but I think we can live with that). 5533 5534Mention the release on the trunk 5535................................ 5536 5537Just put something in the `ChangeLog' so that the trunk also indicates 5538when the release was made. 5539 5540Restart `gdb/version.in' 5541........................ 5542 5543If `gdb/version.in' does not contain an ISO date such as `2002-01-24' 5544then the daily `cronjob' won't update it. Having committed all the 5545release changes it can be set to `5.2.0_0000-00-00-cvs' which will 5546restart things (yes the `_' is important - it affects the snapshot 5547process). 5548 5549 Don't forget the `ChangeLog'. 5550 5551Merge into trunk 5552................ 5553 5554The files committed to the branch may also need changes merged into the 5555trunk. 5556 5557Revise the release schedule 5558........................... 5559 5560Post a revised release schedule to GDB Discussion List 5561<gdb@sources.redhat.com> with an updated announcement. The schedule 5562can be generated by running: 5563 5564 $ ~/ss/schedule `date +%s` schedule 5565 5566The first parameter is approximate date/time in seconds (from the epoch) 5567of the most recent release. 5568 5569 Also update the schedule `cronjob'. 5570 5571Post release 5572============ 5573 5574Remove any `OBSOLETE' code. 5575 5576 5577File: gdbint.info, Node: Testsuite, Next: Hints, Prev: Releasing GDB, Up: Top 5578 5579Testsuite 5580********* 5581 5582The testsuite is an important component of the GDB package. While it 5583is always worthwhile to encourage user testing, in practice this is 5584rarely sufficient; users typically use only a small subset of the 5585available commands, and it has proven all too common for a change to 5586cause a significant regression that went unnoticed for some time. 5587 5588 The GDB testsuite uses the DejaGNU testing framework. DejaGNU is 5589built using `Tcl' and `expect'. The tests themselves are calls to 5590various `Tcl' procs; the framework runs all the procs and summarizes 5591the passes and fails. 5592 5593Using the Testsuite 5594=================== 5595 5596To run the testsuite, simply go to the GDB object directory (or to the 5597testsuite's objdir) and type `make check'. This just sets up some 5598environment variables and invokes DejaGNU's `runtest' script. While 5599the testsuite is running, you'll get mentions of which test file is in 5600use, and a mention of any unexpected passes or fails. When the 5601testsuite is finished, you'll get a summary that looks like this: 5602 5603 === gdb Summary === 5604 5605 # of expected passes 6016 5606 # of unexpected failures 58 5607 # of unexpected successes 5 5608 # of expected failures 183 5609 # of unresolved testcases 3 5610 # of untested testcases 5 5611 5612 The ideal test run consists of expected passes only; however, reality 5613conspires to keep us from this ideal. Unexpected failures indicate 5614real problems, whether in GDB or in the testsuite. Expected failures 5615are still failures, but ones which have been decided are too hard to 5616deal with at the time; for instance, a test case might work everywhere 5617except on AIX, and there is no prospect of the AIX case being fixed in 5618the near future. Expected failures should not be added lightly, since 5619you may be masking serious bugs in GDB. Unexpected successes are 5620expected fails that are passing for some reason, while unresolved and 5621untested cases often indicate some minor catastrophe, such as the 5622compiler being unable to deal with a test program. 5623 5624 When making any significant change to GDB, you should run the 5625testsuite before and after the change, to confirm that there are no 5626regressions. Note that truly complete testing would require that you 5627run the testsuite with all supported configurations and a variety of 5628compilers; however this is more than really necessary. In many cases 5629testing with a single configuration is sufficient. Other useful 5630options are to test one big-endian (Sparc) and one little-endian (x86) 5631host, a cross config with a builtin simulator (powerpc-eabi, mips-elf), 5632or a 64-bit host (Alpha). 5633 5634 If you add new functionality to GDB, please consider adding tests 5635for it as well; this way future GDB hackers can detect and fix their 5636changes that break the functionality you added. Similarly, if you fix 5637a bug that was not previously reported as a test failure, please add a 5638test case for it. Some cases are extremely difficult to test, such as 5639code that handles host OS failures or bugs in particular versions of 5640compilers, and it's OK not to try to write tests for all of those. 5641 5642Testsuite Organization 5643====================== 5644 5645The testsuite is entirely contained in `gdb/testsuite'. While the 5646testsuite includes some makefiles and configury, these are very minimal, 5647and used for little besides cleaning up, since the tests themselves 5648handle the compilation of the programs that GDB will run. The file 5649`testsuite/lib/gdb.exp' contains common utility procs useful for all 5650GDB tests, while the directory `testsuite/config' contains 5651configuration-specific files, typically used for special-purpose 5652definitions of procs like `gdb_load' and `gdb_start'. 5653 5654 The tests themselves are to be found in `testsuite/gdb.*' and 5655subdirectories of those. The names of the test files must always end 5656with `.exp'. DejaGNU collects the test files by wildcarding in the 5657test directories, so both subdirectories and individual files get 5658chosen and run in alphabetical order. 5659 5660 The following table lists the main types of subdirectories and what 5661they are for. Since DejaGNU finds test files no matter where they are 5662located, and since each test file sets up its own compilation and 5663execution environment, this organization is simply for convenience and 5664intelligibility. 5665 5666`gdb.base' 5667 This is the base testsuite. The tests in it should apply to all 5668 configurations of GDB (but generic native-only tests may live 5669 here). The test programs should be in the subset of C that is 5670 valid K&R, ANSI/ISO, and C++ (`#ifdef's are allowed if necessary, 5671 for instance for prototypes). 5672 5673`gdb.LANG' 5674 Language-specific tests for any language LANG besides C. Examples 5675 are `gdb.cp' and `gdb.java'. 5676 5677`gdb.PLATFORM' 5678 Non-portable tests. The tests are specific to a specific 5679 configuration (host or target), such as HP-UX or eCos. Example is 5680 `gdb.hp', for HP-UX. 5681 5682`gdb.COMPILER' 5683 Tests specific to a particular compiler. As of this writing (June 5684 1999), there aren't currently any groups of tests in this category 5685 that couldn't just as sensibly be made platform-specific, but one 5686 could imagine a `gdb.gcc', for tests of GDB's handling of GCC 5687 extensions. 5688 5689`gdb.SUBSYSTEM' 5690 Tests that exercise a specific GDB subsystem in more depth. For 5691 instance, `gdb.disasm' exercises various disassemblers, while 5692 `gdb.stabs' tests pathways through the stabs symbol reader. 5693 5694Writing Tests 5695============= 5696 5697In many areas, the GDB tests are already quite comprehensive; you 5698should be able to copy existing tests to handle new cases. 5699 5700 You should try to use `gdb_test' whenever possible, since it 5701includes cases to handle all the unexpected errors that might happen. 5702However, it doesn't cost anything to add new test procedures; for 5703instance, `gdb.base/exprs.exp' defines a `test_expr' that calls 5704`gdb_test' multiple times. 5705 5706 Only use `send_gdb' and `gdb_expect' when absolutely necessary, such 5707as when GDB has several valid responses to a command. 5708 5709 The source language programs do _not_ need to be in a consistent 5710style. Since GDB is used to debug programs written in many different 5711styles, it's worth having a mix of styles in the testsuite; for 5712instance, some GDB bugs involving the display of source lines would 5713never manifest themselves if the programs used GNU coding style 5714uniformly. 5715 5716 5717File: gdbint.info, Node: Hints, Next: GDB Observers, Prev: Testsuite, Up: Top 5718 5719Hints 5720***** 5721 5722Check the `README' file, it often has useful information that does not 5723appear anywhere else in the directory. 5724 5725* Menu: 5726 5727* Getting Started:: Getting started working on GDB 5728* Debugging GDB:: Debugging GDB with itself 5729 5730 5731File: gdbint.info, Node: Getting Started, Up: Hints 5732 5733Getting Started 5734=============== 5735 5736GDB is a large and complicated program, and if you first starting to 5737work on it, it can be hard to know where to start. Fortunately, if you 5738know how to go about it, there are ways to figure out what is going on. 5739 5740 This manual, the GDB Internals manual, has information which applies 5741generally to many parts of GDB. 5742 5743 Information about particular functions or data structures are 5744located in comments with those functions or data structures. If you 5745run across a function or a global variable which does not have a 5746comment correctly explaining what is does, this can be thought of as a 5747bug in GDB; feel free to submit a bug report, with a suggested comment 5748if you can figure out what the comment should say. If you find a 5749comment which is actually wrong, be especially sure to report that. 5750 5751 Comments explaining the function of macros defined in host, target, 5752or native dependent files can be in several places. Sometimes they are 5753repeated every place the macro is defined. Sometimes they are where the 5754macro is used. Sometimes there is a header file which supplies a 5755default definition of the macro, and the comment is there. This manual 5756also documents all the available macros. 5757 5758 Start with the header files. Once you have some idea of how GDB's 5759internal symbol tables are stored (see `symtab.h', `gdbtypes.h'), you 5760will find it much easier to understand the code which uses and creates 5761those symbol tables. 5762 5763 You may wish to process the information you are getting somehow, to 5764enhance your understanding of it. Summarize it, translate it to another 5765language, add some (perhaps trivial or non-useful) feature to GDB, use 5766the code to predict what a test case would do and write the test case 5767and verify your prediction, etc. If you are reading code and your eyes 5768are starting to glaze over, this is a sign you need to use a more active 5769approach. 5770 5771 Once you have a part of GDB to start with, you can find more 5772specifically the part you are looking for by stepping through each 5773function with the `next' command. Do not use `step' or you will 5774quickly get distracted; when the function you are stepping through 5775calls another function try only to get a big-picture understanding 5776(perhaps using the comment at the beginning of the function being 5777called) of what it does. This way you can identify which of the 5778functions being called by the function you are stepping through is the 5779one which you are interested in. You may need to examine the data 5780structures generated at each stage, with reference to the comments in 5781the header files explaining what the data structures are supposed to 5782look like. 5783 5784 Of course, this same technique can be used if you are just reading 5785the code, rather than actually stepping through it. The same general 5786principle applies--when the code you are looking at calls something 5787else, just try to understand generally what the code being called does, 5788rather than worrying about all its details. 5789 5790 A good place to start when tracking down some particular area is with 5791a command which invokes that feature. Suppose you want to know how 5792single-stepping works. As a GDB user, you know that the `step' command 5793invokes single-stepping. The command is invoked via command tables 5794(see `command.h'); by convention the function which actually performs 5795the command is formed by taking the name of the command and adding 5796`_command', or in the case of an `info' subcommand, `_info'. For 5797example, the `step' command invokes the `step_command' function and the 5798`info display' command invokes `display_info'. When this convention is 5799not followed, you might have to use `grep' or `M-x tags-search' in 5800emacs, or run GDB on itself and set a breakpoint in `execute_command'. 5801 5802 If all of the above fail, it may be appropriate to ask for 5803information on `bug-gdb'. But _never_ post a generic question like "I 5804was wondering if anyone could give me some tips about understanding 5805GDB"--if we had some magic secret we would put it in this manual. 5806Suggestions for improving the manual are always welcome, of course. 5807 5808 5809File: gdbint.info, Node: Debugging GDB, Up: Hints 5810 5811Debugging GDB with itself 5812========================= 5813 5814If GDB is limping on your machine, this is the preferred way to get it 5815fully functional. Be warned that in some ancient Unix systems, like 5816Ultrix 4.2, a program can't be running in one process while it is being 5817debugged in another. Rather than typing the command `./gdb ./gdb', 5818which works on Suns and such, you can copy `gdb' to `gdb2' and then 5819type `./gdb ./gdb2'. 5820 5821 When you run GDB in the GDB source directory, it will read a 5822`.gdbinit' file that sets up some simple things to make debugging gdb 5823easier. The `info' command, when executed without a subcommand in a 5824GDB being debugged by gdb, will pop you back up to the top level gdb. 5825See `.gdbinit' for details. 5826 5827 If you use emacs, you will probably want to do a `make TAGS' after 5828you configure your distribution; this will put the machine dependent 5829routines for your local machine where they will be accessed first by 5830`M-.' 5831 5832 Also, make sure that you've either compiled GDB with your local cc, 5833or have run `fixincludes' if you are compiling with gcc. 5834 5835Submitting Patches 5836================== 5837 5838Thanks for thinking of offering your changes back to the community of 5839GDB users. In general we like to get well designed enhancements. 5840Thanks also for checking in advance about the best way to transfer the 5841changes. 5842 5843 The GDB maintainers will only install "cleanly designed" patches. 5844This manual summarizes what we believe to be clean design for GDB. 5845 5846 If the maintainers don't have time to put the patch in when it 5847arrives, or if there is any question about a patch, it goes into a 5848large queue with everyone else's patches and bug reports. 5849 5850 The legal issue is that to incorporate substantial changes requires a 5851copyright assignment from you and/or your employer, granting ownership 5852of the changes to the Free Software Foundation. You can get the 5853standard documents for doing this by sending mail to `gnu@gnu.org' and 5854asking for it. We recommend that people write in "All programs owned 5855by the Free Software Foundation" as "NAME OF PROGRAM", so that changes 5856in many programs (not just GDB, but GAS, Emacs, GCC, etc) can be 5857contributed with only one piece of legalese pushed through the 5858bureaucracy and filed with the FSF. We can't start merging changes 5859until this paperwork is received by the FSF (their rules, which we 5860follow since we maintain it for them). 5861 5862 Technically, the easiest way to receive changes is to receive each 5863feature as a small context diff or unidiff, suitable for `patch'. Each 5864message sent to me should include the changes to C code and header 5865files for a single feature, plus `ChangeLog' entries for each directory 5866where files were modified, and diffs for any changes needed to the 5867manuals (`gdb/doc/gdb.texinfo' or `gdb/doc/gdbint.texinfo'). If there 5868are a lot of changes for a single feature, they can be split down into 5869multiple messages. 5870 5871 In this way, if we read and like the feature, we can add it to the 5872sources with a single patch command, do some testing, and check it in. 5873If you leave out the `ChangeLog', we have to write one. If you leave 5874out the doc, we have to puzzle out what needs documenting. Etc., etc. 5875 5876 The reason to send each change in a separate message is that we will 5877not install some of the changes. They'll be returned to you with 5878questions or comments. If we're doing our job correctly, the message 5879back to you will say what you have to fix in order to make the change 5880acceptable. The reason to have separate messages for separate features 5881is so that the acceptable changes can be installed while one or more 5882changes are being reworked. If multiple features are sent in a single 5883message, we tend to not put in the effort to sort out the acceptable 5884changes from the unacceptable, so none of the features get installed 5885until all are acceptable. 5886 5887 If this sounds painful or authoritarian, well, it is. But we get a 5888lot of bug reports and a lot of patches, and many of them don't get 5889installed because we don't have the time to finish the job that the bug 5890reporter or the contributor could have done. Patches that arrive 5891complete, working, and well designed, tend to get installed on the day 5892they arrive. The others go into a queue and get installed as time 5893permits, which, since the maintainers have many demands to meet, may not 5894be for quite some time. 5895 5896 Please send patches directly to the GDB maintainers 5897<gdb-patches@sources.redhat.com>. 5898 5899Obsolete Conditionals 5900===================== 5901 5902Fragments of old code in GDB sometimes reference or set the following 5903configuration macros. They should not be used by new code, and old uses 5904should be removed as those parts of the debugger are otherwise touched. 5905 5906`STACK_END_ADDR' 5907 This macro used to define where the end of the stack appeared, for 5908 use in interpreting core file formats that don't record this 5909 address in the core file itself. This information is now 5910 configured in BFD, and GDB gets the info portably from there. The 5911 values in GDB's configuration files should be moved into BFD 5912 configuration files (if needed there), and deleted from all of 5913 GDB's config files. 5914 5915 Any `FOO-xdep.c' file that references STACK_END_ADDR is so old 5916 that it has never been converted to use BFD. Now that's old! 5917 5918 5919 5920File: gdbint.info, Node: GDB Observers, Next: GNU Free Documentation License, Prev: Hints, Up: Top 5921 5922GDB Currently available observers 5923********************************* 5924 5925Implementation rationale 5926======================== 5927 5928An "observer" is an entity which is interested in being notified when 5929GDB reaches certain states, or certain events occur in GDB. The entity 5930being observed is called the "subject". To receive notifications, the 5931observer attaches a callback to the subject. One subject can have 5932several observers. 5933 5934 `observer.c' implements an internal generic low-level event 5935notification mechanism. This generic event notification mechanism is 5936then re-used to implement the exported high-level notification 5937management routines for all possible notifications. 5938 5939 The current implementation of the generic observer provides support 5940for contextual data. This contextual data is given to the subject when 5941attaching the callback. In return, the subject will provide this 5942contextual data back to the observer as a parameter of the callback. 5943 5944 Note that the current support for the contextual data is only 5945partial, as it lacks a mechanism that would deallocate this data when 5946the callback is detached. This is not a problem so far, as this 5947contextual data is only used internally to hold a function pointer. 5948Later on, if a certain observer needs to provide support for user-level 5949contextual data, then the generic notification mechanism will need to be 5950enhanced to allow the observer to provide a routine to deallocate the 5951data when attaching the callback. 5952 5953 The observer implementation is also currently not reentrant. In 5954particular, it is therefore not possible to call the attach or detach 5955routines during a notification. 5956 5957Debugging 5958========= 5959 5960Observer notifications can be traced using the command `set debug 5961observer 1' (*note Optional messages about internal happenings: 5962(gdb)Debugging Output.). 5963 5964`normal_stop' Notifications 5965=========================== 5966 5967GDB notifies all `normal_stop' observers when the inferior execution 5968has just stopped, the associated messages and annotations have been 5969printed, and the control is about to be returned to the user. 5970 5971 Note that the `normal_stop' notification is not emitted when the 5972execution stops due to a breakpoint, and this breakpoint has a 5973condition that is not met. If the breakpoint has any associated 5974commands list, the commands are executed after the notification is 5975emitted. 5976 5977 The following interfaces are available to manage observers: 5978 5979 - Function: extern struct observer *observer_attach_EVENT 5980 (observer_EVENT_ftype *F) 5981 Using the function F, create an observer that is notified when 5982 ever EVENT occures, return the observer. 5983 5984 - Function: extern void observer_detach_EVENT (struct observer 5985 *OBSERVER); 5986 Remove OBSERVER from the list of observers to be notified when 5987 EVENT occurs. 5988 5989 - Function: extern void observer_notify_EVENT (void); 5990 Send a notification to all EVENT observers. 5991 5992 The following observable events are defined: 5993 5994 - Function: void normal_stop (struct bpstats *BS) 5995 The inferior has stopped for real. 5996 5997 - Function: void target_changed (struct target_ops *TARGET) 5998 The target's register contents have changed. 5999 6000 - Function: void inferior_created (struct target_ops *OBJFILE, int 6001 FROM_TTY) 6002 GDB has just connected to an inferior. For `run', GDB calls this 6003 observer while the inferior is still stopped at the entry-point 6004 instruction. For `attach' and `core', GDB calls this observer 6005 immediately after connecting to the inferior, and before any 6006 information on the inferior has been printed. 6007 6008 6009File: gdbint.info, Node: GNU Free Documentation License, Next: Index, Prev: GDB Observers, Up: Top 6010 6011GNU Free Documentation License 6012****************************** 6013 6014 Version 1.2, November 2002 6015 Copyright (C) 2000,2001,2002 Free Software Foundation, Inc. 6016 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA 6017 6018 Everyone is permitted to copy and distribute verbatim copies 6019 of this license document, but changing it is not allowed. 6020 6021 0. PREAMBLE 6022 6023 The purpose of this License is to make a manual, textbook, or other 6024 functional and useful document "free" in the sense of freedom: to 6025 assure everyone the effective freedom to copy and redistribute it, 6026 with or without modifying it, either commercially or 6027 noncommercially. Secondarily, this License preserves for the 6028 author and publisher a way to get credit for their work, while not 6029 being considered responsible for modifications made by others. 6030 6031 This License is a kind of "copyleft", which means that derivative 6032 works of the document must themselves be free in the same sense. 6033 It complements the GNU General Public License, which is a copyleft 6034 license designed for free software. 6035 6036 We have designed this License in order to use it for manuals for 6037 free software, because free software needs free documentation: a 6038 free program should come with manuals providing the same freedoms 6039 that the software does. But this License is not limited to 6040 software manuals; it can be used for any textual work, regardless 6041 of subject matter or whether it is published as a printed book. 6042 We recommend this License principally for works whose purpose is 6043 instruction or reference. 6044 6045 1. APPLICABILITY AND DEFINITIONS 6046 6047 This License applies to any manual or other work, in any medium, 6048 that contains a notice placed by the copyright holder saying it 6049 can be distributed under the terms of this License. Such a notice 6050 grants a world-wide, royalty-free license, unlimited in duration, 6051 to use that work under the conditions stated herein. The 6052 "Document", below, refers to any such manual or work. Any member 6053 of the public is a licensee, and is addressed as "you". You 6054 accept the license if you copy, modify or distribute the work in a 6055 way requiring permission under copyright law. 6056 6057 A "Modified Version" of the Document means any work containing the 6058 Document or a portion of it, either copied verbatim, or with 6059 modifications and/or translated into another language. 6060 6061 A "Secondary Section" is a named appendix or a front-matter section 6062 of the Document that deals exclusively with the relationship of the 6063 publishers or authors of the Document to the Document's overall 6064 subject (or to related matters) and contains nothing that could 6065 fall directly within that overall subject. (Thus, if the Document 6066 is in part a textbook of mathematics, a Secondary Section may not 6067 explain any mathematics.) The relationship could be a matter of 6068 historical connection with the subject or with related matters, or 6069 of legal, commercial, philosophical, ethical or political position 6070 regarding them. 6071 6072 The "Invariant Sections" are certain Secondary Sections whose 6073 titles are designated, as being those of Invariant Sections, in 6074 the notice that says that the Document is released under this 6075 License. If a section does not fit the above definition of 6076 Secondary then it is not allowed to be designated as Invariant. 6077 The Document may contain zero Invariant Sections. If the Document 6078 does not identify any Invariant Sections then there are none. 6079 6080 The "Cover Texts" are certain short passages of text that are 6081 listed, as Front-Cover Texts or Back-Cover Texts, in the notice 6082 that says that the Document is released under this License. A 6083 Front-Cover Text may be at most 5 words, and a Back-Cover Text may 6084 be at most 25 words. 6085 6086 A "Transparent" copy of the Document means a machine-readable copy, 6087 represented in a format whose specification is available to the 6088 general public, that is suitable for revising the document 6089 straightforwardly with generic text editors or (for images 6090 composed of pixels) generic paint programs or (for drawings) some 6091 widely available drawing editor, and that is suitable for input to 6092 text formatters or for automatic translation to a variety of 6093 formats suitable for input to text formatters. A copy made in an 6094 otherwise Transparent file format whose markup, or absence of 6095 markup, has been arranged to thwart or discourage subsequent 6096 modification by readers is not Transparent. An image format is 6097 not Transparent if used for any substantial amount of text. A 6098 copy that is not "Transparent" is called "Opaque". 6099 6100 Examples of suitable formats for Transparent copies include plain 6101 ASCII without markup, Texinfo input format, LaTeX input format, 6102 SGML or XML using a publicly available DTD, and 6103 standard-conforming simple HTML, PostScript or PDF designed for 6104 human modification. Examples of transparent image formats include 6105 PNG, XCF and JPG. Opaque formats include proprietary formats that 6106 can be read and edited only by proprietary word processors, SGML or 6107 XML for which the DTD and/or processing tools are not generally 6108 available, and the machine-generated HTML, PostScript or PDF 6109 produced by some word processors for output purposes only. 6110 6111 The "Title Page" means, for a printed book, the title page itself, 6112 plus such following pages as are needed to hold, legibly, the 6113 material this License requires to appear in the title page. For 6114 works in formats which do not have any title page as such, "Title 6115 Page" means the text near the most prominent appearance of the 6116 work's title, preceding the beginning of the body of the text. 6117 6118 A section "Entitled XYZ" means a named subunit of the Document 6119 whose title either is precisely XYZ or contains XYZ in parentheses 6120 following text that translates XYZ in another language. (Here XYZ 6121 stands for a specific section name mentioned below, such as 6122 "Acknowledgements", "Dedications", "Endorsements", or "History".) 6123 To "Preserve the Title" of such a section when you modify the 6124 Document means that it remains a section "Entitled XYZ" according 6125 to this definition. 6126 6127 The Document may include Warranty Disclaimers next to the notice 6128 which states that this License applies to the Document. These 6129 Warranty Disclaimers are considered to be included by reference in 6130 this License, but only as regards disclaiming warranties: any other 6131 implication that these Warranty Disclaimers may have is void and 6132 has no effect on the meaning of this License. 6133 6134 2. VERBATIM COPYING 6135 6136 You may copy and distribute the Document in any medium, either 6137 commercially or noncommercially, provided that this License, the 6138 copyright notices, and the license notice saying this License 6139 applies to the Document are reproduced in all copies, and that you 6140 add no other conditions whatsoever to those of this License. You 6141 may not use technical measures to obstruct or control the reading 6142 or further copying of the copies you make or distribute. However, 6143 you may accept compensation in exchange for copies. If you 6144 distribute a large enough number of copies you must also follow 6145 the conditions in section 3. 6146 6147 You may also lend copies, under the same conditions stated above, 6148 and you may publicly display copies. 6149 6150 3. COPYING IN QUANTITY 6151 6152 If you publish printed copies (or copies in media that commonly 6153 have printed covers) of the Document, numbering more than 100, and 6154 the Document's license notice requires Cover Texts, you must 6155 enclose the copies in covers that carry, clearly and legibly, all 6156 these Cover Texts: Front-Cover Texts on the front cover, and 6157 Back-Cover Texts on the back cover. Both covers must also clearly 6158 and legibly identify you as the publisher of these copies. The 6159 front cover must present the full title with all words of the 6160 title equally prominent and visible. You may add other material 6161 on the covers in addition. Copying with changes limited to the 6162 covers, as long as they preserve the title of the Document and 6163 satisfy these conditions, can be treated as verbatim copying in 6164 other respects. 6165 6166 If the required texts for either cover are too voluminous to fit 6167 legibly, you should put the first ones listed (as many as fit 6168 reasonably) on the actual cover, and continue the rest onto 6169 adjacent pages. 6170 6171 If you publish or distribute Opaque copies of the Document 6172 numbering more than 100, you must either include a 6173 machine-readable Transparent copy along with each Opaque copy, or 6174 state in or with each Opaque copy a computer-network location from 6175 which the general network-using public has access to download 6176 using public-standard network protocols a complete Transparent 6177 copy of the Document, free of added material. If you use the 6178 latter option, you must take reasonably prudent steps, when you 6179 begin distribution of Opaque copies in quantity, to ensure that 6180 this Transparent copy will remain thus accessible at the stated 6181 location until at least one year after the last time you 6182 distribute an Opaque copy (directly or through your agents or 6183 retailers) of that edition to the public. 6184 6185 It is requested, but not required, that you contact the authors of 6186 the Document well before redistributing any large number of 6187 copies, to give them a chance to provide you with an updated 6188 version of the Document. 6189 6190 4. MODIFICATIONS 6191 6192 You may copy and distribute a Modified Version of the Document 6193 under the conditions of sections 2 and 3 above, provided that you 6194 release the Modified Version under precisely this License, with 6195 the Modified Version filling the role of the Document, thus 6196 licensing distribution and modification of the Modified Version to 6197 whoever possesses a copy of it. In addition, you must do these 6198 things in the Modified Version: 6199 6200 A. Use in the Title Page (and on the covers, if any) a title 6201 distinct from that of the Document, and from those of 6202 previous versions (which should, if there were any, be listed 6203 in the History section of the Document). You may use the 6204 same title as a previous version if the original publisher of 6205 that version gives permission. 6206 6207 B. List on the Title Page, as authors, one or more persons or 6208 entities responsible for authorship of the modifications in 6209 the Modified Version, together with at least five of the 6210 principal authors of the Document (all of its principal 6211 authors, if it has fewer than five), unless they release you 6212 from this requirement. 6213 6214 C. State on the Title page the name of the publisher of the 6215 Modified Version, as the publisher. 6216 6217 D. Preserve all the copyright notices of the Document. 6218 6219 E. Add an appropriate copyright notice for your modifications 6220 adjacent to the other copyright notices. 6221 6222 F. Include, immediately after the copyright notices, a license 6223 notice giving the public permission to use the Modified 6224 Version under the terms of this License, in the form shown in 6225 the Addendum below. 6226 6227 G. Preserve in that license notice the full lists of Invariant 6228 Sections and required Cover Texts given in the Document's 6229 license notice. 6230 6231 H. Include an unaltered copy of this License. 6232 6233 I. Preserve the section Entitled "History", Preserve its Title, 6234 and add to it an item stating at least the title, year, new 6235 authors, and publisher of the Modified Version as given on 6236 the Title Page. If there is no section Entitled "History" in 6237 the Document, create one stating the title, year, authors, 6238 and publisher of the Document as given on its Title Page, 6239 then add an item describing the Modified Version as stated in 6240 the previous sentence. 6241 6242 J. Preserve the network location, if any, given in the Document 6243 for public access to a Transparent copy of the Document, and 6244 likewise the network locations given in the Document for 6245 previous versions it was based on. These may be placed in 6246 the "History" section. You may omit a network location for a 6247 work that was published at least four years before the 6248 Document itself, or if the original publisher of the version 6249 it refers to gives permission. 6250 6251 K. For any section Entitled "Acknowledgements" or "Dedications", 6252 Preserve the Title of the section, and preserve in the 6253 section all the substance and tone of each of the contributor 6254 acknowledgements and/or dedications given therein. 6255 6256 L. Preserve all the Invariant Sections of the Document, 6257 unaltered in their text and in their titles. Section numbers 6258 or the equivalent are not considered part of the section 6259 titles. 6260 6261 M. Delete any section Entitled "Endorsements". Such a section 6262 may not be included in the Modified Version. 6263 6264 N. Do not retitle any existing section to be Entitled 6265 "Endorsements" or to conflict in title with any Invariant 6266 Section. 6267 6268 O. Preserve any Warranty Disclaimers. 6269 6270 If the Modified Version includes new front-matter sections or 6271 appendices that qualify as Secondary Sections and contain no 6272 material copied from the Document, you may at your option 6273 designate some or all of these sections as invariant. To do this, 6274 add their titles to the list of Invariant Sections in the Modified 6275 Version's license notice. These titles must be distinct from any 6276 other section titles. 6277 6278 You may add a section Entitled "Endorsements", provided it contains 6279 nothing but endorsements of your Modified Version by various 6280 parties--for example, statements of peer review or that the text 6281 has been approved by an organization as the authoritative 6282 definition of a standard. 6283 6284 You may add a passage of up to five words as a Front-Cover Text, 6285 and a passage of up to 25 words as a Back-Cover Text, to the end 6286 of the list of Cover Texts in the Modified Version. Only one 6287 passage of Front-Cover Text and one of Back-Cover Text may be 6288 added by (or through arrangements made by) any one entity. If the 6289 Document already includes a cover text for the same cover, 6290 previously added by you or by arrangement made by the same entity 6291 you are acting on behalf of, you may not add another; but you may 6292 replace the old one, on explicit permission from the previous 6293 publisher that added the old one. 6294 6295 The author(s) and publisher(s) of the Document do not by this 6296 License give permission to use their names for publicity for or to 6297 assert or imply endorsement of any Modified Version. 6298 6299 5. COMBINING DOCUMENTS 6300 6301 You may combine the Document with other documents released under 6302 this License, under the terms defined in section 4 above for 6303 modified versions, provided that you include in the combination 6304 all of the Invariant Sections of all of the original documents, 6305 unmodified, and list them all as Invariant Sections of your 6306 combined work in its license notice, and that you preserve all 6307 their Warranty Disclaimers. 6308 6309 The combined work need only contain one copy of this License, and 6310 multiple identical Invariant Sections may be replaced with a single 6311 copy. If there are multiple Invariant Sections with the same name 6312 but different contents, make the title of each such section unique 6313 by adding at the end of it, in parentheses, the name of the 6314 original author or publisher of that section if known, or else a 6315 unique number. Make the same adjustment to the section titles in 6316 the list of Invariant Sections in the license notice of the 6317 combined work. 6318 6319 In the combination, you must combine any sections Entitled 6320 "History" in the various original documents, forming one section 6321 Entitled "History"; likewise combine any sections Entitled 6322 "Acknowledgements", and any sections Entitled "Dedications". You 6323 must delete all sections Entitled "Endorsements." 6324 6325 6. COLLECTIONS OF DOCUMENTS 6326 6327 You may make a collection consisting of the Document and other 6328 documents released under this License, and replace the individual 6329 copies of this License in the various documents with a single copy 6330 that is included in the collection, provided that you follow the 6331 rules of this License for verbatim copying of each of the 6332 documents in all other respects. 6333 6334 You may extract a single document from such a collection, and 6335 distribute it individually under this License, provided you insert 6336 a copy of this License into the extracted document, and follow 6337 this License in all other respects regarding verbatim copying of 6338 that document. 6339 6340 7. AGGREGATION WITH INDEPENDENT WORKS 6341 6342 A compilation of the Document or its derivatives with other 6343 separate and independent documents or works, in or on a volume of 6344 a storage or distribution medium, is called an "aggregate" if the 6345 copyright resulting from the compilation is not used to limit the 6346 legal rights of the compilation's users beyond what the individual 6347 works permit. When the Document is included in an aggregate, this 6348 License does not apply to the other works in the aggregate which 6349 are not themselves derivative works of the Document. 6350 6351 If the Cover Text requirement of section 3 is applicable to these 6352 copies of the Document, then if the Document is less than one half 6353 of the entire aggregate, the Document's Cover Texts may be placed 6354 on covers that bracket the Document within the aggregate, or the 6355 electronic equivalent of covers if the Document is in electronic 6356 form. Otherwise they must appear on printed covers that bracket 6357 the whole aggregate. 6358 6359 8. TRANSLATION 6360 6361 Translation is considered a kind of modification, so you may 6362 distribute translations of the Document under the terms of section 6363 4. Replacing Invariant Sections with translations requires special 6364 permission from their copyright holders, but you may include 6365 translations of some or all Invariant Sections in addition to the 6366 original versions of these Invariant Sections. You may include a 6367 translation of this License, and all the license notices in the 6368 Document, and any Warranty Disclaimers, provided that you also 6369 include the original English version of this License and the 6370 original versions of those notices and disclaimers. In case of a 6371 disagreement between the translation and the original version of 6372 this License or a notice or disclaimer, the original version will 6373 prevail. 6374 6375 If a section in the Document is Entitled "Acknowledgements", 6376 "Dedications", or "History", the requirement (section 4) to 6377 Preserve its Title (section 1) will typically require changing the 6378 actual title. 6379 6380 9. TERMINATION 6381 6382 You may not copy, modify, sublicense, or distribute the Document 6383 except as expressly provided for under this License. Any other 6384 attempt to copy, modify, sublicense or distribute the Document is 6385 void, and will automatically terminate your rights under this 6386 License. However, parties who have received copies, or rights, 6387 from you under this License will not have their licenses 6388 terminated so long as such parties remain in full compliance. 6389 6390 10. FUTURE REVISIONS OF THIS LICENSE 6391 6392 The Free Software Foundation may publish new, revised versions of 6393 the GNU Free Documentation License from time to time. Such new 6394 versions will be similar in spirit to the present version, but may 6395 differ in detail to address new problems or concerns. See 6396 `http://www.gnu.org/copyleft/'. 6397 6398 Each version of the License is given a distinguishing version 6399 number. If the Document specifies that a particular numbered 6400 version of this License "or any later version" applies to it, you 6401 have the option of following the terms and conditions either of 6402 that specified version or of any later version that has been 6403 published (not as a draft) by the Free Software Foundation. If 6404 the Document does not specify a version number of this License, 6405 you may choose any version ever published (not as a draft) by the 6406 Free Software Foundation. 6407 6408ADDENDUM: How to use this License for your documents 6409==================================================== 6410 6411To use this License in a document you have written, include a copy of 6412the License in the document and put the following copyright and license 6413notices just after the title page: 6414 6415 Copyright (C) YEAR YOUR NAME. 6416 Permission is granted to copy, distribute and/or modify this document 6417 under the terms of the GNU Free Documentation License, Version 1.2 6418 or any later version published by the Free Software Foundation; 6419 with no Invariant Sections, no Front-Cover Texts, and no Back-Cover 6420 Texts. A copy of the license is included in the section entitled ``GNU 6421 Free Documentation License''. 6422 6423 If you have Invariant Sections, Front-Cover Texts and Back-Cover 6424Texts, replace the "with...Texts." line with this: 6425 6426 with the Invariant Sections being LIST THEIR TITLES, with 6427 the Front-Cover Texts being LIST, and with the Back-Cover Texts 6428 being LIST. 6429 6430 If you have Invariant Sections without Cover Texts, or some other 6431combination of the three, merge those two alternatives to suit the 6432situation. 6433 6434 If your document contains nontrivial examples of program code, we 6435recommend releasing these examples in parallel under your choice of 6436free software license, such as the GNU General Public License, to 6437permit their use in free software. 6438 6439 6440File: gdbint.info, Node: Index, Prev: GNU Free Documentation License, Up: Top 6441 6442Index 6443***** 6444 6445* Menu: 6446 6447* *ADDRESS_CLASS_TYPE_FLAGS_TO_NAME: Target Architecture Definition. 6448* *gdbarch_data: Coding. 6449* _initialize_language: Language Support. 6450* a.out format: Symbol Handling. 6451* add_cmd: User Interface. 6452* add_com: User Interface. 6453* add_setshow_cmd: User Interface. 6454* add_setshow_cmd_full: User Interface. 6455* add_symtab_fns: Symbol Handling. 6456* adding a new host: Host Definition. 6457* adding a symbol-reading module: Symbol Handling. 6458* adding a target: Target Architecture Definition. 6459* adding debugging info reader: Symbol Handling. 6460* adding source language: Language Support. 6461* ADDR_BITS_REMOVE: Target Architecture Definition. 6462* address classes: Target Architecture Definition. 6463* address representation: Target Architecture Definition. 6464* address spaces, separate data and code: Target Architecture Definition. 6465* ADDRESS_CLASS_NAME_to_TYPE_FLAGS: Target Architecture Definition. 6466* ADDRESS_CLASS_NAME_TO_TYPE_FLAGS: Target Architecture Definition. 6467* ADDRESS_CLASS_NAME_TO_TYPE_FLAGS_P: Target Architecture Definition. 6468* ADDRESS_CLASS_TYPE_FLAGS: Target Architecture Definition. 6469* ADDRESS_CLASS_TYPE_FLAGS (BYTE_SIZE, DWARF2_ADDR_CLASS): Target Architecture Definition. 6470* ADDRESS_CLASS_TYPE_FLAGS_P: Target Architecture Definition. 6471* ADDRESS_CLASS_TYPE_FLAGS_TO_NAME: Target Architecture Definition. 6472* ADDRESS_CLASS_TYPE_FLAGS_TO_NAME_P: Target Architecture Definition. 6473* ADDRESS_TO_POINTER: Target Architecture Definition. 6474* ADJUST_BREAKPOINT_ADDRESS: Target Architecture Definition. 6475* algorithms: Algorithms. 6476* ALIGN_STACK_ON_STARTUP: Host Definition. 6477* allocate_symtab: Language Support. 6478* assumptions about targets: Coding. 6479* ATTR_NORETURN: Host Definition. 6480* BELIEVE_PCC_PROMOTION: Target Architecture Definition. 6481* BFD library: Support Libraries. 6482* BIG_BREAKPOINT: Target Architecture Definition. 6483* BITS_BIG_ENDIAN: Target Architecture Definition. 6484* BPT_VECTOR: Target Architecture Definition. 6485* BREAKPOINT <1>: Target Architecture Definition. 6486* BREAKPOINT: Algorithms. 6487* breakpoint address adjusted: Target Architecture Definition. 6488* BREAKPOINT_FROM_PC: Target Architecture Definition. 6489* breakpoints: Algorithms. 6490* bug-gdb mailing list: Getting Started. 6491* C data types: Coding. 6492* call stack frame: Algorithms. 6493* CALL_DUMMY_LOCATION: Target Architecture Definition. 6494* CANNOT_FETCH_REGISTER: Target Architecture Definition. 6495* CANNOT_STEP_HW_WATCHPOINTS: Algorithms. 6496* CANNOT_STORE_REGISTER: Target Architecture Definition. 6497* CC_HAS_LONG_LONG: Host Definition. 6498* char: Target Architecture Definition. 6499* CHILD_PREPARE_TO_STORE: Native Debugging. 6500* cleanup: User Interface. 6501* cleanups: Coding. 6502* CLEAR_SOLIB: Native Debugging. 6503* CLI: User Interface. 6504* code pointers, word-addressed: Target Architecture Definition. 6505* coding standards: Coding. 6506* COFF debugging info: Symbol Handling. 6507* COFF format: Symbol Handling. 6508* command implementation: Getting Started. 6509* command interpreter: User Interface. 6510* comment formatting: Coding. 6511* compiler warnings: Coding. 6512* CONVERT_REGISTER_P: Target Architecture Definition. 6513* converting between pointers and addresses: Target Architecture Definition. 6514* converting integers to addresses: Target Architecture Definition. 6515* converting targets to multi-arch: Target Architecture Definition. 6516* create_new_frame: Algorithms. 6517* CRLF_SOURCE_FILES: Host Definition. 6518* current_language: Language Support. 6519* D10V addresses: Target Architecture Definition. 6520* data output: User Interface. 6521* data-pointer, per-architecture/per-module: Coding. 6522* DEBUG_PTRACE: Native Debugging. 6523* debugging GDB: Debugging GDB. 6524* DECR_PC_AFTER_BREAK: Target Architecture Definition. 6525* DEFAULT_PROMPT: Host Definition. 6526* deprecate_cmd: User Interface. 6527* DEPRECATED_BIG_REMOTE_BREAKPOINT: Target Architecture Definition. 6528* DEPRECATED_EXTRACT_STRUCT_VALUE_ADDRESS: Target Architecture Definition. 6529* DEPRECATED_EXTRACT_STRUCT_VALUE_ADDRESS_P: Target Architecture Definition. 6530* DEPRECATED_FP_REGNUM: Target Architecture Definition. 6531* DEPRECATED_FRAME_CHAIN: Target Architecture Definition. 6532* DEPRECATED_FRAME_CHAIN_VALID: Target Architecture Definition. 6533* DEPRECATED_FRAME_INIT_SAVED_REGS: Target Architecture Definition. 6534* DEPRECATED_FRAME_SAVED_PC: Target Architecture Definition. 6535* DEPRECATED_FRAMELESS_FUNCTION_INVOCATION: Target Architecture Definition. 6536* DEPRECATED_FUNCTION_START_OFFSET: Target Architecture Definition. 6537* DEPRECATED_GET_SAVED_REGISTER: Target Architecture Definition. 6538* DEPRECATED_IBM6000_TARGET: Target Architecture Definition. 6539* DEPRECATED_INIT_EXTRA_FRAME_INFO: Target Architecture Definition. 6540* DEPRECATED_INIT_FRAME_PC: Target Architecture Definition. 6541* DEPRECATED_LITTLE_REMOTE_BREAKPOINT: Target Architecture Definition. 6542* DEPRECATED_POP_FRAME: Target Architecture Definition. 6543* DEPRECATED_PUSH_ARGUMENTS.: Target Architecture Definition. 6544* DEPRECATED_REG_STRUCT_HAS_ADDR: Target Architecture Definition. 6545* DEPRECATED_REGISTER_BYTES: Target Architecture Definition. 6546* DEPRECATED_REGISTER_RAW_SIZE: Target Architecture Definition. 6547* DEPRECATED_REGISTER_VIRTUAL_SIZE: Target Architecture Definition. 6548* DEPRECATED_REMOTE_BREAKPOINT: Target Architecture Definition. 6549* DEPRECATED_SIGTRAMP_END: Target Architecture Definition. 6550* DEPRECATED_SIGTRAMP_START: Target Architecture Definition. 6551* DEPRECATED_STACK_ALIGN: Target Architecture Definition. 6552* DEPRECATED_USE_STRUCT_CONVENTION: Target Architecture Definition. 6553* deprecating commands: User Interface. 6554* design: Coding. 6555* DEV_TTY: Host Definition. 6556* DIRNAME_SEPARATOR: Coding. 6557* DISABLE_UNSETTABLE_BREAK: Target Architecture Definition. 6558* discard_cleanups: Coding. 6559* do_cleanups: Coding. 6560* DOS text files: Host Definition. 6561* DW_AT_address_class: Target Architecture Definition. 6562* DW_AT_byte_size: Target Architecture Definition. 6563* DWARF 1 debugging info: Symbol Handling. 6564* DWARF 2 debugging info: Symbol Handling. 6565* DWARF2_REG_TO_REGNUM: Target Architecture Definition. 6566* DWARF_REG_TO_REGNUM: Target Architecture Definition. 6567* ECOFF debugging info: Symbol Handling. 6568* ECOFF format: Symbol Handling. 6569* ECOFF_REG_TO_REGNUM: Target Architecture Definition. 6570* ELF format: Symbol Handling. 6571* END_OF_TEXT_DEFAULT: Target Architecture Definition. 6572* evaluate_subexp: Language Support. 6573* expression evaluation routines: Language Support. 6574* expression parser: Language Support. 6575* EXTRACT_RETURN_VALUE: Target Architecture Definition. 6576* extract_typed_address: Target Architecture Definition. 6577* FCLOSE_PROVIDED: Host Definition. 6578* FDL, GNU Free Documentation License: GNU Free Documentation License. 6579* fetch_core_registers: Native Debugging. 6580* FETCH_INFERIOR_REGISTERS: Native Debugging. 6581* field output functions: User Interface. 6582* file names, portability: Coding. 6583* FILENAME_CMP: Coding. 6584* FILES_INFO_HOOK: Native Debugging. 6585* find_pc_function: Symbol Handling. 6586* find_pc_line: Symbol Handling. 6587* find_sym_fns: Symbol Handling. 6588* finding a symbol: Symbol Handling. 6589* fine-tuning gdbarch structure: Target Architecture Definition. 6590* FOPEN_RB: Host Definition. 6591* FP0_REGNUM: Native Debugging. 6592* frame: Algorithms. 6593* frame chain: Algorithms. 6594* frame pointer register: Algorithms. 6595* frame_align: Target Architecture Definition. 6596* FRAME_FP: Algorithms. 6597* FRAME_NUM_ARGS: Target Architecture Definition. 6598* frame_pop: Target Architecture Definition. 6599* full symbol table: Symbol Handling. 6600* function prototypes: Coding. 6601* function usage: Coding. 6602* FUNCTION_EPILOGUE_SIZE: Target Architecture Definition. 6603* fundamental types: Symbol Handling. 6604* GCC2_COMPILED_FLAG_SYMBOL: Target Architecture Definition. 6605* GCC_COMPILED_FLAG_SYMBOL: Target Architecture Definition. 6606* GDB_MULTI_ARCH: Target Architecture Definition. 6607* gdb_osabi: Target Architecture Definition. 6608* GDB_OSABI_ARM_APCS: Target Architecture Definition. 6609* GDB_OSABI_ARM_EABI_V1: Target Architecture Definition. 6610* GDB_OSABI_ARM_EABI_V2: Target Architecture Definition. 6611* GDB_OSABI_FREEBSD_AOUT: Target Architecture Definition. 6612* GDB_OSABI_FREEBSD_ELF: Target Architecture Definition. 6613* GDB_OSABI_GO32: Target Architecture Definition. 6614* GDB_OSABI_HURD: Target Architecture Definition. 6615* GDB_OSABI_LINUX: Target Architecture Definition. 6616* GDB_OSABI_NETBSD_AOUT: Target Architecture Definition. 6617* GDB_OSABI_NETBSD_ELF: Target Architecture Definition. 6618* GDB_OSABI_NETWARE: Target Architecture Definition. 6619* GDB_OSABI_OSF1: Target Architecture Definition. 6620* GDB_OSABI_SOLARIS: Target Architecture Definition. 6621* GDB_OSABI_SVR4: Target Architecture Definition. 6622* GDB_OSABI_UNKNOWN: Target Architecture Definition. 6623* GDB_OSABI_WINCE: Target Architecture Definition. 6624* GDB_TARGET_IS_HPPA: Target Architecture Definition. 6625* gdbarch_data: Coding. 6626* gdbarch_in_function_epilogue_p: Target Architecture Definition. 6627* gdbarch_init_osabi: Target Architecture Definition. 6628* gdbarch_register_osabi: Target Architecture Definition. 6629* gdbarch_register_osabi_sniffer: Target Architecture Definition. 6630* gdbarch_return_value: Target Architecture Definition. 6631* GDBINIT_FILENAME: Host Definition. 6632* generic host support: Host Definition. 6633* GET_LONGJMP_TARGET <1>: Native Debugging. 6634* GET_LONGJMP_TARGET <2>: Target Architecture Definition. 6635* GET_LONGJMP_TARGET: Algorithms. 6636* GETENV_PROVIDED: Host Definition. 6637* hardware breakpoints: Algorithms. 6638* hardware watchpoints: Algorithms. 6639* HAVE_CONTINUABLE_WATCHPOINT: Algorithms. 6640* HAVE_DOS_BASED_FILE_SYSTEM: Coding. 6641* HAVE_LONG_DOUBLE: Host Definition. 6642* HAVE_MMAP: Host Definition. 6643* HAVE_NONSTEPPABLE_WATCHPOINT: Algorithms. 6644* HAVE_STEPPABLE_WATCHPOINT: Algorithms. 6645* HAVE_TERMIO: Host Definition. 6646* host: Overall Structure. 6647* host, adding: Host Definition. 6648* i386_cleanup_dregs: Algorithms. 6649* I386_DR_LOW_GET_STATUS: Algorithms. 6650* I386_DR_LOW_RESET_ADDR: Algorithms. 6651* I386_DR_LOW_SET_ADDR: Algorithms. 6652* I386_DR_LOW_SET_CONTROL: Algorithms. 6653* i386_insert_hw_breakpoint: Algorithms. 6654* i386_insert_watchpoint: Algorithms. 6655* i386_region_ok_for_watchpoint: Algorithms. 6656* i386_remove_hw_breakpoint: Algorithms. 6657* i386_remove_watchpoint: Algorithms. 6658* i386_stopped_by_hwbp: Algorithms. 6659* i386_stopped_data_address: Algorithms. 6660* I386_USE_GENERIC_WATCHPOINTS: Algorithms. 6661* IN_SOLIB_CALL_TRAMPOLINE: Target Architecture Definition. 6662* IN_SOLIB_DYNSYM_RESOLVE_CODE: Target Architecture Definition. 6663* IN_SOLIB_RETURN_TRAMPOLINE: Target Architecture Definition. 6664* inferior_created: GDB Observers. 6665* INNER_THAN: Target Architecture Definition. 6666* insert or remove hardware breakpoint: Algorithms. 6667* INT_MAX: Host Definition. 6668* INT_MIN: Host Definition. 6669* INTEGER_TO_ADDRESS: Target Architecture Definition. 6670* IS_ABSOLUTE_PATH: Coding. 6671* IS_DIR_SEPARATOR: Coding. 6672* ISATTY: Host Definition. 6673* item output functions: User Interface. 6674* KERNEL_U_ADDR: Native Debugging. 6675* KERNEL_U_ADDR_BSD: Native Debugging. 6676* KERNEL_U_ADDR_HPUX: Native Debugging. 6677* L_SET: Host Definition. 6678* language parser: Language Support. 6679* language support: Language Support. 6680* legal papers for code contributions: Debugging GDB. 6681* length_of_subexp: Language Support. 6682* libgdb: libgdb. 6683* libiberty library: Support Libraries. 6684* line wrap in output: Coding. 6685* lint: Host Definition. 6686* list output functions: User Interface. 6687* LITTLE_BREAKPOINT: Target Architecture Definition. 6688* long long data type: Host Definition. 6689* LONG_MAX: Host Definition. 6690* LONGEST: Host Definition. 6691* longjmp debugging: Algorithms. 6692* lookup_symbol: Symbol Handling. 6693* LSEEK_NOT_LINEAR: Host Definition. 6694* make_cleanup: Coding. 6695* making a new release of gdb: Releasing GDB. 6696* memory representation: Target Architecture Definition. 6697* MEMORY_INSERT_BREAKPOINT: Target Architecture Definition. 6698* MEMORY_REMOVE_BREAKPOINT: Target Architecture Definition. 6699* minimal symbol table: Symbol Handling. 6700* minsymtabs: Symbol Handling. 6701* mmap: Host Definition. 6702* multi-arch data: Coding. 6703* NAME_OF_MALLOC: Target Architecture Definition. 6704* NATDEPFILES: Native Debugging. 6705* native conditionals: Native Debugging. 6706* native core files: Native Debugging. 6707* native debugging: Native Debugging. 6708* nesting level in ui_out functions: User Interface. 6709* Netware Loadable Module format: Symbol Handling. 6710* NO_HIF_SUPPORT: Target Architecture Definition. 6711* NO_STD_REGS: Host Definition. 6712* NO_SYS_FILE: Host Definition. 6713* NORETURN: Host Definition. 6714* normal_stop: GDB Observers. 6715* normal_stop observer: GDB Observers. 6716* notification about inferior execution stop: GDB Observers. 6717* notifications about changes in internals: Algorithms. 6718* object file formats: Symbol Handling. 6719* observer pattern interface: Algorithms. 6720* observers implementation rationale: GDB Observers. 6721* obsolete code: Debugging GDB. 6722* obstacks: Support Libraries. 6723* ONE_PROCESS_WRITETEXT: Native Debugging. 6724* op_print_tab: Language Support. 6725* opcodes library: Support Libraries. 6726* OS ABI variants: Target Architecture Definition. 6727* OS9K_VARIABLES_INSIDE_BLOCK: Target Architecture Definition. 6728* PARM_BOUNDARY: Target Architecture Definition. 6729* parse_exp_1: Language Support. 6730* partial symbol table: Symbol Handling. 6731* PC_LOAD_SEGMENT: Target Architecture Definition. 6732* PC_REGNUM: Target Architecture Definition. 6733* PE-COFF format: Symbol Handling. 6734* per-architecture module data: Coding. 6735* pointer representation: Target Architecture Definition. 6736* POINTER_TO_ADDRESS: Target Architecture Definition. 6737* portability: Coding. 6738* portable file name handling: Coding. 6739* porting to new machines: Porting GDB. 6740* prefixify_subexp: Language Support. 6741* PRINT_FLOAT_INFO: Target Architecture Definition. 6742* print_registers_info: Target Architecture Definition. 6743* print_subexp: Language Support. 6744* PRINT_VECTOR_INFO: Target Architecture Definition. 6745* PRINTF_HAS_LONG_DOUBLE: Host Definition. 6746* PRINTF_HAS_LONG_LONG: Host Definition. 6747* PROC_NAME_FMT: Native Debugging. 6748* PROCESS_LINENUMBER_HOOK: Target Architecture Definition. 6749* program counter: Algorithms. 6750* PROLOGUE_FIRSTLINE_OVERLAP: Target Architecture Definition. 6751* prompt: Host Definition. 6752* PS_REGNUM: Target Architecture Definition. 6753* psymtabs: Symbol Handling. 6754* PTRACE_ARG3_TYPE: Native Debugging. 6755* PTRACE_FP_BUG: Native Debugging. 6756* push_dummy_call: Target Architecture Definition. 6757* push_dummy_code: Target Architecture Definition. 6758* raw register representation: Target Architecture Definition. 6759* read_fp: Target Architecture Definition. 6760* read_pc: Target Architecture Definition. 6761* read_sp: Target Architecture Definition. 6762* reading of symbols: Symbol Handling. 6763* red zone: Target Architecture Definition. 6764* register data formats, converting: Target Architecture Definition. 6765* register groups: Target Architecture Definition. 6766* register representation: Target Architecture Definition. 6767* REGISTER_CONVERT_TO_RAW: Target Architecture Definition. 6768* REGISTER_CONVERT_TO_TYPE: Target Architecture Definition. 6769* REGISTER_CONVERT_TO_VIRTUAL: Target Architecture Definition. 6770* REGISTER_CONVERTIBLE: Target Architecture Definition. 6771* REGISTER_NAME: Target Architecture Definition. 6772* register_reggroup_p: Target Architecture Definition. 6773* REGISTER_TO_VALUE: Target Architecture Definition. 6774* register_type: Target Architecture Definition. 6775* REGISTER_U_ADDR: Native Debugging. 6776* REGISTER_VIRTUAL_TYPE: Target Architecture Definition. 6777* regset_from_core_section: Target Architecture Definition. 6778* regular expressions library: Support Libraries. 6779* remote debugging support: Host Definition. 6780* REMOTE_BPT_VECTOR: Target Architecture Definition. 6781* representations, raw and virtual registers: Target Architecture Definition. 6782* representations, register and memory: Target Architecture Definition. 6783* requirements for GDB: Requirements. 6784* running the test suite: Testsuite. 6785* SAVE_DUMMY_FRAME_TOS: Target Architecture Definition. 6786* SCANF_HAS_LONG_DOUBLE: Host Definition. 6787* SDB_REG_TO_REGNUM: Target Architecture Definition. 6788* secondary symbol file: Symbol Handling. 6789* SEEK_CUR: Host Definition. 6790* SEEK_SET: Host Definition. 6791* separate data and code address spaces: Target Architecture Definition. 6792* serial line support: Host Definition. 6793* SHELL_COMMAND_CONCAT: Native Debugging. 6794* SHELL_FILE: Native Debugging. 6795* SIGWINCH_HANDLER: Host Definition. 6796* SIGWINCH_HANDLER_BODY: Host Definition. 6797* SKIP_PERMANENT_BREAKPOINT: Target Architecture Definition. 6798* SKIP_PROLOGUE: Target Architecture Definition. 6799* SKIP_SOLIB_RESOLVER: Target Architecture Definition. 6800* SKIP_TRAMPOLINE_CODE: Target Architecture Definition. 6801* SLASH_STRING: Coding. 6802* software breakpoints: Algorithms. 6803* software watchpoints: Algorithms. 6804* SOFTWARE_SINGLE_STEP: Target Architecture Definition. 6805* SOFTWARE_SINGLE_STEP_P: Target Architecture Definition. 6806* SOFUN_ADDRESS_MAYBE_MISSING: Target Architecture Definition. 6807* SOLIB_ADD: Native Debugging. 6808* SOLIB_CREATE_INFERIOR_HOOK: Native Debugging. 6809* SOM debugging info: Symbol Handling. 6810* SOM format: Symbol Handling. 6811* source code formatting: Coding. 6812* SP_REGNUM: Target Architecture Definition. 6813* spaces, separate data and code address: Target Architecture Definition. 6814* STAB_REG_TO_REGNUM: Target Architecture Definition. 6815* stabs debugging info: Symbol Handling. 6816* stabs_argument_has_addr: Target Architecture Definition. 6817* stack alignment: Host Definition. 6818* START_INFERIOR_TRAPS_EXPECTED: Native Debugging. 6819* STEP_SKIPS_DELAY: Target Architecture Definition. 6820* STOP_SIGNAL: Host Definition. 6821* STOPPED_BY_WATCHPOINT: Algorithms. 6822* STORE_RETURN_VALUE: Target Architecture Definition. 6823* store_typed_address: Target Architecture Definition. 6824* struct: GDB Observers. 6825* struct value, converting register contents to: Target Architecture Definition. 6826* submitting patches: Debugging GDB. 6827* SVR4_SHARED_LIBS: Native Debugging. 6828* sym_fns structure: Symbol Handling. 6829* symbol files: Symbol Handling. 6830* symbol lookup: Symbol Handling. 6831* symbol reading: Symbol Handling. 6832* SYMBOL_RELOADING_DEFAULT: Target Architecture Definition. 6833* SYMBOLS_CAN_START_WITH_DOLLAR: Target Architecture Definition. 6834* symtabs: Symbol Handling. 6835* system dependencies: Coding. 6836* table output functions: User Interface. 6837* target: Overall Structure. 6838* target architecture definition: Target Architecture Definition. 6839* target vector: Target Vector Definition. 6840* TARGET_CAN_USE_HARDWARE_WATCHPOINT: Algorithms. 6841* target_changed: GDB Observers. 6842* TARGET_CHAR_BIT: Target Architecture Definition. 6843* TARGET_CHAR_SIGNED: Target Architecture Definition. 6844* TARGET_COMPLEX_BIT: Target Architecture Definition. 6845* TARGET_DISABLE_HW_WATCHPOINTS: Algorithms. 6846* TARGET_DOUBLE_BIT: Target Architecture Definition. 6847* TARGET_DOUBLE_COMPLEX_BIT: Target Architecture Definition. 6848* TARGET_ENABLE_HW_WATCHPOINTS: Algorithms. 6849* TARGET_FLOAT_BIT: Target Architecture Definition. 6850* TARGET_HAS_HARDWARE_WATCHPOINTS: Algorithms. 6851* target_insert_hw_breakpoint: Algorithms. 6852* target_insert_watchpoint: Algorithms. 6853* TARGET_INT_BIT: Target Architecture Definition. 6854* TARGET_LONG_BIT: Target Architecture Definition. 6855* TARGET_LONG_DOUBLE_BIT: Target Architecture Definition. 6856* TARGET_LONG_LONG_BIT: Target Architecture Definition. 6857* TARGET_PRINT_INSN: Target Architecture Definition. 6858* TARGET_PTR_BIT: Target Architecture Definition. 6859* TARGET_READ_FP: Target Architecture Definition. 6860* TARGET_READ_PC: Target Architecture Definition. 6861* TARGET_READ_SP: Target Architecture Definition. 6862* TARGET_REGION_OK_FOR_HW_WATCHPOINT: Algorithms. 6863* TARGET_REGION_SIZE_OK_FOR_HW_WATCHPOINT: Algorithms. 6864* target_remove_hw_breakpoint: Algorithms. 6865* target_remove_watchpoint: Algorithms. 6866* TARGET_SHORT_BIT: Target Architecture Definition. 6867* target_stopped_data_address: Algorithms. 6868* TARGET_VIRTUAL_FRAME_POINTER: Target Architecture Definition. 6869* TARGET_WRITE_PC: Target Architecture Definition. 6870* TCP remote support: Host Definition. 6871* TDEPFILES: Target Architecture Definition. 6872* terminal device: Host Definition. 6873* test suite: Testsuite. 6874* test suite organization: Testsuite. 6875* trimming language-dependent code: Language Support. 6876* tuple output functions: User Interface. 6877* type: Target Architecture Definition. 6878* type codes: Symbol Handling. 6879* types: Coding. 6880* U_REGS_OFFSET: Native Debugging. 6881* ui_out functions: User Interface. 6882* ui_out functions, usage examples: User Interface. 6883* ui_out_field_core_addr: User Interface. 6884* ui_out_field_fmt: User Interface. 6885* ui_out_field_fmt_int: User Interface. 6886* ui_out_field_int: User Interface. 6887* ui_out_field_skip: User Interface. 6888* ui_out_field_stream: User Interface. 6889* ui_out_field_string: User Interface. 6890* ui_out_flush: User Interface. 6891* ui_out_list_begin: User Interface. 6892* ui_out_list_end: User Interface. 6893* ui_out_message: User Interface. 6894* ui_out_spaces: User Interface. 6895* ui_out_stream_delete: User Interface. 6896* ui_out_table_begin: User Interface. 6897* ui_out_table_body: User Interface. 6898* ui_out_table_end: User Interface. 6899* ui_out_table_header: User Interface. 6900* ui_out_text: User Interface. 6901* ui_out_tuple_begin: User Interface. 6902* ui_out_tuple_end: User Interface. 6903* ui_out_wrap_hint: User Interface. 6904* ui_stream: User Interface. 6905* UINT_MAX: Host Definition. 6906* ULONG_MAX: Host Definition. 6907* unwind_dummy_id: Target Architecture Definition. 6908* unwind_pc: Target Architecture Definition. 6909* unwind_sp: Target Architecture Definition. 6910* USE_O_NOCTTY: Host Definition. 6911* USE_PROC_FS: Native Debugging. 6912* USG: Host Definition. 6913* using ui_out functions: User Interface. 6914* value_as_address: Target Architecture Definition. 6915* value_from_pointer: Target Architecture Definition. 6916* VALUE_TO_REGISTER: Target Architecture Definition. 6917* VARIABLES_INSIDE_BLOCK: Target Architecture Definition. 6918* virtual register representation: Target Architecture Definition. 6919* void: GDB Observers. 6920* volatile: Host Definition. 6921* watchpoints: Algorithms. 6922* watchpoints, on x86: Algorithms. 6923* word-addressed machines: Target Architecture Definition. 6924* wrap_here: Coding. 6925* write_pc: Target Architecture Definition. 6926* writing tests: Testsuite. 6927* x86 debug registers: Algorithms. 6928* XCOFF format: Symbol Handling. 6929 6930 6931 6932Tag Table: 6933Node: Top856 6934Node: Requirements1637 6935Node: Overall Structure3121 6936Node: Algorithms6380 6937Node: User Interface25604 6938Ref: User Interface-Footnote-149269 6939Ref: User Interface-Footnote-249318 6940Node: libgdb49553 6941Node: Symbol Handling53468 6942Node: Language Support67549 6943Node: Host Definition72938 6944Node: Target Architecture Definition80891 6945Ref: BREAKPOINT_FROM_PC106977 6946Ref: DEPRECATED_EXTRACT_STRUCT_VALUE_ADDRESS113173 6947Ref: frame_align114005 6948Ref: DEPRECATED_FRAME_SAVED_PC116382 6949Ref: unwind_pc116568 6950Ref: unwind_sp117121 6951Ref: stabs_argument_has_addr129584 6952Ref: push_dummy_call130358 6953Ref: push_dummy_code130944 6954Ref: DEPRECATED_REG_STRUCT_HAS_ADDR132018 6955Ref: SAVE_DUMMY_FRAME_TOS132252 6956Ref: gdbarch_return_value132871 6957Ref: DEPRECATED_STACK_ALIGN136156 6958Ref: TARGET_WRITE_PC138783 6959Ref: TARGET_READ_SP138817 6960Ref: unwind_dummy_id140512 6961Ref: Target Architecture Definition-Footnote-1148934 6962Ref: Target Architecture Definition-Footnote-2149177 6963Node: Target Vector Definition149296 6964Node: Native Debugging151855 6965Node: Support Libraries162603 6966Node: Coding167337 6967Node: Porting GDB192456 6968Node: Releasing GDB194351 6969Node: Testsuite216264 6970Node: Hints222736 6971Node: Getting Started223052 6972Node: Debugging GDB227185 6973Node: GDB Observers232517 6974Node: GNU Free Documentation License236187 6975Node: Index258600 6976 6977End Tag Table 6978