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