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