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