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