| 1 | \input texinfo @c -*- texinfo -*- |
| 2 | @setfilename gdbint.info |
| 3 | @include gdb-cfg.texi |
| 4 | @settitle @value{GDBN} Internals |
| 5 | @setchapternewpage off |
| 6 | @dircategory Software development |
| 7 | @direntry |
| 8 | * Gdb-Internals: (gdbint). The GNU debugger's internals. |
| 9 | @end direntry |
| 10 | |
| 11 | @copying |
| 12 | Copyright @copyright{} 1990, 1991, 1992, 1993, 1994, 1996, 1998, 1999, |
| 13 | 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2008, 2009, 2010, 2011 |
| 14 | Free Software Foundation, Inc. |
| 15 | Contributed by Cygnus Solutions. Written by John Gilmore. |
| 16 | Second Edition by Stan Shebs. |
| 17 | |
| 18 | Permission is granted to copy, distribute and/or modify this document |
| 19 | under the terms of the GNU Free Documentation License, Version 1.3 or |
| 20 | any later version published by the Free Software Foundation; with no |
| 21 | Invariant Sections, with no Front-Cover Texts, and with no Back-Cover |
| 22 | Texts. A copy of the license is included in the section entitled ``GNU |
| 23 | Free Documentation License''. |
| 24 | @end copying |
| 25 | |
| 26 | @ifnottex |
| 27 | This file documents the internals of the GNU debugger @value{GDBN}. |
| 28 | |
| 29 | @insertcopying |
| 30 | @end ifnottex |
| 31 | |
| 32 | |
| 33 | @syncodeindex fn cp |
| 34 | @syncodeindex vr cp |
| 35 | |
| 36 | @titlepage |
| 37 | @title @value{GDBN} Internals |
| 38 | @subtitle{A guide to the internals of the GNU debugger} |
| 39 | @author John Gilmore |
| 40 | @author Cygnus Solutions |
| 41 | @author Second Edition: |
| 42 | @author Stan Shebs |
| 43 | @author Cygnus Solutions |
| 44 | @page |
| 45 | @tex |
| 46 | \def\$#1${{#1}} % Kluge: collect RCS revision info without $...$ |
| 47 | \xdef\manvers{\$Revision$} % For use in headers, footers too |
| 48 | {\parskip=0pt |
| 49 | \hfill Cygnus Solutions\par |
| 50 | \hfill \manvers\par |
| 51 | \hfill \TeX{}info \texinfoversion\par |
| 52 | } |
| 53 | @end tex |
| 54 | |
| 55 | @vskip 0pt plus 1filll |
| 56 | @insertcopying |
| 57 | @end titlepage |
| 58 | |
| 59 | @contents |
| 60 | |
| 61 | @node Top |
| 62 | @c Perhaps this should be the title of the document (but only for info, |
| 63 | @c not for TeX). Existing GNU manuals seem inconsistent on this point. |
| 64 | @top Scope of this Document |
| 65 | |
| 66 | This document documents the internals of the GNU debugger, @value{GDBN}. It |
| 67 | includes description of @value{GDBN}'s key algorithms and operations, as well |
| 68 | as the mechanisms that adapt @value{GDBN} to specific hosts and targets. |
| 69 | |
| 70 | @menu |
| 71 | * Summary:: |
| 72 | * Overall Structure:: |
| 73 | * Algorithms:: |
| 74 | * User Interface:: |
| 75 | * libgdb:: |
| 76 | * Values:: |
| 77 | * Stack Frames:: |
| 78 | * Symbol Handling:: |
| 79 | * Language Support:: |
| 80 | * Host Definition:: |
| 81 | * Target Architecture Definition:: |
| 82 | * Target Descriptions:: |
| 83 | * Target Vector Definition:: |
| 84 | * Native Debugging:: |
| 85 | * Support Libraries:: |
| 86 | * Coding Standards:: |
| 87 | * Misc Guidelines:: |
| 88 | * Porting GDB:: |
| 89 | * Versions and Branches:: |
| 90 | * Start of New Year Procedure:: |
| 91 | * Releasing GDB:: |
| 92 | * Testsuite:: |
| 93 | * Hints:: |
| 94 | |
| 95 | * GDB Observers:: @value{GDBN} Currently available observers |
| 96 | * GNU Free Documentation License:: The license for this documentation |
| 97 | * Index:: |
| 98 | @end menu |
| 99 | |
| 100 | @node Summary |
| 101 | @chapter Summary |
| 102 | |
| 103 | @menu |
| 104 | * Requirements:: |
| 105 | * Contributors:: |
| 106 | @end menu |
| 107 | |
| 108 | @node Requirements |
| 109 | @section Requirements |
| 110 | @cindex requirements for @value{GDBN} |
| 111 | |
| 112 | Before diving into the internals, you should understand the formal |
| 113 | requirements and other expectations for @value{GDBN}. Although some |
| 114 | of these may seem obvious, there have been proposals for @value{GDBN} |
| 115 | that have run counter to these requirements. |
| 116 | |
| 117 | First of all, @value{GDBN} is a debugger. It's not designed to be a |
| 118 | front panel for embedded systems. It's not a text editor. It's not a |
| 119 | shell. It's not a programming environment. |
| 120 | |
| 121 | @value{GDBN} is an interactive tool. Although a batch mode is |
| 122 | available, @value{GDBN}'s primary role is to interact with a human |
| 123 | programmer. |
| 124 | |
| 125 | @value{GDBN} should be responsive to the user. A programmer hot on |
| 126 | the trail of a nasty bug, and operating under a looming deadline, is |
| 127 | going to be very impatient of everything, including the response time |
| 128 | to debugger commands. |
| 129 | |
| 130 | @value{GDBN} should be relatively permissive, such as for expressions. |
| 131 | While the compiler should be picky (or have the option to be made |
| 132 | picky), since source code lives for a long time usually, the |
| 133 | programmer doing debugging shouldn't be spending time figuring out to |
| 134 | mollify the debugger. |
| 135 | |
| 136 | @value{GDBN} will be called upon to deal with really large programs. |
| 137 | Executable sizes of 50 to 100 megabytes occur regularly, and we've |
| 138 | heard reports of programs approaching 1 gigabyte in size. |
| 139 | |
| 140 | @value{GDBN} should be able to run everywhere. No other debugger is |
| 141 | available for even half as many configurations as @value{GDBN} |
| 142 | supports. |
| 143 | |
| 144 | @node Contributors |
| 145 | @section Contributors |
| 146 | |
| 147 | The first edition of this document was written by John Gilmore of |
| 148 | Cygnus Solutions. The current second edition was written by Stan Shebs |
| 149 | of Cygnus Solutions, who continues to update the manual. |
| 150 | |
| 151 | Over the years, many others have made additions and changes to this |
| 152 | document. This section attempts to record the significant contributors |
| 153 | to that effort. One of the virtues of free software is that everyone |
| 154 | is free to contribute to it; with regret, we cannot actually |
| 155 | acknowledge everyone here. |
| 156 | |
| 157 | @quotation |
| 158 | @emph{Plea:} This section has only been added relatively recently (four |
| 159 | years after publication of the second edition). Additions to this |
| 160 | section are particularly welcome. If you or your friends (or enemies, |
| 161 | to be evenhanded) have been unfairly omitted from this list, we would |
| 162 | like to add your names! |
| 163 | @end quotation |
| 164 | |
| 165 | A document such as this relies on being kept up to date by numerous |
| 166 | small updates by contributing engineers as they make changes to the |
| 167 | code base. The file @file{ChangeLog} in the @value{GDBN} distribution |
| 168 | approximates a blow-by-blow account. The most prolific contributors to |
| 169 | this important, but low profile task are Andrew Cagney (responsible |
| 170 | for over half the entries), Daniel Jacobowitz, Mark Kettenis, Jim |
| 171 | Blandy and Eli Zaretskii. |
| 172 | |
| 173 | Eli Zaretskii and Daniel Jacobowitz wrote the sections documenting |
| 174 | watchpoints. |
| 175 | |
| 176 | Jeremy Bennett updated the sections on initializing a new architecture |
| 177 | and register representation, and added the section on Frame Interpretation. |
| 178 | |
| 179 | |
| 180 | @node Overall Structure |
| 181 | |
| 182 | @chapter Overall Structure |
| 183 | |
| 184 | @value{GDBN} consists of three major subsystems: user interface, |
| 185 | symbol handling (the @dfn{symbol side}), and target system handling (the |
| 186 | @dfn{target side}). |
| 187 | |
| 188 | The user interface consists of several actual interfaces, plus |
| 189 | supporting code. |
| 190 | |
| 191 | The symbol side consists of object file readers, debugging info |
| 192 | interpreters, symbol table management, source language expression |
| 193 | parsing, type and value printing. |
| 194 | |
| 195 | The target side consists of execution control, stack frame analysis, and |
| 196 | physical target manipulation. |
| 197 | |
| 198 | The target side/symbol side division is not formal, and there are a |
| 199 | number of exceptions. For instance, core file support involves symbolic |
| 200 | elements (the basic core file reader is in BFD) and target elements (it |
| 201 | supplies the contents of memory and the values of registers). Instead, |
| 202 | this division is useful for understanding how the minor subsystems |
| 203 | should fit together. |
| 204 | |
| 205 | @section The Symbol Side |
| 206 | |
| 207 | The symbolic side of @value{GDBN} can be thought of as ``everything |
| 208 | you can do in @value{GDBN} without having a live program running''. |
| 209 | For instance, you can look at the types of variables, and evaluate |
| 210 | many kinds of expressions. |
| 211 | |
| 212 | @section The Target Side |
| 213 | |
| 214 | The target side of @value{GDBN} is the ``bits and bytes manipulator''. |
| 215 | Although it may make reference to symbolic info here and there, most |
| 216 | of the target side will run with only a stripped executable |
| 217 | available---or even no executable at all, in remote debugging cases. |
| 218 | |
| 219 | Operations such as disassembly, stack frame crawls, and register |
| 220 | display, are able to work with no symbolic info at all. In some cases, |
| 221 | such as disassembly, @value{GDBN} will use symbolic info to present addresses |
| 222 | relative to symbols rather than as raw numbers, but it will work either |
| 223 | way. |
| 224 | |
| 225 | @section Configurations |
| 226 | |
| 227 | @cindex host |
| 228 | @cindex target |
| 229 | @dfn{Host} refers to attributes of the system where @value{GDBN} runs. |
| 230 | @dfn{Target} refers to the system where the program being debugged |
| 231 | executes. In most cases they are the same machine, in which case a |
| 232 | third type of @dfn{Native} attributes come into play. |
| 233 | |
| 234 | Defines and include files needed to build on the host are host |
| 235 | support. Examples are tty support, system defined types, host byte |
| 236 | order, host float format. These are all calculated by @code{autoconf} |
| 237 | when the debugger is built. |
| 238 | |
| 239 | Defines and information needed to handle the target format are target |
| 240 | dependent. Examples are the stack frame format, instruction set, |
| 241 | breakpoint instruction, registers, and how to set up and tear down the stack |
| 242 | to call a function. |
| 243 | |
| 244 | Information that is only needed when the host and target are the same, |
| 245 | is native dependent. One example is Unix child process support; if the |
| 246 | host and target are not the same, calling @code{fork} to start the target |
| 247 | process is a bad idea. The various macros needed for finding the |
| 248 | registers in the @code{upage}, running @code{ptrace}, and such are all |
| 249 | in the native-dependent files. |
| 250 | |
| 251 | Another example of native-dependent code is support for features that |
| 252 | are really part of the target environment, but which require |
| 253 | @code{#include} files that are only available on the host system. Core |
| 254 | file handling and @code{setjmp} handling are two common cases. |
| 255 | |
| 256 | When you want to make @value{GDBN} work as the traditional native debugger |
| 257 | on a system, you will need to supply both target and native information. |
| 258 | |
| 259 | @section Source Tree Structure |
| 260 | @cindex @value{GDBN} source tree structure |
| 261 | |
| 262 | The @value{GDBN} source directory has a mostly flat structure---there |
| 263 | are only a few subdirectories. A file's name usually gives a hint as |
| 264 | to what it does; for example, @file{stabsread.c} reads stabs, |
| 265 | @file{dwarf2read.c} reads @sc{DWARF 2}, etc. |
| 266 | |
| 267 | Files that are related to some common task have names that share |
| 268 | common substrings. For example, @file{*-thread.c} files deal with |
| 269 | debugging threads on various platforms; @file{*read.c} files deal with |
| 270 | reading various kinds of symbol and object files; @file{inf*.c} files |
| 271 | deal with direct control of the @dfn{inferior program} (@value{GDBN} |
| 272 | parlance for the program being debugged). |
| 273 | |
| 274 | There are several dozens of files in the @file{*-tdep.c} family. |
| 275 | @samp{tdep} stands for @dfn{target-dependent code}---each of these |
| 276 | files implements debug support for a specific target architecture |
| 277 | (sparc, mips, etc). Usually, only one of these will be used in a |
| 278 | specific @value{GDBN} configuration (sometimes two, closely related). |
| 279 | |
| 280 | Similarly, there are many @file{*-nat.c} files, each one for native |
| 281 | debugging on a specific system (e.g., @file{sparc-linux-nat.c} is for |
| 282 | native debugging of Sparc machines running the Linux kernel). |
| 283 | |
| 284 | The few subdirectories of the source tree are: |
| 285 | |
| 286 | @table @file |
| 287 | @item cli |
| 288 | Code that implements @dfn{CLI}, the @value{GDBN} Command-Line |
| 289 | Interpreter. @xref{User Interface, Command Interpreter}. |
| 290 | |
| 291 | @item gdbserver |
| 292 | Code for the @value{GDBN} remote server. |
| 293 | |
| 294 | @item gdbtk |
| 295 | Code for Insight, the @value{GDBN} TK-based GUI front-end. |
| 296 | |
| 297 | @item mi |
| 298 | The @dfn{GDB/MI}, the @value{GDBN} Machine Interface interpreter. |
| 299 | |
| 300 | @item signals |
| 301 | Target signal translation code. |
| 302 | |
| 303 | @item tui |
| 304 | Code for @dfn{TUI}, the @value{GDBN} Text-mode full-screen User |
| 305 | Interface. @xref{User Interface, TUI}. |
| 306 | @end table |
| 307 | |
| 308 | @node Algorithms |
| 309 | |
| 310 | @chapter Algorithms |
| 311 | @cindex algorithms |
| 312 | |
| 313 | @value{GDBN} uses a number of debugging-specific algorithms. They are |
| 314 | often not very complicated, but get lost in the thicket of special |
| 315 | cases and real-world issues. This chapter describes the basic |
| 316 | algorithms and mentions some of the specific target definitions that |
| 317 | they use. |
| 318 | |
| 319 | @section Prologue Analysis |
| 320 | |
| 321 | @cindex prologue analysis |
| 322 | @cindex call frame information |
| 323 | @cindex CFI (call frame information) |
| 324 | To produce a backtrace and allow the user to manipulate older frames' |
| 325 | variables and arguments, @value{GDBN} needs to find the base addresses |
| 326 | of older frames, and discover where those frames' registers have been |
| 327 | saved. Since a frame's ``callee-saves'' registers get saved by |
| 328 | younger frames if and when they're reused, a frame's registers may be |
| 329 | scattered unpredictably across younger frames. This means that |
| 330 | changing the value of a register-allocated variable in an older frame |
| 331 | may actually entail writing to a save slot in some younger frame. |
| 332 | |
| 333 | Modern versions of GCC emit Dwarf call frame information (``CFI''), |
| 334 | which describes how to find frame base addresses and saved registers. |
| 335 | But CFI is not always available, so as a fallback @value{GDBN} uses a |
| 336 | technique called @dfn{prologue analysis} to find frame sizes and saved |
| 337 | registers. A prologue analyzer disassembles the function's machine |
| 338 | code starting from its entry point, and looks for instructions that |
| 339 | allocate frame space, save the stack pointer in a frame pointer |
| 340 | register, save registers, and so on. Obviously, this can't be done |
| 341 | accurately in general, but it's tractable to do well enough to be very |
| 342 | helpful. Prologue analysis predates the GNU toolchain's support for |
| 343 | CFI; at one time, prologue analysis was the only mechanism |
| 344 | @value{GDBN} used for stack unwinding at all, when the function |
| 345 | calling conventions didn't specify a fixed frame layout. |
| 346 | |
| 347 | In the olden days, function prologues were generated by hand-written, |
| 348 | target-specific code in GCC, and treated as opaque and untouchable by |
| 349 | optimizers. Looking at this code, it was usually straightforward to |
| 350 | write a prologue analyzer for @value{GDBN} that would accurately |
| 351 | understand all the prologues GCC would generate. However, over time |
| 352 | GCC became more aggressive about instruction scheduling, and began to |
| 353 | understand more about the semantics of the prologue instructions |
| 354 | themselves; in response, @value{GDBN}'s analyzers became more complex |
| 355 | and fragile. Keeping the prologue analyzers working as GCC (and the |
| 356 | instruction sets themselves) evolved became a substantial task. |
| 357 | |
| 358 | @cindex @file{prologue-value.c} |
| 359 | @cindex abstract interpretation of function prologues |
| 360 | @cindex pseudo-evaluation of function prologues |
| 361 | To try to address this problem, the code in @file{prologue-value.h} |
| 362 | and @file{prologue-value.c} provides a general framework for writing |
| 363 | prologue analyzers that are simpler and more robust than ad-hoc |
| 364 | analyzers. When we analyze a prologue using the prologue-value |
| 365 | framework, we're really doing ``abstract interpretation'' or |
| 366 | ``pseudo-evaluation'': running the function's code in simulation, but |
| 367 | using conservative approximations of the values registers and memory |
| 368 | would hold when the code actually runs. For example, if our function |
| 369 | starts with the instruction: |
| 370 | |
| 371 | @example |
| 372 | addi r1, 42 # add 42 to r1 |
| 373 | @end example |
| 374 | @noindent |
| 375 | we don't know exactly what value will be in @code{r1} after executing |
| 376 | this instruction, but we do know it'll be 42 greater than its original |
| 377 | value. |
| 378 | |
| 379 | If we then see an instruction like: |
| 380 | |
| 381 | @example |
| 382 | addi r1, 22 # add 22 to r1 |
| 383 | @end example |
| 384 | @noindent |
| 385 | we still don't know what @code{r1's} value is, but again, we can say |
| 386 | it is now 64 greater than its original value. |
| 387 | |
| 388 | If the next instruction were: |
| 389 | |
| 390 | @example |
| 391 | mov r2, r1 # set r2 to r1's value |
| 392 | @end example |
| 393 | @noindent |
| 394 | then we can say that @code{r2's} value is now the original value of |
| 395 | @code{r1} plus 64. |
| 396 | |
| 397 | It's common for prologues to save registers on the stack, so we'll |
| 398 | need to track the values of stack frame slots, as well as the |
| 399 | registers. So after an instruction like this: |
| 400 | |
| 401 | @example |
| 402 | mov (fp+4), r2 |
| 403 | @end example |
| 404 | @noindent |
| 405 | then we'd know that the stack slot four bytes above the frame pointer |
| 406 | holds the original value of @code{r1} plus 64. |
| 407 | |
| 408 | And so on. |
| 409 | |
| 410 | Of course, this can only go so far before it gets unreasonable. If we |
| 411 | wanted to be able to say anything about the value of @code{r1} after |
| 412 | the instruction: |
| 413 | |
| 414 | @example |
| 415 | xor r1, r3 # exclusive-or r1 and r3, place result in r1 |
| 416 | @end example |
| 417 | @noindent |
| 418 | then things would get pretty complex. But remember, we're just doing |
| 419 | a conservative approximation; if exclusive-or instructions aren't |
| 420 | relevant to prologues, we can just say @code{r1}'s value is now |
| 421 | ``unknown''. We can ignore things that are too complex, if that loss of |
| 422 | information is acceptable for our application. |
| 423 | |
| 424 | So when we say ``conservative approximation'' here, what we mean is an |
| 425 | approximation that is either accurate, or marked ``unknown'', but |
| 426 | never inaccurate. |
| 427 | |
| 428 | Using this framework, a prologue analyzer is simply an interpreter for |
| 429 | machine code, but one that uses conservative approximations for the |
| 430 | contents of registers and memory instead of actual values. Starting |
| 431 | from the function's entry point, you simulate instructions up to the |
| 432 | current PC, or an instruction that you don't know how to simulate. |
| 433 | Now you can examine the state of the registers and stack slots you've |
| 434 | kept track of. |
| 435 | |
| 436 | @itemize @bullet |
| 437 | |
| 438 | @item |
| 439 | To see how large your stack frame is, just check the value of the |
| 440 | stack pointer register; if it's the original value of the SP |
| 441 | minus a constant, then that constant is the stack frame's size. |
| 442 | If the SP's value has been marked as ``unknown'', then that means |
| 443 | the prologue has done something too complex for us to track, and |
| 444 | we don't know the frame size. |
| 445 | |
| 446 | @item |
| 447 | To see where we've saved the previous frame's registers, we just |
| 448 | search the values we've tracked --- stack slots, usually, but |
| 449 | registers, too, if you want --- for something equal to the register's |
| 450 | original value. If the calling conventions suggest a standard place |
| 451 | to save a given register, then we can check there first, but really, |
| 452 | anything that will get us back the original value will probably work. |
| 453 | @end itemize |
| 454 | |
| 455 | This does take some work. But prologue analyzers aren't |
| 456 | quick-and-simple pattern patching to recognize a few fixed prologue |
| 457 | forms any more; they're big, hairy functions. Along with inferior |
| 458 | function calls, prologue analysis accounts for a substantial portion |
| 459 | of the time needed to stabilize a @value{GDBN} port. So it's |
| 460 | worthwhile to look for an approach that will be easier to understand |
| 461 | and maintain. In the approach described above: |
| 462 | |
| 463 | @itemize @bullet |
| 464 | |
| 465 | @item |
| 466 | It's easier to see that the analyzer is correct: you just see |
| 467 | whether the analyzer properly (albeit conservatively) simulates |
| 468 | the effect of each instruction. |
| 469 | |
| 470 | @item |
| 471 | It's easier to extend the analyzer: you can add support for new |
| 472 | instructions, and know that you haven't broken anything that |
| 473 | wasn't already broken before. |
| 474 | |
| 475 | @item |
| 476 | It's orthogonal: to gather new information, you don't need to |
| 477 | complicate the code for each instruction. As long as your domain |
| 478 | of conservative values is already detailed enough to tell you |
| 479 | what you need, then all the existing instruction simulations are |
| 480 | already gathering the right data for you. |
| 481 | |
| 482 | @end itemize |
| 483 | |
| 484 | The file @file{prologue-value.h} contains detailed comments explaining |
| 485 | the framework and how to use it. |
| 486 | |
| 487 | |
| 488 | @section Breakpoint Handling |
| 489 | |
| 490 | @cindex breakpoints |
| 491 | In general, a breakpoint is a user-designated location in the program |
| 492 | where the user wants to regain control if program execution ever reaches |
| 493 | that location. |
| 494 | |
| 495 | There are two main ways to implement breakpoints; either as ``hardware'' |
| 496 | breakpoints or as ``software'' breakpoints. |
| 497 | |
| 498 | @cindex hardware breakpoints |
| 499 | @cindex program counter |
| 500 | Hardware breakpoints are sometimes available as a builtin debugging |
| 501 | features with some chips. Typically these work by having dedicated |
| 502 | register into which the breakpoint address may be stored. If the PC |
| 503 | (shorthand for @dfn{program counter}) |
| 504 | ever matches a value in a breakpoint registers, the CPU raises an |
| 505 | exception and reports it to @value{GDBN}. |
| 506 | |
| 507 | Another possibility is when an emulator is in use; many emulators |
| 508 | include circuitry that watches the address lines coming out from the |
| 509 | processor, and force it to stop if the address matches a breakpoint's |
| 510 | address. |
| 511 | |
| 512 | A third possibility is that the target already has the ability to do |
| 513 | breakpoints somehow; for instance, a ROM monitor may do its own |
| 514 | software breakpoints. So although these are not literally ``hardware |
| 515 | breakpoints'', from @value{GDBN}'s point of view they work the same; |
| 516 | @value{GDBN} need not do anything more than set the breakpoint and wait |
| 517 | for something to happen. |
| 518 | |
| 519 | Since they depend on hardware resources, hardware breakpoints may be |
| 520 | limited in number; when the user asks for more, @value{GDBN} will |
| 521 | start trying to set software breakpoints. (On some architectures, |
| 522 | notably the 32-bit x86 platforms, @value{GDBN} cannot always know |
| 523 | whether there's enough hardware resources to insert all the hardware |
| 524 | breakpoints and watchpoints. On those platforms, @value{GDBN} prints |
| 525 | an error message only when the program being debugged is continued.) |
| 526 | |
| 527 | @cindex software breakpoints |
| 528 | Software breakpoints require @value{GDBN} to do somewhat more work. |
| 529 | The basic theory is that @value{GDBN} will replace a program |
| 530 | instruction with a trap, illegal divide, or some other instruction |
| 531 | that will cause an exception, and then when it's encountered, |
| 532 | @value{GDBN} will take the exception and stop the program. When the |
| 533 | user says to continue, @value{GDBN} will restore the original |
| 534 | instruction, single-step, re-insert the trap, and continue on. |
| 535 | |
| 536 | Since it literally overwrites the program being tested, the program area |
| 537 | must be writable, so this technique won't work on programs in ROM. It |
| 538 | can also distort the behavior of programs that examine themselves, |
| 539 | although such a situation would be highly unusual. |
| 540 | |
| 541 | Also, the software breakpoint instruction should be the smallest size of |
| 542 | instruction, so it doesn't overwrite an instruction that might be a jump |
| 543 | target, and cause disaster when the program jumps into the middle of the |
| 544 | breakpoint instruction. (Strictly speaking, the breakpoint must be no |
| 545 | larger than the smallest interval between instructions that may be jump |
| 546 | targets; perhaps there is an architecture where only even-numbered |
| 547 | instructions may jumped to.) Note that it's possible for an instruction |
| 548 | set not to have any instructions usable for a software breakpoint, |
| 549 | although in practice only the ARC has failed to define such an |
| 550 | instruction. |
| 551 | |
| 552 | Basic breakpoint object handling is in @file{breakpoint.c}. However, |
| 553 | much of the interesting breakpoint action is in @file{infrun.c}. |
| 554 | |
| 555 | @table @code |
| 556 | @cindex insert or remove software breakpoint |
| 557 | @findex target_remove_breakpoint |
| 558 | @findex target_insert_breakpoint |
| 559 | @item target_remove_breakpoint (@var{bp_tgt}) |
| 560 | @itemx target_insert_breakpoint (@var{bp_tgt}) |
| 561 | Insert or remove a software breakpoint at address |
| 562 | @code{@var{bp_tgt}->placed_address}. Returns zero for success, |
| 563 | non-zero for failure. On input, @var{bp_tgt} contains the address of the |
| 564 | breakpoint, and is otherwise initialized to zero. The fields of the |
| 565 | @code{struct bp_target_info} pointed to by @var{bp_tgt} are updated |
| 566 | to contain other information about the breakpoint on output. The field |
| 567 | @code{placed_address} may be updated if the breakpoint was placed at a |
| 568 | related address; the field @code{shadow_contents} contains the real |
| 569 | contents of the bytes where the breakpoint has been inserted, |
| 570 | if reading memory would return the breakpoint instead of the |
| 571 | underlying memory; the field @code{shadow_len} is the length of |
| 572 | memory cached in @code{shadow_contents}, if any; and the field |
| 573 | @code{placed_size} is optionally set and used by the target, if |
| 574 | it could differ from @code{shadow_len}. |
| 575 | |
| 576 | For example, the remote target @samp{Z0} packet does not require |
| 577 | shadowing memory, so @code{shadow_len} is left at zero. However, |
| 578 | the length reported by @code{gdbarch_breakpoint_from_pc} is cached in |
| 579 | @code{placed_size}, so that a matching @samp{z0} packet can be |
| 580 | used to remove the breakpoint. |
| 581 | |
| 582 | @cindex insert or remove hardware breakpoint |
| 583 | @findex target_remove_hw_breakpoint |
| 584 | @findex target_insert_hw_breakpoint |
| 585 | @item target_remove_hw_breakpoint (@var{bp_tgt}) |
| 586 | @itemx target_insert_hw_breakpoint (@var{bp_tgt}) |
| 587 | Insert or remove a hardware-assisted breakpoint at address |
| 588 | @code{@var{bp_tgt}->placed_address}. Returns zero for success, |
| 589 | non-zero for failure. See @code{target_insert_breakpoint} for |
| 590 | a description of the @code{struct bp_target_info} pointed to by |
| 591 | @var{bp_tgt}; the @code{shadow_contents} and |
| 592 | @code{shadow_len} members are not used for hardware breakpoints, |
| 593 | but @code{placed_size} may be. |
| 594 | @end table |
| 595 | |
| 596 | @section Single Stepping |
| 597 | |
| 598 | @section Signal Handling |
| 599 | |
| 600 | @section Thread Handling |
| 601 | |
| 602 | @section Inferior Function Calls |
| 603 | |
| 604 | @section Longjmp Support |
| 605 | |
| 606 | @cindex @code{longjmp} debugging |
| 607 | @value{GDBN} has support for figuring out that the target is doing a |
| 608 | @code{longjmp} and for stopping at the target of the jump, if we are |
| 609 | stepping. This is done with a few specialized internal breakpoints, |
| 610 | which are visible in the output of the @samp{maint info breakpoint} |
| 611 | command. |
| 612 | |
| 613 | @findex gdbarch_get_longjmp_target |
| 614 | To make this work, you need to define a function called |
| 615 | @code{gdbarch_get_longjmp_target}, which will examine the |
| 616 | @code{jmp_buf} structure and extract the @code{longjmp} target address. |
| 617 | Since @code{jmp_buf} is target specific and typically defined in a |
| 618 | target header not available to @value{GDBN}, you will need to |
| 619 | determine the offset of the PC manually and return that; many targets |
| 620 | define a @code{jb_pc_offset} field in the tdep structure to save the |
| 621 | value once calculated. |
| 622 | |
| 623 | @section Watchpoints |
| 624 | @cindex watchpoints |
| 625 | |
| 626 | Watchpoints are a special kind of breakpoints (@pxref{Algorithms, |
| 627 | breakpoints}) which break when data is accessed rather than when some |
| 628 | instruction is executed. When you have data which changes without |
| 629 | your knowing what code does that, watchpoints are the silver bullet to |
| 630 | hunt down and kill such bugs. |
| 631 | |
| 632 | @cindex hardware watchpoints |
| 633 | @cindex software watchpoints |
| 634 | Watchpoints can be either hardware-assisted or not; the latter type is |
| 635 | known as ``software watchpoints.'' @value{GDBN} always uses |
| 636 | hardware-assisted watchpoints if they are available, and falls back on |
| 637 | software watchpoints otherwise. Typical situations where @value{GDBN} |
| 638 | will use software watchpoints are: |
| 639 | |
| 640 | @itemize @bullet |
| 641 | @item |
| 642 | The watched memory region is too large for the underlying hardware |
| 643 | watchpoint support. For example, each x86 debug register can watch up |
| 644 | to 4 bytes of memory, so trying to watch data structures whose size is |
| 645 | more than 16 bytes will cause @value{GDBN} to use software |
| 646 | watchpoints. |
| 647 | |
| 648 | @item |
| 649 | The value of the expression to be watched depends on data held in |
| 650 | registers (as opposed to memory). |
| 651 | |
| 652 | @item |
| 653 | Too many different watchpoints requested. (On some architectures, |
| 654 | this situation is impossible to detect until the debugged program is |
| 655 | resumed.) Note that x86 debug registers are used both for hardware |
| 656 | breakpoints and for watchpoints, so setting too many hardware |
| 657 | breakpoints might cause watchpoint insertion to fail. |
| 658 | |
| 659 | @item |
| 660 | No hardware-assisted watchpoints provided by the target |
| 661 | implementation. |
| 662 | @end itemize |
| 663 | |
| 664 | Software watchpoints are very slow, since @value{GDBN} needs to |
| 665 | single-step the program being debugged and test the value of the |
| 666 | watched expression(s) after each instruction. The rest of this |
| 667 | section is mostly irrelevant for software watchpoints. |
| 668 | |
| 669 | When the inferior stops, @value{GDBN} tries to establish, among other |
| 670 | possible reasons, whether it stopped due to a watchpoint being hit. |
| 671 | It first uses @code{STOPPED_BY_WATCHPOINT} to see if any watchpoint |
| 672 | was hit. If not, all watchpoint checking is skipped. |
| 673 | |
| 674 | Then @value{GDBN} calls @code{target_stopped_data_address} exactly |
| 675 | once. This method returns the address of the watchpoint which |
| 676 | triggered, if the target can determine it. If the triggered address |
| 677 | is available, @value{GDBN} compares the address returned by this |
| 678 | method with each watched memory address in each active watchpoint. |
| 679 | For data-read and data-access watchpoints, @value{GDBN} announces |
| 680 | every watchpoint that watches the triggered address as being hit. |
| 681 | For this reason, data-read and data-access watchpoints |
| 682 | @emph{require} that the triggered address be available; if not, read |
| 683 | and access watchpoints will never be considered hit. For data-write |
| 684 | watchpoints, if the triggered address is available, @value{GDBN} |
| 685 | considers only those watchpoints which match that address; |
| 686 | otherwise, @value{GDBN} considers all data-write watchpoints. For |
| 687 | each data-write watchpoint that @value{GDBN} considers, it evaluates |
| 688 | the expression whose value is being watched, and tests whether the |
| 689 | watched value has changed. Watchpoints whose watched values have |
| 690 | changed are announced as hit. |
| 691 | |
| 692 | @c FIXME move these to the main lists of target/native defns |
| 693 | |
| 694 | @value{GDBN} uses several macros and primitives to support hardware |
| 695 | watchpoints: |
| 696 | |
| 697 | @table @code |
| 698 | @findex TARGET_CAN_USE_HARDWARE_WATCHPOINT |
| 699 | @item TARGET_CAN_USE_HARDWARE_WATCHPOINT (@var{type}, @var{count}, @var{other}) |
| 700 | Return the number of hardware watchpoints of type @var{type} that are |
| 701 | possible to be set. The value is positive if @var{count} watchpoints |
| 702 | of this type can be set, zero if setting watchpoints of this type is |
| 703 | not supported, and negative if @var{count} is more than the maximum |
| 704 | number of watchpoints of type @var{type} that can be set. @var{other} |
| 705 | is non-zero if other types of watchpoints are currently enabled (there |
| 706 | are architectures which cannot set watchpoints of different types at |
| 707 | the same time). |
| 708 | |
| 709 | @findex TARGET_REGION_OK_FOR_HW_WATCHPOINT |
| 710 | @item TARGET_REGION_OK_FOR_HW_WATCHPOINT (@var{addr}, @var{len}) |
| 711 | Return non-zero if hardware watchpoints can be used to watch a region |
| 712 | whose address is @var{addr} and whose length in bytes is @var{len}. |
| 713 | |
| 714 | @cindex insert or remove hardware watchpoint |
| 715 | @findex target_insert_watchpoint |
| 716 | @findex target_remove_watchpoint |
| 717 | @item target_insert_watchpoint (@var{addr}, @var{len}, @var{type}) |
| 718 | @itemx target_remove_watchpoint (@var{addr}, @var{len}, @var{type}) |
| 719 | Insert or remove a hardware watchpoint starting at @var{addr}, for |
| 720 | @var{len} bytes. @var{type} is the watchpoint type, one of the |
| 721 | possible values of the enumerated data type @code{target_hw_bp_type}, |
| 722 | defined by @file{breakpoint.h} as follows: |
| 723 | |
| 724 | @smallexample |
| 725 | enum target_hw_bp_type |
| 726 | @{ |
| 727 | hw_write = 0, /* Common (write) HW watchpoint */ |
| 728 | hw_read = 1, /* Read HW watchpoint */ |
| 729 | hw_access = 2, /* Access (read or write) HW watchpoint */ |
| 730 | hw_execute = 3 /* Execute HW breakpoint */ |
| 731 | @}; |
| 732 | @end smallexample |
| 733 | |
| 734 | @noindent |
| 735 | These two macros should return 0 for success, non-zero for failure. |
| 736 | |
| 737 | @findex target_stopped_data_address |
| 738 | @item target_stopped_data_address (@var{addr_p}) |
| 739 | If the inferior has some watchpoint that triggered, place the address |
| 740 | associated with the watchpoint at the location pointed to by |
| 741 | @var{addr_p} and return non-zero. Otherwise, return zero. This |
| 742 | is required for data-read and data-access watchpoints. It is |
| 743 | not required for data-write watchpoints, but @value{GDBN} uses |
| 744 | it to improve handling of those also. |
| 745 | |
| 746 | @value{GDBN} will only call this method once per watchpoint stop, |
| 747 | immediately after calling @code{STOPPED_BY_WATCHPOINT}. If the |
| 748 | target's watchpoint indication is sticky, i.e., stays set after |
| 749 | resuming, this method should clear it. For instance, the x86 debug |
| 750 | control register has sticky triggered flags. |
| 751 | |
| 752 | @findex target_watchpoint_addr_within_range |
| 753 | @item target_watchpoint_addr_within_range (@var{target}, @var{addr}, @var{start}, @var{length}) |
| 754 | Check whether @var{addr} (as returned by @code{target_stopped_data_address}) |
| 755 | lies within the hardware-defined watchpoint region described by |
| 756 | @var{start} and @var{length}. This only needs to be provided if the |
| 757 | granularity of a watchpoint is greater than one byte, i.e., if the |
| 758 | watchpoint can also trigger on nearby addresses outside of the watched |
| 759 | region. |
| 760 | |
| 761 | @findex HAVE_STEPPABLE_WATCHPOINT |
| 762 | @item HAVE_STEPPABLE_WATCHPOINT |
| 763 | If defined to a non-zero value, it is not necessary to disable a |
| 764 | watchpoint to step over it. Like @code{gdbarch_have_nonsteppable_watchpoint}, |
| 765 | this is usually set when watchpoints trigger at the instruction |
| 766 | which will perform an interesting read or write. It should be |
| 767 | set if there is a temporary disable bit which allows the processor |
| 768 | to step over the interesting instruction without raising the |
| 769 | watchpoint exception again. |
| 770 | |
| 771 | @findex gdbarch_have_nonsteppable_watchpoint |
| 772 | @item int gdbarch_have_nonsteppable_watchpoint (@var{gdbarch}) |
| 773 | If it returns a non-zero value, @value{GDBN} should disable a |
| 774 | watchpoint to step the inferior over it. This is usually set when |
| 775 | watchpoints trigger at the instruction which will perform an |
| 776 | interesting read or write. |
| 777 | |
| 778 | @findex HAVE_CONTINUABLE_WATCHPOINT |
| 779 | @item HAVE_CONTINUABLE_WATCHPOINT |
| 780 | If defined to a non-zero value, it is possible to continue the |
| 781 | inferior after a watchpoint has been hit. This is usually set |
| 782 | when watchpoints trigger at the instruction following an interesting |
| 783 | read or write. |
| 784 | |
| 785 | @findex STOPPED_BY_WATCHPOINT |
| 786 | @item STOPPED_BY_WATCHPOINT (@var{wait_status}) |
| 787 | Return non-zero if stopped by a watchpoint. @var{wait_status} is of |
| 788 | the type @code{struct target_waitstatus}, defined by @file{target.h}. |
| 789 | Normally, this macro is defined to invoke the function pointed to by |
| 790 | the @code{to_stopped_by_watchpoint} member of the structure (of the |
| 791 | type @code{target_ops}, defined on @file{target.h}) that describes the |
| 792 | target-specific operations; @code{to_stopped_by_watchpoint} ignores |
| 793 | the @var{wait_status} argument. |
| 794 | |
| 795 | @value{GDBN} does not require the non-zero value returned by |
| 796 | @code{STOPPED_BY_WATCHPOINT} to be 100% correct, so if a target cannot |
| 797 | determine for sure whether the inferior stopped due to a watchpoint, |
| 798 | it could return non-zero ``just in case''. |
| 799 | @end table |
| 800 | |
| 801 | @subsection Watchpoints and Threads |
| 802 | @cindex watchpoints, with threads |
| 803 | |
| 804 | @value{GDBN} only supports process-wide watchpoints, which trigger |
| 805 | in all threads. @value{GDBN} uses the thread ID to make watchpoints |
| 806 | act as if they were thread-specific, but it cannot set hardware |
| 807 | watchpoints that only trigger in a specific thread. Therefore, even |
| 808 | if the target supports threads, per-thread debug registers, and |
| 809 | watchpoints which only affect a single thread, it should set the |
| 810 | per-thread debug registers for all threads to the same value. On |
| 811 | @sc{gnu}/Linux native targets, this is accomplished by using |
| 812 | @code{ALL_LWPS} in @code{target_insert_watchpoint} and |
| 813 | @code{target_remove_watchpoint} and by using |
| 814 | @code{linux_set_new_thread} to register a handler for newly created |
| 815 | threads. |
| 816 | |
| 817 | @value{GDBN}'s @sc{gnu}/Linux support only reports a single event |
| 818 | at a time, although multiple events can trigger simultaneously for |
| 819 | multi-threaded programs. When multiple events occur, @file{linux-nat.c} |
| 820 | queues subsequent events and returns them the next time the program |
| 821 | is resumed. This means that @code{STOPPED_BY_WATCHPOINT} and |
| 822 | @code{target_stopped_data_address} only need to consult the current |
| 823 | thread's state---the thread indicated by @code{inferior_ptid}. If |
| 824 | two threads have hit watchpoints simultaneously, those routines |
| 825 | will be called a second time for the second thread. |
| 826 | |
| 827 | @subsection x86 Watchpoints |
| 828 | @cindex x86 debug registers |
| 829 | @cindex watchpoints, on x86 |
| 830 | |
| 831 | The 32-bit Intel x86 (a.k.a.@: ia32) processors feature special debug |
| 832 | registers designed to facilitate debugging. @value{GDBN} provides a |
| 833 | generic library of functions that x86-based ports can use to implement |
| 834 | support for watchpoints and hardware-assisted breakpoints. This |
| 835 | subsection documents the x86 watchpoint facilities in @value{GDBN}. |
| 836 | |
| 837 | (At present, the library functions read and write debug registers directly, and are |
| 838 | thus only available for native configurations.) |
| 839 | |
| 840 | To use the generic x86 watchpoint support, a port should do the |
| 841 | following: |
| 842 | |
| 843 | @itemize @bullet |
| 844 | @findex I386_USE_GENERIC_WATCHPOINTS |
| 845 | @item |
| 846 | Define the macro @code{I386_USE_GENERIC_WATCHPOINTS} somewhere in the |
| 847 | target-dependent headers. |
| 848 | |
| 849 | @item |
| 850 | Include the @file{config/i386/nm-i386.h} header file @emph{after} |
| 851 | defining @code{I386_USE_GENERIC_WATCHPOINTS}. |
| 852 | |
| 853 | @item |
| 854 | Add @file{i386-nat.o} to the value of the Make variable |
| 855 | @code{NATDEPFILES} (@pxref{Native Debugging, NATDEPFILES}). |
| 856 | |
| 857 | @item |
| 858 | Provide implementations for the @code{I386_DR_LOW_*} macros described |
| 859 | below. Typically, each macro should call a target-specific function |
| 860 | which does the real work. |
| 861 | @end itemize |
| 862 | |
| 863 | The x86 watchpoint support works by maintaining mirror images of the |
| 864 | debug registers. Values are copied between the mirror images and the |
| 865 | real debug registers via a set of macros which each target needs to |
| 866 | provide: |
| 867 | |
| 868 | @table @code |
| 869 | @findex I386_DR_LOW_SET_CONTROL |
| 870 | @item I386_DR_LOW_SET_CONTROL (@var{val}) |
| 871 | Set the Debug Control (DR7) register to the value @var{val}. |
| 872 | |
| 873 | @findex I386_DR_LOW_SET_ADDR |
| 874 | @item I386_DR_LOW_SET_ADDR (@var{idx}, @var{addr}) |
| 875 | Put the address @var{addr} into the debug register number @var{idx}. |
| 876 | |
| 877 | @findex I386_DR_LOW_RESET_ADDR |
| 878 | @item I386_DR_LOW_RESET_ADDR (@var{idx}) |
| 879 | Reset (i.e.@: zero out) the address stored in the debug register |
| 880 | number @var{idx}. |
| 881 | |
| 882 | @findex I386_DR_LOW_GET_STATUS |
| 883 | @item I386_DR_LOW_GET_STATUS |
| 884 | Return the value of the Debug Status (DR6) register. This value is |
| 885 | used immediately after it is returned by |
| 886 | @code{I386_DR_LOW_GET_STATUS}, so as to support per-thread status |
| 887 | register values. |
| 888 | @end table |
| 889 | |
| 890 | For each one of the 4 debug registers (whose indices are from 0 to 3) |
| 891 | that store addresses, a reference count is maintained by @value{GDBN}, |
| 892 | to allow sharing of debug registers by several watchpoints. This |
| 893 | allows users to define several watchpoints that watch the same |
| 894 | expression, but with different conditions and/or commands, without |
| 895 | wasting debug registers which are in short supply. @value{GDBN} |
| 896 | maintains the reference counts internally, targets don't have to do |
| 897 | anything to use this feature. |
| 898 | |
| 899 | The x86 debug registers can each watch a region that is 1, 2, or 4 |
| 900 | bytes long. The ia32 architecture requires that each watched region |
| 901 | be appropriately aligned: 2-byte region on 2-byte boundary, 4-byte |
| 902 | region on 4-byte boundary. However, the x86 watchpoint support in |
| 903 | @value{GDBN} can watch unaligned regions and regions larger than 4 |
| 904 | bytes (up to 16 bytes) by allocating several debug registers to watch |
| 905 | a single region. This allocation of several registers per a watched |
| 906 | region is also done automatically without target code intervention. |
| 907 | |
| 908 | The generic x86 watchpoint support provides the following API for the |
| 909 | @value{GDBN}'s application code: |
| 910 | |
| 911 | @table @code |
| 912 | @findex i386_region_ok_for_watchpoint |
| 913 | @item i386_region_ok_for_watchpoint (@var{addr}, @var{len}) |
| 914 | The macro @code{TARGET_REGION_OK_FOR_HW_WATCHPOINT} is set to call |
| 915 | this function. It counts the number of debug registers required to |
| 916 | watch a given region, and returns a non-zero value if that number is |
| 917 | less than 4, the number of debug registers available to x86 |
| 918 | processors. |
| 919 | |
| 920 | @findex i386_stopped_data_address |
| 921 | @item i386_stopped_data_address (@var{addr_p}) |
| 922 | The target function |
| 923 | @code{target_stopped_data_address} is set to call this function. |
| 924 | This |
| 925 | function examines the breakpoint condition bits in the DR6 Debug |
| 926 | Status register, as returned by the @code{I386_DR_LOW_GET_STATUS} |
| 927 | macro, and returns the address associated with the first bit that is |
| 928 | set in DR6. |
| 929 | |
| 930 | @findex i386_stopped_by_watchpoint |
| 931 | @item i386_stopped_by_watchpoint (void) |
| 932 | The macro @code{STOPPED_BY_WATCHPOINT} |
| 933 | is set to call this function. The |
| 934 | argument passed to @code{STOPPED_BY_WATCHPOINT} is ignored. This |
| 935 | function examines the breakpoint condition bits in the DR6 Debug |
| 936 | Status register, as returned by the @code{I386_DR_LOW_GET_STATUS} |
| 937 | macro, and returns true if any bit is set. Otherwise, false is |
| 938 | returned. |
| 939 | |
| 940 | @findex i386_insert_watchpoint |
| 941 | @findex i386_remove_watchpoint |
| 942 | @item i386_insert_watchpoint (@var{addr}, @var{len}, @var{type}) |
| 943 | @itemx i386_remove_watchpoint (@var{addr}, @var{len}, @var{type}) |
| 944 | Insert or remove a watchpoint. The macros |
| 945 | @code{target_insert_watchpoint} and @code{target_remove_watchpoint} |
| 946 | are set to call these functions. @code{i386_insert_watchpoint} first |
| 947 | looks for a debug register which is already set to watch the same |
| 948 | region for the same access types; if found, it just increments the |
| 949 | reference count of that debug register, thus implementing debug |
| 950 | register sharing between watchpoints. If no such register is found, |
| 951 | the function looks for a vacant debug register, sets its mirrored |
| 952 | value to @var{addr}, sets the mirrored value of DR7 Debug Control |
| 953 | register as appropriate for the @var{len} and @var{type} parameters, |
| 954 | and then passes the new values of the debug register and DR7 to the |
| 955 | inferior by calling @code{I386_DR_LOW_SET_ADDR} and |
| 956 | @code{I386_DR_LOW_SET_CONTROL}. If more than one debug register is |
| 957 | required to cover the given region, the above process is repeated for |
| 958 | each debug register. |
| 959 | |
| 960 | @code{i386_remove_watchpoint} does the opposite: it resets the address |
| 961 | in the mirrored value of the debug register and its read/write and |
| 962 | length bits in the mirrored value of DR7, then passes these new |
| 963 | values to the inferior via @code{I386_DR_LOW_RESET_ADDR} and |
| 964 | @code{I386_DR_LOW_SET_CONTROL}. If a register is shared by several |
| 965 | watchpoints, each time a @code{i386_remove_watchpoint} is called, it |
| 966 | decrements the reference count, and only calls |
| 967 | @code{I386_DR_LOW_RESET_ADDR} and @code{I386_DR_LOW_SET_CONTROL} when |
| 968 | the count goes to zero. |
| 969 | |
| 970 | @findex i386_insert_hw_breakpoint |
| 971 | @findex i386_remove_hw_breakpoint |
| 972 | @item i386_insert_hw_breakpoint (@var{bp_tgt}) |
| 973 | @itemx i386_remove_hw_breakpoint (@var{bp_tgt}) |
| 974 | These functions insert and remove hardware-assisted breakpoints. The |
| 975 | macros @code{target_insert_hw_breakpoint} and |
| 976 | @code{target_remove_hw_breakpoint} are set to call these functions. |
| 977 | The argument is a @code{struct bp_target_info *}, as described in |
| 978 | the documentation for @code{target_insert_breakpoint}. |
| 979 | These functions work like @code{i386_insert_watchpoint} and |
| 980 | @code{i386_remove_watchpoint}, respectively, except that they set up |
| 981 | the debug registers to watch instruction execution, and each |
| 982 | hardware-assisted breakpoint always requires exactly one debug |
| 983 | register. |
| 984 | |
| 985 | @findex i386_cleanup_dregs |
| 986 | @item i386_cleanup_dregs (void) |
| 987 | This function clears all the reference counts, addresses, and control |
| 988 | bits in the mirror images of the debug registers. It doesn't affect |
| 989 | the actual debug registers in the inferior process. |
| 990 | @end table |
| 991 | |
| 992 | @noindent |
| 993 | @strong{Notes:} |
| 994 | @enumerate 1 |
| 995 | @item |
| 996 | x86 processors support setting watchpoints on I/O reads or writes. |
| 997 | However, since no target supports this (as of March 2001), and since |
| 998 | @code{enum target_hw_bp_type} doesn't even have an enumeration for I/O |
| 999 | watchpoints, this feature is not yet available to @value{GDBN} running |
| 1000 | on x86. |
| 1001 | |
| 1002 | @item |
| 1003 | x86 processors can enable watchpoints locally, for the current task |
| 1004 | only, or globally, for all the tasks. For each debug register, |
| 1005 | there's a bit in the DR7 Debug Control register that determines |
| 1006 | whether the associated address is watched locally or globally. The |
| 1007 | current implementation of x86 watchpoint support in @value{GDBN} |
| 1008 | always sets watchpoints to be locally enabled, since global |
| 1009 | watchpoints might interfere with the underlying OS and are probably |
| 1010 | unavailable in many platforms. |
| 1011 | @end enumerate |
| 1012 | |
| 1013 | @section Checkpoints |
| 1014 | @cindex checkpoints |
| 1015 | @cindex restart |
| 1016 | In the abstract, a checkpoint is a point in the execution history of |
| 1017 | the program, which the user may wish to return to at some later time. |
| 1018 | |
| 1019 | Internally, a checkpoint is a saved copy of the program state, including |
| 1020 | whatever information is required in order to restore the program to that |
| 1021 | state at a later time. This can be expected to include the state of |
| 1022 | registers and memory, and may include external state such as the state |
| 1023 | of open files and devices. |
| 1024 | |
| 1025 | There are a number of ways in which checkpoints may be implemented |
| 1026 | in gdb, e.g.@: as corefiles, as forked processes, and as some opaque |
| 1027 | method implemented on the target side. |
| 1028 | |
| 1029 | A corefile can be used to save an image of target memory and register |
| 1030 | state, which can in principle be restored later --- but corefiles do |
| 1031 | not typically include information about external entities such as |
| 1032 | open files. Currently this method is not implemented in gdb. |
| 1033 | |
| 1034 | A forked process can save the state of user memory and registers, |
| 1035 | as well as some subset of external (kernel) state. This method |
| 1036 | is used to implement checkpoints on Linux, and in principle might |
| 1037 | be used on other systems. |
| 1038 | |
| 1039 | Some targets, e.g.@: simulators, might have their own built-in |
| 1040 | method for saving checkpoints, and gdb might be able to take |
| 1041 | advantage of that capability without necessarily knowing any |
| 1042 | details of how it is done. |
| 1043 | |
| 1044 | |
| 1045 | @section Observing changes in @value{GDBN} internals |
| 1046 | @cindex observer pattern interface |
| 1047 | @cindex notifications about changes in internals |
| 1048 | |
| 1049 | In order to function properly, several modules need to be notified when |
| 1050 | some changes occur in the @value{GDBN} internals. Traditionally, these |
| 1051 | modules have relied on several paradigms, the most common ones being |
| 1052 | hooks and gdb-events. Unfortunately, none of these paradigms was |
| 1053 | versatile enough to become the standard notification mechanism in |
| 1054 | @value{GDBN}. The fact that they only supported one ``client'' was also |
| 1055 | a strong limitation. |
| 1056 | |
| 1057 | A new paradigm, based on the Observer pattern of the @cite{Design |
| 1058 | Patterns} book, has therefore been implemented. The goal was to provide |
| 1059 | a new interface overcoming the issues with the notification mechanisms |
| 1060 | previously available. This new interface needed to be strongly typed, |
| 1061 | easy to extend, and versatile enough to be used as the standard |
| 1062 | interface when adding new notifications. |
| 1063 | |
| 1064 | See @ref{GDB Observers} for a brief description of the observers |
| 1065 | currently implemented in GDB. The rationale for the current |
| 1066 | implementation is also briefly discussed. |
| 1067 | |
| 1068 | @node User Interface |
| 1069 | |
| 1070 | @chapter User Interface |
| 1071 | |
| 1072 | @value{GDBN} has several user interfaces, of which the traditional |
| 1073 | command-line interface is perhaps the most familiar. |
| 1074 | |
| 1075 | @section Command Interpreter |
| 1076 | |
| 1077 | @cindex command interpreter |
| 1078 | @cindex CLI |
| 1079 | The command interpreter in @value{GDBN} is fairly simple. It is designed to |
| 1080 | allow for the set of commands to be augmented dynamically, and also |
| 1081 | has a recursive subcommand capability, where the first argument to |
| 1082 | a command may itself direct a lookup on a different command list. |
| 1083 | |
| 1084 | For instance, the @samp{set} command just starts a lookup on the |
| 1085 | @code{setlist} command list, while @samp{set thread} recurses |
| 1086 | to the @code{set_thread_cmd_list}. |
| 1087 | |
| 1088 | @findex add_cmd |
| 1089 | @findex add_com |
| 1090 | To add commands in general, use @code{add_cmd}. @code{add_com} adds to |
| 1091 | the main command list, and should be used for those commands. The usual |
| 1092 | place to add commands is in the @code{_initialize_@var{xyz}} routines at |
| 1093 | the ends of most source files. |
| 1094 | |
| 1095 | @findex add_setshow_cmd |
| 1096 | @findex add_setshow_cmd_full |
| 1097 | To add paired @samp{set} and @samp{show} commands, use |
| 1098 | @code{add_setshow_cmd} or @code{add_setshow_cmd_full}. The former is |
| 1099 | a slightly simpler interface which is useful when you don't need to |
| 1100 | further modify the new command structures, while the latter returns |
| 1101 | the new command structures for manipulation. |
| 1102 | |
| 1103 | @cindex deprecating commands |
| 1104 | @findex deprecate_cmd |
| 1105 | Before removing commands from the command set it is a good idea to |
| 1106 | deprecate them for some time. Use @code{deprecate_cmd} on commands or |
| 1107 | aliases to set the deprecated flag. @code{deprecate_cmd} takes a |
| 1108 | @code{struct cmd_list_element} as it's first argument. You can use the |
| 1109 | return value from @code{add_com} or @code{add_cmd} to deprecate the |
| 1110 | command immediately after it is created. |
| 1111 | |
| 1112 | The first time a command is used the user will be warned and offered a |
| 1113 | replacement (if one exists). Note that the replacement string passed to |
| 1114 | @code{deprecate_cmd} should be the full name of the command, i.e., the |
| 1115 | entire string the user should type at the command line. |
| 1116 | |
| 1117 | @anchor{UI-Independent Output} |
| 1118 | @section UI-Independent Output---the @code{ui_out} Functions |
| 1119 | @c This section is based on the documentation written by Fernando |
| 1120 | @c Nasser <fnasser@redhat.com>. |
| 1121 | |
| 1122 | @cindex @code{ui_out} functions |
| 1123 | The @code{ui_out} functions present an abstraction level for the |
| 1124 | @value{GDBN} output code. They hide the specifics of different user |
| 1125 | interfaces supported by @value{GDBN}, and thus free the programmer |
| 1126 | from the need to write several versions of the same code, one each for |
| 1127 | every UI, to produce output. |
| 1128 | |
| 1129 | @subsection Overview and Terminology |
| 1130 | |
| 1131 | In general, execution of each @value{GDBN} command produces some sort |
| 1132 | of output, and can even generate an input request. |
| 1133 | |
| 1134 | Output can be generated for the following purposes: |
| 1135 | |
| 1136 | @itemize @bullet |
| 1137 | @item |
| 1138 | to display a @emph{result} of an operation; |
| 1139 | |
| 1140 | @item |
| 1141 | to convey @emph{info} or produce side-effects of a requested |
| 1142 | operation; |
| 1143 | |
| 1144 | @item |
| 1145 | to provide a @emph{notification} of an asynchronous event (including |
| 1146 | progress indication of a prolonged asynchronous operation); |
| 1147 | |
| 1148 | @item |
| 1149 | to display @emph{error messages} (including warnings); |
| 1150 | |
| 1151 | @item |
| 1152 | to show @emph{debug data}; |
| 1153 | |
| 1154 | @item |
| 1155 | to @emph{query} or prompt a user for input (a special case). |
| 1156 | @end itemize |
| 1157 | |
| 1158 | @noindent |
| 1159 | This section mainly concentrates on how to build result output, |
| 1160 | although some of it also applies to other kinds of output. |
| 1161 | |
| 1162 | Generation of output that displays the results of an operation |
| 1163 | involves one or more of the following: |
| 1164 | |
| 1165 | @itemize @bullet |
| 1166 | @item |
| 1167 | output of the actual data |
| 1168 | |
| 1169 | @item |
| 1170 | formatting the output as appropriate for console output, to make it |
| 1171 | easily readable by humans |
| 1172 | |
| 1173 | @item |
| 1174 | machine oriented formatting--a more terse formatting to allow for easy |
| 1175 | parsing by programs which read @value{GDBN}'s output |
| 1176 | |
| 1177 | @item |
| 1178 | annotation, whose purpose is to help legacy GUIs to identify interesting |
| 1179 | parts in the output |
| 1180 | @end itemize |
| 1181 | |
| 1182 | The @code{ui_out} routines take care of the first three aspects. |
| 1183 | Annotations are provided by separate annotation routines. Note that use |
| 1184 | of annotations for an interface between a GUI and @value{GDBN} is |
| 1185 | deprecated. |
| 1186 | |
| 1187 | Output can be in the form of a single item, which we call a @dfn{field}; |
| 1188 | a @dfn{list} consisting of identical fields; a @dfn{tuple} consisting of |
| 1189 | non-identical fields; or a @dfn{table}, which is a tuple consisting of a |
| 1190 | header and a body. In a BNF-like form: |
| 1191 | |
| 1192 | @table @code |
| 1193 | @item <table> @expansion{} |
| 1194 | @code{<header> <body>} |
| 1195 | @item <header> @expansion{} |
| 1196 | @code{@{ <column> @}} |
| 1197 | @item <column> @expansion{} |
| 1198 | @code{<width> <alignment> <title>} |
| 1199 | @item <body> @expansion{} |
| 1200 | @code{@{<row>@}} |
| 1201 | @end table |
| 1202 | |
| 1203 | |
| 1204 | @subsection General Conventions |
| 1205 | |
| 1206 | Most @code{ui_out} routines are of type @code{void}, the exceptions are |
| 1207 | @code{ui_out_stream_new} (which returns a pointer to the newly created |
| 1208 | object) and the @code{make_cleanup} routines. |
| 1209 | |
| 1210 | The first parameter is always the @code{ui_out} vector object, a pointer |
| 1211 | to a @code{struct ui_out}. |
| 1212 | |
| 1213 | The @var{format} parameter is like in @code{printf} family of functions. |
| 1214 | When it is present, there must also be a variable list of arguments |
| 1215 | sufficient used to satisfy the @code{%} specifiers in the supplied |
| 1216 | format. |
| 1217 | |
| 1218 | When a character string argument is not used in a @code{ui_out} function |
| 1219 | call, a @code{NULL} pointer has to be supplied instead. |
| 1220 | |
| 1221 | |
| 1222 | @subsection Table, Tuple and List Functions |
| 1223 | |
| 1224 | @cindex list output functions |
| 1225 | @cindex table output functions |
| 1226 | @cindex tuple output functions |
| 1227 | This section introduces @code{ui_out} routines for building lists, |
| 1228 | tuples and tables. The routines to output the actual data items |
| 1229 | (fields) are presented in the next section. |
| 1230 | |
| 1231 | To recap: A @dfn{tuple} is a sequence of @dfn{fields}, each field |
| 1232 | containing information about an object; a @dfn{list} is a sequence of |
| 1233 | fields where each field describes an identical object. |
| 1234 | |
| 1235 | Use the @dfn{table} functions when your output consists of a list of |
| 1236 | rows (tuples) and the console output should include a heading. Use this |
| 1237 | even when you are listing just one object but you still want the header. |
| 1238 | |
| 1239 | @cindex nesting level in @code{ui_out} functions |
| 1240 | Tables can not be nested. Tuples and lists can be nested up to a |
| 1241 | maximum of five levels. |
| 1242 | |
| 1243 | The overall structure of the table output code is something like this: |
| 1244 | |
| 1245 | @smallexample |
| 1246 | ui_out_table_begin |
| 1247 | ui_out_table_header |
| 1248 | @dots{} |
| 1249 | ui_out_table_body |
| 1250 | ui_out_tuple_begin |
| 1251 | ui_out_field_* |
| 1252 | @dots{} |
| 1253 | ui_out_tuple_end |
| 1254 | @dots{} |
| 1255 | ui_out_table_end |
| 1256 | @end smallexample |
| 1257 | |
| 1258 | Here is the description of table-, tuple- and list-related @code{ui_out} |
| 1259 | functions: |
| 1260 | |
| 1261 | @deftypefun void ui_out_table_begin (struct ui_out *@var{uiout}, int @var{nbrofcols}, int @var{nr_rows}, const char *@var{tblid}) |
| 1262 | The function @code{ui_out_table_begin} marks the beginning of the output |
| 1263 | of a table. It should always be called before any other @code{ui_out} |
| 1264 | function for a given table. @var{nbrofcols} is the number of columns in |
| 1265 | the table. @var{nr_rows} is the number of rows in the table. |
| 1266 | @var{tblid} is an optional string identifying the table. The string |
| 1267 | pointed to by @var{tblid} is copied by the implementation of |
| 1268 | @code{ui_out_table_begin}, so the application can free the string if it |
| 1269 | was @code{malloc}ed. |
| 1270 | |
| 1271 | The companion function @code{ui_out_table_end}, described below, marks |
| 1272 | the end of the table's output. |
| 1273 | @end deftypefun |
| 1274 | |
| 1275 | @deftypefun void ui_out_table_header (struct ui_out *@var{uiout}, int @var{width}, enum ui_align @var{alignment}, const char *@var{colhdr}) |
| 1276 | @code{ui_out_table_header} provides the header information for a single |
| 1277 | table column. You call this function several times, one each for every |
| 1278 | column of the table, after @code{ui_out_table_begin}, but before |
| 1279 | @code{ui_out_table_body}. |
| 1280 | |
| 1281 | The value of @var{width} gives the column width in characters. The |
| 1282 | value of @var{alignment} is one of @code{left}, @code{center}, and |
| 1283 | @code{right}, and it specifies how to align the header: left-justify, |
| 1284 | center, or right-justify it. @var{colhdr} points to a string that |
| 1285 | specifies the column header; the implementation copies that string, so |
| 1286 | column header strings in @code{malloc}ed storage can be freed after the |
| 1287 | call. |
| 1288 | @end deftypefun |
| 1289 | |
| 1290 | @deftypefun void ui_out_table_body (struct ui_out *@var{uiout}) |
| 1291 | This function delimits the table header from the table body. |
| 1292 | @end deftypefun |
| 1293 | |
| 1294 | @deftypefun void ui_out_table_end (struct ui_out *@var{uiout}) |
| 1295 | This function signals the end of a table's output. It should be called |
| 1296 | after the table body has been produced by the list and field output |
| 1297 | functions. |
| 1298 | |
| 1299 | There should be exactly one call to @code{ui_out_table_end} for each |
| 1300 | call to @code{ui_out_table_begin}, otherwise the @code{ui_out} functions |
| 1301 | will signal an internal error. |
| 1302 | @end deftypefun |
| 1303 | |
| 1304 | The output of the tuples that represent the table rows must follow the |
| 1305 | call to @code{ui_out_table_body} and precede the call to |
| 1306 | @code{ui_out_table_end}. You build a tuple by calling |
| 1307 | @code{ui_out_tuple_begin} and @code{ui_out_tuple_end}, with suitable |
| 1308 | calls to functions which actually output fields between them. |
| 1309 | |
| 1310 | @deftypefun void ui_out_tuple_begin (struct ui_out *@var{uiout}, const char *@var{id}) |
| 1311 | This function marks the beginning of a tuple output. @var{id} points |
| 1312 | to an optional string that identifies the tuple; it is copied by the |
| 1313 | implementation, and so strings in @code{malloc}ed storage can be freed |
| 1314 | after the call. |
| 1315 | @end deftypefun |
| 1316 | |
| 1317 | @deftypefun void ui_out_tuple_end (struct ui_out *@var{uiout}) |
| 1318 | This function signals an end of a tuple output. There should be exactly |
| 1319 | one call to @code{ui_out_tuple_end} for each call to |
| 1320 | @code{ui_out_tuple_begin}, otherwise an internal @value{GDBN} error will |
| 1321 | be signaled. |
| 1322 | @end deftypefun |
| 1323 | |
| 1324 | @deftypefun {struct cleanup *} make_cleanup_ui_out_tuple_begin_end (struct ui_out *@var{uiout}, const char *@var{id}) |
| 1325 | This function first opens the tuple and then establishes a cleanup |
| 1326 | (@pxref{Misc Guidelines, Cleanups}) to close the tuple. |
| 1327 | It provides a convenient and correct implementation of the |
| 1328 | non-portable@footnote{The function cast is not portable ISO C.} code sequence: |
| 1329 | @smallexample |
| 1330 | struct cleanup *old_cleanup; |
| 1331 | ui_out_tuple_begin (uiout, "..."); |
| 1332 | old_cleanup = make_cleanup ((void(*)(void *)) ui_out_tuple_end, |
| 1333 | uiout); |
| 1334 | @end smallexample |
| 1335 | @end deftypefun |
| 1336 | |
| 1337 | @deftypefun void ui_out_list_begin (struct ui_out *@var{uiout}, const char *@var{id}) |
| 1338 | This function marks the beginning of a list output. @var{id} points to |
| 1339 | an optional string that identifies the list; it is copied by the |
| 1340 | implementation, and so strings in @code{malloc}ed storage can be freed |
| 1341 | after the call. |
| 1342 | @end deftypefun |
| 1343 | |
| 1344 | @deftypefun void ui_out_list_end (struct ui_out *@var{uiout}) |
| 1345 | This function signals an end of a list output. There should be exactly |
| 1346 | one call to @code{ui_out_list_end} for each call to |
| 1347 | @code{ui_out_list_begin}, otherwise an internal @value{GDBN} error will |
| 1348 | be signaled. |
| 1349 | @end deftypefun |
| 1350 | |
| 1351 | @deftypefun {struct cleanup *} make_cleanup_ui_out_list_begin_end (struct ui_out *@var{uiout}, const char *@var{id}) |
| 1352 | Similar to @code{make_cleanup_ui_out_tuple_begin_end}, this function |
| 1353 | opens a list and then establishes cleanup |
| 1354 | (@pxref{Misc Guidelines, Cleanups}) |
| 1355 | that will close the list. |
| 1356 | @end deftypefun |
| 1357 | |
| 1358 | @subsection Item Output Functions |
| 1359 | |
| 1360 | @cindex item output functions |
| 1361 | @cindex field output functions |
| 1362 | @cindex data output |
| 1363 | The functions described below produce output for the actual data |
| 1364 | items, or fields, which contain information about the object. |
| 1365 | |
| 1366 | Choose the appropriate function accordingly to your particular needs. |
| 1367 | |
| 1368 | @deftypefun void ui_out_field_fmt (struct ui_out *@var{uiout}, char *@var{fldname}, char *@var{format}, ...) |
| 1369 | This is the most general output function. It produces the |
| 1370 | representation of the data in the variable-length argument list |
| 1371 | according to formatting specifications in @var{format}, a |
| 1372 | @code{printf}-like format string. The optional argument @var{fldname} |
| 1373 | supplies the name of the field. The data items themselves are |
| 1374 | supplied as additional arguments after @var{format}. |
| 1375 | |
| 1376 | This generic function should be used only when it is not possible to |
| 1377 | use one of the specialized versions (see below). |
| 1378 | @end deftypefun |
| 1379 | |
| 1380 | @deftypefun void ui_out_field_int (struct ui_out *@var{uiout}, const char *@var{fldname}, int @var{value}) |
| 1381 | This function outputs a value of an @code{int} variable. It uses the |
| 1382 | @code{"%d"} output conversion specification. @var{fldname} specifies |
| 1383 | the name of the field. |
| 1384 | @end deftypefun |
| 1385 | |
| 1386 | @deftypefun void ui_out_field_fmt_int (struct ui_out *@var{uiout}, int @var{width}, enum ui_align @var{alignment}, const char *@var{fldname}, int @var{value}) |
| 1387 | This function outputs a value of an @code{int} variable. It differs from |
| 1388 | @code{ui_out_field_int} in that the caller specifies the desired @var{width} and @var{alignment} of the output. |
| 1389 | @var{fldname} specifies |
| 1390 | the name of the field. |
| 1391 | @end deftypefun |
| 1392 | |
| 1393 | @deftypefun void ui_out_field_core_addr (struct ui_out *@var{uiout}, const char *@var{fldname}, struct gdbarch *@var{gdbarch}, CORE_ADDR @var{address}) |
| 1394 | This function outputs an address as appropriate for @var{gdbarch}. |
| 1395 | @end deftypefun |
| 1396 | |
| 1397 | @deftypefun void ui_out_field_string (struct ui_out *@var{uiout}, const char *@var{fldname}, const char *@var{string}) |
| 1398 | This function outputs a string using the @code{"%s"} conversion |
| 1399 | specification. |
| 1400 | @end deftypefun |
| 1401 | |
| 1402 | Sometimes, there's a need to compose your output piece by piece using |
| 1403 | functions that operate on a stream, such as @code{value_print} or |
| 1404 | @code{fprintf_symbol_filtered}. These functions accept an argument of |
| 1405 | the type @code{struct ui_file *}, a pointer to a @code{ui_file} object |
| 1406 | used to store the data stream used for the output. When you use one |
| 1407 | of these functions, you need a way to pass their results stored in a |
| 1408 | @code{ui_file} object to the @code{ui_out} functions. To this end, |
| 1409 | you first create a @code{ui_stream} object by calling |
| 1410 | @code{ui_out_stream_new}, pass the @code{stream} member of that |
| 1411 | @code{ui_stream} object to @code{value_print} and similar functions, |
| 1412 | and finally call @code{ui_out_field_stream} to output the field you |
| 1413 | constructed. When the @code{ui_stream} object is no longer needed, |
| 1414 | you should destroy it and free its memory by calling |
| 1415 | @code{ui_out_stream_delete}. |
| 1416 | |
| 1417 | @deftypefun {struct ui_stream *} ui_out_stream_new (struct ui_out *@var{uiout}) |
| 1418 | This function creates a new @code{ui_stream} object which uses the |
| 1419 | same output methods as the @code{ui_out} object whose pointer is |
| 1420 | passed in @var{uiout}. It returns a pointer to the newly created |
| 1421 | @code{ui_stream} object. |
| 1422 | @end deftypefun |
| 1423 | |
| 1424 | @deftypefun void ui_out_stream_delete (struct ui_stream *@var{streambuf}) |
| 1425 | This functions destroys a @code{ui_stream} object specified by |
| 1426 | @var{streambuf}. |
| 1427 | @end deftypefun |
| 1428 | |
| 1429 | @deftypefun void ui_out_field_stream (struct ui_out *@var{uiout}, const char *@var{fieldname}, struct ui_stream *@var{streambuf}) |
| 1430 | This function consumes all the data accumulated in |
| 1431 | @code{streambuf->stream} and outputs it like |
| 1432 | @code{ui_out_field_string} does. After a call to |
| 1433 | @code{ui_out_field_stream}, the accumulated data no longer exists, but |
| 1434 | the stream is still valid and may be used for producing more fields. |
| 1435 | @end deftypefun |
| 1436 | |
| 1437 | @strong{Important:} If there is any chance that your code could bail |
| 1438 | out before completing output generation and reaching the point where |
| 1439 | @code{ui_out_stream_delete} is called, it is necessary to set up a |
| 1440 | cleanup, to avoid leaking memory and other resources. Here's a |
| 1441 | skeleton code to do that: |
| 1442 | |
| 1443 | @smallexample |
| 1444 | struct ui_stream *mybuf = ui_out_stream_new (uiout); |
| 1445 | struct cleanup *old = make_cleanup (ui_out_stream_delete, mybuf); |
| 1446 | ... |
| 1447 | do_cleanups (old); |
| 1448 | @end smallexample |
| 1449 | |
| 1450 | If the function already has the old cleanup chain set (for other kinds |
| 1451 | of cleanups), you just have to add your cleanup to it: |
| 1452 | |
| 1453 | @smallexample |
| 1454 | mybuf = ui_out_stream_new (uiout); |
| 1455 | make_cleanup (ui_out_stream_delete, mybuf); |
| 1456 | @end smallexample |
| 1457 | |
| 1458 | Note that with cleanups in place, you should not call |
| 1459 | @code{ui_out_stream_delete} directly, or you would attempt to free the |
| 1460 | same buffer twice. |
| 1461 | |
| 1462 | @subsection Utility Output Functions |
| 1463 | |
| 1464 | @deftypefun void ui_out_field_skip (struct ui_out *@var{uiout}, const char *@var{fldname}) |
| 1465 | This function skips a field in a table. Use it if you have to leave |
| 1466 | an empty field without disrupting the table alignment. The argument |
| 1467 | @var{fldname} specifies a name for the (missing) filed. |
| 1468 | @end deftypefun |
| 1469 | |
| 1470 | @deftypefun void ui_out_text (struct ui_out *@var{uiout}, const char *@var{string}) |
| 1471 | This function outputs the text in @var{string} in a way that makes it |
| 1472 | easy to be read by humans. For example, the console implementation of |
| 1473 | this method filters the text through a built-in pager, to prevent it |
| 1474 | from scrolling off the visible portion of the screen. |
| 1475 | |
| 1476 | Use this function for printing relatively long chunks of text around |
| 1477 | the actual field data: the text it produces is not aligned according |
| 1478 | to the table's format. Use @code{ui_out_field_string} to output a |
| 1479 | string field, and use @code{ui_out_message}, described below, to |
| 1480 | output short messages. |
| 1481 | @end deftypefun |
| 1482 | |
| 1483 | @deftypefun void ui_out_spaces (struct ui_out *@var{uiout}, int @var{nspaces}) |
| 1484 | This function outputs @var{nspaces} spaces. It is handy to align the |
| 1485 | text produced by @code{ui_out_text} with the rest of the table or |
| 1486 | list. |
| 1487 | @end deftypefun |
| 1488 | |
| 1489 | @deftypefun void ui_out_message (struct ui_out *@var{uiout}, int @var{verbosity}, const char *@var{format}, ...) |
| 1490 | This function produces a formatted message, provided that the current |
| 1491 | verbosity level is at least as large as given by @var{verbosity}. The |
| 1492 | current verbosity level is specified by the user with the @samp{set |
| 1493 | verbositylevel} command.@footnote{As of this writing (April 2001), |
| 1494 | setting verbosity level is not yet implemented, and is always returned |
| 1495 | as zero. So calling @code{ui_out_message} with a @var{verbosity} |
| 1496 | argument more than zero will cause the message to never be printed.} |
| 1497 | @end deftypefun |
| 1498 | |
| 1499 | @deftypefun void ui_out_wrap_hint (struct ui_out *@var{uiout}, char *@var{indent}) |
| 1500 | This function gives the console output filter (a paging filter) a hint |
| 1501 | of where to break lines which are too long. Ignored for all other |
| 1502 | output consumers. @var{indent}, if non-@code{NULL}, is the string to |
| 1503 | be printed to indent the wrapped text on the next line; it must remain |
| 1504 | accessible until the next call to @code{ui_out_wrap_hint}, or until an |
| 1505 | explicit newline is produced by one of the other functions. If |
| 1506 | @var{indent} is @code{NULL}, the wrapped text will not be indented. |
| 1507 | @end deftypefun |
| 1508 | |
| 1509 | @deftypefun void ui_out_flush (struct ui_out *@var{uiout}) |
| 1510 | This function flushes whatever output has been accumulated so far, if |
| 1511 | the UI buffers output. |
| 1512 | @end deftypefun |
| 1513 | |
| 1514 | |
| 1515 | @subsection Examples of Use of @code{ui_out} functions |
| 1516 | |
| 1517 | @cindex using @code{ui_out} functions |
| 1518 | @cindex @code{ui_out} functions, usage examples |
| 1519 | This section gives some practical examples of using the @code{ui_out} |
| 1520 | functions to generalize the old console-oriented code in |
| 1521 | @value{GDBN}. The examples all come from functions defined on the |
| 1522 | @file{breakpoints.c} file. |
| 1523 | |
| 1524 | This example, from the @code{breakpoint_1} function, shows how to |
| 1525 | produce a table. |
| 1526 | |
| 1527 | The original code was: |
| 1528 | |
| 1529 | @smallexample |
| 1530 | if (!found_a_breakpoint++) |
| 1531 | @{ |
| 1532 | annotate_breakpoints_headers (); |
| 1533 | |
| 1534 | annotate_field (0); |
| 1535 | printf_filtered ("Num "); |
| 1536 | annotate_field (1); |
| 1537 | printf_filtered ("Type "); |
| 1538 | annotate_field (2); |
| 1539 | printf_filtered ("Disp "); |
| 1540 | annotate_field (3); |
| 1541 | printf_filtered ("Enb "); |
| 1542 | if (addressprint) |
| 1543 | @{ |
| 1544 | annotate_field (4); |
| 1545 | printf_filtered ("Address "); |
| 1546 | @} |
| 1547 | annotate_field (5); |
| 1548 | printf_filtered ("What\n"); |
| 1549 | |
| 1550 | annotate_breakpoints_table (); |
| 1551 | @} |
| 1552 | @end smallexample |
| 1553 | |
| 1554 | Here's the new version: |
| 1555 | |
| 1556 | @smallexample |
| 1557 | nr_printable_breakpoints = @dots{}; |
| 1558 | |
| 1559 | if (addressprint) |
| 1560 | ui_out_table_begin (ui, 6, nr_printable_breakpoints, "BreakpointTable"); |
| 1561 | else |
| 1562 | ui_out_table_begin (ui, 5, nr_printable_breakpoints, "BreakpointTable"); |
| 1563 | |
| 1564 | if (nr_printable_breakpoints > 0) |
| 1565 | annotate_breakpoints_headers (); |
| 1566 | if (nr_printable_breakpoints > 0) |
| 1567 | annotate_field (0); |
| 1568 | ui_out_table_header (uiout, 3, ui_left, "number", "Num"); /* 1 */ |
| 1569 | if (nr_printable_breakpoints > 0) |
| 1570 | annotate_field (1); |
| 1571 | ui_out_table_header (uiout, 14, ui_left, "type", "Type"); /* 2 */ |
| 1572 | if (nr_printable_breakpoints > 0) |
| 1573 | annotate_field (2); |
| 1574 | ui_out_table_header (uiout, 4, ui_left, "disp", "Disp"); /* 3 */ |
| 1575 | if (nr_printable_breakpoints > 0) |
| 1576 | annotate_field (3); |
| 1577 | ui_out_table_header (uiout, 3, ui_left, "enabled", "Enb"); /* 4 */ |
| 1578 | if (addressprint) |
| 1579 | @{ |
| 1580 | if (nr_printable_breakpoints > 0) |
| 1581 | annotate_field (4); |
| 1582 | if (print_address_bits <= 32) |
| 1583 | ui_out_table_header (uiout, 10, ui_left, "addr", "Address");/* 5 */ |
| 1584 | else |
| 1585 | ui_out_table_header (uiout, 18, ui_left, "addr", "Address");/* 5 */ |
| 1586 | @} |
| 1587 | if (nr_printable_breakpoints > 0) |
| 1588 | annotate_field (5); |
| 1589 | ui_out_table_header (uiout, 40, ui_noalign, "what", "What"); /* 6 */ |
| 1590 | ui_out_table_body (uiout); |
| 1591 | if (nr_printable_breakpoints > 0) |
| 1592 | annotate_breakpoints_table (); |
| 1593 | @end smallexample |
| 1594 | |
| 1595 | This example, from the @code{print_one_breakpoint} function, shows how |
| 1596 | to produce the actual data for the table whose structure was defined |
| 1597 | in the above example. The original code was: |
| 1598 | |
| 1599 | @smallexample |
| 1600 | annotate_record (); |
| 1601 | annotate_field (0); |
| 1602 | printf_filtered ("%-3d ", b->number); |
| 1603 | annotate_field (1); |
| 1604 | if ((int)b->type > (sizeof(bptypes)/sizeof(bptypes[0])) |
| 1605 | || ((int) b->type != bptypes[(int) b->type].type)) |
| 1606 | internal_error ("bptypes table does not describe type #%d.", |
| 1607 | (int)b->type); |
| 1608 | printf_filtered ("%-14s ", bptypes[(int)b->type].description); |
| 1609 | annotate_field (2); |
| 1610 | printf_filtered ("%-4s ", bpdisps[(int)b->disposition]); |
| 1611 | annotate_field (3); |
| 1612 | printf_filtered ("%-3c ", bpenables[(int)b->enable]); |
| 1613 | @dots{} |
| 1614 | @end smallexample |
| 1615 | |
| 1616 | This is the new version: |
| 1617 | |
| 1618 | @smallexample |
| 1619 | annotate_record (); |
| 1620 | ui_out_tuple_begin (uiout, "bkpt"); |
| 1621 | annotate_field (0); |
| 1622 | ui_out_field_int (uiout, "number", b->number); |
| 1623 | annotate_field (1); |
| 1624 | if (((int) b->type > (sizeof (bptypes) / sizeof (bptypes[0]))) |
| 1625 | || ((int) b->type != bptypes[(int) b->type].type)) |
| 1626 | internal_error ("bptypes table does not describe type #%d.", |
| 1627 | (int) b->type); |
| 1628 | ui_out_field_string (uiout, "type", bptypes[(int)b->type].description); |
| 1629 | annotate_field (2); |
| 1630 | ui_out_field_string (uiout, "disp", bpdisps[(int)b->disposition]); |
| 1631 | annotate_field (3); |
| 1632 | ui_out_field_fmt (uiout, "enabled", "%c", bpenables[(int)b->enable]); |
| 1633 | @dots{} |
| 1634 | @end smallexample |
| 1635 | |
| 1636 | This example, also from @code{print_one_breakpoint}, shows how to |
| 1637 | produce a complicated output field using the @code{print_expression} |
| 1638 | functions which requires a stream to be passed. It also shows how to |
| 1639 | automate stream destruction with cleanups. The original code was: |
| 1640 | |
| 1641 | @smallexample |
| 1642 | annotate_field (5); |
| 1643 | print_expression (b->exp, gdb_stdout); |
| 1644 | @end smallexample |
| 1645 | |
| 1646 | The new version is: |
| 1647 | |
| 1648 | @smallexample |
| 1649 | struct ui_stream *stb = ui_out_stream_new (uiout); |
| 1650 | struct cleanup *old_chain = make_cleanup_ui_out_stream_delete (stb); |
| 1651 | ... |
| 1652 | annotate_field (5); |
| 1653 | print_expression (b->exp, stb->stream); |
| 1654 | ui_out_field_stream (uiout, "what", local_stream); |
| 1655 | @end smallexample |
| 1656 | |
| 1657 | This example, also from @code{print_one_breakpoint}, shows how to use |
| 1658 | @code{ui_out_text} and @code{ui_out_field_string}. The original code |
| 1659 | was: |
| 1660 | |
| 1661 | @smallexample |
| 1662 | annotate_field (5); |
| 1663 | if (b->dll_pathname == NULL) |
| 1664 | printf_filtered ("<any library> "); |
| 1665 | else |
| 1666 | printf_filtered ("library \"%s\" ", b->dll_pathname); |
| 1667 | @end smallexample |
| 1668 | |
| 1669 | It became: |
| 1670 | |
| 1671 | @smallexample |
| 1672 | annotate_field (5); |
| 1673 | if (b->dll_pathname == NULL) |
| 1674 | @{ |
| 1675 | ui_out_field_string (uiout, "what", "<any library>"); |
| 1676 | ui_out_spaces (uiout, 1); |
| 1677 | @} |
| 1678 | else |
| 1679 | @{ |
| 1680 | ui_out_text (uiout, "library \""); |
| 1681 | ui_out_field_string (uiout, "what", b->dll_pathname); |
| 1682 | ui_out_text (uiout, "\" "); |
| 1683 | @} |
| 1684 | @end smallexample |
| 1685 | |
| 1686 | The following example from @code{print_one_breakpoint} shows how to |
| 1687 | use @code{ui_out_field_int} and @code{ui_out_spaces}. The original |
| 1688 | code was: |
| 1689 | |
| 1690 | @smallexample |
| 1691 | annotate_field (5); |
| 1692 | if (b->forked_inferior_pid != 0) |
| 1693 | printf_filtered ("process %d ", b->forked_inferior_pid); |
| 1694 | @end smallexample |
| 1695 | |
| 1696 | It became: |
| 1697 | |
| 1698 | @smallexample |
| 1699 | annotate_field (5); |
| 1700 | if (b->forked_inferior_pid != 0) |
| 1701 | @{ |
| 1702 | ui_out_text (uiout, "process "); |
| 1703 | ui_out_field_int (uiout, "what", b->forked_inferior_pid); |
| 1704 | ui_out_spaces (uiout, 1); |
| 1705 | @} |
| 1706 | @end smallexample |
| 1707 | |
| 1708 | Here's an example of using @code{ui_out_field_string}. The original |
| 1709 | code was: |
| 1710 | |
| 1711 | @smallexample |
| 1712 | annotate_field (5); |
| 1713 | if (b->exec_pathname != NULL) |
| 1714 | printf_filtered ("program \"%s\" ", b->exec_pathname); |
| 1715 | @end smallexample |
| 1716 | |
| 1717 | It became: |
| 1718 | |
| 1719 | @smallexample |
| 1720 | annotate_field (5); |
| 1721 | if (b->exec_pathname != NULL) |
| 1722 | @{ |
| 1723 | ui_out_text (uiout, "program \""); |
| 1724 | ui_out_field_string (uiout, "what", b->exec_pathname); |
| 1725 | ui_out_text (uiout, "\" "); |
| 1726 | @} |
| 1727 | @end smallexample |
| 1728 | |
| 1729 | Finally, here's an example of printing an address. The original code: |
| 1730 | |
| 1731 | @smallexample |
| 1732 | annotate_field (4); |
| 1733 | printf_filtered ("%s ", |
| 1734 | hex_string_custom ((unsigned long) b->address, 8)); |
| 1735 | @end smallexample |
| 1736 | |
| 1737 | It became: |
| 1738 | |
| 1739 | @smallexample |
| 1740 | annotate_field (4); |
| 1741 | ui_out_field_core_addr (uiout, "Address", b->address); |
| 1742 | @end smallexample |
| 1743 | |
| 1744 | |
| 1745 | @section Console Printing |
| 1746 | |
| 1747 | @section TUI |
| 1748 | |
| 1749 | @node libgdb |
| 1750 | |
| 1751 | @chapter libgdb |
| 1752 | |
| 1753 | @section libgdb 1.0 |
| 1754 | @cindex @code{libgdb} |
| 1755 | @code{libgdb} 1.0 was an abortive project of years ago. The theory was |
| 1756 | to provide an API to @value{GDBN}'s functionality. |
| 1757 | |
| 1758 | @section libgdb 2.0 |
| 1759 | @cindex @code{libgdb} |
| 1760 | @code{libgdb} 2.0 is an ongoing effort to update @value{GDBN} so that is |
| 1761 | better able to support graphical and other environments. |
| 1762 | |
| 1763 | Since @code{libgdb} development is on-going, its architecture is still |
| 1764 | evolving. The following components have so far been identified: |
| 1765 | |
| 1766 | @itemize @bullet |
| 1767 | @item |
| 1768 | Observer - @file{gdb-events.h}. |
| 1769 | @item |
| 1770 | Builder - @file{ui-out.h} |
| 1771 | @item |
| 1772 | Event Loop - @file{event-loop.h} |
| 1773 | @item |
| 1774 | Library - @file{gdb.h} |
| 1775 | @end itemize |
| 1776 | |
| 1777 | The model that ties these components together is described below. |
| 1778 | |
| 1779 | @section The @code{libgdb} Model |
| 1780 | |
| 1781 | A client of @code{libgdb} interacts with the library in two ways. |
| 1782 | |
| 1783 | @itemize @bullet |
| 1784 | @item |
| 1785 | As an observer (using @file{gdb-events}) receiving notifications from |
| 1786 | @code{libgdb} of any internal state changes (break point changes, run |
| 1787 | state, etc). |
| 1788 | @item |
| 1789 | As a client querying @code{libgdb} (using the @file{ui-out} builder) to |
| 1790 | obtain various status values from @value{GDBN}. |
| 1791 | @end itemize |
| 1792 | |
| 1793 | Since @code{libgdb} could have multiple clients (e.g., a GUI supporting |
| 1794 | the existing @value{GDBN} CLI), those clients must co-operate when |
| 1795 | controlling @code{libgdb}. In particular, a client must ensure that |
| 1796 | @code{libgdb} is idle (i.e.@: no other client is using @code{libgdb}) |
| 1797 | before responding to a @file{gdb-event} by making a query. |
| 1798 | |
| 1799 | @section CLI support |
| 1800 | |
| 1801 | At present @value{GDBN}'s CLI is very much entangled in with the core of |
| 1802 | @code{libgdb}. Consequently, a client wishing to include the CLI in |
| 1803 | their interface needs to carefully co-ordinate its own and the CLI's |
| 1804 | requirements. |
| 1805 | |
| 1806 | It is suggested that the client set @code{libgdb} up to be bi-modal |
| 1807 | (alternate between CLI and client query modes). The notes below sketch |
| 1808 | out the theory: |
| 1809 | |
| 1810 | @itemize @bullet |
| 1811 | @item |
| 1812 | The client registers itself as an observer of @code{libgdb}. |
| 1813 | @item |
| 1814 | The client create and install @code{cli-out} builder using its own |
| 1815 | versions of the @code{ui-file} @code{gdb_stderr}, @code{gdb_stdtarg} and |
| 1816 | @code{gdb_stdout} streams. |
| 1817 | @item |
| 1818 | The client creates a separate custom @code{ui-out} builder that is only |
| 1819 | used while making direct queries to @code{libgdb}. |
| 1820 | @end itemize |
| 1821 | |
| 1822 | When the client receives input intended for the CLI, it simply passes it |
| 1823 | along. Since the @code{cli-out} builder is installed by default, all |
| 1824 | the CLI output in response to that command is routed (pronounced rooted) |
| 1825 | through to the client controlled @code{gdb_stdout} et.@: al.@: streams. |
| 1826 | At the same time, the client is kept abreast of internal changes by |
| 1827 | virtue of being a @code{libgdb} observer. |
| 1828 | |
| 1829 | The only restriction on the client is that it must wait until |
| 1830 | @code{libgdb} becomes idle before initiating any queries (using the |
| 1831 | client's custom builder). |
| 1832 | |
| 1833 | @section @code{libgdb} components |
| 1834 | |
| 1835 | @subheading Observer - @file{gdb-events.h} |
| 1836 | @file{gdb-events} provides the client with a very raw mechanism that can |
| 1837 | be used to implement an observer. At present it only allows for one |
| 1838 | observer and that observer must, internally, handle the need to delay |
| 1839 | the processing of any event notifications until after @code{libgdb} has |
| 1840 | finished the current command. |
| 1841 | |
| 1842 | @subheading Builder - @file{ui-out.h} |
| 1843 | @file{ui-out} provides the infrastructure necessary for a client to |
| 1844 | create a builder. That builder is then passed down to @code{libgdb} |
| 1845 | when doing any queries. |
| 1846 | |
| 1847 | @subheading Event Loop - @file{event-loop.h} |
| 1848 | @c There could be an entire section on the event-loop |
| 1849 | @file{event-loop}, currently non-re-entrant, provides a simple event |
| 1850 | loop. A client would need to either plug its self into this loop or, |
| 1851 | implement a new event-loop that @value{GDBN} would use. |
| 1852 | |
| 1853 | The event-loop will eventually be made re-entrant. This is so that |
| 1854 | @value{GDBN} can better handle the problem of some commands blocking |
| 1855 | instead of returning. |
| 1856 | |
| 1857 | @subheading Library - @file{gdb.h} |
| 1858 | @file{libgdb} is the most obvious component of this system. It provides |
| 1859 | the query interface. Each function is parameterized by a @code{ui-out} |
| 1860 | builder. The result of the query is constructed using that builder |
| 1861 | before the query function returns. |
| 1862 | |
| 1863 | @node Values |
| 1864 | @chapter Values |
| 1865 | @section Values |
| 1866 | |
| 1867 | @cindex values |
| 1868 | @cindex @code{value} structure |
| 1869 | @value{GDBN} uses @code{struct value}, or @dfn{values}, as an internal |
| 1870 | abstraction for the representation of a variety of inferior objects |
| 1871 | and @value{GDBN} convenience objects. |
| 1872 | |
| 1873 | Values have an associated @code{struct type}, that describes a virtual |
| 1874 | view of the raw data or object stored in or accessed through the |
| 1875 | value. |
| 1876 | |
| 1877 | A value is in addition discriminated by its lvalue-ness, given its |
| 1878 | @code{enum lval_type} enumeration type: |
| 1879 | |
| 1880 | @cindex @code{lval_type} enumeration, for values. |
| 1881 | @table @code |
| 1882 | @item @code{not_lval} |
| 1883 | This value is not an lval. It can't be assigned to. |
| 1884 | |
| 1885 | @item @code{lval_memory} |
| 1886 | This value represents an object in memory. |
| 1887 | |
| 1888 | @item @code{lval_register} |
| 1889 | This value represents an object that lives in a register. |
| 1890 | |
| 1891 | @item @code{lval_internalvar} |
| 1892 | Represents the value of an internal variable. |
| 1893 | |
| 1894 | @item @code{lval_internalvar_component} |
| 1895 | Represents part of a @value{GDBN} internal variable. E.g., a |
| 1896 | structure field. |
| 1897 | |
| 1898 | @cindex computed values |
| 1899 | @item @code{lval_computed} |
| 1900 | These are ``computed'' values. They allow creating specialized value |
| 1901 | objects for specific purposes, all abstracted away from the core value |
| 1902 | support code. The creator of such a value writes specialized |
| 1903 | functions to handle the reading and writing to/from the value's |
| 1904 | backend data, and optionally, a ``copy operator'' and a |
| 1905 | ``destructor''. |
| 1906 | |
| 1907 | Pointers to these functions are stored in a @code{struct lval_funcs} |
| 1908 | instance (declared in @file{value.h}), and passed to the |
| 1909 | @code{allocate_computed_value} function, as in the example below. |
| 1910 | |
| 1911 | @smallexample |
| 1912 | static void |
| 1913 | nil_value_read (struct value *v) |
| 1914 | @{ |
| 1915 | /* This callback reads data from some backend, and stores it in V. |
| 1916 | In this case, we always read null data. You'll want to fill in |
| 1917 | something more interesting. */ |
| 1918 | |
| 1919 | memset (value_contents_all_raw (v), |
| 1920 | value_offset (v), |
| 1921 | TYPE_LENGTH (value_type (v))); |
| 1922 | @} |
| 1923 | |
| 1924 | static void |
| 1925 | nil_value_write (struct value *v, struct value *fromval) |
| 1926 | @{ |
| 1927 | /* Takes the data from FROMVAL and stores it in the backend of V. */ |
| 1928 | |
| 1929 | to_oblivion (value_contents_all_raw (fromval), |
| 1930 | value_offset (v), |
| 1931 | TYPE_LENGTH (value_type (fromval))); |
| 1932 | @} |
| 1933 | |
| 1934 | static struct lval_funcs nil_value_funcs = |
| 1935 | @{ |
| 1936 | nil_value_read, |
| 1937 | nil_value_write |
| 1938 | @}; |
| 1939 | |
| 1940 | struct value * |
| 1941 | make_nil_value (void) |
| 1942 | @{ |
| 1943 | struct type *type; |
| 1944 | struct value *v; |
| 1945 | |
| 1946 | type = make_nils_type (); |
| 1947 | v = allocate_computed_value (type, &nil_value_funcs, NULL); |
| 1948 | |
| 1949 | return v; |
| 1950 | @} |
| 1951 | @end smallexample |
| 1952 | |
| 1953 | See the implementation of the @code{$_siginfo} convenience variable in |
| 1954 | @file{infrun.c} as a real example use of lval_computed. |
| 1955 | |
| 1956 | @end table |
| 1957 | |
| 1958 | @node Stack Frames |
| 1959 | @chapter Stack Frames |
| 1960 | |
| 1961 | @cindex frame |
| 1962 | @cindex call stack frame |
| 1963 | A frame is a construct that @value{GDBN} uses to keep track of calling |
| 1964 | and called functions. |
| 1965 | |
| 1966 | @cindex unwind frame |
| 1967 | @value{GDBN}'s frame model, a fresh design, was implemented with the |
| 1968 | need to support @sc{dwarf}'s Call Frame Information in mind. In fact, |
| 1969 | the term ``unwind'' is taken directly from that specification. |
| 1970 | Developers wishing to learn more about unwinders, are encouraged to |
| 1971 | read the @sc{dwarf} specification, available from |
| 1972 | @url{http://www.dwarfstd.org}. |
| 1973 | |
| 1974 | @findex frame_register_unwind |
| 1975 | @findex get_frame_register |
| 1976 | @value{GDBN}'s model is that you find a frame's registers by |
| 1977 | ``unwinding'' them from the next younger frame. That is, |
| 1978 | @samp{get_frame_register} which returns the value of a register in |
| 1979 | frame #1 (the next-to-youngest frame), is implemented by calling frame |
| 1980 | #0's @code{frame_register_unwind} (the youngest frame). But then the |
| 1981 | obvious question is: how do you access the registers of the youngest |
| 1982 | frame itself? |
| 1983 | |
| 1984 | @cindex sentinel frame |
| 1985 | @findex get_frame_type |
| 1986 | @vindex SENTINEL_FRAME |
| 1987 | To answer this question, @value{GDBN} has the @dfn{sentinel} frame, the |
| 1988 | ``-1st'' frame. Unwinding registers from the sentinel frame gives you |
| 1989 | the current values of the youngest real frame's registers. If @var{f} |
| 1990 | is a sentinel frame, then @code{get_frame_type (@var{f}) @equiv{} |
| 1991 | SENTINEL_FRAME}. |
| 1992 | |
| 1993 | @section Selecting an Unwinder |
| 1994 | |
| 1995 | @findex frame_unwind_prepend_unwinder |
| 1996 | @findex frame_unwind_append_unwinder |
| 1997 | The architecture registers a list of frame unwinders (@code{struct |
| 1998 | frame_unwind}), using the functions |
| 1999 | @code{frame_unwind_prepend_unwinder} and |
| 2000 | @code{frame_unwind_append_unwinder}. Each unwinder includes a |
| 2001 | sniffer. Whenever @value{GDBN} needs to unwind a frame (to fetch the |
| 2002 | previous frame's registers or the current frame's ID), it calls |
| 2003 | registered sniffers in order to find one which recognizes the frame. |
| 2004 | The first time a sniffer returns non-zero, the corresponding unwinder |
| 2005 | is assigned to the frame. |
| 2006 | |
| 2007 | @section Unwinding the Frame ID |
| 2008 | @cindex frame ID |
| 2009 | |
| 2010 | Every frame has an associated ID, of type @code{struct frame_id}. |
| 2011 | The ID includes the stack base and function start address for |
| 2012 | the frame. The ID persists through the entire life of the frame, |
| 2013 | including while other called frames are running; it is used to |
| 2014 | locate an appropriate @code{struct frame_info} from the cache. |
| 2015 | |
| 2016 | Every time the inferior stops, and at various other times, the frame |
| 2017 | cache is flushed. Because of this, parts of @value{GDBN} which need |
| 2018 | to keep track of individual frames cannot use pointers to @code{struct |
| 2019 | frame_info}. A frame ID provides a stable reference to a frame, even |
| 2020 | when the unwinder must be run again to generate a new @code{struct |
| 2021 | frame_info} for the same frame. |
| 2022 | |
| 2023 | The frame's unwinder's @code{this_id} method is called to find the ID. |
| 2024 | Note that this is different from register unwinding, where the next |
| 2025 | frame's @code{prev_register} is called to unwind this frame's |
| 2026 | registers. |
| 2027 | |
| 2028 | Both stack base and function address are required to identify the |
| 2029 | frame, because a recursive function has the same function address for |
| 2030 | two consecutive frames and a leaf function may have the same stack |
| 2031 | address as its caller. On some platforms, a third address is part of |
| 2032 | the ID to further disambiguate frames---for instance, on IA-64 |
| 2033 | the separate register stack address is included in the ID. |
| 2034 | |
| 2035 | An invalid frame ID (@code{outer_frame_id}) returned from the |
| 2036 | @code{this_id} method means to stop unwinding after this frame. |
| 2037 | |
| 2038 | @code{null_frame_id} is another invalid frame ID which should be used |
| 2039 | when there is no frame. For instance, certain breakpoints are attached |
| 2040 | to a specific frame, and that frame is identified through its frame ID |
| 2041 | (we use this to implement the "finish" command). Using |
| 2042 | @code{null_frame_id} as the frame ID for a given breakpoint means |
| 2043 | that the breakpoint is not specific to any frame. The @code{this_id} |
| 2044 | method should never return @code{null_frame_id}. |
| 2045 | |
| 2046 | @section Unwinding Registers |
| 2047 | |
| 2048 | Each unwinder includes a @code{prev_register} method. This method |
| 2049 | takes a frame, an associated cache pointer, and a register number. |
| 2050 | It returns a @code{struct value *} describing the requested register, |
| 2051 | as saved by this frame. This is the value of the register that is |
| 2052 | current in this frame's caller. |
| 2053 | |
| 2054 | The returned value must have the same type as the register. It may |
| 2055 | have any lvalue type. In most circumstances one of these routines |
| 2056 | will generate the appropriate value: |
| 2057 | |
| 2058 | @table @code |
| 2059 | @item frame_unwind_got_optimized |
| 2060 | @findex frame_unwind_got_optimized |
| 2061 | This register was not saved. |
| 2062 | |
| 2063 | @item frame_unwind_got_register |
| 2064 | @findex frame_unwind_got_register |
| 2065 | This register was copied into another register in this frame. This |
| 2066 | is also used for unchanged registers; they are ``copied'' into the |
| 2067 | same register. |
| 2068 | |
| 2069 | @item frame_unwind_got_memory |
| 2070 | @findex frame_unwind_got_memory |
| 2071 | This register was saved in memory. |
| 2072 | |
| 2073 | @item frame_unwind_got_constant |
| 2074 | @findex frame_unwind_got_constant |
| 2075 | This register was not saved, but the unwinder can compute the previous |
| 2076 | value some other way. |
| 2077 | |
| 2078 | @item frame_unwind_got_address |
| 2079 | @findex frame_unwind_got_address |
| 2080 | Same as @code{frame_unwind_got_constant}, except that the value is a target |
| 2081 | address. This is frequently used for the stack pointer, which is not |
| 2082 | explicitly saved but has a known offset from this frame's stack |
| 2083 | pointer. For architectures with a flat unified address space, this is |
| 2084 | generally the same as @code{frame_unwind_got_constant}. |
| 2085 | @end table |
| 2086 | |
| 2087 | @node Symbol Handling |
| 2088 | |
| 2089 | @chapter Symbol Handling |
| 2090 | |
| 2091 | Symbols are a key part of @value{GDBN}'s operation. Symbols include |
| 2092 | variables, functions, and types. |
| 2093 | |
| 2094 | Symbol information for a large program can be truly massive, and |
| 2095 | reading of symbol information is one of the major performance |
| 2096 | bottlenecks in @value{GDBN}; it can take many minutes to process it |
| 2097 | all. Studies have shown that nearly all the time spent is |
| 2098 | computational, rather than file reading. |
| 2099 | |
| 2100 | One of the ways for @value{GDBN} to provide a good user experience is |
| 2101 | to start up quickly, taking no more than a few seconds. It is simply |
| 2102 | not possible to process all of a program's debugging info in that |
| 2103 | time, and so we attempt to handle symbols incrementally. For instance, |
| 2104 | we create @dfn{partial symbol tables} consisting of only selected |
| 2105 | symbols, and only expand them to full symbol tables when necessary. |
| 2106 | |
| 2107 | @section Symbol Reading |
| 2108 | |
| 2109 | @cindex symbol reading |
| 2110 | @cindex reading of symbols |
| 2111 | @cindex symbol files |
| 2112 | @value{GDBN} reads symbols from @dfn{symbol files}. The usual symbol |
| 2113 | file is the file containing the program which @value{GDBN} is |
| 2114 | debugging. @value{GDBN} can be directed to use a different file for |
| 2115 | symbols (with the @samp{symbol-file} command), and it can also read |
| 2116 | more symbols via the @samp{add-file} and @samp{load} commands. In |
| 2117 | addition, it may bring in more symbols while loading shared |
| 2118 | libraries. |
| 2119 | |
| 2120 | @findex find_sym_fns |
| 2121 | Symbol files are initially opened by code in @file{symfile.c} using |
| 2122 | the BFD library (@pxref{Support Libraries}). BFD identifies the type |
| 2123 | of the file by examining its header. @code{find_sym_fns} then uses |
| 2124 | this identification to locate a set of symbol-reading functions. |
| 2125 | |
| 2126 | @findex add_symtab_fns |
| 2127 | @cindex @code{sym_fns} structure |
| 2128 | @cindex adding a symbol-reading module |
| 2129 | Symbol-reading modules identify themselves to @value{GDBN} by calling |
| 2130 | @code{add_symtab_fns} during their module initialization. The argument |
| 2131 | to @code{add_symtab_fns} is a @code{struct sym_fns} which contains the |
| 2132 | name (or name prefix) of the symbol format, the length of the prefix, |
| 2133 | and pointers to four functions. These functions are called at various |
| 2134 | times to process symbol files whose identification matches the specified |
| 2135 | prefix. |
| 2136 | |
| 2137 | The functions supplied by each module are: |
| 2138 | |
| 2139 | @table @code |
| 2140 | @item @var{xyz}_symfile_init(struct sym_fns *sf) |
| 2141 | |
| 2142 | @cindex secondary symbol file |
| 2143 | Called from @code{symbol_file_add} when we are about to read a new |
| 2144 | symbol file. This function should clean up any internal state (possibly |
| 2145 | resulting from half-read previous files, for example) and prepare to |
| 2146 | read a new symbol file. Note that the symbol file which we are reading |
| 2147 | might be a new ``main'' symbol file, or might be a secondary symbol file |
| 2148 | whose symbols are being added to the existing symbol table. |
| 2149 | |
| 2150 | The argument to @code{@var{xyz}_symfile_init} is a newly allocated |
| 2151 | @code{struct sym_fns} whose @code{bfd} field contains the BFD for the |
| 2152 | new symbol file being read. Its @code{private} field has been zeroed, |
| 2153 | and can be modified as desired. Typically, a struct of private |
| 2154 | information will be @code{malloc}'d, and a pointer to it will be placed |
| 2155 | in the @code{private} field. |
| 2156 | |
| 2157 | There is no result from @code{@var{xyz}_symfile_init}, but it can call |
| 2158 | @code{error} if it detects an unavoidable problem. |
| 2159 | |
| 2160 | @item @var{xyz}_new_init() |
| 2161 | |
| 2162 | Called from @code{symbol_file_add} when discarding existing symbols. |
| 2163 | This function needs only handle the symbol-reading module's internal |
| 2164 | state; the symbol table data structures visible to the rest of |
| 2165 | @value{GDBN} will be discarded by @code{symbol_file_add}. It has no |
| 2166 | arguments and no result. It may be called after |
| 2167 | @code{@var{xyz}_symfile_init}, if a new symbol table is being read, or |
| 2168 | may be called alone if all symbols are simply being discarded. |
| 2169 | |
| 2170 | @item @var{xyz}_symfile_read(struct sym_fns *sf, CORE_ADDR addr, int mainline) |
| 2171 | |
| 2172 | Called from @code{symbol_file_add} to actually read the symbols from a |
| 2173 | symbol-file into a set of psymtabs or symtabs. |
| 2174 | |
| 2175 | @code{sf} points to the @code{struct sym_fns} originally passed to |
| 2176 | @code{@var{xyz}_sym_init} for possible initialization. @code{addr} is |
| 2177 | the offset between the file's specified start address and its true |
| 2178 | address in memory. @code{mainline} is 1 if this is the main symbol |
| 2179 | table being read, and 0 if a secondary symbol file (e.g., shared library |
| 2180 | or dynamically loaded file) is being read.@refill |
| 2181 | @end table |
| 2182 | |
| 2183 | In addition, if a symbol-reading module creates psymtabs when |
| 2184 | @var{xyz}_symfile_read is called, these psymtabs will contain a pointer |
| 2185 | to a function @code{@var{xyz}_psymtab_to_symtab}, which can be called |
| 2186 | from any point in the @value{GDBN} symbol-handling code. |
| 2187 | |
| 2188 | @table @code |
| 2189 | @item @var{xyz}_psymtab_to_symtab (struct partial_symtab *pst) |
| 2190 | |
| 2191 | Called from @code{psymtab_to_symtab} (or the @code{PSYMTAB_TO_SYMTAB} macro) if |
| 2192 | the psymtab has not already been read in and had its @code{pst->symtab} |
| 2193 | pointer set. The argument is the psymtab to be fleshed-out into a |
| 2194 | symtab. Upon return, @code{pst->readin} should have been set to 1, and |
| 2195 | @code{pst->symtab} should contain a pointer to the new corresponding symtab, or |
| 2196 | zero if there were no symbols in that part of the symbol file. |
| 2197 | @end table |
| 2198 | |
| 2199 | @section Partial Symbol Tables |
| 2200 | |
| 2201 | @value{GDBN} has three types of symbol tables: |
| 2202 | |
| 2203 | @itemize @bullet |
| 2204 | @cindex full symbol table |
| 2205 | @cindex symtabs |
| 2206 | @item |
| 2207 | Full symbol tables (@dfn{symtabs}). These contain the main |
| 2208 | information about symbols and addresses. |
| 2209 | |
| 2210 | @cindex psymtabs |
| 2211 | @item |
| 2212 | Partial symbol tables (@dfn{psymtabs}). These contain enough |
| 2213 | information to know when to read the corresponding part of the full |
| 2214 | symbol table. |
| 2215 | |
| 2216 | @cindex minimal symbol table |
| 2217 | @cindex minsymtabs |
| 2218 | @item |
| 2219 | Minimal symbol tables (@dfn{msymtabs}). These contain information |
| 2220 | gleaned from non-debugging symbols. |
| 2221 | @end itemize |
| 2222 | |
| 2223 | @cindex partial symbol table |
| 2224 | This section describes partial symbol tables. |
| 2225 | |
| 2226 | A psymtab is constructed by doing a very quick pass over an executable |
| 2227 | file's debugging information. Small amounts of information are |
| 2228 | extracted---enough to identify which parts of the symbol table will |
| 2229 | need to be re-read and fully digested later, when the user needs the |
| 2230 | information. The speed of this pass causes @value{GDBN} to start up very |
| 2231 | quickly. Later, as the detailed rereading occurs, it occurs in small |
| 2232 | pieces, at various times, and the delay therefrom is mostly invisible to |
| 2233 | the user. |
| 2234 | @c (@xref{Symbol Reading}.) |
| 2235 | |
| 2236 | The symbols that show up in a file's psymtab should be, roughly, those |
| 2237 | visible to the debugger's user when the program is not running code from |
| 2238 | that file. These include external symbols and types, static symbols and |
| 2239 | types, and @code{enum} values declared at file scope. |
| 2240 | |
| 2241 | The psymtab also contains the range of instruction addresses that the |
| 2242 | full symbol table would represent. |
| 2243 | |
| 2244 | @cindex finding a symbol |
| 2245 | @cindex symbol lookup |
| 2246 | The idea is that there are only two ways for the user (or much of the |
| 2247 | code in the debugger) to reference a symbol: |
| 2248 | |
| 2249 | @itemize @bullet |
| 2250 | @findex find_pc_function |
| 2251 | @findex find_pc_line |
| 2252 | @item |
| 2253 | By its address (e.g., execution stops at some address which is inside a |
| 2254 | function in this file). The address will be noticed to be in the |
| 2255 | range of this psymtab, and the full symtab will be read in. |
| 2256 | @code{find_pc_function}, @code{find_pc_line}, and other |
| 2257 | @code{find_pc_@dots{}} functions handle this. |
| 2258 | |
| 2259 | @cindex lookup_symbol |
| 2260 | @item |
| 2261 | By its name |
| 2262 | (e.g., the user asks to print a variable, or set a breakpoint on a |
| 2263 | function). Global names and file-scope names will be found in the |
| 2264 | psymtab, which will cause the symtab to be pulled in. Local names will |
| 2265 | have to be qualified by a global name, or a file-scope name, in which |
| 2266 | case we will have already read in the symtab as we evaluated the |
| 2267 | qualifier. Or, a local symbol can be referenced when we are ``in'' a |
| 2268 | local scope, in which case the first case applies. @code{lookup_symbol} |
| 2269 | does most of the work here. |
| 2270 | @end itemize |
| 2271 | |
| 2272 | The only reason that psymtabs exist is to cause a symtab to be read in |
| 2273 | at the right moment. Any symbol that can be elided from a psymtab, |
| 2274 | while still causing that to happen, should not appear in it. Since |
| 2275 | psymtabs don't have the idea of scope, you can't put local symbols in |
| 2276 | them anyway. Psymtabs don't have the idea of the type of a symbol, |
| 2277 | either, so types need not appear, unless they will be referenced by |
| 2278 | name. |
| 2279 | |
| 2280 | It is a bug for @value{GDBN} to behave one way when only a psymtab has |
| 2281 | been read, and another way if the corresponding symtab has been read |
| 2282 | in. Such bugs are typically caused by a psymtab that does not contain |
| 2283 | all the visible symbols, or which has the wrong instruction address |
| 2284 | ranges. |
| 2285 | |
| 2286 | The psymtab for a particular section of a symbol file (objfile) could be |
| 2287 | thrown away after the symtab has been read in. The symtab should always |
| 2288 | be searched before the psymtab, so the psymtab will never be used (in a |
| 2289 | bug-free environment). Currently, psymtabs are allocated on an obstack, |
| 2290 | and all the psymbols themselves are allocated in a pair of large arrays |
| 2291 | on an obstack, so there is little to be gained by trying to free them |
| 2292 | unless you want to do a lot more work. |
| 2293 | |
| 2294 | Whether or not psymtabs are created depends on the objfile's symbol |
| 2295 | reader. The core of @value{GDBN} hides the details of partial symbols |
| 2296 | and partial symbol tables behind a set of function pointers known as |
| 2297 | the @dfn{quick symbol functions}. These are documented in |
| 2298 | @file{symfile.h}. |
| 2299 | |
| 2300 | @section Types |
| 2301 | |
| 2302 | @unnumberedsubsec Fundamental Types (e.g., @code{FT_VOID}, @code{FT_BOOLEAN}). |
| 2303 | |
| 2304 | @cindex fundamental types |
| 2305 | These are the fundamental types that @value{GDBN} uses internally. Fundamental |
| 2306 | types from the various debugging formats (stabs, ELF, etc) are mapped |
| 2307 | into one of these. They are basically a union of all fundamental types |
| 2308 | that @value{GDBN} knows about for all the languages that @value{GDBN} |
| 2309 | knows about. |
| 2310 | |
| 2311 | @unnumberedsubsec Type Codes (e.g., @code{TYPE_CODE_PTR}, @code{TYPE_CODE_ARRAY}). |
| 2312 | |
| 2313 | @cindex type codes |
| 2314 | Each time @value{GDBN} builds an internal type, it marks it with one |
| 2315 | of these types. The type may be a fundamental type, such as |
| 2316 | @code{TYPE_CODE_INT}, or a derived type, such as @code{TYPE_CODE_PTR} |
| 2317 | which is a pointer to another type. Typically, several @code{FT_*} |
| 2318 | types map to one @code{TYPE_CODE_*} type, and are distinguished by |
| 2319 | other members of the type struct, such as whether the type is signed |
| 2320 | or unsigned, and how many bits it uses. |
| 2321 | |
| 2322 | @unnumberedsubsec Builtin Types (e.g., @code{builtin_type_void}, @code{builtin_type_char}). |
| 2323 | |
| 2324 | These are instances of type structs that roughly correspond to |
| 2325 | fundamental types and are created as global types for @value{GDBN} to |
| 2326 | use for various ugly historical reasons. We eventually want to |
| 2327 | eliminate these. Note for example that @code{builtin_type_int} |
| 2328 | initialized in @file{gdbtypes.c} is basically the same as a |
| 2329 | @code{TYPE_CODE_INT} type that is initialized in @file{c-lang.c} for |
| 2330 | an @code{FT_INTEGER} fundamental type. The difference is that the |
| 2331 | @code{builtin_type} is not associated with any particular objfile, and |
| 2332 | only one instance exists, while @file{c-lang.c} builds as many |
| 2333 | @code{TYPE_CODE_INT} types as needed, with each one associated with |
| 2334 | some particular objfile. |
| 2335 | |
| 2336 | @section Object File Formats |
| 2337 | @cindex object file formats |
| 2338 | |
| 2339 | @subsection a.out |
| 2340 | |
| 2341 | @cindex @code{a.out} format |
| 2342 | The @code{a.out} format is the original file format for Unix. It |
| 2343 | consists of three sections: @code{text}, @code{data}, and @code{bss}, |
| 2344 | which are for program code, initialized data, and uninitialized data, |
| 2345 | respectively. |
| 2346 | |
| 2347 | The @code{a.out} format is so simple that it doesn't have any reserved |
| 2348 | place for debugging information. (Hey, the original Unix hackers used |
| 2349 | @samp{adb}, which is a machine-language debugger!) The only debugging |
| 2350 | format for @code{a.out} is stabs, which is encoded as a set of normal |
| 2351 | symbols with distinctive attributes. |
| 2352 | |
| 2353 | The basic @code{a.out} reader is in @file{dbxread.c}. |
| 2354 | |
| 2355 | @subsection COFF |
| 2356 | |
| 2357 | @cindex COFF format |
| 2358 | The COFF format was introduced with System V Release 3 (SVR3) Unix. |
| 2359 | COFF files may have multiple sections, each prefixed by a header. The |
| 2360 | number of sections is limited. |
| 2361 | |
| 2362 | The COFF specification includes support for debugging. Although this |
| 2363 | was a step forward, the debugging information was woefully limited. |
| 2364 | For instance, it was not possible to represent code that came from an |
| 2365 | included file. GNU's COFF-using configs often use stabs-type info, |
| 2366 | encapsulated in special sections. |
| 2367 | |
| 2368 | The COFF reader is in @file{coffread.c}. |
| 2369 | |
| 2370 | @subsection ECOFF |
| 2371 | |
| 2372 | @cindex ECOFF format |
| 2373 | ECOFF is an extended COFF originally introduced for Mips and Alpha |
| 2374 | workstations. |
| 2375 | |
| 2376 | The basic ECOFF reader is in @file{mipsread.c}. |
| 2377 | |
| 2378 | @subsection XCOFF |
| 2379 | |
| 2380 | @cindex XCOFF format |
| 2381 | The IBM RS/6000 running AIX uses an object file format called XCOFF. |
| 2382 | The COFF sections, symbols, and line numbers are used, but debugging |
| 2383 | symbols are @code{dbx}-style stabs whose strings are located in the |
| 2384 | @code{.debug} section (rather than the string table). For more |
| 2385 | information, see @ref{Top,,,stabs,The Stabs Debugging Format}. |
| 2386 | |
| 2387 | The shared library scheme has a clean interface for figuring out what |
| 2388 | shared libraries are in use, but the catch is that everything which |
| 2389 | refers to addresses (symbol tables and breakpoints at least) needs to be |
| 2390 | relocated for both shared libraries and the main executable. At least |
| 2391 | using the standard mechanism this can only be done once the program has |
| 2392 | been run (or the core file has been read). |
| 2393 | |
| 2394 | @subsection PE |
| 2395 | |
| 2396 | @cindex PE-COFF format |
| 2397 | Windows 95 and NT use the PE (@dfn{Portable Executable}) format for their |
| 2398 | executables. PE is basically COFF with additional headers. |
| 2399 | |
| 2400 | While BFD includes special PE support, @value{GDBN} needs only the basic |
| 2401 | COFF reader. |
| 2402 | |
| 2403 | @subsection ELF |
| 2404 | |
| 2405 | @cindex ELF format |
| 2406 | The ELF format came with System V Release 4 (SVR4) Unix. ELF is |
| 2407 | similar to COFF in being organized into a number of sections, but it |
| 2408 | removes many of COFF's limitations. Debugging info may be either stabs |
| 2409 | encapsulated in ELF sections, or more commonly these days, DWARF. |
| 2410 | |
| 2411 | The basic ELF reader is in @file{elfread.c}. |
| 2412 | |
| 2413 | @subsection SOM |
| 2414 | |
| 2415 | @cindex SOM format |
| 2416 | SOM is HP's object file and debug format (not to be confused with IBM's |
| 2417 | SOM, which is a cross-language ABI). |
| 2418 | |
| 2419 | The SOM reader is in @file{somread.c}. |
| 2420 | |
| 2421 | @section Debugging File Formats |
| 2422 | |
| 2423 | This section describes characteristics of debugging information that |
| 2424 | are independent of the object file format. |
| 2425 | |
| 2426 | @subsection stabs |
| 2427 | |
| 2428 | @cindex stabs debugging info |
| 2429 | @code{stabs} started out as special symbols within the @code{a.out} |
| 2430 | format. Since then, it has been encapsulated into other file |
| 2431 | formats, such as COFF and ELF. |
| 2432 | |
| 2433 | While @file{dbxread.c} does some of the basic stab processing, |
| 2434 | including for encapsulated versions, @file{stabsread.c} does |
| 2435 | the real work. |
| 2436 | |
| 2437 | @subsection COFF |
| 2438 | |
| 2439 | @cindex COFF debugging info |
| 2440 | The basic COFF definition includes debugging information. The level |
| 2441 | of support is minimal and non-extensible, and is not often used. |
| 2442 | |
| 2443 | @subsection Mips debug (Third Eye) |
| 2444 | |
| 2445 | @cindex ECOFF debugging info |
| 2446 | ECOFF includes a definition of a special debug format. |
| 2447 | |
| 2448 | The file @file{mdebugread.c} implements reading for this format. |
| 2449 | |
| 2450 | @c mention DWARF 1 as a formerly-supported format |
| 2451 | |
| 2452 | @subsection DWARF 2 |
| 2453 | |
| 2454 | @cindex DWARF 2 debugging info |
| 2455 | DWARF 2 is an improved but incompatible version of DWARF 1. |
| 2456 | |
| 2457 | The DWARF 2 reader is in @file{dwarf2read.c}. |
| 2458 | |
| 2459 | @subsection Compressed DWARF 2 |
| 2460 | |
| 2461 | @cindex Compressed DWARF 2 debugging info |
| 2462 | Compressed DWARF 2 is not technically a separate debugging format, but |
| 2463 | merely DWARF 2 debug information that has been compressed. In this |
| 2464 | format, every object-file section holding DWARF 2 debugging |
| 2465 | information is compressed and prepended with a header. (The section |
| 2466 | is also typically renamed, so a section called @code{.debug_info} in a |
| 2467 | DWARF 2 binary would be called @code{.zdebug_info} in a compressed |
| 2468 | DWARF 2 binary.) The header is 12 bytes long: |
| 2469 | |
| 2470 | @itemize @bullet |
| 2471 | @item |
| 2472 | 4 bytes: the literal string ``ZLIB'' |
| 2473 | @item |
| 2474 | 8 bytes: the uncompressed size of the section, in big-endian byte |
| 2475 | order. |
| 2476 | @end itemize |
| 2477 | |
| 2478 | The same reader is used for both compressed an normal DWARF 2 info. |
| 2479 | Section decompression is done in @code{zlib_decompress_section} in |
| 2480 | @file{dwarf2read.c}. |
| 2481 | |
| 2482 | @subsection DWARF 3 |
| 2483 | |
| 2484 | @cindex DWARF 3 debugging info |
| 2485 | DWARF 3 is an improved version of DWARF 2. |
| 2486 | |
| 2487 | @subsection SOM |
| 2488 | |
| 2489 | @cindex SOM debugging info |
| 2490 | Like COFF, the SOM definition includes debugging information. |
| 2491 | |
| 2492 | @section Adding a New Symbol Reader to @value{GDBN} |
| 2493 | |
| 2494 | @cindex adding debugging info reader |
| 2495 | If you are using an existing object file format (@code{a.out}, COFF, ELF, etc), |
| 2496 | there is probably little to be done. |
| 2497 | |
| 2498 | If you need to add a new object file format, you must first add it to |
| 2499 | BFD. This is beyond the scope of this document. |
| 2500 | |
| 2501 | You must then arrange for the BFD code to provide access to the |
| 2502 | debugging symbols. Generally @value{GDBN} will have to call swapping |
| 2503 | routines from BFD and a few other BFD internal routines to locate the |
| 2504 | debugging information. As much as possible, @value{GDBN} should not |
| 2505 | depend on the BFD internal data structures. |
| 2506 | |
| 2507 | For some targets (e.g., COFF), there is a special transfer vector used |
| 2508 | to call swapping routines, since the external data structures on various |
| 2509 | platforms have different sizes and layouts. Specialized routines that |
| 2510 | will only ever be implemented by one object file format may be called |
| 2511 | directly. This interface should be described in a file |
| 2512 | @file{bfd/lib@var{xyz}.h}, which is included by @value{GDBN}. |
| 2513 | |
| 2514 | @section Memory Management for Symbol Files |
| 2515 | |
| 2516 | Most memory associated with a loaded symbol file is stored on |
| 2517 | its @code{objfile_obstack}. This includes symbols, types, |
| 2518 | namespace data, and other information produced by the symbol readers. |
| 2519 | |
| 2520 | Because this data lives on the objfile's obstack, it is automatically |
| 2521 | released when the objfile is unloaded or reloaded. Therefore one |
| 2522 | objfile must not reference symbol or type data from another objfile; |
| 2523 | they could be unloaded at different times. |
| 2524 | |
| 2525 | User convenience variables, et cetera, have associated types. Normally |
| 2526 | these types live in the associated objfile. However, when the objfile |
| 2527 | is unloaded, those types are deep copied to global memory, so that |
| 2528 | the values of the user variables and history items are not lost. |
| 2529 | |
| 2530 | |
| 2531 | @node Language Support |
| 2532 | |
| 2533 | @chapter Language Support |
| 2534 | |
| 2535 | @cindex language support |
| 2536 | @value{GDBN}'s language support is mainly driven by the symbol reader, |
| 2537 | although it is possible for the user to set the source language |
| 2538 | manually. |
| 2539 | |
| 2540 | @value{GDBN} chooses the source language by looking at the extension |
| 2541 | of the file recorded in the debug info; @file{.c} means C, @file{.f} |
| 2542 | means Fortran, etc. It may also use a special-purpose language |
| 2543 | identifier if the debug format supports it, like with DWARF. |
| 2544 | |
| 2545 | @section Adding a Source Language to @value{GDBN} |
| 2546 | |
| 2547 | @cindex adding source language |
| 2548 | To add other languages to @value{GDBN}'s expression parser, follow the |
| 2549 | following steps: |
| 2550 | |
| 2551 | @table @emph |
| 2552 | @item Create the expression parser. |
| 2553 | |
| 2554 | @cindex expression parser |
| 2555 | This should reside in a file @file{@var{lang}-exp.y}. Routines for |
| 2556 | building parsed expressions into a @code{union exp_element} list are in |
| 2557 | @file{parse.c}. |
| 2558 | |
| 2559 | @cindex language parser |
| 2560 | Since we can't depend upon everyone having Bison, and YACC produces |
| 2561 | parsers that define a bunch of global names, the following lines |
| 2562 | @strong{must} be included at the top of the YACC parser, to prevent the |
| 2563 | various parsers from defining the same global names: |
| 2564 | |
| 2565 | @smallexample |
| 2566 | #define yyparse @var{lang}_parse |
| 2567 | #define yylex @var{lang}_lex |
| 2568 | #define yyerror @var{lang}_error |
| 2569 | #define yylval @var{lang}_lval |
| 2570 | #define yychar @var{lang}_char |
| 2571 | #define yydebug @var{lang}_debug |
| 2572 | #define yypact @var{lang}_pact |
| 2573 | #define yyr1 @var{lang}_r1 |
| 2574 | #define yyr2 @var{lang}_r2 |
| 2575 | #define yydef @var{lang}_def |
| 2576 | #define yychk @var{lang}_chk |
| 2577 | #define yypgo @var{lang}_pgo |
| 2578 | #define yyact @var{lang}_act |
| 2579 | #define yyexca @var{lang}_exca |
| 2580 | #define yyerrflag @var{lang}_errflag |
| 2581 | #define yynerrs @var{lang}_nerrs |
| 2582 | @end smallexample |
| 2583 | |
| 2584 | At the bottom of your parser, define a @code{struct language_defn} and |
| 2585 | initialize it with the right values for your language. Define an |
| 2586 | @code{initialize_@var{lang}} routine and have it call |
| 2587 | @samp{add_language(@var{lang}_language_defn)} to tell the rest of @value{GDBN} |
| 2588 | that your language exists. You'll need some other supporting variables |
| 2589 | and functions, which will be used via pointers from your |
| 2590 | @code{@var{lang}_language_defn}. See the declaration of @code{struct |
| 2591 | language_defn} in @file{language.h}, and the other @file{*-exp.y} files, |
| 2592 | for more information. |
| 2593 | |
| 2594 | @item Add any evaluation routines, if necessary |
| 2595 | |
| 2596 | @cindex expression evaluation routines |
| 2597 | @findex evaluate_subexp |
| 2598 | @findex prefixify_subexp |
| 2599 | @findex length_of_subexp |
| 2600 | If you need new opcodes (that represent the operations of the language), |
| 2601 | add them to the enumerated type in @file{expression.h}. Add support |
| 2602 | code for these operations in the @code{evaluate_subexp} function |
| 2603 | defined in the file @file{eval.c}. Add cases |
| 2604 | for new opcodes in two functions from @file{parse.c}: |
| 2605 | @code{prefixify_subexp} and @code{length_of_subexp}. These compute |
| 2606 | the number of @code{exp_element}s that a given operation takes up. |
| 2607 | |
| 2608 | @item Update some existing code |
| 2609 | |
| 2610 | Add an enumerated identifier for your language to the enumerated type |
| 2611 | @code{enum language} in @file{defs.h}. |
| 2612 | |
| 2613 | Update the routines in @file{language.c} so your language is included. |
| 2614 | These routines include type predicates and such, which (in some cases) |
| 2615 | are language dependent. If your language does not appear in the switch |
| 2616 | statement, an error is reported. |
| 2617 | |
| 2618 | @vindex current_language |
| 2619 | Also included in @file{language.c} is the code that updates the variable |
| 2620 | @code{current_language}, and the routines that translate the |
| 2621 | @code{language_@var{lang}} enumerated identifier into a printable |
| 2622 | string. |
| 2623 | |
| 2624 | @findex _initialize_language |
| 2625 | Update the function @code{_initialize_language} to include your |
| 2626 | language. This function picks the default language upon startup, so is |
| 2627 | dependent upon which languages that @value{GDBN} is built for. |
| 2628 | |
| 2629 | @findex allocate_symtab |
| 2630 | Update @code{allocate_symtab} in @file{symfile.c} and/or symbol-reading |
| 2631 | code so that the language of each symtab (source file) is set properly. |
| 2632 | This is used to determine the language to use at each stack frame level. |
| 2633 | Currently, the language is set based upon the extension of the source |
| 2634 | file. If the language can be better inferred from the symbol |
| 2635 | information, please set the language of the symtab in the symbol-reading |
| 2636 | code. |
| 2637 | |
| 2638 | @findex print_subexp |
| 2639 | @findex op_print_tab |
| 2640 | Add helper code to @code{print_subexp} (in @file{expprint.c}) to handle any new |
| 2641 | expression opcodes you have added to @file{expression.h}. Also, add the |
| 2642 | printed representations of your operators to @code{op_print_tab}. |
| 2643 | |
| 2644 | @item Add a place of call |
| 2645 | |
| 2646 | @findex parse_exp_1 |
| 2647 | Add a call to @code{@var{lang}_parse()} and @code{@var{lang}_error} in |
| 2648 | @code{parse_exp_1} (defined in @file{parse.c}). |
| 2649 | |
| 2650 | @item Edit @file{Makefile.in} |
| 2651 | |
| 2652 | Add dependencies in @file{Makefile.in}. Make sure you update the macro |
| 2653 | variables such as @code{HFILES} and @code{OBJS}, otherwise your code may |
| 2654 | not get linked in, or, worse yet, it may not get @code{tar}red into the |
| 2655 | distribution! |
| 2656 | @end table |
| 2657 | |
| 2658 | |
| 2659 | @node Host Definition |
| 2660 | |
| 2661 | @chapter Host Definition |
| 2662 | |
| 2663 | With the advent of Autoconf, it's rarely necessary to have host |
| 2664 | definition machinery anymore. The following information is provided, |
| 2665 | mainly, as an historical reference. |
| 2666 | |
| 2667 | @section Adding a New Host |
| 2668 | |
| 2669 | @cindex adding a new host |
| 2670 | @cindex host, adding |
| 2671 | @value{GDBN}'s host configuration support normally happens via Autoconf. |
| 2672 | New host-specific definitions should not be needed. Older hosts |
| 2673 | @value{GDBN} still use the host-specific definitions and files listed |
| 2674 | below, but these mostly exist for historical reasons, and will |
| 2675 | eventually disappear. |
| 2676 | |
| 2677 | @table @file |
| 2678 | @item gdb/config/@var{arch}/@var{xyz}.mh |
| 2679 | This file is a Makefile fragment that once contained both host and |
| 2680 | native configuration information (@pxref{Native Debugging}) for the |
| 2681 | machine @var{xyz}. The host configuration information is now handled |
| 2682 | by Autoconf. |
| 2683 | |
| 2684 | Host configuration information included definitions for @code{CC}, |
| 2685 | @code{SYSV_DEFINE}, @code{XM_CFLAGS}, @code{XM_ADD_FILES}, |
| 2686 | @code{XM_CLIBS}, @code{XM_CDEPS}, etc.; see @file{Makefile.in}. |
| 2687 | |
| 2688 | New host-only configurations do not need this file. |
| 2689 | |
| 2690 | @end table |
| 2691 | |
| 2692 | (Files named @file{gdb/config/@var{arch}/xm-@var{xyz}.h} were once |
| 2693 | used to define host-specific macros, but were no longer needed and |
| 2694 | have all been removed.) |
| 2695 | |
| 2696 | @subheading Generic Host Support Files |
| 2697 | |
| 2698 | @cindex generic host support |
| 2699 | There are some ``generic'' versions of routines that can be used by |
| 2700 | various systems. |
| 2701 | |
| 2702 | @table @file |
| 2703 | @cindex remote debugging support |
| 2704 | @cindex serial line support |
| 2705 | @item ser-unix.c |
| 2706 | This contains serial line support for Unix systems. It is included by |
| 2707 | default on all Unix-like hosts. |
| 2708 | |
| 2709 | @item ser-pipe.c |
| 2710 | This contains serial pipe support for Unix systems. It is included by |
| 2711 | default on all Unix-like hosts. |
| 2712 | |
| 2713 | @item ser-mingw.c |
| 2714 | This contains serial line support for 32-bit programs running under |
| 2715 | Windows using MinGW. |
| 2716 | |
| 2717 | @item ser-go32.c |
| 2718 | This contains serial line support for 32-bit programs running under DOS, |
| 2719 | using the DJGPP (a.k.a.@: GO32) execution environment. |
| 2720 | |
| 2721 | @cindex TCP remote support |
| 2722 | @item ser-tcp.c |
| 2723 | This contains generic TCP support using sockets. It is included by |
| 2724 | default on all Unix-like hosts and with MinGW. |
| 2725 | @end table |
| 2726 | |
| 2727 | @section Host Conditionals |
| 2728 | |
| 2729 | When @value{GDBN} is configured and compiled, various macros are |
| 2730 | defined or left undefined, to control compilation based on the |
| 2731 | attributes of the host system. While formerly they could be set in |
| 2732 | host-specific header files, at present they can be changed only by |
| 2733 | setting @code{CFLAGS} when building, or by editing the source code. |
| 2734 | |
| 2735 | These macros and their meanings (or if the meaning is not documented |
| 2736 | here, then one of the source files where they are used is indicated) |
| 2737 | are: |
| 2738 | |
| 2739 | @ftable @code |
| 2740 | @item @value{GDBN}INIT_FILENAME |
| 2741 | The default name of @value{GDBN}'s initialization file (normally |
| 2742 | @file{.gdbinit}). |
| 2743 | |
| 2744 | @item SIGWINCH_HANDLER |
| 2745 | If your host defines @code{SIGWINCH}, you can define this to be the name |
| 2746 | of a function to be called if @code{SIGWINCH} is received. |
| 2747 | |
| 2748 | @item SIGWINCH_HANDLER_BODY |
| 2749 | Define this to expand into code that will define the function named by |
| 2750 | the expansion of @code{SIGWINCH_HANDLER}. |
| 2751 | |
| 2752 | @item CRLF_SOURCE_FILES |
| 2753 | @cindex DOS text files |
| 2754 | Define this if host files use @code{\r\n} rather than @code{\n} as a |
| 2755 | line terminator. This will cause source file listings to omit @code{\r} |
| 2756 | characters when printing and it will allow @code{\r\n} line endings of files |
| 2757 | which are ``sourced'' by gdb. It must be possible to open files in binary |
| 2758 | mode using @code{O_BINARY} or, for fopen, @code{"rb"}. |
| 2759 | |
| 2760 | @item DEFAULT_PROMPT |
| 2761 | @cindex prompt |
| 2762 | The default value of the prompt string (normally @code{"(gdb) "}). |
| 2763 | |
| 2764 | @item DEV_TTY |
| 2765 | @cindex terminal device |
| 2766 | The name of the generic TTY device, defaults to @code{"/dev/tty"}. |
| 2767 | |
| 2768 | @item ISATTY |
| 2769 | Substitute for isatty, if not available. |
| 2770 | |
| 2771 | @item FOPEN_RB |
| 2772 | Define this if binary files are opened the same way as text files. |
| 2773 | |
| 2774 | @item CC_HAS_LONG_LONG |
| 2775 | @cindex @code{long long} data type |
| 2776 | Define this if the host C compiler supports @code{long long}. This is set |
| 2777 | by the @code{configure} script. |
| 2778 | |
| 2779 | @item PRINTF_HAS_LONG_LONG |
| 2780 | Define this if the host can handle printing of long long integers via |
| 2781 | the printf format conversion specifier @code{ll}. This is set by the |
| 2782 | @code{configure} script. |
| 2783 | |
| 2784 | @item LSEEK_NOT_LINEAR |
| 2785 | Define this if @code{lseek (n)} does not necessarily move to byte number |
| 2786 | @code{n} in the file. This is only used when reading source files. It |
| 2787 | is normally faster to define @code{CRLF_SOURCE_FILES} when possible. |
| 2788 | |
| 2789 | @item lint |
| 2790 | Define this to help placate @code{lint} in some situations. |
| 2791 | |
| 2792 | @item volatile |
| 2793 | Define this to override the defaults of @code{__volatile__} or |
| 2794 | @code{/**/}. |
| 2795 | @end ftable |
| 2796 | |
| 2797 | |
| 2798 | @node Target Architecture Definition |
| 2799 | |
| 2800 | @chapter Target Architecture Definition |
| 2801 | |
| 2802 | @cindex target architecture definition |
| 2803 | @value{GDBN}'s target architecture defines what sort of |
| 2804 | machine-language programs @value{GDBN} can work with, and how it works |
| 2805 | with them. |
| 2806 | |
| 2807 | The target architecture object is implemented as the C structure |
| 2808 | @code{struct gdbarch *}. The structure, and its methods, are generated |
| 2809 | using the Bourne shell script @file{gdbarch.sh}. |
| 2810 | |
| 2811 | @menu |
| 2812 | * OS ABI Variant Handling:: |
| 2813 | * Initialize New Architecture:: |
| 2814 | * Registers and Memory:: |
| 2815 | * Pointers and Addresses:: |
| 2816 | * Address Classes:: |
| 2817 | * Register Representation:: |
| 2818 | * Frame Interpretation:: |
| 2819 | * Inferior Call Setup:: |
| 2820 | * Adding support for debugging core files:: |
| 2821 | * Defining Other Architecture Features:: |
| 2822 | * Adding a New Target:: |
| 2823 | @end menu |
| 2824 | |
| 2825 | @node OS ABI Variant Handling |
| 2826 | @section Operating System ABI Variant Handling |
| 2827 | @cindex OS ABI variants |
| 2828 | |
| 2829 | @value{GDBN} provides a mechanism for handling variations in OS |
| 2830 | ABIs. An OS ABI variant may have influence over any number of |
| 2831 | variables in the target architecture definition. There are two major |
| 2832 | components in the OS ABI mechanism: sniffers and handlers. |
| 2833 | |
| 2834 | A @dfn{sniffer} examines a file matching a BFD architecture/flavour pair |
| 2835 | (the architecture may be wildcarded) in an attempt to determine the |
| 2836 | OS ABI of that file. Sniffers with a wildcarded architecture are considered |
| 2837 | to be @dfn{generic}, while sniffers for a specific architecture are |
| 2838 | considered to be @dfn{specific}. A match from a specific sniffer |
| 2839 | overrides a match from a generic sniffer. Multiple sniffers for an |
| 2840 | architecture/flavour may exist, in order to differentiate between two |
| 2841 | different operating systems which use the same basic file format. The |
| 2842 | OS ABI framework provides a generic sniffer for ELF-format files which |
| 2843 | examines the @code{EI_OSABI} field of the ELF header, as well as note |
| 2844 | sections known to be used by several operating systems. |
| 2845 | |
| 2846 | @cindex fine-tuning @code{gdbarch} structure |
| 2847 | A @dfn{handler} is used to fine-tune the @code{gdbarch} structure for the |
| 2848 | selected OS ABI. There may be only one handler for a given OS ABI |
| 2849 | for each BFD architecture. |
| 2850 | |
| 2851 | The following OS ABI variants are defined in @file{defs.h}: |
| 2852 | |
| 2853 | @table @code |
| 2854 | |
| 2855 | @findex GDB_OSABI_UNINITIALIZED |
| 2856 | @item GDB_OSABI_UNINITIALIZED |
| 2857 | Used for struct gdbarch_info if ABI is still uninitialized. |
| 2858 | |
| 2859 | @findex GDB_OSABI_UNKNOWN |
| 2860 | @item GDB_OSABI_UNKNOWN |
| 2861 | The ABI of the inferior is unknown. The default @code{gdbarch} |
| 2862 | settings for the architecture will be used. |
| 2863 | |
| 2864 | @findex GDB_OSABI_SVR4 |
| 2865 | @item GDB_OSABI_SVR4 |
| 2866 | UNIX System V Release 4. |
| 2867 | |
| 2868 | @findex GDB_OSABI_HURD |
| 2869 | @item GDB_OSABI_HURD |
| 2870 | GNU using the Hurd kernel. |
| 2871 | |
| 2872 | @findex GDB_OSABI_SOLARIS |
| 2873 | @item GDB_OSABI_SOLARIS |
| 2874 | Sun Solaris. |
| 2875 | |
| 2876 | @findex GDB_OSABI_OSF1 |
| 2877 | @item GDB_OSABI_OSF1 |
| 2878 | OSF/1, including Digital UNIX and Compaq Tru64 UNIX. |
| 2879 | |
| 2880 | @findex GDB_OSABI_LINUX |
| 2881 | @item GDB_OSABI_LINUX |
| 2882 | GNU using the Linux kernel. |
| 2883 | |
| 2884 | @findex GDB_OSABI_FREEBSD_AOUT |
| 2885 | @item GDB_OSABI_FREEBSD_AOUT |
| 2886 | FreeBSD using the @code{a.out} executable format. |
| 2887 | |
| 2888 | @findex GDB_OSABI_FREEBSD_ELF |
| 2889 | @item GDB_OSABI_FREEBSD_ELF |
| 2890 | FreeBSD using the ELF executable format. |
| 2891 | |
| 2892 | @findex GDB_OSABI_NETBSD_AOUT |
| 2893 | @item GDB_OSABI_NETBSD_AOUT |
| 2894 | NetBSD using the @code{a.out} executable format. |
| 2895 | |
| 2896 | @findex GDB_OSABI_NETBSD_ELF |
| 2897 | @item GDB_OSABI_NETBSD_ELF |
| 2898 | NetBSD using the ELF executable format. |
| 2899 | |
| 2900 | @findex GDB_OSABI_OPENBSD_ELF |
| 2901 | @item GDB_OSABI_OPENBSD_ELF |
| 2902 | OpenBSD using the ELF executable format. |
| 2903 | |
| 2904 | @findex GDB_OSABI_WINCE |
| 2905 | @item GDB_OSABI_WINCE |
| 2906 | Windows CE. |
| 2907 | |
| 2908 | @findex GDB_OSABI_GO32 |
| 2909 | @item GDB_OSABI_GO32 |
| 2910 | DJGPP. |
| 2911 | |
| 2912 | @findex GDB_OSABI_IRIX |
| 2913 | @item GDB_OSABI_IRIX |
| 2914 | Irix. |
| 2915 | |
| 2916 | @findex GDB_OSABI_INTERIX |
| 2917 | @item GDB_OSABI_INTERIX |
| 2918 | Interix (Posix layer for MS-Windows systems). |
| 2919 | |
| 2920 | @findex GDB_OSABI_HPUX_ELF |
| 2921 | @item GDB_OSABI_HPUX_ELF |
| 2922 | HP/UX using the ELF executable format. |
| 2923 | |
| 2924 | @findex GDB_OSABI_HPUX_SOM |
| 2925 | @item GDB_OSABI_HPUX_SOM |
| 2926 | HP/UX using the SOM executable format. |
| 2927 | |
| 2928 | @findex GDB_OSABI_QNXNTO |
| 2929 | @item GDB_OSABI_QNXNTO |
| 2930 | QNX Neutrino. |
| 2931 | |
| 2932 | @findex GDB_OSABI_CYGWIN |
| 2933 | @item GDB_OSABI_CYGWIN |
| 2934 | Cygwin. |
| 2935 | |
| 2936 | @findex GDB_OSABI_AIX |
| 2937 | @item GDB_OSABI_AIX |
| 2938 | AIX. |
| 2939 | |
| 2940 | @end table |
| 2941 | |
| 2942 | Here are the functions that make up the OS ABI framework: |
| 2943 | |
| 2944 | @deftypefun {const char *} gdbarch_osabi_name (enum gdb_osabi @var{osabi}) |
| 2945 | Return the name of the OS ABI corresponding to @var{osabi}. |
| 2946 | @end deftypefun |
| 2947 | |
| 2948 | @deftypefun void gdbarch_register_osabi (enum bfd_architecture @var{arch}, unsigned long @var{machine}, enum gdb_osabi @var{osabi}, void (*@var{init_osabi})(struct gdbarch_info @var{info}, struct gdbarch *@var{gdbarch})) |
| 2949 | Register the OS ABI handler specified by @var{init_osabi} for the |
| 2950 | architecture, machine type and OS ABI specified by @var{arch}, |
| 2951 | @var{machine} and @var{osabi}. In most cases, a value of zero for the |
| 2952 | machine type, which implies the architecture's default machine type, |
| 2953 | will suffice. |
| 2954 | @end deftypefun |
| 2955 | |
| 2956 | @deftypefun void gdbarch_register_osabi_sniffer (enum bfd_architecture @var{arch}, enum bfd_flavour @var{flavour}, enum gdb_osabi (*@var{sniffer})(bfd *@var{abfd})) |
| 2957 | Register the OS ABI file sniffer specified by @var{sniffer} for the |
| 2958 | BFD architecture/flavour pair specified by @var{arch} and @var{flavour}. |
| 2959 | If @var{arch} is @code{bfd_arch_unknown}, the sniffer is considered to |
| 2960 | be generic, and is allowed to examine @var{flavour}-flavoured files for |
| 2961 | any architecture. |
| 2962 | @end deftypefun |
| 2963 | |
| 2964 | @deftypefun {enum gdb_osabi} gdbarch_lookup_osabi (bfd *@var{abfd}) |
| 2965 | Examine the file described by @var{abfd} to determine its OS ABI. |
| 2966 | The value @code{GDB_OSABI_UNKNOWN} is returned if the OS ABI cannot |
| 2967 | be determined. |
| 2968 | @end deftypefun |
| 2969 | |
| 2970 | @deftypefun void gdbarch_init_osabi (struct gdbarch info @var{info}, struct gdbarch *@var{gdbarch}, enum gdb_osabi @var{osabi}) |
| 2971 | Invoke the OS ABI handler corresponding to @var{osabi} to fine-tune the |
| 2972 | @code{gdbarch} structure specified by @var{gdbarch}. If a handler |
| 2973 | corresponding to @var{osabi} has not been registered for @var{gdbarch}'s |
| 2974 | architecture, a warning will be issued and the debugging session will continue |
| 2975 | with the defaults already established for @var{gdbarch}. |
| 2976 | @end deftypefun |
| 2977 | |
| 2978 | @deftypefun void generic_elf_osabi_sniff_abi_tag_sections (bfd *@var{abfd}, asection *@var{sect}, void *@var{obj}) |
| 2979 | Helper routine for ELF file sniffers. Examine the file described by |
| 2980 | @var{abfd} and look at ABI tag note sections to determine the OS ABI |
| 2981 | from the note. This function should be called via |
| 2982 | @code{bfd_map_over_sections}. |
| 2983 | @end deftypefun |
| 2984 | |
| 2985 | @node Initialize New Architecture |
| 2986 | @section Initializing a New Architecture |
| 2987 | |
| 2988 | @menu |
| 2989 | * How an Architecture is Represented:: |
| 2990 | * Looking Up an Existing Architecture:: |
| 2991 | * Creating a New Architecture:: |
| 2992 | @end menu |
| 2993 | |
| 2994 | @node How an Architecture is Represented |
| 2995 | @subsection How an Architecture is Represented |
| 2996 | @cindex architecture representation |
| 2997 | @cindex representation of architecture |
| 2998 | |
| 2999 | Each @code{gdbarch} is associated with a single @sc{bfd} architecture, |
| 3000 | via a @code{bfd_arch_@var{arch}} in the @code{bfd_architecture} |
| 3001 | enumeration. The @code{gdbarch} is registered by a call to |
| 3002 | @code{register_gdbarch_init}, usually from the file's |
| 3003 | @code{_initialize_@var{filename}} routine, which will be automatically |
| 3004 | called during @value{GDBN} startup. The arguments are a @sc{bfd} |
| 3005 | architecture constant and an initialization function. |
| 3006 | |
| 3007 | @findex _initialize_@var{arch}_tdep |
| 3008 | @cindex @file{@var{arch}-tdep.c} |
| 3009 | A @value{GDBN} description for a new architecture, @var{arch} is created by |
| 3010 | defining a global function @code{_initialize_@var{arch}_tdep}, by |
| 3011 | convention in the source file @file{@var{arch}-tdep.c}. For example, |
| 3012 | in the case of the OpenRISC 1000, this function is called |
| 3013 | @code{_initialize_or1k_tdep} and is found in the file |
| 3014 | @file{or1k-tdep.c}. |
| 3015 | |
| 3016 | @cindex @file{configure.tgt} |
| 3017 | @cindex @code{gdbarch} |
| 3018 | @findex gdbarch_register |
| 3019 | The resulting object files containing the implementation of the |
| 3020 | @code{_initialize_@var{arch}_tdep} function are specified in the @value{GDBN} |
| 3021 | @file{configure.tgt} file, which includes a large case statement |
| 3022 | pattern matching against the @code{--target} option of the |
| 3023 | @code{configure} script. The new @code{struct gdbarch} is created |
| 3024 | within the @code{_initialize_@var{arch}_tdep} function by calling |
| 3025 | @code{gdbarch_register}: |
| 3026 | |
| 3027 | @smallexample |
| 3028 | void gdbarch_register (enum bfd_architecture @var{architecture}, |
| 3029 | gdbarch_init_ftype *@var{init_func}, |
| 3030 | gdbarch_dump_tdep_ftype *@var{tdep_dump_func}); |
| 3031 | @end smallexample |
| 3032 | |
| 3033 | The @var{architecture} will identify the unique @sc{bfd} to be |
| 3034 | associated with this @code{gdbarch}. The @var{init_func} funciton is |
| 3035 | called to create and return the new @code{struct gdbarch}. The |
| 3036 | @var{tdep_dump_func} function will dump the target specific details |
| 3037 | associated with this architecture. |
| 3038 | |
| 3039 | For example the function @code{_initialize_or1k_tdep} creates its |
| 3040 | architecture for 32-bit OpenRISC 1000 architectures by calling: |
| 3041 | |
| 3042 | @smallexample |
| 3043 | gdbarch_register (bfd_arch_or32, or1k_gdbarch_init, or1k_dump_tdep); |
| 3044 | @end smallexample |
| 3045 | |
| 3046 | @node Looking Up an Existing Architecture |
| 3047 | @subsection Looking Up an Existing Architecture |
| 3048 | @cindex @code{gdbarch} lookup |
| 3049 | |
| 3050 | The initialization function has this prototype: |
| 3051 | |
| 3052 | @smallexample |
| 3053 | static struct gdbarch * |
| 3054 | @var{arch}_gdbarch_init (struct gdbarch_info @var{info}, |
| 3055 | struct gdbarch_list *@var{arches}) |
| 3056 | @end smallexample |
| 3057 | |
| 3058 | The @var{info} argument contains parameters used to select the correct |
| 3059 | architecture, and @var{arches} is a list of architectures which |
| 3060 | have already been created with the same @code{bfd_arch_@var{arch}} |
| 3061 | value. |
| 3062 | |
| 3063 | The initialization function should first make sure that @var{info} |
| 3064 | is acceptable, and return @code{NULL} if it is not. Then, it should |
| 3065 | search through @var{arches} for an exact match to @var{info}, and |
| 3066 | return one if found. Lastly, if no exact match was found, it should |
| 3067 | create a new architecture based on @var{info} and return it. |
| 3068 | |
| 3069 | @findex gdbarch_list_lookup_by_info |
| 3070 | @cindex @code{gdbarch_info} |
| 3071 | The lookup is done using @code{gdbarch_list_lookup_by_info}. It is |
| 3072 | passed the list of existing architectures, @var{arches}, and the |
| 3073 | @code{struct gdbarch_info}, @var{info}, and returns the first matching |
| 3074 | architecture it finds, or @code{NULL} if none are found. If an |
| 3075 | architecture is found it can be returned as the result from the |
| 3076 | initialization function, otherwise a new @code{struct gdbach} will need |
| 3077 | to be created. |
| 3078 | |
| 3079 | The struct gdbarch_info has the following components: |
| 3080 | |
| 3081 | @smallexample |
| 3082 | struct gdbarch_info |
| 3083 | @{ |
| 3084 | const struct bfd_arch_info *bfd_arch_info; |
| 3085 | int byte_order; |
| 3086 | bfd *abfd; |
| 3087 | struct gdbarch_tdep_info *tdep_info; |
| 3088 | enum gdb_osabi osabi; |
| 3089 | const struct target_desc *target_desc; |
| 3090 | @}; |
| 3091 | @end smallexample |
| 3092 | |
| 3093 | @vindex bfd_arch_info |
| 3094 | The @code{bfd_arch_info} member holds the key details about the |
| 3095 | architecture. The @code{byte_order} member is a value in an |
| 3096 | enumeration indicating the endianism. The @code{abfd} member is a |
| 3097 | pointer to the full @sc{bfd}, the @code{tdep_info} member is |
| 3098 | additional custom target specific information, @code{osabi} identifies |
| 3099 | which (if any) of a number of operating specific ABIs are used by this |
| 3100 | architecture and the @code{target_desc} member is a set of name-value |
| 3101 | pairs with information about register usage in this target. |
| 3102 | |
| 3103 | When the @code{struct gdbarch} initialization function is called, not |
| 3104 | all the fields are provided---only those which can be deduced from the |
| 3105 | @sc{bfd}. The @code{struct gdbarch_info}, @var{info} is used as a |
| 3106 | look-up key with the list of existing architectures, @var{arches} to |
| 3107 | see if a suitable architecture already exists. The @var{tdep_info}, |
| 3108 | @var{osabi} and @var{target_desc} fields may be added before this |
| 3109 | lookup to refine the search. |
| 3110 | |
| 3111 | Only information in @var{info} should be used to choose the new |
| 3112 | architecture. Historically, @var{info} could be sparse, and |
| 3113 | defaults would be collected from the first element on @var{arches}. |
| 3114 | However, @value{GDBN} now fills in @var{info} more thoroughly, |
| 3115 | so new @code{gdbarch} initialization functions should not take |
| 3116 | defaults from @var{arches}. |
| 3117 | |
| 3118 | @node Creating a New Architecture |
| 3119 | @subsection Creating a New Architecture |
| 3120 | @cindex @code{struct gdbarch} creation |
| 3121 | |
| 3122 | @findex gdbarch_alloc |
| 3123 | @cindex @code{gdbarch_tdep} when allocating new @code{gdbarch} |
| 3124 | If no architecture is found, then a new architecture must be created, |
| 3125 | by calling @code{gdbarch_alloc} using the supplied @code{@w{struct |
| 3126 | gdbarch_info}} and any additional custom target specific |
| 3127 | information in a @code{struct gdbarch_tdep}. The prototype for |
| 3128 | @code{gdbarch_alloc} is: |
| 3129 | |
| 3130 | @smallexample |
| 3131 | struct gdbarch *gdbarch_alloc (const struct gdbarch_info *@var{info}, |
| 3132 | struct gdbarch_tdep *@var{tdep}); |
| 3133 | @end smallexample |
| 3134 | |
| 3135 | @cindex @code{set_gdbarch} functions |
| 3136 | @cindex @code{gdbarch} accessor functions |
| 3137 | The newly created struct gdbarch must then be populated. Although |
| 3138 | there are default values, in most cases they are not what is |
| 3139 | required. |
| 3140 | |
| 3141 | For each element, @var{X}, there is are a pair of corresponding accessor |
| 3142 | functions, one to set the value of that element, |
| 3143 | @code{set_gdbarch_@var{X}}, the second to either get the value of an |
| 3144 | element (if it is a variable) or to apply the element (if it is a |
| 3145 | function), @code{gdbarch_@var{X}}. Note that both accessor functions |
| 3146 | take a pointer to the @code{@w{struct gdbarch}} as first |
| 3147 | argument. Populating the new @code{gdbarch} should use the |
| 3148 | @code{set_gdbarch} functions. |
| 3149 | |
| 3150 | The following sections identify the main elements that should be set |
| 3151 | in this way. This is not the complete list, but represents the |
| 3152 | functions and elements that must commonly be specified for a new |
| 3153 | architecture. Many of the functions and variables are described in the |
| 3154 | header file @file{gdbarch.h}. |
| 3155 | |
| 3156 | This is the main work in defining a new architecture. Implementing the |
| 3157 | set of functions to populate the @code{struct gdbarch}. |
| 3158 | |
| 3159 | @cindex @code{gdbarch_tdep} definition |
| 3160 | @code{struct gdbarch_tdep} is not defined within @value{GDBN}---it is up |
| 3161 | to the user to define this struct if it is needed to hold custom target |
| 3162 | information that is not covered by the standard @code{@w{struct |
| 3163 | gdbarch}}. For example with the OpenRISC 1000 architecture it is used to |
| 3164 | hold the number of matchpoints available in the target (along with other |
| 3165 | information). |
| 3166 | |
| 3167 | If there is no additional target specific information, it can be set to |
| 3168 | @code{NULL}. |
| 3169 | |
| 3170 | @node Registers and Memory |
| 3171 | @section Registers and Memory |
| 3172 | |
| 3173 | @value{GDBN}'s model of the target machine is rather simple. |
| 3174 | @value{GDBN} assumes the machine includes a bank of registers and a |
| 3175 | block of memory. Each register may have a different size. |
| 3176 | |
| 3177 | @value{GDBN} does not have a magical way to match up with the |
| 3178 | compiler's idea of which registers are which; however, it is critical |
| 3179 | that they do match up accurately. The only way to make this work is |
| 3180 | to get accurate information about the order that the compiler uses, |
| 3181 | and to reflect that in the @code{gdbarch_register_name} and related functions. |
| 3182 | |
| 3183 | @value{GDBN} can handle big-endian, little-endian, and bi-endian architectures. |
| 3184 | |
| 3185 | @node Pointers and Addresses |
| 3186 | @section Pointers Are Not Always Addresses |
| 3187 | @cindex pointer representation |
| 3188 | @cindex address representation |
| 3189 | @cindex word-addressed machines |
| 3190 | @cindex separate data and code address spaces |
| 3191 | @cindex spaces, separate data and code address |
| 3192 | @cindex address spaces, separate data and code |
| 3193 | @cindex code pointers, word-addressed |
| 3194 | @cindex converting between pointers and addresses |
| 3195 | @cindex D10V addresses |
| 3196 | |
| 3197 | On almost all 32-bit architectures, the representation of a pointer is |
| 3198 | indistinguishable from the representation of some fixed-length number |
| 3199 | whose value is the byte address of the object pointed to. On such |
| 3200 | machines, the words ``pointer'' and ``address'' can be used interchangeably. |
| 3201 | However, architectures with smaller word sizes are often cramped for |
| 3202 | address space, so they may choose a pointer representation that breaks this |
| 3203 | identity, and allows a larger code address space. |
| 3204 | |
| 3205 | @c D10V is gone from sources - more current example? |
| 3206 | |
| 3207 | For example, the Renesas D10V is a 16-bit VLIW processor whose |
| 3208 | instructions are 32 bits long@footnote{Some D10V instructions are |
| 3209 | actually pairs of 16-bit sub-instructions. However, since you can't |
| 3210 | jump into the middle of such a pair, code addresses can only refer to |
| 3211 | full 32 bit instructions, which is what matters in this explanation.}. |
| 3212 | If the D10V used ordinary byte addresses to refer to code locations, |
| 3213 | then the processor would only be able to address 64kb of instructions. |
| 3214 | However, since instructions must be aligned on four-byte boundaries, the |
| 3215 | low two bits of any valid instruction's byte address are always |
| 3216 | zero---byte addresses waste two bits. So instead of byte addresses, |
| 3217 | the D10V uses word addresses---byte addresses shifted right two bits---to |
| 3218 | refer to code. Thus, the D10V can use 16-bit words to address 256kb of |
| 3219 | code space. |
| 3220 | |
| 3221 | However, this means that code pointers and data pointers have different |
| 3222 | forms on the D10V. The 16-bit word @code{0xC020} refers to byte address |
| 3223 | @code{0xC020} when used as a data address, but refers to byte address |
| 3224 | @code{0x30080} when used as a code address. |
| 3225 | |
| 3226 | (The D10V also uses separate code and data address spaces, which also |
| 3227 | affects the correspondence between pointers and addresses, but we're |
| 3228 | going to ignore that here; this example is already too long.) |
| 3229 | |
| 3230 | To cope with architectures like this---the D10V is not the only |
| 3231 | one!---@value{GDBN} tries to distinguish between @dfn{addresses}, which are |
| 3232 | byte numbers, and @dfn{pointers}, which are the target's representation |
| 3233 | of an address of a particular type of data. In the example above, |
| 3234 | @code{0xC020} is the pointer, which refers to one of the addresses |
| 3235 | @code{0xC020} or @code{0x30080}, depending on the type imposed upon it. |
| 3236 | @value{GDBN} provides functions for turning a pointer into an address |
| 3237 | and vice versa, in the appropriate way for the current architecture. |
| 3238 | |
| 3239 | Unfortunately, since addresses and pointers are identical on almost all |
| 3240 | processors, this distinction tends to bit-rot pretty quickly. Thus, |
| 3241 | each time you port @value{GDBN} to an architecture which does |
| 3242 | distinguish between pointers and addresses, you'll probably need to |
| 3243 | clean up some architecture-independent code. |
| 3244 | |
| 3245 | Here are functions which convert between pointers and addresses: |
| 3246 | |
| 3247 | @deftypefun CORE_ADDR extract_typed_address (void *@var{buf}, struct type *@var{type}) |
| 3248 | Treat the bytes at @var{buf} as a pointer or reference of type |
| 3249 | @var{type}, and return the address it represents, in a manner |
| 3250 | appropriate for the current architecture. This yields an address |
| 3251 | @value{GDBN} can use to read target memory, disassemble, etc. Note that |
| 3252 | @var{buf} refers to a buffer in @value{GDBN}'s memory, not the |
| 3253 | inferior's. |
| 3254 | |
| 3255 | For example, if the current architecture is the Intel x86, this function |
| 3256 | extracts a little-endian integer of the appropriate length from |
| 3257 | @var{buf} and returns it. However, if the current architecture is the |
| 3258 | D10V, this function will return a 16-bit integer extracted from |
| 3259 | @var{buf}, multiplied by four if @var{type} is a pointer to a function. |
| 3260 | |
| 3261 | If @var{type} is not a pointer or reference type, then this function |
| 3262 | will signal an internal error. |
| 3263 | @end deftypefun |
| 3264 | |
| 3265 | @deftypefun CORE_ADDR store_typed_address (void *@var{buf}, struct type *@var{type}, CORE_ADDR @var{addr}) |
| 3266 | Store the address @var{addr} in @var{buf}, in the proper format for a |
| 3267 | pointer of type @var{type} in the current architecture. Note that |
| 3268 | @var{buf} refers to a buffer in @value{GDBN}'s memory, not the |
| 3269 | inferior's. |
| 3270 | |
| 3271 | For example, if the current architecture is the Intel x86, this function |
| 3272 | stores @var{addr} unmodified as a little-endian integer of the |
| 3273 | appropriate length in @var{buf}. However, if the current architecture |
| 3274 | is the D10V, this function divides @var{addr} by four if @var{type} is |
| 3275 | a pointer to a function, and then stores it in @var{buf}. |
| 3276 | |
| 3277 | If @var{type} is not a pointer or reference type, then this function |
| 3278 | will signal an internal error. |
| 3279 | @end deftypefun |
| 3280 | |
| 3281 | @deftypefun CORE_ADDR value_as_address (struct value *@var{val}) |
| 3282 | Assuming that @var{val} is a pointer, return the address it represents, |
| 3283 | as appropriate for the current architecture. |
| 3284 | |
| 3285 | This function actually works on integral values, as well as pointers. |
| 3286 | For pointers, it performs architecture-specific conversions as |
| 3287 | described above for @code{extract_typed_address}. |
| 3288 | @end deftypefun |
| 3289 | |
| 3290 | @deftypefun CORE_ADDR value_from_pointer (struct type *@var{type}, CORE_ADDR @var{addr}) |
| 3291 | Create and return a value representing a pointer of type @var{type} to |
| 3292 | the address @var{addr}, as appropriate for the current architecture. |
| 3293 | This function performs architecture-specific conversions as described |
| 3294 | above for @code{store_typed_address}. |
| 3295 | @end deftypefun |
| 3296 | |
| 3297 | Here are two functions which architectures can define to indicate the |
| 3298 | relationship between pointers and addresses. These have default |
| 3299 | definitions, appropriate for architectures on which all pointers are |
| 3300 | simple unsigned byte addresses. |
| 3301 | |
| 3302 | @deftypefun CORE_ADDR gdbarch_pointer_to_address (struct gdbarch *@var{gdbarch}, struct type *@var{type}, char *@var{buf}) |
| 3303 | Assume that @var{buf} holds a pointer of type @var{type}, in the |
| 3304 | appropriate format for the current architecture. Return the byte |
| 3305 | address the pointer refers to. |
| 3306 | |
| 3307 | This function may safely assume that @var{type} is either a pointer or a |
| 3308 | C@t{++} reference type. |
| 3309 | @end deftypefun |
| 3310 | |
| 3311 | @deftypefun void gdbarch_address_to_pointer (struct gdbarch *@var{gdbarch}, struct type *@var{type}, char *@var{buf}, CORE_ADDR @var{addr}) |
| 3312 | Store in @var{buf} a pointer of type @var{type} representing the address |
| 3313 | @var{addr}, in the appropriate format for the current architecture. |
| 3314 | |
| 3315 | This function may safely assume that @var{type} is either a pointer or a |
| 3316 | C@t{++} reference type. |
| 3317 | @end deftypefun |
| 3318 | |
| 3319 | @node Address Classes |
| 3320 | @section Address Classes |
| 3321 | @cindex address classes |
| 3322 | @cindex DW_AT_byte_size |
| 3323 | @cindex DW_AT_address_class |
| 3324 | |
| 3325 | Sometimes information about different kinds of addresses is available |
| 3326 | via the debug information. For example, some programming environments |
| 3327 | define addresses of several different sizes. If the debug information |
| 3328 | distinguishes these kinds of address classes through either the size |
| 3329 | info (e.g, @code{DW_AT_byte_size} in @w{DWARF 2}) or through an explicit |
| 3330 | address class attribute (e.g, @code{DW_AT_address_class} in @w{DWARF 2}), the |
| 3331 | following macros should be defined in order to disambiguate these |
| 3332 | types within @value{GDBN} as well as provide the added information to |
| 3333 | a @value{GDBN} user when printing type expressions. |
| 3334 | |
| 3335 | @deftypefun int gdbarch_address_class_type_flags (struct gdbarch *@var{gdbarch}, int @var{byte_size}, int @var{dwarf2_addr_class}) |
| 3336 | Returns the type flags needed to construct a pointer type whose size |
| 3337 | is @var{byte_size} and whose address class is @var{dwarf2_addr_class}. |
| 3338 | This function is normally called from within a symbol reader. See |
| 3339 | @file{dwarf2read.c}. |
| 3340 | @end deftypefun |
| 3341 | |
| 3342 | @deftypefun {char *} gdbarch_address_class_type_flags_to_name (struct gdbarch *@var{gdbarch}, int @var{type_flags}) |
| 3343 | Given the type flags representing an address class qualifier, return |
| 3344 | its name. |
| 3345 | @end deftypefun |
| 3346 | @deftypefun int gdbarch_address_class_name_to_type_flags (struct gdbarch *@var{gdbarch}, int @var{name}, int *@var{type_flags_ptr}) |
| 3347 | Given an address qualifier name, set the @code{int} referenced by @var{type_flags_ptr} to the type flags |
| 3348 | for that address class qualifier. |
| 3349 | @end deftypefun |
| 3350 | |
| 3351 | Since the need for address classes is rather rare, none of |
| 3352 | the address class functions are defined by default. Predicate |
| 3353 | functions are provided to detect when they are defined. |
| 3354 | |
| 3355 | Consider a hypothetical architecture in which addresses are normally |
| 3356 | 32-bits wide, but 16-bit addresses are also supported. Furthermore, |
| 3357 | suppose that the @w{DWARF 2} information for this architecture simply |
| 3358 | uses a @code{DW_AT_byte_size} value of 2 to indicate the use of one |
| 3359 | of these "short" pointers. The following functions could be defined |
| 3360 | to implement the address class functions: |
| 3361 | |
| 3362 | @smallexample |
| 3363 | somearch_address_class_type_flags (int byte_size, |
| 3364 | int dwarf2_addr_class) |
| 3365 | @{ |
| 3366 | if (byte_size == 2) |
| 3367 | return TYPE_FLAG_ADDRESS_CLASS_1; |
| 3368 | else |
| 3369 | return 0; |
| 3370 | @} |
| 3371 | |
| 3372 | static char * |
| 3373 | somearch_address_class_type_flags_to_name (int type_flags) |
| 3374 | @{ |
| 3375 | if (type_flags & TYPE_FLAG_ADDRESS_CLASS_1) |
| 3376 | return "short"; |
| 3377 | else |
| 3378 | return NULL; |
| 3379 | @} |
| 3380 | |
| 3381 | int |
| 3382 | somearch_address_class_name_to_type_flags (char *name, |
| 3383 | int *type_flags_ptr) |
| 3384 | @{ |
| 3385 | if (strcmp (name, "short") == 0) |
| 3386 | @{ |
| 3387 | *type_flags_ptr = TYPE_FLAG_ADDRESS_CLASS_1; |
| 3388 | return 1; |
| 3389 | @} |
| 3390 | else |
| 3391 | return 0; |
| 3392 | @} |
| 3393 | @end smallexample |
| 3394 | |
| 3395 | The qualifier @code{@@short} is used in @value{GDBN}'s type expressions |
| 3396 | to indicate the presence of one of these ``short'' pointers. For |
| 3397 | example if the debug information indicates that @code{short_ptr_var} is |
| 3398 | one of these short pointers, @value{GDBN} might show the following |
| 3399 | behavior: |
| 3400 | |
| 3401 | @smallexample |
| 3402 | (gdb) ptype short_ptr_var |
| 3403 | type = int * @@short |
| 3404 | @end smallexample |
| 3405 | |
| 3406 | |
| 3407 | @node Register Representation |
| 3408 | @section Register Representation |
| 3409 | |
| 3410 | @menu |
| 3411 | * Raw and Cooked Registers:: |
| 3412 | * Register Architecture Functions & Variables:: |
| 3413 | * Register Information Functions:: |
| 3414 | * Register and Memory Data:: |
| 3415 | * Register Caching:: |
| 3416 | @end menu |
| 3417 | |
| 3418 | @node Raw and Cooked Registers |
| 3419 | @subsection Raw and Cooked Registers |
| 3420 | @cindex raw register representation |
| 3421 | @cindex cooked register representation |
| 3422 | @cindex representations, raw and cooked registers |
| 3423 | |
| 3424 | @value{GDBN} considers registers to be a set with members numbered |
| 3425 | linearly from 0 upwards. The first part of that set corresponds to real |
| 3426 | physical registers, the second part to any @dfn{pseudo-registers}. |
| 3427 | Pseudo-registers have no independent physical existence, but are useful |
| 3428 | representations of information within the architecture. For example the |
| 3429 | OpenRISC 1000 architecture has up to 32 general purpose registers, which |
| 3430 | are typically represented as 32-bit (or 64-bit) integers. However the |
| 3431 | GPRs are also used as operands to the floating point operations, and it |
| 3432 | could be convenient to define a set of pseudo-registers, to show the |
| 3433 | GPRs represented as floating point values. |
| 3434 | |
| 3435 | For any architecture, the implementer will decide on a mapping from |
| 3436 | hardware to @value{GDBN} register numbers. The registers corresponding to real |
| 3437 | hardware are referred to as @dfn{raw} registers, the remaining registers are |
| 3438 | @dfn{pseudo-registers}. The total register set (raw and pseudo) is called |
| 3439 | the @dfn{cooked} register set. |
| 3440 | |
| 3441 | |
| 3442 | @node Register Architecture Functions & Variables |
| 3443 | @subsection Functions and Variables Specifying the Register Architecture |
| 3444 | @cindex @code{gdbarch} register architecture functions |
| 3445 | |
| 3446 | These @code{struct gdbarch} functions and variables specify the number |
| 3447 | and type of registers in the architecture. |
| 3448 | |
| 3449 | @deftypefn {Architecture Function} CORE_ADDR read_pc (struct regcache *@var{regcache}) |
| 3450 | @end deftypefn |
| 3451 | @deftypefn {Architecture Function} void write_pc (struct regcache *@var{regcache}, CORE_ADDR @var{val}) |
| 3452 | |
| 3453 | Read or write the program counter. The default value of both |
| 3454 | functions is @code{NULL} (no function available). If the program |
| 3455 | counter is just an ordinary register, it can be specified in |
| 3456 | @code{struct gdbarch} instead (see @code{pc_regnum} below) and it will |
| 3457 | be read or written using the standard routines to access registers. This |
| 3458 | function need only be specified if the program counter is not an |
| 3459 | ordinary register. |
| 3460 | |
| 3461 | Any register information can be obtained using the supplied register |
| 3462 | cache, @var{regcache}. @xref{Register Caching, , Register Caching}. |
| 3463 | |
| 3464 | @end deftypefn |
| 3465 | |
| 3466 | @deftypefn {Architecture Function} void pseudo_register_read (struct gdbarch *@var{gdbarch}, struct regcache *@var{regcache}, int @var{regnum}, const gdb_byte *@var{buf}) |
| 3467 | @end deftypefn |
| 3468 | @deftypefn {Architecture Function} void pseudo_register_write (struct gdbarch *@var{gdbarch}, struct regcache *@var{regcache}, int @var{regnum}, const gdb_byte *@var{buf}) |
| 3469 | |
| 3470 | These functions should be defined if there are any pseudo-registers. |
| 3471 | The default value is @code{NULL}. @var{regnum} is the number of the |
| 3472 | register to read or write (which will be a @dfn{cooked} register |
| 3473 | number) and @var{buf} is the buffer where the value read will be |
| 3474 | placed, or from which the value to be written will be taken. The |
| 3475 | value in the buffer may be converted to or from a signed or unsigned |
| 3476 | integral value using one of the utility functions (@pxref{Register and |
| 3477 | Memory Data, , Using Different Register and Memory Data |
| 3478 | Representations}). |
| 3479 | |
| 3480 | The access should be for the specified architecture, |
| 3481 | @var{gdbarch}. Any register information can be obtained using the |
| 3482 | supplied register cache, @var{regcache}. @xref{Register Caching, , |
| 3483 | Register Caching}. |
| 3484 | |
| 3485 | @end deftypefn |
| 3486 | |
| 3487 | @deftypevr {Architecture Variable} int sp_regnum |
| 3488 | @vindex sp_regnum |
| 3489 | @cindex stack pointer |
| 3490 | @cindex @kbd{$sp} |
| 3491 | |
| 3492 | This specifies the register holding the stack pointer, which may be a |
| 3493 | raw or pseudo-register. It defaults to -1 (not defined), but it is an |
| 3494 | error for it not to be defined. |
| 3495 | |
| 3496 | The value of the stack pointer register can be accessed withing |
| 3497 | @value{GDBN} as the variable @kbd{$sp}. |
| 3498 | |
| 3499 | @end deftypevr |
| 3500 | |
| 3501 | @deftypevr {Architecture Variable} int pc_regnum |
| 3502 | @vindex pc_regnum |
| 3503 | @cindex program counter |
| 3504 | @cindex @kbd{$pc} |
| 3505 | |
| 3506 | This specifies the register holding the program counter, which may be a |
| 3507 | raw or pseudo-register. It defaults to -1 (not defined). If |
| 3508 | @code{pc_regnum} is not defined, then the functions @code{read_pc} and |
| 3509 | @code{write_pc} (see above) must be defined. |
| 3510 | |
| 3511 | The value of the program counter (whether defined as a register, or |
| 3512 | through @code{read_pc} and @code{write_pc}) can be accessed withing |
| 3513 | @value{GDBN} as the variable @kbd{$pc}. |
| 3514 | |
| 3515 | @end deftypevr |
| 3516 | |
| 3517 | @deftypevr {Architecture Variable} int ps_regnum |
| 3518 | @vindex ps_regnum |
| 3519 | @cindex processor status register |
| 3520 | @cindex status register |
| 3521 | @cindex @kbd{$ps} |
| 3522 | |
| 3523 | This specifies the register holding the processor status (often called |
| 3524 | the status register), which may be a raw or pseudo-register. It |
| 3525 | defaults to -1 (not defined). |
| 3526 | |
| 3527 | If defined, the value of this register can be accessed withing |
| 3528 | @value{GDBN} as the variable @kbd{$ps}. |
| 3529 | |
| 3530 | @end deftypevr |
| 3531 | |
| 3532 | @deftypevr {Architecture Variable} int fp0_regnum |
| 3533 | @vindex fp0_regnum |
| 3534 | @cindex first floating point register |
| 3535 | |
| 3536 | This specifies the first floating point register. It defaults to |
| 3537 | 0. @code{fp0_regnum} is not needed unless the target offers support |
| 3538 | for floating point. |
| 3539 | |
| 3540 | @end deftypevr |
| 3541 | |
| 3542 | @node Register Information Functions |
| 3543 | @subsection Functions Giving Register Information |
| 3544 | @cindex @code{gdbarch} register information functions |
| 3545 | |
| 3546 | These functions return information about registers. |
| 3547 | |
| 3548 | @deftypefn {Architecture Function} {const char *} register_name (struct gdbarch *@var{gdbarch}, int @var{regnum}) |
| 3549 | |
| 3550 | This function should convert a register number (raw or pseudo) to a |
| 3551 | register name (as a C @code{const char *}). This is used both to |
| 3552 | determine the name of a register for output and to work out the meaning |
| 3553 | of any register names used as input. The function may also return |
| 3554 | @code{NULL}, to indicate that @var{regnum} is not a valid register. |
| 3555 | |
| 3556 | For example with the OpenRISC 1000, @value{GDBN} registers 0-31 are the |
| 3557 | General Purpose Registers, register 32 is the program counter and |
| 3558 | register 33 is the supervision register (i.e.@: the processor status |
| 3559 | register), which map to the strings @code{"gpr00"} through |
| 3560 | @code{"gpr31"}, @code{"pc"} and @code{"sr"} respectively. This means |
| 3561 | that the @value{GDBN} command @kbd{print $gpr5} should print the value of |
| 3562 | the OR1K general purpose register 5@footnote{ |
| 3563 | @cindex frame pointer |
| 3564 | @cindex @kbd{$fp} |
| 3565 | Historically, @value{GDBN} always had a concept of a frame pointer |
| 3566 | register, which could be accessed via the @value{GDBN} variable, |
| 3567 | @kbd{$fp}. That concept is now deprecated, recognizing that not all |
| 3568 | architectures have a frame pointer. However if an architecture does |
| 3569 | have a frame pointer register, and defines a register or |
| 3570 | pseudo-register with the name @code{"fp"}, then that register will be |
| 3571 | used as the value of the @kbd{$fp} variable.}. |
| 3572 | |
| 3573 | The default value for this function is @code{NULL}, meaning |
| 3574 | undefined. It should always be defined. |
| 3575 | |
| 3576 | The access should be for the specified architecture, @var{gdbarch}. |
| 3577 | |
| 3578 | @end deftypefn |
| 3579 | |
| 3580 | @deftypefn {Architecture Function} {struct type *} register_type (struct gdbarch *@var{gdbarch}, int @var{regnum}) |
| 3581 | |
| 3582 | Given a register number, this function identifies the type of data it |
| 3583 | may be holding, specified as a @code{struct type}. @value{GDBN} allows |
| 3584 | creation of arbitrary types, but a number of built in types are |
| 3585 | provided (@code{builtin_type_void}, @code{builtin_type_int32} etc), |
| 3586 | together with functions to derive types from these. |
| 3587 | |
| 3588 | Typically the program counter will have a type of ``pointer to |
| 3589 | function'' (it points to code), the frame pointer and stack pointer |
| 3590 | will have types of ``pointer to void'' (they point to data on the stack) |
| 3591 | and all other integer registers will have a type of 32-bit integer or |
| 3592 | 64-bit integer. |
| 3593 | |
| 3594 | This information guides the formatting when displaying register |
| 3595 | information. The default value is @code{NULL} meaning no information is |
| 3596 | available to guide formatting when displaying registers. |
| 3597 | |
| 3598 | @end deftypefn |
| 3599 | |
| 3600 | @deftypefn {Architecture Function} void print_registers_info (struct gdbarch *@var{gdbarch}, struct ui_file *@var{file}, struct frame_info *@var{frame}, int @var{regnum}, int @var{all}) |
| 3601 | |
| 3602 | Define this function to print out one or all of the registers for the |
| 3603 | @value{GDBN} @kbd{info registers} command. The default value is the |
| 3604 | function @code{default_print_registers_info}, which uses the register |
| 3605 | type information (see @code{register_type} above) to determine how each |
| 3606 | register should be printed. Define a custom version of this function |
| 3607 | for fuller control over how the registers are displayed. |
| 3608 | |
| 3609 | The access should be for the specified architecture, @var{gdbarch}, |
| 3610 | with output to the the file specified by the User Interface |
| 3611 | Independent Output file handle, @var{file} (@pxref{UI-Independent |
| 3612 | Output, , UI-Independent Output---the @code{ui_out} |
| 3613 | Functions}). |
| 3614 | |
| 3615 | The registers should show their values in the frame specified by |
| 3616 | @var{frame}. If @var{regnum} is -1 and @var{all} is zero, then all |
| 3617 | the ``significant'' registers should be shown (the implementer should |
| 3618 | decide which registers are ``significant''). Otherwise only the value of |
| 3619 | the register specified by @var{regnum} should be output. If |
| 3620 | @var{regnum} is -1 and @var{all} is non-zero (true), then the value of |
| 3621 | all registers should be shown. |
| 3622 | |
| 3623 | By default @code{default_print_registers_info} prints one register per |
| 3624 | line, and if @var{all} is zero omits floating-point registers. |
| 3625 | |
| 3626 | @end deftypefn |
| 3627 | |
| 3628 | @deftypefn {Architecture Function} void print_float_info (struct gdbarch *@var{gdbarch}, struct ui_file *@var{file}, struct frame_info *@var{frame}, const char *@var{args}) |
| 3629 | |
| 3630 | Define this function to provide output about the floating point unit and |
| 3631 | registers for the @value{GDBN} @kbd{info float} command respectively. |
| 3632 | The default value is @code{NULL} (not defined), meaning no information |
| 3633 | will be provided. |
| 3634 | |
| 3635 | The @var{gdbarch} and @var{file} and @var{frame} arguments have the same |
| 3636 | meaning as in the @code{print_registers_info} function above. The string |
| 3637 | @var{args} contains any supplementary arguments to the @kbd{info float} |
| 3638 | command. |
| 3639 | |
| 3640 | Define this function if the target supports floating point operations. |
| 3641 | |
| 3642 | @end deftypefn |
| 3643 | |
| 3644 | @deftypefn {Architecture Function} void print_vector_info (struct gdbarch *@var{gdbarch}, struct ui_file *@var{file}, struct frame_info *@var{frame}, const char *@var{args}) |
| 3645 | |
| 3646 | Define this function to provide output about the vector unit and |
| 3647 | registers for the @value{GDBN} @kbd{info vector} command respectively. |
| 3648 | The default value is @code{NULL} (not defined), meaning no information |
| 3649 | will be provided. |
| 3650 | |
| 3651 | The @var{gdbarch}, @var{file} and @var{frame} arguments have the |
| 3652 | same meaning as in the @code{print_registers_info} function above. The |
| 3653 | string @var{args} contains any supplementary arguments to the @kbd{info |
| 3654 | vector} command. |
| 3655 | |
| 3656 | Define this function if the target supports vector operations. |
| 3657 | |
| 3658 | @end deftypefn |
| 3659 | |
| 3660 | @deftypefn {Architecture Function} int register_reggroup_p (struct gdbarch *@var{gdbarch}, int @var{regnum}, struct reggroup *@var{group}) |
| 3661 | |
| 3662 | @value{GDBN} groups registers into different categories (general, |
| 3663 | vector, floating point etc). This function, given a register, |
| 3664 | @var{regnum}, and group, @var{group}, returns 1 (true) if the register |
| 3665 | is in the group and 0 (false) otherwise. |
| 3666 | |
| 3667 | The information should be for the specified architecture, |
| 3668 | @var{gdbarch} |
| 3669 | |
| 3670 | The default value is the function @code{default_register_reggroup_p} |
| 3671 | which will do a reasonable job based on the type of the register (see |
| 3672 | the function @code{register_type} above), with groups for general |
| 3673 | purpose registers, floating point registers, vector registers and raw |
| 3674 | (i.e not pseudo) registers. |
| 3675 | |
| 3676 | @end deftypefn |
| 3677 | |
| 3678 | @node Register and Memory Data |
| 3679 | @subsection Using Different Register and Memory Data Representations |
| 3680 | @cindex register representation |
| 3681 | @cindex memory representation |
| 3682 | @cindex representations, register and memory |
| 3683 | @cindex register data formats, converting |
| 3684 | @cindex @code{struct value}, converting register contents to |
| 3685 | |
| 3686 | Some architectures have different representations of data objects, |
| 3687 | depending whether the object is held in a register or memory. For |
| 3688 | example: |
| 3689 | |
| 3690 | @itemize @bullet |
| 3691 | |
| 3692 | @item |
| 3693 | The Alpha architecture can represent 32 bit integer values in |
| 3694 | floating-point registers. |
| 3695 | |
| 3696 | @item |
| 3697 | The x86 architecture supports 80-bit floating-point registers. The |
| 3698 | @code{long double} data type occupies 96 bits in memory but only 80 |
| 3699 | bits when stored in a register. |
| 3700 | |
| 3701 | @end itemize |
| 3702 | |
| 3703 | In general, the register representation of a data type is determined by |
| 3704 | the architecture, or @value{GDBN}'s interface to the architecture, while |
| 3705 | the memory representation is determined by the Application Binary |
| 3706 | Interface. |
| 3707 | |
| 3708 | For almost all data types on almost all architectures, the two |
| 3709 | representations are identical, and no special handling is needed. |
| 3710 | However, they do occasionally differ. An architecture may define the |
| 3711 | following @code{struct gdbarch} functions to request conversions |
| 3712 | between the register and memory representations of a data type: |
| 3713 | |
| 3714 | @deftypefn {Architecture Function} int gdbarch_convert_register_p (struct gdbarch *@var{gdbarch}, int @var{reg}) |
| 3715 | |
| 3716 | Return non-zero (true) if the representation of a data value stored in |
| 3717 | this register may be different to the representation of that same data |
| 3718 | value when stored in memory. The default value is @code{NULL} |
| 3719 | (undefined). |
| 3720 | |
| 3721 | If this function is defined and returns non-zero, the @code{struct |
| 3722 | gdbarch} functions @code{gdbarch_register_to_value} and |
| 3723 | @code{gdbarch_value_to_register} (see below) should be used to perform |
| 3724 | any necessary conversion. |
| 3725 | |
| 3726 | If defined, this function should return zero for the register's native |
| 3727 | type, when no conversion is necessary. |
| 3728 | @end deftypefn |
| 3729 | |
| 3730 | @deftypefn {Architecture Function} void gdbarch_register_to_value (struct gdbarch *@var{gdbarch}, int @var{reg}, struct type *@var{type}, char *@var{from}, char *@var{to}) |
| 3731 | |
| 3732 | Convert the value of register number @var{reg} to a data object of |
| 3733 | type @var{type}. The buffer at @var{from} holds the register's value |
| 3734 | in raw format; the converted value should be placed in the buffer at |
| 3735 | @var{to}. |
| 3736 | |
| 3737 | @quotation |
| 3738 | @emph{Note:} @code{gdbarch_register_to_value} and |
| 3739 | @code{gdbarch_value_to_register} take their @var{reg} and @var{type} |
| 3740 | arguments in different orders. |
| 3741 | @end quotation |
| 3742 | |
| 3743 | @code{gdbarch_register_to_value} should only be used with registers |
| 3744 | for which the @code{gdbarch_convert_register_p} function returns a |
| 3745 | non-zero value. |
| 3746 | |
| 3747 | @end deftypefn |
| 3748 | |
| 3749 | @deftypefn {Architecture Function} void gdbarch_value_to_register (struct gdbarch *@var{gdbarch}, struct type *@var{type}, int @var{reg}, char *@var{from}, char *@var{to}) |
| 3750 | |
| 3751 | Convert a data value of type @var{type} to register number @var{reg}' |
| 3752 | raw format. |
| 3753 | |
| 3754 | @quotation |
| 3755 | @emph{Note:} @code{gdbarch_register_to_value} and |
| 3756 | @code{gdbarch_value_to_register} take their @var{reg} and @var{type} |
| 3757 | arguments in different orders. |
| 3758 | @end quotation |
| 3759 | |
| 3760 | @code{gdbarch_value_to_register} should only be used with registers |
| 3761 | for which the @code{gdbarch_convert_register_p} function returns a |
| 3762 | non-zero value. |
| 3763 | |
| 3764 | @end deftypefn |
| 3765 | |
| 3766 | @node Register Caching |
| 3767 | @subsection Register Caching |
| 3768 | @cindex register caching |
| 3769 | |
| 3770 | Caching of registers is used, so that the target does not need to be |
| 3771 | accessed and reanalyzed multiple times for each register in |
| 3772 | circumstances where the register value cannot have changed. |
| 3773 | |
| 3774 | @cindex @code{struct regcache} |
| 3775 | @value{GDBN} provides @code{struct regcache}, associated with a |
| 3776 | particular @code{struct gdbarch} to hold the cached values of the raw |
| 3777 | registers. A set of functions is provided to access both the raw |
| 3778 | registers (with @code{raw} in their name) and the full set of cooked |
| 3779 | registers (with @code{cooked} in their name). Functions are provided |
| 3780 | to ensure the register cache is kept synchronized with the values of |
| 3781 | the actual registers in the target. |
| 3782 | |
| 3783 | Accessing registers through the @code{struct regcache} routines will |
| 3784 | ensure that the appropriate @code{struct gdbarch} functions are called |
| 3785 | when necessary to access the underlying target architecture. In general |
| 3786 | users should use the @dfn{cooked} functions, since these will map to the |
| 3787 | @dfn{raw} functions automatically as appropriate. |
| 3788 | |
| 3789 | @findex regcache_cooked_read |
| 3790 | @findex regcache_cooked_write |
| 3791 | @cindex @code{gdb_byte} |
| 3792 | @findex regcache_cooked_read_signed |
| 3793 | @findex regcache_cooked_read_unsigned |
| 3794 | @findex regcache_cooked_write_signed |
| 3795 | @findex regcache_cooked_write_unsigned |
| 3796 | The two key functions are @code{regcache_cooked_read} and |
| 3797 | @code{regcache_cooked_write} which read or write a register from or to |
| 3798 | a byte buffer (type @code{gdb_byte *}). For convenience the wrapper |
| 3799 | functions @code{regcache_cooked_read_signed}, |
| 3800 | @code{regcache_cooked_read_unsigned}, |
| 3801 | @code{regcache_cooked_write_signed} and |
| 3802 | @code{regcache_cooked_write_unsigned} are provided, which read or |
| 3803 | write the value using the buffer and convert to or from an integral |
| 3804 | value as appropriate. |
| 3805 | |
| 3806 | @node Frame Interpretation |
| 3807 | @section Frame Interpretation |
| 3808 | |
| 3809 | @menu |
| 3810 | * All About Stack Frames:: |
| 3811 | * Frame Handling Terminology:: |
| 3812 | * Prologue Caches:: |
| 3813 | * Functions and Variable to Analyze Frames:: |
| 3814 | * Functions to Access Frame Data:: |
| 3815 | * Analyzing Stacks---Frame Sniffers:: |
| 3816 | @end menu |
| 3817 | |
| 3818 | @node All About Stack Frames |
| 3819 | @subsection All About Stack Frames |
| 3820 | |
| 3821 | @value{GDBN} needs to understand the stack on which local (automatic) |
| 3822 | variables are stored. The area of the stack containing all the local |
| 3823 | variables for a function invocation is known as the @dfn{stack frame} |
| 3824 | for that function (or colloquially just as the @dfn{frame}). In turn the |
| 3825 | function that called the function will have its stack frame, and so on |
| 3826 | back through the chain of functions that have been called. |
| 3827 | |
| 3828 | Almost all architectures have one register dedicated to point to the |
| 3829 | end of the stack (the @dfn{stack pointer}). Many have a second register |
| 3830 | which points to the start of the currently active stack frame (the |
| 3831 | @dfn{frame pointer}). The specific arrangements for an architecture are |
| 3832 | a key part of the ABI. |
| 3833 | |
| 3834 | A diagram helps to explain this. Here is a simple program to compute |
| 3835 | factorials: |
| 3836 | |
| 3837 | @smallexample |
| 3838 | #include <stdio.h> |
| 3839 | int fact (int n) |
| 3840 | @{ |
| 3841 | if (0 == n) |
| 3842 | @{ |
| 3843 | return 1; |
| 3844 | @} |
| 3845 | else |
| 3846 | @{ |
| 3847 | return n * fact (n - 1); |
| 3848 | @} |
| 3849 | @} |
| 3850 | |
| 3851 | main () |
| 3852 | @{ |
| 3853 | int i; |
| 3854 | |
| 3855 | for (i = 0; i < 10; i++) |
| 3856 | @{ |
| 3857 | int f = fact (i); |
| 3858 | printf ("%d! = %d\n", i, f); |
| 3859 | @} |
| 3860 | @} |
| 3861 | @end smallexample |
| 3862 | |
| 3863 | Consider the state of the stack when the code reaches line 6 after the |
| 3864 | main program has called @code{fact@w{ }(3)}. The chain of function |
| 3865 | calls will be @code{main ()}, @code{fact@w{ }(3)}, @code{fact@w{ |
| 3866 | }(2)}, @code{@w{fact (1)}} and @code{fact@w{ }(0)}. |
| 3867 | |
| 3868 | In this illustration the stack is falling (as used for example by the |
| 3869 | OpenRISC 1000 ABI). The stack pointer (SP) is at the end of the stack |
| 3870 | (lowest address) and the frame pointer (FP) is at the highest address |
| 3871 | in the current stack frame. The following diagram shows how the stack |
| 3872 | looks. |
| 3873 | |
| 3874 | @center @image{stack_frame,14cm} |
| 3875 | |
| 3876 | In each stack frame, offset 0 from the stack pointer is the frame |
| 3877 | pointer of the previous frame and offset 4 (this is illustrating a |
| 3878 | 32-bit architecture) from the stack pointer is the return address. |
| 3879 | Local variables are indexed from the frame pointer, with negative |
| 3880 | indexes. In the function @code{fact}, offset -4 from the frame |
| 3881 | pointer is the argument @var{n}. In the @code{main} function, offset |
| 3882 | -4 from the frame pointer is the local variable @var{i} and offset -8 |
| 3883 | from the frame pointer is the local variable @var{f}@footnote{This is |
| 3884 | a simplified example for illustrative purposes only. Good optimizing |
| 3885 | compilers would not put anything on the stack for such simple |
| 3886 | functions. Indeed they might eliminate the recursion and use of the |
| 3887 | stack entirely!}. |
| 3888 | |
| 3889 | It is very easy to get confused when examining stacks. @value{GDBN} |
| 3890 | has terminology it uses rigorously throughout. The stack frame of the |
| 3891 | function currently executing, or where execution stopped is numbered |
| 3892 | zero. In this example frame #0 is the stack frame of the call to |
| 3893 | @code{fact@w{ }(0)}. The stack frame of its calling function |
| 3894 | (@code{fact@w{ }(1)} in this case) is numbered #1 and so on back |
| 3895 | through the chain of calls. |
| 3896 | |
| 3897 | The main @value{GDBN} data structure describing frames is |
| 3898 | @code{@w{struct frame_info}}. It is not used directly, but only via |
| 3899 | its accessor functions. @code{frame_info} includes information about |
| 3900 | the registers in the frame and a pointer to the code of the function |
| 3901 | with which the frame is associated. The entire stack is represented as |
| 3902 | a linked list of @code{frame_info} structs. |
| 3903 | |
| 3904 | @node Frame Handling Terminology |
| 3905 | @subsection Frame Handling Terminology |
| 3906 | |
| 3907 | It is easy to get confused when referencing stack frames. @value{GDBN} |
| 3908 | uses some precise terminology. |
| 3909 | |
| 3910 | @itemize @bullet |
| 3911 | |
| 3912 | @item |
| 3913 | @cindex THIS frame |
| 3914 | @cindex stack frame, definition of THIS frame |
| 3915 | @cindex frame, definition of THIS frame |
| 3916 | @dfn{THIS} frame is the frame currently under consideration. |
| 3917 | |
| 3918 | @item |
| 3919 | @cindex NEXT frame |
| 3920 | @cindex stack frame, definition of NEXT frame |
| 3921 | @cindex frame, definition of NEXT frame |
| 3922 | The @dfn{NEXT} frame, also sometimes called the inner or newer frame is the |
| 3923 | frame of the function called by the function of THIS frame. |
| 3924 | |
| 3925 | @item |
| 3926 | @cindex PREVIOUS frame |
| 3927 | @cindex stack frame, definition of PREVIOUS frame |
| 3928 | @cindex frame, definition of PREVIOUS frame |
| 3929 | The @dfn{PREVIOUS} frame, also sometimes called the outer or older frame is |
| 3930 | the frame of the function which called the function of THIS frame. |
| 3931 | |
| 3932 | @end itemize |
| 3933 | |
| 3934 | So in the example in the previous section (@pxref{All About Stack |
| 3935 | Frames, , All About Stack Frames}), if THIS frame is #3 (the call to |
| 3936 | @code{fact@w{ }(3)}), the NEXT frame is frame #2 (the call to |
| 3937 | @code{fact@w{ }(2)}) and the PREVIOUS frame is frame #4 (the call to |
| 3938 | @code{main@w{ }()}). |
| 3939 | |
| 3940 | @cindex innermost frame |
| 3941 | @cindex stack frame, definition of innermost frame |
| 3942 | @cindex frame, definition of innermost frame |
| 3943 | The @dfn{innermost} frame is the frame of the current executing |
| 3944 | function, or where the program stopped, in this example, in the middle |
| 3945 | of the call to @code{@w{fact (0))}}. It is always numbered frame #0. |
| 3946 | |
| 3947 | @cindex base of a frame |
| 3948 | @cindex stack frame, definition of base of a frame |
| 3949 | @cindex frame, definition of base of a frame |
| 3950 | The @dfn{base} of a frame is the address immediately before the start |
| 3951 | of the NEXT frame. For a stack which grows down in memory (a |
| 3952 | @dfn{falling} stack) this will be the lowest address and for a stack |
| 3953 | which grows up in memory (a @dfn{rising} stack) this will be the |
| 3954 | highest address in the frame. |
| 3955 | |
| 3956 | @value{GDBN} functions to analyze the stack are typically given a |
| 3957 | pointer to the NEXT frame to determine information about THIS |
| 3958 | frame. Information about THIS frame includes data on where the |
| 3959 | registers of the PREVIOUS frame are stored in this stack frame. In |
| 3960 | this example the frame pointer of the PREVIOUS frame is stored at |
| 3961 | offset 0 from the stack pointer of THIS frame. |
| 3962 | |
| 3963 | @cindex unwinding |
| 3964 | @cindex stack frame, definition of unwinding |
| 3965 | @cindex frame, definition of unwinding |
| 3966 | The process whereby a function is given a pointer to the NEXT |
| 3967 | frame to work out information about THIS frame is referred to as |
| 3968 | @dfn{unwinding}. The @value{GDBN} functions involved in this typically |
| 3969 | include unwind in their name. |
| 3970 | |
| 3971 | @cindex sniffing |
| 3972 | @cindex stack frame, definition of sniffing |
| 3973 | @cindex frame, definition of sniffing |
| 3974 | The process of analyzing a target to determine the information that |
| 3975 | should go in struct frame_info is called @dfn{sniffing}. The functions |
| 3976 | that carry this out are called sniffers and typically include sniffer |
| 3977 | in their name. More than one sniffer may be required to extract all |
| 3978 | the information for a particular frame. |
| 3979 | |
| 3980 | @cindex sentinel frame |
| 3981 | @cindex stack frame, definition of sentinel frame |
| 3982 | @cindex frame, definition of sentinel frame |
| 3983 | Because so many functions work using the NEXT frame, there is an issue |
| 3984 | about addressing the innermost frame---it has no NEXT frame. To solve |
| 3985 | this @value{GDBN} creates a dummy frame #-1, known as the |
| 3986 | @dfn{sentinel} frame. |
| 3987 | |
| 3988 | @node Prologue Caches |
| 3989 | @subsection Prologue Caches |
| 3990 | |
| 3991 | @cindex function prologue |
| 3992 | @cindex prologue of a function |
| 3993 | All the frame sniffing functions typically examine the code at the |
| 3994 | start of the corresponding function, to determine the state of |
| 3995 | registers. The ABI will save old values and set new values of key |
| 3996 | registers at the start of each function in what is known as the |
| 3997 | function @dfn{prologue}. |
| 3998 | |
| 3999 | @cindex prologue cache |
| 4000 | For any particular stack frame this data does not change, so all the |
| 4001 | standard unwinding functions, in addition to receiving a pointer to |
| 4002 | the NEXT frame as their first argument, receive a pointer to a |
| 4003 | @dfn{prologue cache} as their second argument. This can be used to store |
| 4004 | values associated with a particular frame, for reuse on subsequent |
| 4005 | calls involving the same frame. |
| 4006 | |
| 4007 | It is up to the user to define the structure used (it is a |
| 4008 | @code{void@w{ }*} pointer) and arrange allocation and deallocation of |
| 4009 | storage. However for general use, @value{GDBN} provides |
| 4010 | @code{@w{struct trad_frame_cache}}, with a set of accessor |
| 4011 | routines. This structure holds the stack and code address of |
| 4012 | THIS frame, the base address of the frame, a pointer to the |
| 4013 | struct @code{frame_info} for the NEXT frame and details of |
| 4014 | where the registers of the PREVIOUS frame may be found in THIS |
| 4015 | frame. |
| 4016 | |
| 4017 | Typically the first time any sniffer function is called with NEXT |
| 4018 | frame, the prologue sniffer for THIS frame will be @code{NULL}. The |
| 4019 | sniffer will analyze the frame, allocate a prologue cache structure |
| 4020 | and populate it. Subsequent calls using the same NEXT frame will |
| 4021 | pass in this prologue cache, so the data can be returned with no |
| 4022 | additional analysis. |
| 4023 | |
| 4024 | @node Functions and Variable to Analyze Frames |
| 4025 | @subsection Functions and Variable to Analyze Frames |
| 4026 | |
| 4027 | These struct @code{gdbarch} functions and variable should be defined |
| 4028 | to provide analysis of the stack frame and allow it to be adjusted as |
| 4029 | required. |
| 4030 | |
| 4031 | @deftypefn {Architecture Function} CORE_ADDR skip_prologue (struct gdbarch *@var{gdbarch}, CORE_ADDR @var{pc}) |
| 4032 | |
| 4033 | The prologue of a function is the code at the beginning of the |
| 4034 | function which sets up the stack frame, saves the return address |
| 4035 | etc. The code representing the behavior of the function starts after |
| 4036 | the prologue. |
| 4037 | |
| 4038 | This function skips past the prologue of a function if the program |
| 4039 | counter, @var{pc}, is within the prologue of a function. The result is |
| 4040 | the program counter immediately after the prologue. With modern |
| 4041 | optimizing compilers, this may be a far from trivial exercise. However |
| 4042 | the required information may be within the binary as DWARF2 debugging |
| 4043 | information, making the job much easier. |
| 4044 | |
| 4045 | The default value is @code{NULL} (not defined). This function should always |
| 4046 | be provided, but can take advantage of DWARF2 debugging information, |
| 4047 | if that is available. |
| 4048 | |
| 4049 | @end deftypefn |
| 4050 | |
| 4051 | @deftypefn {Architecture Function} int inner_than (CORE_ADDR @var{lhs}, CORE_ADDR @var{rhs}) |
| 4052 | @findex core_addr_lessthan |
| 4053 | @findex core_addr_greaterthan |
| 4054 | |
| 4055 | Given two frame or stack pointers, return non-zero (true) if the first |
| 4056 | represents the @dfn{inner} stack frame and 0 (false) otherwise. This |
| 4057 | is used to determine whether the target has a stack which grows up in |
| 4058 | memory (rising stack) or grows down in memory (falling stack). |
| 4059 | @xref{All About Stack Frames, , All About Stack Frames}, for an |
| 4060 | explanation of @dfn{inner} frames. |
| 4061 | |
| 4062 | The default value of this function is @code{NULL} and it should always |
| 4063 | be defined. However for almost all architectures one of the built-in |
| 4064 | functions can be used: @code{core_addr_lessthan} (for stacks growing |
| 4065 | down in memory) or @code{core_addr_greaterthan} (for stacks growing up |
| 4066 | in memory). |
| 4067 | |
| 4068 | @end deftypefn |
| 4069 | |
| 4070 | @anchor{frame_align} |
| 4071 | @deftypefn {Architecture Function} CORE_ADDR frame_align (struct gdbarch *@var{gdbarch}, CORE_ADDR @var{address}) |
| 4072 | @findex align_down |
| 4073 | @findex align_up |
| 4074 | |
| 4075 | The architecture may have constraints on how its frames are |
| 4076 | aligned. For example the OpenRISC 1000 ABI requires stack frames to be |
| 4077 | double-word aligned, but 32-bit versions of the architecture allocate |
| 4078 | single-word values to the stack. Thus extra padding may be needed at |
| 4079 | the end of a stack frame. |
| 4080 | |
| 4081 | Given a proposed address for the stack pointer, this function |
| 4082 | returns a suitably aligned address (by expanding the stack frame). |
| 4083 | |
| 4084 | The default value is @code{NULL} (undefined). This function should be defined |
| 4085 | for any architecture where it is possible the stack could become |
| 4086 | misaligned. The utility functions @code{align_down} (for falling |
| 4087 | stacks) and @code{align_up} (for rising stacks) will facilitate the |
| 4088 | implementation of this function. |
| 4089 | |
| 4090 | @end deftypefn |
| 4091 | |
| 4092 | @deftypevr {Architecture Variable} int frame_red_zone_size |
| 4093 | |
| 4094 | Some ABIs reserve space beyond the end of the stack for use by leaf |
| 4095 | functions without prologue or epilogue or by exception handlers (for |
| 4096 | example the OpenRISC 1000). |
| 4097 | |
| 4098 | This is known as a @dfn{red zone} (AMD terminology). The @sc{amd64} |
| 4099 | (nee x86-64) ABI documentation refers to the @dfn{red zone} when |
| 4100 | describing this scratch area. |
| 4101 | |
| 4102 | The default value is 0. Set this field if the architecture has such a |
| 4103 | red zone. The value must be aligned as required by the ABI (see |
| 4104 | @code{frame_align} above for an explanation of stack frame alignment). |
| 4105 | |
| 4106 | @end deftypevr |
| 4107 | |
| 4108 | @node Functions to Access Frame Data |
| 4109 | @subsection Functions to Access Frame Data |
| 4110 | |
| 4111 | These functions provide access to key registers and arguments in the |
| 4112 | stack frame. |
| 4113 | |
| 4114 | @deftypefn {Architecture Function} CORE_ADDR unwind_pc (struct gdbarch *@var{gdbarch}, struct frame_info *@var{next_frame}) |
| 4115 | |
| 4116 | This function is given a pointer to the NEXT stack frame (@pxref{All |
| 4117 | About Stack Frames, , All About Stack Frames}, for how frames are |
| 4118 | represented) and returns the value of the program counter in the |
| 4119 | PREVIOUS frame (i.e.@: the frame of the function that called THIS |
| 4120 | one). This is commonly referred to as the @dfn{return address}. |
| 4121 | |
| 4122 | The implementation, which must be frame agnostic (work with any frame), |
| 4123 | is typically no more than: |
| 4124 | |
| 4125 | @smallexample |
| 4126 | ULONGEST pc; |
| 4127 | pc = frame_unwind_register_unsigned (next_frame, @var{ARCH}_PC_REGNUM); |
| 4128 | return gdbarch_addr_bits_remove (gdbarch, pc); |
| 4129 | @end smallexample |
| 4130 | |
| 4131 | @end deftypefn |
| 4132 | |
| 4133 | @deftypefn {Architecture Function} CORE_ADDR unwind_sp (struct gdbarch *@var{gdbarch}, struct frame_info *@var{next_frame}) |
| 4134 | |
| 4135 | This function is given a pointer to the NEXT stack frame |
| 4136 | (@pxref{All About Stack Frames, , All About Stack Frames} for how |
| 4137 | frames are represented) and returns the value of the stack pointer in |
| 4138 | the PREVIOUS frame (i.e.@: the frame of the function that called |
| 4139 | THIS one). |
| 4140 | |
| 4141 | The implementation, which must be frame agnostic (work with any frame), |
| 4142 | is typically no more than: |
| 4143 | |
| 4144 | @smallexample |
| 4145 | ULONGEST sp; |
| 4146 | sp = frame_unwind_register_unsigned (next_frame, @var{ARCH}_SP_REGNUM); |
| 4147 | return gdbarch_addr_bits_remove (gdbarch, sp); |
| 4148 | @end smallexample |
| 4149 | |
| 4150 | @end deftypefn |
| 4151 | |
| 4152 | @deftypefn {Architecture Function} int frame_num_args (struct gdbarch *@var{gdbarch}, struct frame_info *@var{this_frame}) |
| 4153 | |
| 4154 | This function is given a pointer to THIS stack frame (@pxref{All |
| 4155 | About Stack Frames, , All About Stack Frames} for how frames are |
| 4156 | represented), and returns the number of arguments that are being |
| 4157 | passed, or -1 if not known. |
| 4158 | |
| 4159 | The default value is @code{NULL} (undefined), in which case the number of |
| 4160 | arguments passed on any stack frame is always unknown. For many |
| 4161 | architectures this will be a suitable default. |
| 4162 | |
| 4163 | @end deftypefn |
| 4164 | |
| 4165 | @node Analyzing Stacks---Frame Sniffers |
| 4166 | @subsection Analyzing Stacks---Frame Sniffers |
| 4167 | |
| 4168 | When a program stops, @value{GDBN} needs to construct the chain of |
| 4169 | struct @code{frame_info} representing the state of the stack using |
| 4170 | appropriate @dfn{sniffers}. |
| 4171 | |
| 4172 | Each architecture requires appropriate sniffers, but they do not form |
| 4173 | entries in @code{@w{struct gdbarch}}, since more than one sniffer may |
| 4174 | be required and a sniffer may be suitable for more than one |
| 4175 | @code{@w{struct gdbarch}}. Instead sniffers are associated with |
| 4176 | architectures using the following functions. |
| 4177 | |
| 4178 | @itemize @bullet |
| 4179 | |
| 4180 | @item |
| 4181 | @findex frame_unwind_append_sniffer |
| 4182 | @code{frame_unwind_append_sniffer} is used to add a new sniffer to |
| 4183 | analyze THIS frame when given a pointer to the NEXT frame. |
| 4184 | |
| 4185 | @item |
| 4186 | @findex frame_base_append_sniffer |
| 4187 | @code{frame_base_append_sniffer} is used to add a new sniffer |
| 4188 | which can determine information about the base of a stack frame. |
| 4189 | |
| 4190 | @item |
| 4191 | @findex frame_base_set_default |
| 4192 | @code{frame_base_set_default} is used to specify the default base |
| 4193 | sniffer. |
| 4194 | |
| 4195 | @end itemize |
| 4196 | |
| 4197 | These functions all take a reference to @code{@w{struct gdbarch}}, so |
| 4198 | they are associated with a specific architecture. They are usually |
| 4199 | called in the @code{gdbarch} initialization function, after the |
| 4200 | @code{gdbarch} struct has been set up. Unless a default has been set, the |
| 4201 | most recently appended sniffer will be tried first. |
| 4202 | |
| 4203 | The main frame unwinding sniffer (as set by |
| 4204 | @code{frame_unwind_append_sniffer)} returns a structure specifying |
| 4205 | a set of sniffing functions: |
| 4206 | |
| 4207 | @cindex @code{frame_unwind} |
| 4208 | @smallexample |
| 4209 | struct frame_unwind |
| 4210 | @{ |
| 4211 | enum frame_type type; |
| 4212 | frame_this_id_ftype *this_id; |
| 4213 | frame_prev_register_ftype *prev_register; |
| 4214 | const struct frame_data *unwind_data; |
| 4215 | frame_sniffer_ftype *sniffer; |
| 4216 | frame_prev_pc_ftype *prev_pc; |
| 4217 | frame_dealloc_cache_ftype *dealloc_cache; |
| 4218 | @}; |
| 4219 | @end smallexample |
| 4220 | |
| 4221 | The @code{type} field indicates the type of frame this sniffer can |
| 4222 | handle: normal, dummy (@pxref{Functions Creating Dummy Frames, , |
| 4223 | Functions Creating Dummy Frames}), signal handler or sentinel. Signal |
| 4224 | handlers sometimes have their own simplified stack structure for |
| 4225 | efficiency, so may need their own handlers. |
| 4226 | |
| 4227 | The @code{unwind_data} field holds additional information which may be |
| 4228 | relevant to particular types of frame. For example it may hold |
| 4229 | additional information for signal handler frames. |
| 4230 | |
| 4231 | The remaining fields define functions that yield different types of |
| 4232 | information when given a pointer to the NEXT stack frame. Not all |
| 4233 | functions need be provided. If an entry is @code{NULL}, the next sniffer will |
| 4234 | be tried instead. |
| 4235 | |
| 4236 | @itemize @bullet |
| 4237 | |
| 4238 | @item |
| 4239 | @code{this_id} determines the stack pointer and function (code |
| 4240 | entry point) for THIS stack frame. |
| 4241 | |
| 4242 | @item |
| 4243 | @code{prev_register} determines where the values of registers for |
| 4244 | the PREVIOUS stack frame are stored in THIS stack frame. |
| 4245 | |
| 4246 | @item |
| 4247 | @code{sniffer} takes a look at THIS frame's registers to |
| 4248 | determine if this is the appropriate unwinder. |
| 4249 | |
| 4250 | @item |
| 4251 | @code{prev_pc} determines the program counter for THIS |
| 4252 | frame. Only needed if the program counter is not an ordinary register |
| 4253 | (@pxref{Register Architecture Functions & Variables, |
| 4254 | , Functions and Variables Specifying the Register Architecture}). |
| 4255 | |
| 4256 | @item |
| 4257 | @code{dealloc_cache} frees any additional memory associated with |
| 4258 | the prologue cache for this frame (@pxref{Prologue Caches, , Prologue |
| 4259 | Caches}). |
| 4260 | |
| 4261 | @end itemize |
| 4262 | |
| 4263 | In general it is only the @code{this_id} and @code{prev_register} |
| 4264 | fields that need be defined for custom sniffers. |
| 4265 | |
| 4266 | The frame base sniffer is much simpler. It is a @code{@w{struct |
| 4267 | frame_base}}, which refers to the corresponding @code{frame_unwind} |
| 4268 | struct and whose fields refer to functions yielding various addresses |
| 4269 | within the frame. |
| 4270 | |
| 4271 | @cindex @code{frame_base} |
| 4272 | @smallexample |
| 4273 | struct frame_base |
| 4274 | @{ |
| 4275 | const struct frame_unwind *unwind; |
| 4276 | frame_this_base_ftype *this_base; |
| 4277 | frame_this_locals_ftype *this_locals; |
| 4278 | frame_this_args_ftype *this_args; |
| 4279 | @}; |
| 4280 | @end smallexample |
| 4281 | |
| 4282 | All the functions referred to take a pointer to the NEXT frame as |
| 4283 | argument. The function referred to by @code{this_base} returns the |
| 4284 | base address of THIS frame, the function referred to by |
| 4285 | @code{this_locals} returns the base address of local variables in THIS |
| 4286 | frame and the function referred to by @code{this_args} returns the |
| 4287 | base address of the function arguments in this frame. |
| 4288 | |
| 4289 | As described above, the base address of a frame is the address |
| 4290 | immediately before the start of the NEXT frame. For a falling |
| 4291 | stack, this is the lowest address in the frame and for a rising stack |
| 4292 | it is the highest address in the frame. For most architectures the |
| 4293 | same address is also the base address for local variables and |
| 4294 | arguments, in which case the same function can be used for all three |
| 4295 | entries@footnote{It is worth noting that if it cannot be determined in any |
| 4296 | other way (for example by there being a register with the name |
| 4297 | @code{"fp"}), then the result of the @code{this_base} function will be |
| 4298 | used as the value of the frame pointer variable @kbd{$fp} in |
| 4299 | @value{GDBN}. This is very often not correct (for example with the |
| 4300 | OpenRISC 1000, this value is the stack pointer, @kbd{$sp}). In this |
| 4301 | case a register (raw or pseudo) with the name @code{"fp"} should be |
| 4302 | defined. It will be used in preference as the value of @kbd{$fp}.}. |
| 4303 | |
| 4304 | @node Inferior Call Setup |
| 4305 | @section Inferior Call Setup |
| 4306 | @cindex calls to the inferior |
| 4307 | |
| 4308 | @menu |
| 4309 | * About Dummy Frames:: |
| 4310 | * Functions Creating Dummy Frames:: |
| 4311 | @end menu |
| 4312 | |
| 4313 | @node About Dummy Frames |
| 4314 | @subsection About Dummy Frames |
| 4315 | @cindex dummy frames |
| 4316 | |
| 4317 | @value{GDBN} can call functions in the target code (for example by |
| 4318 | using the @kbd{call} or @kbd{print} commands). These functions may be |
| 4319 | breakpointed, and it is essential that if a function does hit a |
| 4320 | breakpoint, commands like @kbd{backtrace} work correctly. |
| 4321 | |
| 4322 | This is achieved by making the stack look as though the function had |
| 4323 | been called from the point where @value{GDBN} had previously stopped. |
| 4324 | This requires that @value{GDBN} can set up stack frames appropriate for |
| 4325 | such function calls. |
| 4326 | |
| 4327 | @node Functions Creating Dummy Frames |
| 4328 | @subsection Functions Creating Dummy Frames |
| 4329 | |
| 4330 | The following functions provide the functionality to set up such |
| 4331 | @dfn{dummy} stack frames. |
| 4332 | |
| 4333 | @deftypefn {Architecture Function} CORE_ADDR push_dummy_call (struct gdbarch *@var{gdbarch}, struct value *@var{function}, struct regcache *@var{regcache}, CORE_ADDR @var{bp_addr}, int @var{nargs}, struct value **@var{args}, CORE_ADDR @var{sp}, int @var{struct_return}, CORE_ADDR @var{struct_addr}) |
| 4334 | |
| 4335 | This function sets up a dummy stack frame for the function about to be |
| 4336 | called. @code{push_dummy_call} is given the arguments to be passed |
| 4337 | and must copy them into registers or push them on to the stack as |
| 4338 | appropriate for the ABI. |
| 4339 | |
| 4340 | @var{function} is a pointer to the function |
| 4341 | that will be called and @var{regcache} the register cache from which |
| 4342 | values should be obtained. @var{bp_addr} is the address to which the |
| 4343 | function should return (which is breakpointed, so @value{GDBN} can |
| 4344 | regain control, hence the name). @var{nargs} is the number of |
| 4345 | arguments to pass and @var{args} an array containing the argument |
| 4346 | values. @var{struct_return} is non-zero (true) if the function returns |
| 4347 | a structure, and if so @var{struct_addr} is the address in which the |
| 4348 | structure should be returned. |
| 4349 | |
| 4350 | After calling this function, @value{GDBN} will pass control to the |
| 4351 | target at the address of the function, which will find the stack and |
| 4352 | registers set up just as expected. |
| 4353 | |
| 4354 | The default value of this function is @code{NULL} (undefined). If the |
| 4355 | function is not defined, then @value{GDBN} will not allow the user to |
| 4356 | call functions within the target being debugged. |
| 4357 | |
| 4358 | @end deftypefn |
| 4359 | |
| 4360 | @deftypefn {Architecture Function} {struct frame_id} unwind_dummy_id (struct gdbarch *@var{gdbarch}, struct frame_info *@var{next_frame}) |
| 4361 | |
| 4362 | This is the inverse of @code{push_dummy_call} which restores the stack |
| 4363 | pointer and program counter after a call to evaluate a function using |
| 4364 | a dummy stack frame. The result is a @code{@w{struct frame_id}}, which |
| 4365 | contains the value of the stack pointer and program counter to be |
| 4366 | used. |
| 4367 | |
| 4368 | The NEXT frame pointer is provided as argument, |
| 4369 | @var{next_frame}. THIS frame is the frame of the dummy function, |
| 4370 | which can be unwound, to yield the required stack pointer and program |
| 4371 | counter from the PREVIOUS frame. |
| 4372 | |
| 4373 | The default value is @code{NULL} (undefined). If @code{push_dummy_call} is |
| 4374 | defined, then this function should also be defined. |
| 4375 | |
| 4376 | @end deftypefn |
| 4377 | |
| 4378 | @deftypefn {Architecture Function} CORE_ADDR push_dummy_code (struct gdbarch *@var{gdbarch}, CORE_ADDR @var{sp}, CORE_ADDR @var{funaddr}, struct value **@var{args}, int @var{nargs}, struct type *@var{value_type}, CORE_ADDR *@var{real_pc}, CORE_ADDR *@var{bp_addr}, struct regcache *@var{regcache}) |
| 4379 | |
| 4380 | If this function is not defined (its default value is @code{NULL}), a dummy |
| 4381 | call will use the entry point of the currently loaded code on the |
| 4382 | target as its return address. A temporary breakpoint will be set |
| 4383 | there, so the location must be writable and have room for a |
| 4384 | breakpoint. |
| 4385 | |
| 4386 | It is possible that this default is not suitable. It might not be |
| 4387 | writable (in ROM possibly), or the ABI might require code to be |
| 4388 | executed on return from a call to unwind the stack before the |
| 4389 | breakpoint is encountered. |
| 4390 | |
| 4391 | If either of these is the case, then push_dummy_code should be defined |
| 4392 | to push an instruction sequence onto the end of the stack to which the |
| 4393 | dummy call should return. |
| 4394 | |
| 4395 | The arguments are essentially the same as those to |
| 4396 | @code{push_dummy_call}. However the function is provided with the |
| 4397 | type of the function result, @var{value_type}, @var{bp_addr} is used |
| 4398 | to return a value (the address at which the breakpoint instruction |
| 4399 | should be inserted) and @var{real pc} is used to specify the resume |
| 4400 | address when starting the call sequence. The function should return |
| 4401 | the updated innermost stack address. |
| 4402 | |
| 4403 | @quotation |
| 4404 | @emph{Note:} This does require that code in the stack can be executed. |
| 4405 | Some Harvard architectures may not allow this. |
| 4406 | @end quotation |
| 4407 | |
| 4408 | @end deftypefn |
| 4409 | |
| 4410 | @node Adding support for debugging core files |
| 4411 | @section Adding support for debugging core files |
| 4412 | @cindex core files |
| 4413 | |
| 4414 | The prerequisite for adding core file support in @value{GDBN} is to have |
| 4415 | core file support in BFD. |
| 4416 | |
| 4417 | Once BFD support is available, writing the apropriate |
| 4418 | @code{regset_from_core_section} architecture function should be all |
| 4419 | that is needed in order to add support for core files in @value{GDBN}. |
| 4420 | |
| 4421 | @node Defining Other Architecture Features |
| 4422 | @section Defining Other Architecture Features |
| 4423 | |
| 4424 | This section describes other functions and values in @code{gdbarch}, |
| 4425 | together with some useful macros, that you can use to define the |
| 4426 | target architecture. |
| 4427 | |
| 4428 | @table @code |
| 4429 | |
| 4430 | @item CORE_ADDR gdbarch_addr_bits_remove (@var{gdbarch}, @var{addr}) |
| 4431 | @findex gdbarch_addr_bits_remove |
| 4432 | If a raw machine instruction address includes any bits that are not |
| 4433 | really part of the address, then this function is used to zero those bits in |
| 4434 | @var{addr}. This is only used for addresses of instructions, and even then not |
| 4435 | in all contexts. |
| 4436 | |
| 4437 | For example, the two low-order bits of the PC on the Hewlett-Packard PA |
| 4438 | 2.0 architecture contain the privilege level of the corresponding |
| 4439 | instruction. Since instructions must always be aligned on four-byte |
| 4440 | boundaries, the processor masks out these bits to generate the actual |
| 4441 | address of the instruction. @code{gdbarch_addr_bits_remove} would then for |
| 4442 | example look like that: |
| 4443 | @smallexample |
| 4444 | arch_addr_bits_remove (CORE_ADDR addr) |
| 4445 | @{ |
| 4446 | return (addr &= ~0x3); |
| 4447 | @} |
| 4448 | @end smallexample |
| 4449 | |
| 4450 | @item int address_class_name_to_type_flags (@var{gdbarch}, @var{name}, @var{type_flags_ptr}) |
| 4451 | @findex address_class_name_to_type_flags |
| 4452 | If @var{name} is a valid address class qualifier name, set the @code{int} |
| 4453 | referenced by @var{type_flags_ptr} to the mask representing the qualifier |
| 4454 | and return 1. If @var{name} is not a valid address class qualifier name, |
| 4455 | return 0. |
| 4456 | |
| 4457 | The value for @var{type_flags_ptr} should be one of |
| 4458 | @code{TYPE_FLAG_ADDRESS_CLASS_1}, @code{TYPE_FLAG_ADDRESS_CLASS_2}, or |
| 4459 | possibly some combination of these values or'd together. |
| 4460 | @xref{Target Architecture Definition, , Address Classes}. |
| 4461 | |
| 4462 | @item int address_class_name_to_type_flags_p (@var{gdbarch}) |
| 4463 | @findex address_class_name_to_type_flags_p |
| 4464 | Predicate which indicates whether @code{address_class_name_to_type_flags} |
| 4465 | has been defined. |
| 4466 | |
| 4467 | @item int gdbarch_address_class_type_flags (@var{gdbarch}, @var{byte_size}, @var{dwarf2_addr_class}) |
| 4468 | @findex gdbarch_address_class_type_flags |
| 4469 | Given a pointers byte size (as described by the debug information) and |
| 4470 | the possible @code{DW_AT_address_class} value, return the type flags |
| 4471 | used by @value{GDBN} to represent this address class. The value |
| 4472 | returned should be one of @code{TYPE_FLAG_ADDRESS_CLASS_1}, |
| 4473 | @code{TYPE_FLAG_ADDRESS_CLASS_2}, or possibly some combination of these |
| 4474 | values or'd together. |
| 4475 | @xref{Target Architecture Definition, , Address Classes}. |
| 4476 | |
| 4477 | @item int gdbarch_address_class_type_flags_p (@var{gdbarch}) |
| 4478 | @findex gdbarch_address_class_type_flags_p |
| 4479 | Predicate which indicates whether @code{gdbarch_address_class_type_flags_p} has |
| 4480 | been defined. |
| 4481 | |
| 4482 | @item const char *gdbarch_address_class_type_flags_to_name (@var{gdbarch}, @var{type_flags}) |
| 4483 | @findex gdbarch_address_class_type_flags_to_name |
| 4484 | Return the name of the address class qualifier associated with the type |
| 4485 | flags given by @var{type_flags}. |
| 4486 | |
| 4487 | @item int gdbarch_address_class_type_flags_to_name_p (@var{gdbarch}) |
| 4488 | @findex gdbarch_address_class_type_flags_to_name_p |
| 4489 | Predicate which indicates whether @code{gdbarch_address_class_type_flags_to_name} has been defined. |
| 4490 | @xref{Target Architecture Definition, , Address Classes}. |
| 4491 | |
| 4492 | @item void gdbarch_address_to_pointer (@var{gdbarch}, @var{type}, @var{buf}, @var{addr}) |
| 4493 | @findex gdbarch_address_to_pointer |
| 4494 | Store in @var{buf} a pointer of type @var{type} representing the address |
| 4495 | @var{addr}, in the appropriate format for the current architecture. |
| 4496 | This function may safely assume that @var{type} is either a pointer or a |
| 4497 | C@t{++} reference type. |
| 4498 | @xref{Target Architecture Definition, , Pointers Are Not Always Addresses}. |
| 4499 | |
| 4500 | @item int gdbarch_believe_pcc_promotion (@var{gdbarch}) |
| 4501 | @findex gdbarch_believe_pcc_promotion |
| 4502 | Used to notify if the compiler promotes a @code{short} or @code{char} |
| 4503 | parameter to an @code{int}, but still reports the parameter as its |
| 4504 | original type, rather than the promoted type. |
| 4505 | |
| 4506 | @item gdbarch_bits_big_endian (@var{gdbarch}) |
| 4507 | @findex gdbarch_bits_big_endian |
| 4508 | This is used if the numbering of bits in the targets does @strong{not} match |
| 4509 | the endianism of the target byte order. A value of 1 means that the bits |
| 4510 | are numbered in a big-endian bit order, 0 means little-endian. |
| 4511 | |
| 4512 | @item set_gdbarch_bits_big_endian (@var{gdbarch}, @var{bits_big_endian}) |
| 4513 | @findex set_gdbarch_bits_big_endian |
| 4514 | Calling set_gdbarch_bits_big_endian with a value of 1 indicates that the |
| 4515 | bits in the target are numbered in a big-endian bit order, 0 indicates |
| 4516 | little-endian. |
| 4517 | |
| 4518 | @item BREAKPOINT |
| 4519 | @findex BREAKPOINT |
| 4520 | This is the character array initializer for the bit pattern to put into |
| 4521 | memory where a breakpoint is set. Although it's common to use a trap |
| 4522 | instruction for a breakpoint, it's not required; for instance, the bit |
| 4523 | pattern could be an invalid instruction. The breakpoint must be no |
| 4524 | longer than the shortest instruction of the architecture. |
| 4525 | |
| 4526 | @code{BREAKPOINT} has been deprecated in favor of |
| 4527 | @code{gdbarch_breakpoint_from_pc}. |
| 4528 | |
| 4529 | @item BIG_BREAKPOINT |
| 4530 | @itemx LITTLE_BREAKPOINT |
| 4531 | @findex LITTLE_BREAKPOINT |
| 4532 | @findex BIG_BREAKPOINT |
| 4533 | Similar to BREAKPOINT, but used for bi-endian targets. |
| 4534 | |
| 4535 | @code{BIG_BREAKPOINT} and @code{LITTLE_BREAKPOINT} have been deprecated in |
| 4536 | favor of @code{gdbarch_breakpoint_from_pc}. |
| 4537 | |
| 4538 | @item const gdb_byte *gdbarch_breakpoint_from_pc (@var{gdbarch}, @var{pcptr}, @var{lenptr}) |
| 4539 | @findex gdbarch_breakpoint_from_pc |
| 4540 | @anchor{gdbarch_breakpoint_from_pc} Use the program counter to determine the |
| 4541 | contents and size of a breakpoint instruction. It returns a pointer to |
| 4542 | a static string of bytes that encode a breakpoint instruction, stores the |
| 4543 | length of the string to @code{*@var{lenptr}}, and adjusts the program |
| 4544 | counter (if necessary) to point to the actual memory location where the |
| 4545 | breakpoint should be inserted. May return @code{NULL} to indicate that |
| 4546 | software breakpoints are not supported. |
| 4547 | |
| 4548 | Although it is common to use a trap instruction for a breakpoint, it's |
| 4549 | not required; for instance, the bit pattern could be an invalid |
| 4550 | instruction. The breakpoint must be no longer than the shortest |
| 4551 | instruction of the architecture. |
| 4552 | |
| 4553 | Provided breakpoint bytes can be also used by @code{bp_loc_is_permanent} to |
| 4554 | detect permanent breakpoints. @code{gdbarch_breakpoint_from_pc} should return |
| 4555 | an unchanged memory copy if it was called for a location with permanent |
| 4556 | breakpoint as some architectures use breakpoint instructions containing |
| 4557 | arbitrary parameter value. |
| 4558 | |
| 4559 | Replaces all the other @var{BREAKPOINT} macros. |
| 4560 | |
| 4561 | @item int gdbarch_memory_insert_breakpoint (@var{gdbarch}, @var{bp_tgt}) |
| 4562 | @itemx gdbarch_memory_remove_breakpoint (@var{gdbarch}, @var{bp_tgt}) |
| 4563 | @findex gdbarch_memory_remove_breakpoint |
| 4564 | @findex gdbarch_memory_insert_breakpoint |
| 4565 | Insert or remove memory based breakpoints. Reasonable defaults |
| 4566 | (@code{default_memory_insert_breakpoint} and |
| 4567 | @code{default_memory_remove_breakpoint} respectively) have been |
| 4568 | provided so that it is not necessary to set these for most |
| 4569 | architectures. Architectures which may want to set |
| 4570 | @code{gdbarch_memory_insert_breakpoint} and @code{gdbarch_memory_remove_breakpoint} will likely have instructions that are oddly sized or are not stored in a |
| 4571 | conventional manner. |
| 4572 | |
| 4573 | It may also be desirable (from an efficiency standpoint) to define |
| 4574 | custom breakpoint insertion and removal routines if |
| 4575 | @code{gdbarch_breakpoint_from_pc} needs to read the target's memory for some |
| 4576 | reason. |
| 4577 | |
| 4578 | @item CORE_ADDR gdbarch_adjust_breakpoint_address (@var{gdbarch}, @var{bpaddr}) |
| 4579 | @findex gdbarch_adjust_breakpoint_address |
| 4580 | @cindex breakpoint address adjusted |
| 4581 | Given an address at which a breakpoint is desired, return a breakpoint |
| 4582 | address adjusted to account for architectural constraints on |
| 4583 | breakpoint placement. This method is not needed by most targets. |
| 4584 | |
| 4585 | The FR-V target (see @file{frv-tdep.c}) requires this method. |
| 4586 | The FR-V is a VLIW architecture in which a number of RISC-like |
| 4587 | instructions are grouped (packed) together into an aggregate |
| 4588 | instruction or instruction bundle. When the processor executes |
| 4589 | one of these bundles, the component instructions are executed |
| 4590 | in parallel. |
| 4591 | |
| 4592 | In the course of optimization, the compiler may group instructions |
| 4593 | from distinct source statements into the same bundle. The line number |
| 4594 | information associated with one of the latter statements will likely |
| 4595 | refer to some instruction other than the first one in the bundle. So, |
| 4596 | if the user attempts to place a breakpoint on one of these latter |
| 4597 | statements, @value{GDBN} must be careful to @emph{not} place the break |
| 4598 | instruction on any instruction other than the first one in the bundle. |
| 4599 | (Remember though that the instructions within a bundle execute |
| 4600 | in parallel, so the @emph{first} instruction is the instruction |
| 4601 | at the lowest address and has nothing to do with execution order.) |
| 4602 | |
| 4603 | The FR-V's @code{gdbarch_adjust_breakpoint_address} method will adjust a |
| 4604 | breakpoint's address by scanning backwards for the beginning of |
| 4605 | the bundle, returning the address of the bundle. |
| 4606 | |
| 4607 | Since the adjustment of a breakpoint may significantly alter a user's |
| 4608 | expectation, @value{GDBN} prints a warning when an adjusted breakpoint |
| 4609 | is initially set and each time that that breakpoint is hit. |
| 4610 | |
| 4611 | @item int gdbarch_call_dummy_location (@var{gdbarch}) |
| 4612 | @findex gdbarch_call_dummy_location |
| 4613 | See the file @file{inferior.h}. |
| 4614 | |
| 4615 | This method has been replaced by @code{gdbarch_push_dummy_code} |
| 4616 | (@pxref{gdbarch_push_dummy_code}). |
| 4617 | |
| 4618 | @item int gdbarch_cannot_fetch_register (@var{gdbarch}, @var{regum}) |
| 4619 | @findex gdbarch_cannot_fetch_register |
| 4620 | This function should return nonzero if @var{regno} cannot be fetched |
| 4621 | from an inferior process. |
| 4622 | |
| 4623 | @item int gdbarch_cannot_store_register (@var{gdbarch}, @var{regnum}) |
| 4624 | @findex gdbarch_cannot_store_register |
| 4625 | This function should return nonzero if @var{regno} should not be |
| 4626 | written to the target. This is often the case for program counters, |
| 4627 | status words, and other special registers. This function returns 0 as |
| 4628 | default so that @value{GDBN} will assume that all registers may be written. |
| 4629 | |
| 4630 | @item int gdbarch_convert_register_p (@var{gdbarch}, @var{regnum}, struct type *@var{type}) |
| 4631 | @findex gdbarch_convert_register_p |
| 4632 | Return non-zero if register @var{regnum} represents data values of type |
| 4633 | @var{type} in a non-standard form. |
| 4634 | @xref{Target Architecture Definition, , Using Different Register and Memory Data Representations}. |
| 4635 | |
| 4636 | @item int gdbarch_fp0_regnum (@var{gdbarch}) |
| 4637 | @findex gdbarch_fp0_regnum |
| 4638 | This function returns the number of the first floating point register, |
| 4639 | if the machine has such registers. Otherwise, it returns -1. |
| 4640 | |
| 4641 | @item CORE_ADDR gdbarch_decr_pc_after_break (@var{gdbarch}) |
| 4642 | @findex gdbarch_decr_pc_after_break |
| 4643 | This function shall return the amount by which to decrement the PC after the |
| 4644 | program encounters a breakpoint. This is often the number of bytes in |
| 4645 | @code{BREAKPOINT}, though not always. For most targets this value will be 0. |
| 4646 | |
| 4647 | @item DISABLE_UNSETTABLE_BREAK (@var{addr}) |
| 4648 | @findex DISABLE_UNSETTABLE_BREAK |
| 4649 | If defined, this should evaluate to 1 if @var{addr} is in a shared |
| 4650 | library in which breakpoints cannot be set and so should be disabled. |
| 4651 | |
| 4652 | @item int gdbarch_dwarf2_reg_to_regnum (@var{gdbarch}, @var{dwarf2_regnr}) |
| 4653 | @findex gdbarch_dwarf2_reg_to_regnum |
| 4654 | Convert DWARF2 register number @var{dwarf2_regnr} into @value{GDBN} regnum. |
| 4655 | If not defined, no conversion will be performed. |
| 4656 | |
| 4657 | @item int gdbarch_ecoff_reg_to_regnum (@var{gdbarch}, @var{ecoff_regnr}) |
| 4658 | @findex gdbarch_ecoff_reg_to_regnum |
| 4659 | Convert ECOFF register number @var{ecoff_regnr} into @value{GDBN} regnum. If |
| 4660 | not defined, no conversion will be performed. |
| 4661 | |
| 4662 | @item GCC_COMPILED_FLAG_SYMBOL |
| 4663 | @itemx GCC2_COMPILED_FLAG_SYMBOL |
| 4664 | @findex GCC2_COMPILED_FLAG_SYMBOL |
| 4665 | @findex GCC_COMPILED_FLAG_SYMBOL |
| 4666 | If defined, these are the names of the symbols that @value{GDBN} will |
| 4667 | look for to detect that GCC compiled the file. The default symbols |
| 4668 | are @code{gcc_compiled.} and @code{gcc2_compiled.}, |
| 4669 | respectively. (Currently only defined for the Delta 68.) |
| 4670 | |
| 4671 | @item gdbarch_get_longjmp_target |
| 4672 | @findex gdbarch_get_longjmp_target |
| 4673 | This function determines the target PC address that @code{longjmp} |
| 4674 | will jump to, assuming that we have just stopped at a @code{longjmp} |
| 4675 | breakpoint. It takes a @code{CORE_ADDR *} as argument, and stores the |
| 4676 | target PC value through this pointer. It examines the current state |
| 4677 | of the machine as needed, typically by using a manually-determined |
| 4678 | offset into the @code{jmp_buf}. (While we might like to get the offset |
| 4679 | from the target's @file{jmpbuf.h}, that header file cannot be assumed |
| 4680 | to be available when building a cross-debugger.) |
| 4681 | |
| 4682 | @item DEPRECATED_IBM6000_TARGET |
| 4683 | @findex DEPRECATED_IBM6000_TARGET |
| 4684 | Shows that we are configured for an IBM RS/6000 system. This |
| 4685 | conditional should be eliminated (FIXME) and replaced by |
| 4686 | feature-specific macros. It was introduced in haste and we are |
| 4687 | repenting at leisure. |
| 4688 | |
| 4689 | @item I386_USE_GENERIC_WATCHPOINTS |
| 4690 | An x86-based target can define this to use the generic x86 watchpoint |
| 4691 | support; see @ref{Algorithms, I386_USE_GENERIC_WATCHPOINTS}. |
| 4692 | |
| 4693 | @item gdbarch_in_function_epilogue_p (@var{gdbarch}, @var{addr}) |
| 4694 | @findex gdbarch_in_function_epilogue_p |
| 4695 | Returns non-zero if the given @var{addr} is in the epilogue of a function. |
| 4696 | The epilogue of a function is defined as the part of a function where |
| 4697 | the stack frame of the function already has been destroyed up to the |
| 4698 | final `return from function call' instruction. |
| 4699 | |
| 4700 | @item int gdbarch_in_solib_return_trampoline (@var{gdbarch}, @var{pc}, @var{name}) |
| 4701 | @findex gdbarch_in_solib_return_trampoline |
| 4702 | Define this function to return nonzero if the program is stopped in the |
| 4703 | trampoline that returns from a shared library. |
| 4704 | |
| 4705 | @item target_so_ops.in_dynsym_resolve_code (@var{pc}) |
| 4706 | @findex in_dynsym_resolve_code |
| 4707 | Define this to return nonzero if the program is stopped in the |
| 4708 | dynamic linker. |
| 4709 | |
| 4710 | @item SKIP_SOLIB_RESOLVER (@var{pc}) |
| 4711 | @findex SKIP_SOLIB_RESOLVER |
| 4712 | Define this to evaluate to the (nonzero) address at which execution |
| 4713 | should continue to get past the dynamic linker's symbol resolution |
| 4714 | function. A zero value indicates that it is not important or necessary |
| 4715 | to set a breakpoint to get through the dynamic linker and that single |
| 4716 | stepping will suffice. |
| 4717 | |
| 4718 | @item CORE_ADDR gdbarch_integer_to_address (@var{gdbarch}, @var{type}, @var{buf}) |
| 4719 | @findex gdbarch_integer_to_address |
| 4720 | @cindex converting integers to addresses |
| 4721 | Define this when the architecture needs to handle non-pointer to address |
| 4722 | conversions specially. Converts that value to an address according to |
| 4723 | the current architectures conventions. |
| 4724 | |
| 4725 | @emph{Pragmatics: When the user copies a well defined expression from |
| 4726 | their source code and passes it, as a parameter, to @value{GDBN}'s |
| 4727 | @code{print} command, they should get the same value as would have been |
| 4728 | computed by the target program. Any deviation from this rule can cause |
| 4729 | major confusion and annoyance, and needs to be justified carefully. In |
| 4730 | other words, @value{GDBN} doesn't really have the freedom to do these |
| 4731 | conversions in clever and useful ways. It has, however, been pointed |
| 4732 | out that users aren't complaining about how @value{GDBN} casts integers |
| 4733 | to pointers; they are complaining that they can't take an address from a |
| 4734 | disassembly listing and give it to @code{x/i}. Adding an architecture |
| 4735 | method like @code{gdbarch_integer_to_address} certainly makes it possible for |
| 4736 | @value{GDBN} to ``get it right'' in all circumstances.} |
| 4737 | |
| 4738 | @xref{Target Architecture Definition, , Pointers Are Not Always |
| 4739 | Addresses}. |
| 4740 | |
| 4741 | @item CORE_ADDR gdbarch_pointer_to_address (@var{gdbarch}, @var{type}, @var{buf}) |
| 4742 | @findex gdbarch_pointer_to_address |
| 4743 | Assume that @var{buf} holds a pointer of type @var{type}, in the |
| 4744 | appropriate format for the current architecture. Return the byte |
| 4745 | address the pointer refers to. |
| 4746 | @xref{Target Architecture Definition, , Pointers Are Not Always Addresses}. |
| 4747 | |
| 4748 | @item void gdbarch_register_to_value(@var{gdbarch}, @var{frame}, @var{regnum}, @var{type}, @var{fur}) |
| 4749 | @findex gdbarch_register_to_value |
| 4750 | Convert the raw contents of register @var{regnum} into a value of type |
| 4751 | @var{type}. |
| 4752 | @xref{Target Architecture Definition, , Using Different Register and Memory Data Representations}. |
| 4753 | |
| 4754 | @item REGISTER_CONVERT_TO_VIRTUAL(@var{reg}, @var{type}, @var{from}, @var{to}) |
| 4755 | @findex REGISTER_CONVERT_TO_VIRTUAL |
| 4756 | Convert the value of register @var{reg} from its raw form to its virtual |
| 4757 | form. |
| 4758 | @xref{Target Architecture Definition, , Raw and Virtual Register Representations}. |
| 4759 | |
| 4760 | @item REGISTER_CONVERT_TO_RAW(@var{type}, @var{reg}, @var{from}, @var{to}) |
| 4761 | @findex REGISTER_CONVERT_TO_RAW |
| 4762 | Convert the value of register @var{reg} from its virtual form to its raw |
| 4763 | form. |
| 4764 | @xref{Target Architecture Definition, , Raw and Virtual Register Representations}. |
| 4765 | |
| 4766 | @item const struct regset *regset_from_core_section (struct gdbarch * @var{gdbarch}, const char * @var{sect_name}, size_t @var{sect_size}) |
| 4767 | @findex regset_from_core_section |
| 4768 | Return the appropriate register set for a core file section with name |
| 4769 | @var{sect_name} and size @var{sect_size}. |
| 4770 | |
| 4771 | @item SOFTWARE_SINGLE_STEP_P() |
| 4772 | @findex SOFTWARE_SINGLE_STEP_P |
| 4773 | Define this as 1 if the target does not have a hardware single-step |
| 4774 | mechanism. The macro @code{SOFTWARE_SINGLE_STEP} must also be defined. |
| 4775 | |
| 4776 | @item SOFTWARE_SINGLE_STEP(@var{signal}, @var{insert_breakpoints_p}) |
| 4777 | @findex SOFTWARE_SINGLE_STEP |
| 4778 | A function that inserts or removes (depending on |
| 4779 | @var{insert_breakpoints_p}) breakpoints at each possible destinations of |
| 4780 | the next instruction. See @file{sparc-tdep.c} and @file{rs6000-tdep.c} |
| 4781 | for examples. |
| 4782 | |
| 4783 | @item set_gdbarch_sofun_address_maybe_missing (@var{gdbarch}, @var{set}) |
| 4784 | @findex set_gdbarch_sofun_address_maybe_missing |
| 4785 | Somebody clever observed that, the more actual addresses you have in the |
| 4786 | debug information, the more time the linker has to spend relocating |
| 4787 | them. So whenever there's some other way the debugger could find the |
| 4788 | address it needs, you should omit it from the debug info, to make |
| 4789 | linking faster. |
| 4790 | |
| 4791 | Calling @code{set_gdbarch_sofun_address_maybe_missing} with a non-zero |
| 4792 | argument @var{set} indicates that a particular set of hacks of this sort |
| 4793 | are in use, affecting @code{N_SO} and @code{N_FUN} entries in stabs-format |
| 4794 | debugging information. @code{N_SO} stabs mark the beginning and ending |
| 4795 | addresses of compilation units in the text segment. @code{N_FUN} stabs |
| 4796 | mark the starts and ends of functions. |
| 4797 | |
| 4798 | In this case, @value{GDBN} assumes two things: |
| 4799 | |
| 4800 | @itemize @bullet |
| 4801 | @item |
| 4802 | @code{N_FUN} stabs have an address of zero. Instead of using those |
| 4803 | addresses, you should find the address where the function starts by |
| 4804 | taking the function name from the stab, and then looking that up in the |
| 4805 | minsyms (the linker/assembler symbol table). In other words, the stab |
| 4806 | has the name, and the linker/assembler symbol table is the only place |
| 4807 | that carries the address. |
| 4808 | |
| 4809 | @item |
| 4810 | @code{N_SO} stabs have an address of zero, too. You just look at the |
| 4811 | @code{N_FUN} stabs that appear before and after the @code{N_SO} stab, and |
| 4812 | guess the starting and ending addresses of the compilation unit from them. |
| 4813 | @end itemize |
| 4814 | |
| 4815 | @item int gdbarch_stabs_argument_has_addr (@var{gdbarch}, @var{type}) |
| 4816 | @findex gdbarch_stabs_argument_has_addr |
| 4817 | @anchor{gdbarch_stabs_argument_has_addr} Define this function to return |
| 4818 | nonzero if a function argument of type @var{type} is passed by reference |
| 4819 | instead of value. |
| 4820 | |
| 4821 | @item CORE_ADDR gdbarch_push_dummy_call (@var{gdbarch}, @var{function}, @var{regcache}, @var{bp_addr}, @var{nargs}, @var{args}, @var{sp}, @var{struct_return}, @var{struct_addr}) |
| 4822 | @findex gdbarch_push_dummy_call |
| 4823 | @anchor{gdbarch_push_dummy_call} Define this to push the dummy frame's call to |
| 4824 | the inferior function onto the stack. In addition to pushing @var{nargs}, the |
| 4825 | code should push @var{struct_addr} (when @var{struct_return} is non-zero), and |
| 4826 | the return address (@var{bp_addr}). |
| 4827 | |
| 4828 | @var{function} is a pointer to a @code{struct value}; on architectures that use |
| 4829 | function descriptors, this contains the function descriptor value. |
| 4830 | |
| 4831 | Returns the updated top-of-stack pointer. |
| 4832 | |
| 4833 | @item CORE_ADDR gdbarch_push_dummy_code (@var{gdbarch}, @var{sp}, @var{funaddr}, @var{using_gcc}, @var{args}, @var{nargs}, @var{value_type}, @var{real_pc}, @var{bp_addr}, @var{regcache}) |
| 4834 | @findex gdbarch_push_dummy_code |
| 4835 | @anchor{gdbarch_push_dummy_code} Given a stack based call dummy, push the |
| 4836 | instruction sequence (including space for a breakpoint) to which the |
| 4837 | called function should return. |
| 4838 | |
| 4839 | Set @var{bp_addr} to the address at which the breakpoint instruction |
| 4840 | should be inserted, @var{real_pc} to the resume address when starting |
| 4841 | the call sequence, and return the updated inner-most stack address. |
| 4842 | |
| 4843 | By default, the stack is grown sufficient to hold a frame-aligned |
| 4844 | (@pxref{frame_align}) breakpoint, @var{bp_addr} is set to the address |
| 4845 | reserved for that breakpoint, and @var{real_pc} set to @var{funaddr}. |
| 4846 | |
| 4847 | This method replaces @w{@code{gdbarch_call_dummy_location (@var{gdbarch})}}. |
| 4848 | |
| 4849 | @item int gdbarch_sdb_reg_to_regnum (@var{gdbarch}, @var{sdb_regnr}) |
| 4850 | @findex gdbarch_sdb_reg_to_regnum |
| 4851 | Use this function to convert sdb register @var{sdb_regnr} into @value{GDBN} |
| 4852 | regnum. If not defined, no conversion will be done. |
| 4853 | |
| 4854 | @item enum return_value_convention gdbarch_return_value (struct gdbarch *@var{gdbarch}, struct type *@var{valtype}, struct regcache *@var{regcache}, void *@var{readbuf}, const void *@var{writebuf}) |
| 4855 | @findex gdbarch_return_value |
| 4856 | @anchor{gdbarch_return_value} Given a function with a return-value of |
| 4857 | type @var{rettype}, return which return-value convention that function |
| 4858 | would use. |
| 4859 | |
| 4860 | @value{GDBN} currently recognizes two function return-value conventions: |
| 4861 | @code{RETURN_VALUE_REGISTER_CONVENTION} where the return value is found |
| 4862 | in registers; and @code{RETURN_VALUE_STRUCT_CONVENTION} where the return |
| 4863 | value is found in memory and the address of that memory location is |
| 4864 | passed in as the function's first parameter. |
| 4865 | |
| 4866 | If the register convention is being used, and @var{writebuf} is |
| 4867 | non-@code{NULL}, also copy the return-value in @var{writebuf} into |
| 4868 | @var{regcache}. |
| 4869 | |
| 4870 | If the register convention is being used, and @var{readbuf} is |
| 4871 | non-@code{NULL}, also copy the return value from @var{regcache} into |
| 4872 | @var{readbuf} (@var{regcache} contains a copy of the registers from the |
| 4873 | just returned function). |
| 4874 | |
| 4875 | @emph{Maintainer note: This method replaces separate predicate, extract, |
| 4876 | store methods. By having only one method, the logic needed to determine |
| 4877 | the return-value convention need only be implemented in one place. If |
| 4878 | @value{GDBN} were written in an @sc{oo} language, this method would |
| 4879 | instead return an object that knew how to perform the register |
| 4880 | return-value extract and store.} |
| 4881 | |
| 4882 | @emph{Maintainer note: This method does not take a @var{gcc_p} |
| 4883 | parameter, and such a parameter should not be added. If an architecture |
| 4884 | that requires per-compiler or per-function information be identified, |
| 4885 | then the replacement of @var{rettype} with @code{struct value} |
| 4886 | @var{function} should be pursued.} |
| 4887 | |
| 4888 | @emph{Maintainer note: The @var{regcache} parameter limits this methods |
| 4889 | to the inner most frame. While replacing @var{regcache} with a |
| 4890 | @code{struct frame_info} @var{frame} parameter would remove that |
| 4891 | limitation there has yet to be a demonstrated need for such a change.} |
| 4892 | |
| 4893 | @item void gdbarch_skip_permanent_breakpoint (@var{gdbarch}, @var{regcache}) |
| 4894 | @findex gdbarch_skip_permanent_breakpoint |
| 4895 | Advance the inferior's PC past a permanent breakpoint. @value{GDBN} normally |
| 4896 | steps over a breakpoint by removing it, stepping one instruction, and |
| 4897 | re-inserting the breakpoint. However, permanent breakpoints are |
| 4898 | hardwired into the inferior, and can't be removed, so this strategy |
| 4899 | doesn't work. Calling @code{gdbarch_skip_permanent_breakpoint} adjusts the |
| 4900 | processor's state so that execution will resume just after the breakpoint. |
| 4901 | This function does the right thing even when the breakpoint is in the delay slot |
| 4902 | of a branch or jump. |
| 4903 | |
| 4904 | @item CORE_ADDR gdbarch_skip_trampoline_code (@var{gdbarch}, @var{frame}, @var{pc}) |
| 4905 | @findex gdbarch_skip_trampoline_code |
| 4906 | If the target machine has trampoline code that sits between callers and |
| 4907 | the functions being called, then define this function to return a new PC |
| 4908 | that is at the start of the real function. |
| 4909 | |
| 4910 | @item int gdbarch_deprecated_fp_regnum (@var{gdbarch}) |
| 4911 | @findex gdbarch_deprecated_fp_regnum |
| 4912 | If the frame pointer is in a register, use this function to return the |
| 4913 | number of that register. |
| 4914 | |
| 4915 | @item int gdbarch_stab_reg_to_regnum (@var{gdbarch}, @var{stab_regnr}) |
| 4916 | @findex gdbarch_stab_reg_to_regnum |
| 4917 | Use this function to convert stab register @var{stab_regnr} into @value{GDBN} |
| 4918 | regnum. If not defined, no conversion will be done. |
| 4919 | |
| 4920 | @item SYMBOL_RELOADING_DEFAULT |
| 4921 | @findex SYMBOL_RELOADING_DEFAULT |
| 4922 | The default value of the ``symbol-reloading'' variable. (Never defined in |
| 4923 | current sources.) |
| 4924 | |
| 4925 | @item TARGET_CHAR_BIT |
| 4926 | @findex TARGET_CHAR_BIT |
| 4927 | Number of bits in a char; defaults to 8. |
| 4928 | |
| 4929 | @item int gdbarch_char_signed (@var{gdbarch}) |
| 4930 | @findex gdbarch_char_signed |
| 4931 | Non-zero if @code{char} is normally signed on this architecture; zero if |
| 4932 | it should be unsigned. |
| 4933 | |
| 4934 | The ISO C standard requires the compiler to treat @code{char} as |
| 4935 | equivalent to either @code{signed char} or @code{unsigned char}; any |
| 4936 | character in the standard execution set is supposed to be positive. |
| 4937 | Most compilers treat @code{char} as signed, but @code{char} is unsigned |
| 4938 | on the IBM S/390, RS6000, and PowerPC targets. |
| 4939 | |
| 4940 | @item int gdbarch_double_bit (@var{gdbarch}) |
| 4941 | @findex gdbarch_double_bit |
| 4942 | Number of bits in a double float; defaults to @w{@code{8 * TARGET_CHAR_BIT}}. |
| 4943 | |
| 4944 | @item int gdbarch_float_bit (@var{gdbarch}) |
| 4945 | @findex gdbarch_float_bit |
| 4946 | Number of bits in a float; defaults to @w{@code{4 * TARGET_CHAR_BIT}}. |
| 4947 | |
| 4948 | @item int gdbarch_int_bit (@var{gdbarch}) |
| 4949 | @findex gdbarch_int_bit |
| 4950 | Number of bits in an integer; defaults to @w{@code{4 * TARGET_CHAR_BIT}}. |
| 4951 | |
| 4952 | @item int gdbarch_long_bit (@var{gdbarch}) |
| 4953 | @findex gdbarch_long_bit |
| 4954 | Number of bits in a long integer; defaults to @w{@code{4 * TARGET_CHAR_BIT}}. |
| 4955 | |
| 4956 | @item int gdbarch_long_double_bit (@var{gdbarch}) |
| 4957 | @findex gdbarch_long_double_bit |
| 4958 | Number of bits in a long double float; |
| 4959 | defaults to @w{@code{2 * gdbarch_double_bit (@var{gdbarch})}}. |
| 4960 | |
| 4961 | @item int gdbarch_long_long_bit (@var{gdbarch}) |
| 4962 | @findex gdbarch_long_long_bit |
| 4963 | Number of bits in a long long integer; defaults to |
| 4964 | @w{@code{2 * gdbarch_long_bit (@var{gdbarch})}}. |
| 4965 | |
| 4966 | @item int gdbarch_ptr_bit (@var{gdbarch}) |
| 4967 | @findex gdbarch_ptr_bit |
| 4968 | Number of bits in a pointer; defaults to |
| 4969 | @w{@code{gdbarch_int_bit (@var{gdbarch})}}. |
| 4970 | |
| 4971 | @item int gdbarch_short_bit (@var{gdbarch}) |
| 4972 | @findex gdbarch_short_bit |
| 4973 | Number of bits in a short integer; defaults to @w{@code{2 * TARGET_CHAR_BIT}}. |
| 4974 | |
| 4975 | @item void gdbarch_virtual_frame_pointer (@var{gdbarch}, @var{pc}, @var{frame_regnum}, @var{frame_offset}) |
| 4976 | @findex gdbarch_virtual_frame_pointer |
| 4977 | Returns a @code{(@var{register}, @var{offset})} pair representing the virtual |
| 4978 | frame pointer in use at the code address @var{pc}. If virtual frame |
| 4979 | pointers are not used, a default definition simply returns |
| 4980 | @code{gdbarch_deprecated_fp_regnum} (or @code{gdbarch_sp_regnum}, if |
| 4981 | no frame pointer is defined), with an offset of zero. |
| 4982 | |
| 4983 | @c need to explain virtual frame pointers, they are recorded in agent |
| 4984 | @c expressions for tracepoints |
| 4985 | |
| 4986 | @item TARGET_HAS_HARDWARE_WATCHPOINTS |
| 4987 | If non-zero, the target has support for hardware-assisted |
| 4988 | watchpoints. @xref{Algorithms, watchpoints}, for more details and |
| 4989 | other related macros. |
| 4990 | |
| 4991 | @item int gdbarch_print_insn (@var{gdbarch}, @var{vma}, @var{info}) |
| 4992 | @findex gdbarch_print_insn |
| 4993 | This is the function used by @value{GDBN} to print an assembly |
| 4994 | instruction. It prints the instruction at address @var{vma} in |
| 4995 | debugged memory and returns the length of the instruction, in bytes. |
| 4996 | This usually points to a function in the @code{opcodes} library |
| 4997 | (@pxref{Support Libraries, ,Opcodes}). @var{info} is a structure (of |
| 4998 | type @code{disassemble_info}) defined in the header file |
| 4999 | @file{include/dis-asm.h}, and used to pass information to the |
| 5000 | instruction decoding routine. |
| 5001 | |
| 5002 | @item frame_id gdbarch_dummy_id (@var{gdbarch}, @var{frame}) |
| 5003 | @findex gdbarch_dummy_id |
| 5004 | @anchor{gdbarch_dummy_id} Given @var{frame} return a @w{@code{struct |
| 5005 | frame_id}} that uniquely identifies an inferior function call's dummy |
| 5006 | frame. The value returned must match the dummy frame stack value |
| 5007 | previously saved by @code{call_function_by_hand}. |
| 5008 | |
| 5009 | @item void gdbarch_value_to_register (@var{gdbarch}, @var{frame}, @var{type}, @var{buf}) |
| 5010 | @findex gdbarch_value_to_register |
| 5011 | Convert a value of type @var{type} into the raw contents of a register. |
| 5012 | @xref{Target Architecture Definition, , Using Different Register and Memory Data Representations}. |
| 5013 | |
| 5014 | @end table |
| 5015 | |
| 5016 | Motorola M68K target conditionals. |
| 5017 | |
| 5018 | @ftable @code |
| 5019 | @item BPT_VECTOR |
| 5020 | Define this to be the 4-bit location of the breakpoint trap vector. If |
| 5021 | not defined, it will default to @code{0xf}. |
| 5022 | |
| 5023 | @item REMOTE_BPT_VECTOR |
| 5024 | Defaults to @code{1}. |
| 5025 | |
| 5026 | @end ftable |
| 5027 | |
| 5028 | @node Adding a New Target |
| 5029 | @section Adding a New Target |
| 5030 | |
| 5031 | @cindex adding a target |
| 5032 | The following files add a target to @value{GDBN}: |
| 5033 | |
| 5034 | @table @file |
| 5035 | @cindex target dependent files |
| 5036 | |
| 5037 | @item gdb/@var{ttt}-tdep.c |
| 5038 | Contains any miscellaneous code required for this target machine. On |
| 5039 | some machines it doesn't exist at all. |
| 5040 | |
| 5041 | @item gdb/@var{arch}-tdep.c |
| 5042 | @itemx gdb/@var{arch}-tdep.h |
| 5043 | This is required to describe the basic layout of the target machine's |
| 5044 | processor chip (registers, stack, etc.). It can be shared among many |
| 5045 | targets that use the same processor architecture. |
| 5046 | |
| 5047 | @end table |
| 5048 | |
| 5049 | (Target header files such as |
| 5050 | @file{gdb/config/@var{arch}/tm-@var{ttt}.h}, |
| 5051 | @file{gdb/config/@var{arch}/tm-@var{arch}.h}, and |
| 5052 | @file{config/tm-@var{os}.h} are no longer used.) |
| 5053 | |
| 5054 | @findex _initialize_@var{arch}_tdep |
| 5055 | A @value{GDBN} description for a new architecture, arch is created by |
| 5056 | defining a global function @code{_initialize_@var{arch}_tdep}, by |
| 5057 | convention in the source file @file{@var{arch}-tdep.c}. For |
| 5058 | example, in the case of the OpenRISC 1000, this function is called |
| 5059 | @code{_initialize_or1k_tdep} and is found in the file |
| 5060 | @file{or1k-tdep.c}. |
| 5061 | |
| 5062 | The object file resulting from compiling this source file, which will |
| 5063 | contain the implementation of the |
| 5064 | @code{_initialize_@var{arch}_tdep} function is specified in the |
| 5065 | @value{GDBN} @file{configure.tgt} file, which includes a large case |
| 5066 | statement pattern matching against the @code{--target} option of the |
| 5067 | @kbd{configure} script. |
| 5068 | |
| 5069 | @quotation |
| 5070 | @emph{Note:} If the architecture requires multiple source files, the |
| 5071 | corresponding binaries should be included in |
| 5072 | @file{configure.tgt}. However if there are header files, the |
| 5073 | dependencies on these will not be picked up from the entries in |
| 5074 | @file{configure.tgt}. The @file{Makefile.in} file will need extending to |
| 5075 | show these dependencies. |
| 5076 | @end quotation |
| 5077 | |
| 5078 | @findex gdbarch_register |
| 5079 | A new struct gdbarch, defining the new architecture, is created within |
| 5080 | the @code{_initialize_@var{arch}_tdep} function by calling |
| 5081 | @code{gdbarch_register}: |
| 5082 | |
| 5083 | @smallexample |
| 5084 | void gdbarch_register (enum bfd_architecture architecture, |
| 5085 | gdbarch_init_ftype *init_func, |
| 5086 | gdbarch_dump_tdep_ftype *tdep_dump_func); |
| 5087 | @end smallexample |
| 5088 | |
| 5089 | This function has been described fully in an earlier |
| 5090 | section. @xref{How an Architecture is Represented, , How an |
| 5091 | Architecture is Represented}. |
| 5092 | |
| 5093 | The new @code{@w{struct gdbarch}} should contain implementations of |
| 5094 | the necessary functions (described in the previous sections) to |
| 5095 | describe the basic layout of the target machine's processor chip |
| 5096 | (registers, stack, etc.). It can be shared among many targets that use |
| 5097 | the same processor architecture. |
| 5098 | |
| 5099 | @node Target Descriptions |
| 5100 | @chapter Target Descriptions |
| 5101 | @cindex target descriptions |
| 5102 | |
| 5103 | The target architecture definition (@pxref{Target Architecture Definition}) |
| 5104 | contains @value{GDBN}'s hard-coded knowledge about an architecture. For |
| 5105 | some platforms, it is handy to have more flexible knowledge about a specific |
| 5106 | instance of the architecture---for instance, a processor or development board. |
| 5107 | @dfn{Target descriptions} provide a mechanism for the user to tell @value{GDBN} |
| 5108 | more about what their target supports, or for the target to tell @value{GDBN} |
| 5109 | directly. |
| 5110 | |
| 5111 | For details on writing, automatically supplying, and manually selecting |
| 5112 | target descriptions, see @ref{Target Descriptions, , , gdb, |
| 5113 | Debugging with @value{GDBN}}. This section will cover some related |
| 5114 | topics about the @value{GDBN} internals. |
| 5115 | |
| 5116 | @menu |
| 5117 | * Target Descriptions Implementation:: |
| 5118 | * Adding Target Described Register Support:: |
| 5119 | @end menu |
| 5120 | |
| 5121 | @node Target Descriptions Implementation |
| 5122 | @section Target Descriptions Implementation |
| 5123 | @cindex target descriptions, implementation |
| 5124 | |
| 5125 | Before @value{GDBN} connects to a new target, or runs a new program on |
| 5126 | an existing target, it discards any existing target description and |
| 5127 | reverts to a default gdbarch. Then, after connecting, it looks for a |
| 5128 | new target description by calling @code{target_find_description}. |
| 5129 | |
| 5130 | A description may come from a user specified file (XML), the remote |
| 5131 | @samp{qXfer:features:read} packet (also XML), or from any custom |
| 5132 | @code{to_read_description} routine in the target vector. For instance, |
| 5133 | the remote target supports guessing whether a MIPS target is 32-bit or |
| 5134 | 64-bit based on the size of the @samp{g} packet. |
| 5135 | |
| 5136 | If any target description is found, @value{GDBN} creates a new gdbarch |
| 5137 | incorporating the description by calling @code{gdbarch_update_p}. Any |
| 5138 | @samp{<architecture>} element is handled first, to determine which |
| 5139 | architecture's gdbarch initialization routine is called to create the |
| 5140 | new architecture. Then the initialization routine is called, and has |
| 5141 | a chance to adjust the constructed architecture based on the contents |
| 5142 | of the target description. For instance, it can recognize any |
| 5143 | properties set by a @code{to_read_description} routine. Also |
| 5144 | see @ref{Adding Target Described Register Support}. |
| 5145 | |
| 5146 | @node Adding Target Described Register Support |
| 5147 | @section Adding Target Described Register Support |
| 5148 | @cindex target descriptions, adding register support |
| 5149 | |
| 5150 | Target descriptions can report additional registers specific to an |
| 5151 | instance of the target. But it takes a little work in the architecture |
| 5152 | specific routines to support this. |
| 5153 | |
| 5154 | A target description must either have no registers or a complete |
| 5155 | set---this avoids complexity in trying to merge standard registers |
| 5156 | with the target defined registers. It is the architecture's |
| 5157 | responsibility to validate that a description with registers has |
| 5158 | everything it needs. To keep architecture code simple, the same |
| 5159 | mechanism is used to assign fixed internal register numbers to |
| 5160 | standard registers. |
| 5161 | |
| 5162 | If @code{tdesc_has_registers} returns 1, the description contains |
| 5163 | registers. The architecture's @code{gdbarch_init} routine should: |
| 5164 | |
| 5165 | @itemize @bullet |
| 5166 | |
| 5167 | @item |
| 5168 | Call @code{tdesc_data_alloc} to allocate storage, early, before |
| 5169 | searching for a matching gdbarch or allocating a new one. |
| 5170 | |
| 5171 | @item |
| 5172 | Use @code{tdesc_find_feature} to locate standard features by name. |
| 5173 | |
| 5174 | @item |
| 5175 | Use @code{tdesc_numbered_register} and @code{tdesc_numbered_register_choices} |
| 5176 | to locate the expected registers in the standard features. |
| 5177 | |
| 5178 | @item |
| 5179 | Return @code{NULL} if a required feature is missing, or if any standard |
| 5180 | feature is missing expected registers. This will produce a warning that |
| 5181 | the description was incomplete. |
| 5182 | |
| 5183 | @item |
| 5184 | Free the allocated data before returning, unless @code{tdesc_use_registers} |
| 5185 | is called. |
| 5186 | |
| 5187 | @item |
| 5188 | Call @code{set_gdbarch_num_regs} as usual, with a number higher than any |
| 5189 | fixed number passed to @code{tdesc_numbered_register}. |
| 5190 | |
| 5191 | @item |
| 5192 | Call @code{tdesc_use_registers} after creating a new gdbarch, before |
| 5193 | returning it. |
| 5194 | |
| 5195 | @end itemize |
| 5196 | |
| 5197 | After @code{tdesc_use_registers} has been called, the architecture's |
| 5198 | @code{register_name}, @code{register_type}, and @code{register_reggroup_p} |
| 5199 | routines will not be called; that information will be taken from |
| 5200 | the target description. @code{num_regs} may be increased to account |
| 5201 | for any additional registers in the description. |
| 5202 | |
| 5203 | Pseudo-registers require some extra care: |
| 5204 | |
| 5205 | @itemize @bullet |
| 5206 | |
| 5207 | @item |
| 5208 | Using @code{tdesc_numbered_register} allows the architecture to give |
| 5209 | constant register numbers to standard architectural registers, e.g.@: |
| 5210 | as an @code{enum} in @file{@var{arch}-tdep.h}. But because |
| 5211 | pseudo-registers are always numbered above @code{num_regs}, |
| 5212 | which may be increased by the description, constant numbers |
| 5213 | can not be used for pseudos. They must be numbered relative to |
| 5214 | @code{num_regs} instead. |
| 5215 | |
| 5216 | @item |
| 5217 | The description will not describe pseudo-registers, so the |
| 5218 | architecture must call @code{set_tdesc_pseudo_register_name}, |
| 5219 | @code{set_tdesc_pseudo_register_type}, and |
| 5220 | @code{set_tdesc_pseudo_register_reggroup_p} to supply routines |
| 5221 | describing pseudo registers. These routines will be passed |
| 5222 | internal register numbers, so the same routines used for the |
| 5223 | gdbarch equivalents are usually suitable. |
| 5224 | |
| 5225 | @end itemize |
| 5226 | |
| 5227 | |
| 5228 | @node Target Vector Definition |
| 5229 | |
| 5230 | @chapter Target Vector Definition |
| 5231 | @cindex target vector |
| 5232 | |
| 5233 | The target vector defines the interface between @value{GDBN}'s |
| 5234 | abstract handling of target systems, and the nitty-gritty code that |
| 5235 | actually exercises control over a process or a serial port. |
| 5236 | @value{GDBN} includes some 30-40 different target vectors; however, |
| 5237 | each configuration of @value{GDBN} includes only a few of them. |
| 5238 | |
| 5239 | @menu |
| 5240 | * Managing Execution State:: |
| 5241 | * Existing Targets:: |
| 5242 | @end menu |
| 5243 | |
| 5244 | @node Managing Execution State |
| 5245 | @section Managing Execution State |
| 5246 | @cindex execution state |
| 5247 | |
| 5248 | A target vector can be completely inactive (not pushed on the target |
| 5249 | stack), active but not running (pushed, but not connected to a fully |
| 5250 | manifested inferior), or completely active (pushed, with an accessible |
| 5251 | inferior). Most targets are only completely inactive or completely |
| 5252 | active, but some support persistent connections to a target even |
| 5253 | when the target has exited or not yet started. |
| 5254 | |
| 5255 | For example, connecting to the simulator using @code{target sim} does |
| 5256 | not create a running program. Neither registers nor memory are |
| 5257 | accessible until @code{run}. Similarly, after @code{kill}, the |
| 5258 | program can not continue executing. But in both cases @value{GDBN} |
| 5259 | remains connected to the simulator, and target-specific commands |
| 5260 | are directed to the simulator. |
| 5261 | |
| 5262 | A target which only supports complete activation should push itself |
| 5263 | onto the stack in its @code{to_open} routine (by calling |
| 5264 | @code{push_target}), and unpush itself from the stack in its |
| 5265 | @code{to_mourn_inferior} routine (by calling @code{unpush_target}). |
| 5266 | |
| 5267 | A target which supports both partial and complete activation should |
| 5268 | still call @code{push_target} in @code{to_open}, but not call |
| 5269 | @code{unpush_target} in @code{to_mourn_inferior}. Instead, it should |
| 5270 | call either @code{target_mark_running} or @code{target_mark_exited} |
| 5271 | in its @code{to_open}, depending on whether the target is fully active |
| 5272 | after connection. It should also call @code{target_mark_running} any |
| 5273 | time the inferior becomes fully active (e.g.@: in |
| 5274 | @code{to_create_inferior} and @code{to_attach}), and |
| 5275 | @code{target_mark_exited} when the inferior becomes inactive (in |
| 5276 | @code{to_mourn_inferior}). The target should also make sure to call |
| 5277 | @code{target_mourn_inferior} from its @code{to_kill}, to return the |
| 5278 | target to inactive state. |
| 5279 | |
| 5280 | @node Existing Targets |
| 5281 | @section Existing Targets |
| 5282 | @cindex targets |
| 5283 | |
| 5284 | @subsection File Targets |
| 5285 | |
| 5286 | Both executables and core files have target vectors. |
| 5287 | |
| 5288 | @subsection Standard Protocol and Remote Stubs |
| 5289 | |
| 5290 | @value{GDBN}'s file @file{remote.c} talks a serial protocol to code that |
| 5291 | runs in the target system. @value{GDBN} provides several sample |
| 5292 | @dfn{stubs} that can be integrated into target programs or operating |
| 5293 | systems for this purpose; they are named @file{@var{cpu}-stub.c}. Many |
| 5294 | operating systems, embedded targets, emulators, and simulators already |
| 5295 | have a @value{GDBN} stub built into them, and maintenance of the remote |
| 5296 | protocol must be careful to preserve compatibility. |
| 5297 | |
| 5298 | The @value{GDBN} user's manual describes how to put such a stub into |
| 5299 | your target code. What follows is a discussion of integrating the |
| 5300 | SPARC stub into a complicated operating system (rather than a simple |
| 5301 | program), by Stu Grossman, the author of this stub. |
| 5302 | |
| 5303 | The trap handling code in the stub assumes the following upon entry to |
| 5304 | @code{trap_low}: |
| 5305 | |
| 5306 | @enumerate |
| 5307 | @item |
| 5308 | %l1 and %l2 contain pc and npc respectively at the time of the trap; |
| 5309 | |
| 5310 | @item |
| 5311 | traps are disabled; |
| 5312 | |
| 5313 | @item |
| 5314 | you are in the correct trap window. |
| 5315 | @end enumerate |
| 5316 | |
| 5317 | As long as your trap handler can guarantee those conditions, then there |
| 5318 | is no reason why you shouldn't be able to ``share'' traps with the stub. |
| 5319 | The stub has no requirement that it be jumped to directly from the |
| 5320 | hardware trap vector. That is why it calls @code{exceptionHandler()}, |
| 5321 | which is provided by the external environment. For instance, this could |
| 5322 | set up the hardware traps to actually execute code which calls the stub |
| 5323 | first, and then transfers to its own trap handler. |
| 5324 | |
| 5325 | For the most point, there probably won't be much of an issue with |
| 5326 | ``sharing'' traps, as the traps we use are usually not used by the kernel, |
| 5327 | and often indicate unrecoverable error conditions. Anyway, this is all |
| 5328 | controlled by a table, and is trivial to modify. The most important |
| 5329 | trap for us is for @code{ta 1}. Without that, we can't single step or |
| 5330 | do breakpoints. Everything else is unnecessary for the proper operation |
| 5331 | of the debugger/stub. |
| 5332 | |
| 5333 | From reading the stub, it's probably not obvious how breakpoints work. |
| 5334 | They are simply done by deposit/examine operations from @value{GDBN}. |
| 5335 | |
| 5336 | @subsection ROM Monitor Interface |
| 5337 | |
| 5338 | @subsection Custom Protocols |
| 5339 | |
| 5340 | @subsection Transport Layer |
| 5341 | |
| 5342 | @subsection Builtin Simulator |
| 5343 | |
| 5344 | |
| 5345 | @node Native Debugging |
| 5346 | |
| 5347 | @chapter Native Debugging |
| 5348 | @cindex native debugging |
| 5349 | |
| 5350 | Several files control @value{GDBN}'s configuration for native support: |
| 5351 | |
| 5352 | @table @file |
| 5353 | @vindex NATDEPFILES |
| 5354 | @item gdb/config/@var{arch}/@var{xyz}.mh |
| 5355 | Specifies Makefile fragments needed by a @emph{native} configuration on |
| 5356 | machine @var{xyz}. In particular, this lists the required |
| 5357 | native-dependent object files, by defining @samp{NATDEPFILES=@dots{}}. |
| 5358 | Also specifies the header file which describes native support on |
| 5359 | @var{xyz}, by defining @samp{NAT_FILE= nm-@var{xyz}.h}. You can also |
| 5360 | define @samp{NAT_CFLAGS}, @samp{NAT_ADD_FILES}, @samp{NAT_CLIBS}, |
| 5361 | @samp{NAT_CDEPS}, @samp{NAT_GENERATED_FILES}, etc.; see @file{Makefile.in}. |
| 5362 | |
| 5363 | @emph{Maintainer's note: The @file{.mh} suffix is because this file |
| 5364 | originally contained @file{Makefile} fragments for hosting @value{GDBN} |
| 5365 | on machine @var{xyz}. While the file is no longer used for this |
| 5366 | purpose, the @file{.mh} suffix remains. Perhaps someone will |
| 5367 | eventually rename these fragments so that they have a @file{.mn} |
| 5368 | suffix.} |
| 5369 | |
| 5370 | @item gdb/config/@var{arch}/nm-@var{xyz}.h |
| 5371 | (@file{nm.h} is a link to this file, created by @code{configure}). Contains C |
| 5372 | macro definitions describing the native system environment, such as |
| 5373 | child process control and core file support. |
| 5374 | |
| 5375 | @item gdb/@var{xyz}-nat.c |
| 5376 | Contains any miscellaneous C code required for this native support of |
| 5377 | this machine. On some machines it doesn't exist at all. |
| 5378 | @end table |
| 5379 | |
| 5380 | There are some ``generic'' versions of routines that can be used by |
| 5381 | various systems. These can be customized in various ways by macros |
| 5382 | defined in your @file{nm-@var{xyz}.h} file. If these routines work for |
| 5383 | the @var{xyz} host, you can just include the generic file's name (with |
| 5384 | @samp{.o}, not @samp{.c}) in @code{NATDEPFILES}. |
| 5385 | |
| 5386 | Otherwise, if your machine needs custom support routines, you will need |
| 5387 | to write routines that perform the same functions as the generic file. |
| 5388 | Put them into @file{@var{xyz}-nat.c}, and put @file{@var{xyz}-nat.o} |
| 5389 | into @code{NATDEPFILES}. |
| 5390 | |
| 5391 | @table @file |
| 5392 | @item inftarg.c |
| 5393 | This contains the @emph{target_ops vector} that supports Unix child |
| 5394 | processes on systems which use ptrace and wait to control the child. |
| 5395 | |
| 5396 | @item procfs.c |
| 5397 | This contains the @emph{target_ops vector} that supports Unix child |
| 5398 | processes on systems which use /proc to control the child. |
| 5399 | |
| 5400 | @item fork-child.c |
| 5401 | This does the low-level grunge that uses Unix system calls to do a ``fork |
| 5402 | and exec'' to start up a child process. |
| 5403 | |
| 5404 | @item infptrace.c |
| 5405 | This is the low level interface to inferior processes for systems using |
| 5406 | the Unix @code{ptrace} call in a vanilla way. |
| 5407 | @end table |
| 5408 | |
| 5409 | @section ptrace |
| 5410 | |
| 5411 | @section /proc |
| 5412 | |
| 5413 | @section win32 |
| 5414 | |
| 5415 | @section shared libraries |
| 5416 | |
| 5417 | @section Native Conditionals |
| 5418 | @cindex native conditionals |
| 5419 | |
| 5420 | When @value{GDBN} is configured and compiled, various macros are |
| 5421 | defined or left undefined, to control compilation when the host and |
| 5422 | target systems are the same. These macros should be defined (or left |
| 5423 | undefined) in @file{nm-@var{system}.h}. |
| 5424 | |
| 5425 | @table @code |
| 5426 | |
| 5427 | @item I386_USE_GENERIC_WATCHPOINTS |
| 5428 | An x86-based machine can define this to use the generic x86 watchpoint |
| 5429 | support; see @ref{Algorithms, I386_USE_GENERIC_WATCHPOINTS}. |
| 5430 | |
| 5431 | @item SOLIB_ADD (@var{filename}, @var{from_tty}, @var{targ}, @var{readsyms}) |
| 5432 | @findex SOLIB_ADD |
| 5433 | Define this to expand into an expression that will cause the symbols in |
| 5434 | @var{filename} to be added to @value{GDBN}'s symbol table. If |
| 5435 | @var{readsyms} is zero symbols are not read but any necessary low level |
| 5436 | processing for @var{filename} is still done. |
| 5437 | |
| 5438 | @item SOLIB_CREATE_INFERIOR_HOOK |
| 5439 | @findex SOLIB_CREATE_INFERIOR_HOOK |
| 5440 | Define this to expand into any shared-library-relocation code that you |
| 5441 | want to be run just after the child process has been forked. |
| 5442 | |
| 5443 | @item START_INFERIOR_TRAPS_EXPECTED |
| 5444 | @findex START_INFERIOR_TRAPS_EXPECTED |
| 5445 | When starting an inferior, @value{GDBN} normally expects to trap |
| 5446 | twice; once when |
| 5447 | the shell execs, and once when the program itself execs. If the actual |
| 5448 | number of traps is something other than 2, then define this macro to |
| 5449 | expand into the number expected. |
| 5450 | |
| 5451 | @end table |
| 5452 | |
| 5453 | @node Support Libraries |
| 5454 | |
| 5455 | @chapter Support Libraries |
| 5456 | |
| 5457 | @section BFD |
| 5458 | @cindex BFD library |
| 5459 | |
| 5460 | BFD provides support for @value{GDBN} in several ways: |
| 5461 | |
| 5462 | @table @emph |
| 5463 | @item identifying executable and core files |
| 5464 | BFD will identify a variety of file types, including a.out, coff, and |
| 5465 | several variants thereof, as well as several kinds of core files. |
| 5466 | |
| 5467 | @item access to sections of files |
| 5468 | BFD parses the file headers to determine the names, virtual addresses, |
| 5469 | sizes, and file locations of all the various named sections in files |
| 5470 | (such as the text section or the data section). @value{GDBN} simply |
| 5471 | calls BFD to read or write section @var{x} at byte offset @var{y} for |
| 5472 | length @var{z}. |
| 5473 | |
| 5474 | @item specialized core file support |
| 5475 | BFD provides routines to determine the failing command name stored in a |
| 5476 | core file, the signal with which the program failed, and whether a core |
| 5477 | file matches (i.e.@: could be a core dump of) a particular executable |
| 5478 | file. |
| 5479 | |
| 5480 | @item locating the symbol information |
| 5481 | @value{GDBN} uses an internal interface of BFD to determine where to find the |
| 5482 | symbol information in an executable file or symbol-file. @value{GDBN} itself |
| 5483 | handles the reading of symbols, since BFD does not ``understand'' debug |
| 5484 | symbols, but @value{GDBN} uses BFD's cached information to find the symbols, |
| 5485 | string table, etc. |
| 5486 | @end table |
| 5487 | |
| 5488 | @section opcodes |
| 5489 | @cindex opcodes library |
| 5490 | |
| 5491 | The opcodes library provides @value{GDBN}'s disassembler. (It's a separate |
| 5492 | library because it's also used in binutils, for @file{objdump}). |
| 5493 | |
| 5494 | @section readline |
| 5495 | @cindex readline library |
| 5496 | The @code{readline} library provides a set of functions for use by applications |
| 5497 | that allow users to edit command lines as they are typed in. |
| 5498 | |
| 5499 | @section libiberty |
| 5500 | @cindex @code{libiberty} library |
| 5501 | |
| 5502 | The @code{libiberty} library provides a set of functions and features |
| 5503 | that integrate and improve on functionality found in modern operating |
| 5504 | systems. Broadly speaking, such features can be divided into three |
| 5505 | groups: supplemental functions (functions that may be missing in some |
| 5506 | environments and operating systems), replacement functions (providing |
| 5507 | a uniform and easier to use interface for commonly used standard |
| 5508 | functions), and extensions (which provide additional functionality |
| 5509 | beyond standard functions). |
| 5510 | |
| 5511 | @value{GDBN} uses various features provided by the @code{libiberty} |
| 5512 | library, for instance the C@t{++} demangler, the @acronym{IEEE} |
| 5513 | floating format support functions, the input options parser |
| 5514 | @samp{getopt}, the @samp{obstack} extension, and other functions. |
| 5515 | |
| 5516 | @subsection @code{obstacks} in @value{GDBN} |
| 5517 | @cindex @code{obstacks} |
| 5518 | |
| 5519 | The obstack mechanism provides a convenient way to allocate and free |
| 5520 | chunks of memory. Each obstack is a pool of memory that is managed |
| 5521 | like a stack. Objects (of any nature, size and alignment) are |
| 5522 | allocated and freed in a @acronym{LIFO} fashion on an obstack (see |
| 5523 | @code{libiberty}'s documentation for a more detailed explanation of |
| 5524 | @code{obstacks}). |
| 5525 | |
| 5526 | The most noticeable use of the @code{obstacks} in @value{GDBN} is in |
| 5527 | object files. There is an obstack associated with each internal |
| 5528 | representation of an object file. Lots of things get allocated on |
| 5529 | these @code{obstacks}: dictionary entries, blocks, blockvectors, |
| 5530 | symbols, minimal symbols, types, vectors of fundamental types, class |
| 5531 | fields of types, object files section lists, object files section |
| 5532 | offset lists, line tables, symbol tables, partial symbol tables, |
| 5533 | string tables, symbol table private data, macros tables, debug |
| 5534 | information sections and entries, import and export lists (som), |
| 5535 | unwind information (hppa), dwarf2 location expressions data. Plus |
| 5536 | various strings such as directory names strings, debug format strings, |
| 5537 | names of types. |
| 5538 | |
| 5539 | An essential and convenient property of all data on @code{obstacks} is |
| 5540 | that memory for it gets allocated (with @code{obstack_alloc}) at |
| 5541 | various times during a debugging session, but it is released all at |
| 5542 | once using the @code{obstack_free} function. The @code{obstack_free} |
| 5543 | function takes a pointer to where in the stack it must start the |
| 5544 | deletion from (much like the cleanup chains have a pointer to where to |
| 5545 | start the cleanups). Because of the stack like structure of the |
| 5546 | @code{obstacks}, this allows to free only a top portion of the |
| 5547 | obstack. There are a few instances in @value{GDBN} where such thing |
| 5548 | happens. Calls to @code{obstack_free} are done after some local data |
| 5549 | is allocated to the obstack. Only the local data is deleted from the |
| 5550 | obstack. Of course this assumes that nothing between the |
| 5551 | @code{obstack_alloc} and the @code{obstack_free} allocates anything |
| 5552 | else on the same obstack. For this reason it is best and safest to |
| 5553 | use temporary @code{obstacks}. |
| 5554 | |
| 5555 | Releasing the whole obstack is also not safe per se. It is safe only |
| 5556 | under the condition that we know the @code{obstacks} memory is no |
| 5557 | longer needed. In @value{GDBN} we get rid of the @code{obstacks} only |
| 5558 | when we get rid of the whole objfile(s), for instance upon reading a |
| 5559 | new symbol file. |
| 5560 | |
| 5561 | @section gnu-regex |
| 5562 | @cindex regular expressions library |
| 5563 | |
| 5564 | Regex conditionals. |
| 5565 | |
| 5566 | @table @code |
| 5567 | @item C_ALLOCA |
| 5568 | |
| 5569 | @item NFAILURES |
| 5570 | |
| 5571 | @item RE_NREGS |
| 5572 | |
| 5573 | @item SIGN_EXTEND_CHAR |
| 5574 | |
| 5575 | @item SWITCH_ENUM_BUG |
| 5576 | |
| 5577 | @item SYNTAX_TABLE |
| 5578 | |
| 5579 | @item Sword |
| 5580 | |
| 5581 | @item sparc |
| 5582 | @end table |
| 5583 | |
| 5584 | @section Array Containers |
| 5585 | @cindex Array Containers |
| 5586 | @cindex VEC |
| 5587 | |
| 5588 | Often it is necessary to manipulate a dynamic array of a set of |
| 5589 | objects. C forces some bookkeeping on this, which can get cumbersome |
| 5590 | and repetitive. The @file{vec.h} file contains macros for defining |
| 5591 | and using a typesafe vector type. The functions defined will be |
| 5592 | inlined when compiling, and so the abstraction cost should be zero. |
| 5593 | Domain checks are added to detect programming errors. |
| 5594 | |
| 5595 | An example use would be an array of symbols or section information. |
| 5596 | The array can be grown as symbols are read in (or preallocated), and |
| 5597 | the accessor macros provided keep care of all the necessary |
| 5598 | bookkeeping. Because the arrays are type safe, there is no danger of |
| 5599 | accidentally mixing up the contents. Think of these as C++ templates, |
| 5600 | but implemented in C. |
| 5601 | |
| 5602 | Because of the different behavior of structure objects, scalar objects |
| 5603 | and of pointers, there are three flavors of vector, one for each of |
| 5604 | these variants. Both the structure object and pointer variants pass |
| 5605 | pointers to objects around --- in the former case the pointers are |
| 5606 | stored into the vector and in the latter case the pointers are |
| 5607 | dereferenced and the objects copied into the vector. The scalar |
| 5608 | object variant is suitable for @code{int}-like objects, and the vector |
| 5609 | elements are returned by value. |
| 5610 | |
| 5611 | There are both @code{index} and @code{iterate} accessors. The iterator |
| 5612 | returns a boolean iteration condition and updates the iteration |
| 5613 | variable passed by reference. Because the iterator will be inlined, |
| 5614 | the address-of can be optimized away. |
| 5615 | |
| 5616 | The vectors are implemented using the trailing array idiom, thus they |
| 5617 | are not resizeable without changing the address of the vector object |
| 5618 | itself. This means you cannot have variables or fields of vector type |
| 5619 | --- always use a pointer to a vector. The one exception is the final |
| 5620 | field of a structure, which could be a vector type. You will have to |
| 5621 | use the @code{embedded_size} & @code{embedded_init} calls to create |
| 5622 | such objects, and they will probably not be resizeable (so don't use |
| 5623 | the @dfn{safe} allocation variants). The trailing array idiom is used |
| 5624 | (rather than a pointer to an array of data), because, if we allow |
| 5625 | @code{NULL} to also represent an empty vector, empty vectors occupy |
| 5626 | minimal space in the structure containing them. |
| 5627 | |
| 5628 | Each operation that increases the number of active elements is |
| 5629 | available in @dfn{quick} and @dfn{safe} variants. The former presumes |
| 5630 | that there is sufficient allocated space for the operation to succeed |
| 5631 | (it dies if there is not). The latter will reallocate the vector, if |
| 5632 | needed. Reallocation causes an exponential increase in vector size. |
| 5633 | If you know you will be adding N elements, it would be more efficient |
| 5634 | to use the reserve operation before adding the elements with the |
| 5635 | @dfn{quick} operation. This will ensure there are at least as many |
| 5636 | elements as you ask for, it will exponentially increase if there are |
| 5637 | too few spare slots. If you want reserve a specific number of slots, |
| 5638 | but do not want the exponential increase (for instance, you know this |
| 5639 | is the last allocation), use a negative number for reservation. You |
| 5640 | can also create a vector of a specific size from the get go. |
| 5641 | |
| 5642 | You should prefer the push and pop operations, as they append and |
| 5643 | remove from the end of the vector. If you need to remove several items |
| 5644 | in one go, use the truncate operation. The insert and remove |
| 5645 | operations allow you to change elements in the middle of the vector. |
| 5646 | There are two remove operations, one which preserves the element |
| 5647 | ordering @code{ordered_remove}, and one which does not |
| 5648 | @code{unordered_remove}. The latter function copies the end element |
| 5649 | into the removed slot, rather than invoke a memmove operation. The |
| 5650 | @code{lower_bound} function will determine where to place an item in |
| 5651 | the array using insert that will maintain sorted order. |
| 5652 | |
| 5653 | If you need to directly manipulate a vector, then the @code{address} |
| 5654 | accessor will return the address of the start of the vector. Also the |
| 5655 | @code{space} predicate will tell you whether there is spare capacity in the |
| 5656 | vector. You will not normally need to use these two functions. |
| 5657 | |
| 5658 | Vector types are defined using a |
| 5659 | @code{DEF_VEC_@{O,P,I@}(@var{typename})} macro. Variables of vector |
| 5660 | type are declared using a @code{VEC(@var{typename})} macro. The |
| 5661 | characters @code{O}, @code{P} and @code{I} indicate whether |
| 5662 | @var{typename} is an object (@code{O}), pointer (@code{P}) or integral |
| 5663 | (@code{I}) type. Be careful to pick the correct one, as you'll get an |
| 5664 | awkward and inefficient API if you use the wrong one. There is a |
| 5665 | check, which results in a compile-time warning, for the @code{P} and |
| 5666 | @code{I} versions, but there is no check for the @code{O} versions, as |
| 5667 | that is not possible in plain C. |
| 5668 | |
| 5669 | An example of their use would be, |
| 5670 | |
| 5671 | @smallexample |
| 5672 | DEF_VEC_P(tree); // non-managed tree vector. |
| 5673 | |
| 5674 | struct my_struct @{ |
| 5675 | VEC(tree) *v; // A (pointer to) a vector of tree pointers. |
| 5676 | @}; |
| 5677 | |
| 5678 | struct my_struct *s; |
| 5679 | |
| 5680 | if (VEC_length(tree, s->v)) @{ we have some contents @} |
| 5681 | VEC_safe_push(tree, s->v, decl); // append some decl onto the end |
| 5682 | for (ix = 0; VEC_iterate(tree, s->v, ix, elt); ix++) |
| 5683 | @{ do something with elt @} |
| 5684 | |
| 5685 | @end smallexample |
| 5686 | |
| 5687 | The @file{vec.h} file provides details on how to invoke the various |
| 5688 | accessors provided. They are enumerated here: |
| 5689 | |
| 5690 | @table @code |
| 5691 | @item VEC_length |
| 5692 | Return the number of items in the array, |
| 5693 | |
| 5694 | @item VEC_empty |
| 5695 | Return true if the array has no elements. |
| 5696 | |
| 5697 | @item VEC_last |
| 5698 | @itemx VEC_index |
| 5699 | Return the last or arbitrary item in the array. |
| 5700 | |
| 5701 | @item VEC_iterate |
| 5702 | Access an array element and indicate whether the array has been |
| 5703 | traversed. |
| 5704 | |
| 5705 | @item VEC_alloc |
| 5706 | @itemx VEC_free |
| 5707 | Create and destroy an array. |
| 5708 | |
| 5709 | @item VEC_embedded_size |
| 5710 | @itemx VEC_embedded_init |
| 5711 | Helpers for embedding an array as the final element of another struct. |
| 5712 | |
| 5713 | @item VEC_copy |
| 5714 | Duplicate an array. |
| 5715 | |
| 5716 | @item VEC_space |
| 5717 | Return the amount of free space in an array. |
| 5718 | |
| 5719 | @item VEC_reserve |
| 5720 | Ensure a certain amount of free space. |
| 5721 | |
| 5722 | @item VEC_quick_push |
| 5723 | @itemx VEC_safe_push |
| 5724 | Append to an array, either assuming the space is available, or making |
| 5725 | sure that it is. |
| 5726 | |
| 5727 | @item VEC_pop |
| 5728 | Remove the last item from an array. |
| 5729 | |
| 5730 | @item VEC_truncate |
| 5731 | Remove several items from the end of an array. |
| 5732 | |
| 5733 | @item VEC_safe_grow |
| 5734 | Add several items to the end of an array. |
| 5735 | |
| 5736 | @item VEC_replace |
| 5737 | Overwrite an item in the array. |
| 5738 | |
| 5739 | @item VEC_quick_insert |
| 5740 | @itemx VEC_safe_insert |
| 5741 | Insert an item into the middle of the array. Either the space must |
| 5742 | already exist, or the space is created. |
| 5743 | |
| 5744 | @item VEC_ordered_remove |
| 5745 | @itemx VEC_unordered_remove |
| 5746 | Remove an item from the array, preserving order or not. |
| 5747 | |
| 5748 | @item VEC_block_remove |
| 5749 | Remove a set of items from the array. |
| 5750 | |
| 5751 | @item VEC_address |
| 5752 | Provide the address of the first element. |
| 5753 | |
| 5754 | @item VEC_lower_bound |
| 5755 | Binary search the array. |
| 5756 | |
| 5757 | @end table |
| 5758 | |
| 5759 | @section include |
| 5760 | |
| 5761 | @node Coding Standards |
| 5762 | |
| 5763 | @chapter Coding Standards |
| 5764 | @cindex coding standards |
| 5765 | |
| 5766 | @section @value{GDBN} C Coding Standards |
| 5767 | |
| 5768 | @value{GDBN} follows the GNU coding standards, as described in |
| 5769 | @file{etc/standards.texi}. This file is also available for anonymous |
| 5770 | FTP from GNU archive sites. @value{GDBN} takes a strict interpretation |
| 5771 | of the standard; in general, when the GNU standard recommends a practice |
| 5772 | but does not require it, @value{GDBN} requires it. |
| 5773 | |
| 5774 | @value{GDBN} follows an additional set of coding standards specific to |
| 5775 | @value{GDBN}, as described in the following sections. |
| 5776 | |
| 5777 | @subsection ISO C |
| 5778 | |
| 5779 | @value{GDBN} assumes an ISO/IEC 9899:1990 (a.k.a.@: ISO C90) compliant |
| 5780 | compiler. |
| 5781 | |
| 5782 | @value{GDBN} does not assume an ISO C or POSIX compliant C library. |
| 5783 | |
| 5784 | @subsection Formatting |
| 5785 | |
| 5786 | @cindex source code formatting |
| 5787 | The standard GNU recommendations for formatting must be followed |
| 5788 | strictly. Any @value{GDBN}-specific deviation from GNU |
| 5789 | recomendations is described below. |
| 5790 | |
| 5791 | A function declaration should not have its name in column zero. A |
| 5792 | function definition should have its name in column zero. |
| 5793 | |
| 5794 | @smallexample |
| 5795 | /* Declaration */ |
| 5796 | static void foo (void); |
| 5797 | /* Definition */ |
| 5798 | void |
| 5799 | foo (void) |
| 5800 | @{ |
| 5801 | @} |
| 5802 | @end smallexample |
| 5803 | |
| 5804 | @emph{Pragmatics: This simplifies scripting. Function definitions can |
| 5805 | be found using @samp{^function-name}.} |
| 5806 | |
| 5807 | There must be a space between a function or macro name and the opening |
| 5808 | parenthesis of its argument list (except for macro definitions, as |
| 5809 | required by C). There must not be a space after an open paren/bracket |
| 5810 | or before a close paren/bracket. |
| 5811 | |
| 5812 | While additional whitespace is generally helpful for reading, do not use |
| 5813 | more than one blank line to separate blocks, and avoid adding whitespace |
| 5814 | after the end of a program line (as of 1/99, some 600 lines had |
| 5815 | whitespace after the semicolon). Excess whitespace causes difficulties |
| 5816 | for @code{diff} and @code{patch} utilities. |
| 5817 | |
| 5818 | Pointers are declared using the traditional K&R C style: |
| 5819 | |
| 5820 | @smallexample |
| 5821 | void *foo; |
| 5822 | @end smallexample |
| 5823 | |
| 5824 | @noindent |
| 5825 | and not: |
| 5826 | |
| 5827 | @smallexample |
| 5828 | void * foo; |
| 5829 | void* foo; |
| 5830 | @end smallexample |
| 5831 | |
| 5832 | In addition, whitespace around casts and unary operators should follow |
| 5833 | the following guidelines: |
| 5834 | |
| 5835 | @multitable @columnfractions .2 .2 .8 |
| 5836 | @item Use... @tab ...instead of @tab |
| 5837 | |
| 5838 | @item @code{!x} |
| 5839 | @tab @code{! x} |
| 5840 | @item @code{~x} |
| 5841 | @tab @code{~ x} |
| 5842 | @item @code{-x} |
| 5843 | @tab @code{- x} |
| 5844 | @tab (unary minus) |
| 5845 | @item @code{(foo) x} |
| 5846 | @tab @code{(foo)x} |
| 5847 | @tab (cast) |
| 5848 | @item @code{*x} |
| 5849 | @tab @code{* x} |
| 5850 | @tab (pointer dereference) |
| 5851 | @end multitable |
| 5852 | |
| 5853 | @subsection Comments |
| 5854 | |
| 5855 | @cindex comment formatting |
| 5856 | The standard GNU requirements on comments must be followed strictly. |
| 5857 | |
| 5858 | Block comments must appear in the following form, with no @code{/*}- or |
| 5859 | @code{*/}-only lines, and no leading @code{*}: |
| 5860 | |
| 5861 | @smallexample |
| 5862 | /* Wait for control to return from inferior to debugger. If inferior |
| 5863 | gets a signal, we may decide to start it up again instead of |
| 5864 | returning. That is why there is a loop in this function. When |
| 5865 | this function actually returns it means the inferior should be left |
| 5866 | stopped and @value{GDBN} should read more commands. */ |
| 5867 | @end smallexample |
| 5868 | |
| 5869 | (Note that this format is encouraged by Emacs; tabbing for a multi-line |
| 5870 | comment works correctly, and @kbd{M-q} fills the block consistently.) |
| 5871 | |
| 5872 | Put a blank line between the block comments preceding function or |
| 5873 | variable definitions, and the definition itself. |
| 5874 | |
| 5875 | In general, put function-body comments on lines by themselves, rather |
| 5876 | than trying to fit them into the 20 characters left at the end of a |
| 5877 | line, since either the comment or the code will inevitably get longer |
| 5878 | than will fit, and then somebody will have to move it anyhow. |
| 5879 | |
| 5880 | @subsection C Usage |
| 5881 | |
| 5882 | @cindex C data types |
| 5883 | Code must not depend on the sizes of C data types, the format of the |
| 5884 | host's floating point numbers, the alignment of anything, or the order |
| 5885 | of evaluation of expressions. |
| 5886 | |
| 5887 | @cindex function usage |
| 5888 | Use functions freely. There are only a handful of compute-bound areas |
| 5889 | in @value{GDBN} that might be affected by the overhead of a function |
| 5890 | call, mainly in symbol reading. Most of @value{GDBN}'s performance is |
| 5891 | limited by the target interface (whether serial line or system call). |
| 5892 | |
| 5893 | However, use functions with moderation. A thousand one-line functions |
| 5894 | are just as hard to understand as a single thousand-line function. |
| 5895 | |
| 5896 | @emph{Macros are bad, M'kay.} |
| 5897 | (But if you have to use a macro, make sure that the macro arguments are |
| 5898 | protected with parentheses.) |
| 5899 | |
| 5900 | @cindex types |
| 5901 | |
| 5902 | Declarations like @samp{struct foo *} should be used in preference to |
| 5903 | declarations like @samp{typedef struct foo @{ @dots{} @} *foo_ptr}. |
| 5904 | |
| 5905 | @subsection Function Prototypes |
| 5906 | @cindex function prototypes |
| 5907 | |
| 5908 | Prototypes must be used when both @emph{declaring} and @emph{defining} |
| 5909 | a function. Prototypes for @value{GDBN} functions must include both the |
| 5910 | argument type and name, with the name matching that used in the actual |
| 5911 | function definition. |
| 5912 | |
| 5913 | All external functions should have a declaration in a header file that |
| 5914 | callers include, except for @code{_initialize_*} functions, which must |
| 5915 | be external so that @file{init.c} construction works, but shouldn't be |
| 5916 | visible to random source files. |
| 5917 | |
| 5918 | Where a source file needs a forward declaration of a static function, |
| 5919 | that declaration must appear in a block near the top of the source file. |
| 5920 | |
| 5921 | @subsection File Names |
| 5922 | |
| 5923 | Any file used when building the core of @value{GDBN} must be in lower |
| 5924 | case. Any file used when building the core of @value{GDBN} must be 8.3 |
| 5925 | unique. These requirements apply to both source and generated files. |
| 5926 | |
| 5927 | @emph{Pragmatics: The core of @value{GDBN} must be buildable on many |
| 5928 | platforms including DJGPP and MacOS/HFS. Every time an unfriendly file |
| 5929 | is introduced to the build process both @file{Makefile.in} and |
| 5930 | @file{configure.in} need to be modified accordingly. Compare the |
| 5931 | convoluted conversion process needed to transform @file{COPYING} into |
| 5932 | @file{copying.c} with the conversion needed to transform |
| 5933 | @file{version.in} into @file{version.c}.} |
| 5934 | |
| 5935 | Any file non 8.3 compliant file (that is not used when building the core |
| 5936 | of @value{GDBN}) must be added to @file{gdb/config/djgpp/fnchange.lst}. |
| 5937 | |
| 5938 | @emph{Pragmatics: This is clearly a compromise.} |
| 5939 | |
| 5940 | When @value{GDBN} has a local version of a system header file (ex |
| 5941 | @file{string.h}) the file name based on the POSIX header prefixed with |
| 5942 | @file{gdb_} (@file{gdb_string.h}). These headers should be relatively |
| 5943 | independent: they should use only macros defined by @file{configure}, |
| 5944 | the compiler, or the host; they should include only system headers; they |
| 5945 | should refer only to system types. They may be shared between multiple |
| 5946 | programs, e.g.@: @value{GDBN} and @sc{gdbserver}. |
| 5947 | |
| 5948 | For other files @samp{-} is used as the separator. |
| 5949 | |
| 5950 | @subsection Include Files |
| 5951 | |
| 5952 | A @file{.c} file should include @file{defs.h} first. |
| 5953 | |
| 5954 | A @file{.c} file should directly include the @code{.h} file of every |
| 5955 | declaration and/or definition it directly refers to. It cannot rely on |
| 5956 | indirect inclusion. |
| 5957 | |
| 5958 | A @file{.h} file should directly include the @code{.h} file of every |
| 5959 | declaration and/or definition it directly refers to. It cannot rely on |
| 5960 | indirect inclusion. Exception: The file @file{defs.h} does not need to |
| 5961 | be directly included. |
| 5962 | |
| 5963 | An external declaration should only appear in one include file. |
| 5964 | |
| 5965 | An external declaration should never appear in a @code{.c} file. |
| 5966 | Exception: a declaration for the @code{_initialize} function that |
| 5967 | pacifies @option{-Wmissing-declaration}. |
| 5968 | |
| 5969 | A @code{typedef} definition should only appear in one include file. |
| 5970 | |
| 5971 | An opaque @code{struct} declaration can appear in multiple @file{.h} |
| 5972 | files. Where possible, a @file{.h} file should use an opaque |
| 5973 | @code{struct} declaration instead of an include. |
| 5974 | |
| 5975 | All @file{.h} files should be wrapped in: |
| 5976 | |
| 5977 | @smallexample |
| 5978 | #ifndef INCLUDE_FILE_NAME_H |
| 5979 | #define INCLUDE_FILE_NAME_H |
| 5980 | header body |
| 5981 | #endif |
| 5982 | @end smallexample |
| 5983 | |
| 5984 | @section @value{GDBN} Python Coding Standards |
| 5985 | |
| 5986 | @value{GDBN} follows the published @code{Python} coding standards in |
| 5987 | @uref{http://www.python.org/dev/peps/pep-0008/, @code{PEP008}}. |
| 5988 | |
| 5989 | In addition, the guidelines in the |
| 5990 | @uref{http://google-styleguide.googlecode.com/svn/trunk/pyguide.html, |
| 5991 | Google Python Style Guide} are also followed where they do not |
| 5992 | conflict with @code{PEP008}. |
| 5993 | |
| 5994 | @subsection @value{GDBN}-specific exceptions |
| 5995 | |
| 5996 | There are a few exceptions to the published standards. |
| 5997 | They exist mainly for consistency with the @code{C} standards. |
| 5998 | |
| 5999 | @c It is expected that there are a few more exceptions, |
| 6000 | @c so we use itemize here. |
| 6001 | |
| 6002 | @itemize @bullet |
| 6003 | |
| 6004 | @item |
| 6005 | Use @code{FIXME} instead of @code{TODO}. |
| 6006 | |
| 6007 | @end itemize |
| 6008 | |
| 6009 | @node Misc Guidelines |
| 6010 | |
| 6011 | @chapter Misc Guidelines |
| 6012 | |
| 6013 | This chapter covers topics that are lower-level than the major |
| 6014 | algorithms of @value{GDBN}. |
| 6015 | |
| 6016 | @section Cleanups |
| 6017 | @cindex cleanups |
| 6018 | |
| 6019 | Cleanups are a structured way to deal with things that need to be done |
| 6020 | later. |
| 6021 | |
| 6022 | When your code does something (e.g., @code{xmalloc} some memory, or |
| 6023 | @code{open} a file) that needs to be undone later (e.g., @code{xfree} |
| 6024 | the memory or @code{close} the file), it can make a cleanup. The |
| 6025 | cleanup will be done at some future point: when the command is finished |
| 6026 | and control returns to the top level; when an error occurs and the stack |
| 6027 | is unwound; or when your code decides it's time to explicitly perform |
| 6028 | cleanups. Alternatively you can elect to discard the cleanups you |
| 6029 | created. |
| 6030 | |
| 6031 | Syntax: |
| 6032 | |
| 6033 | @table @code |
| 6034 | @item struct cleanup *@var{old_chain}; |
| 6035 | Declare a variable which will hold a cleanup chain handle. |
| 6036 | |
| 6037 | @findex make_cleanup |
| 6038 | @item @var{old_chain} = make_cleanup (@var{function}, @var{arg}); |
| 6039 | Make a cleanup which will cause @var{function} to be called with |
| 6040 | @var{arg} (a @code{char *}) later. The result, @var{old_chain}, is a |
| 6041 | handle that can later be passed to @code{do_cleanups} or |
| 6042 | @code{discard_cleanups}. Unless you are going to call |
| 6043 | @code{do_cleanups} or @code{discard_cleanups}, you can ignore the result |
| 6044 | from @code{make_cleanup}. |
| 6045 | |
| 6046 | @findex do_cleanups |
| 6047 | @item do_cleanups (@var{old_chain}); |
| 6048 | Do all cleanups added to the chain since the corresponding |
| 6049 | @code{make_cleanup} call was made. |
| 6050 | |
| 6051 | @findex discard_cleanups |
| 6052 | @item discard_cleanups (@var{old_chain}); |
| 6053 | Same as @code{do_cleanups} except that it just removes the cleanups from |
| 6054 | the chain and does not call the specified functions. |
| 6055 | @end table |
| 6056 | |
| 6057 | Cleanups are implemented as a chain. The handle returned by |
| 6058 | @code{make_cleanups} includes the cleanup passed to the call and any |
| 6059 | later cleanups appended to the chain (but not yet discarded or |
| 6060 | performed). E.g.: |
| 6061 | |
| 6062 | @smallexample |
| 6063 | make_cleanup (a, 0); |
| 6064 | @{ |
| 6065 | struct cleanup *old = make_cleanup (b, 0); |
| 6066 | make_cleanup (c, 0) |
| 6067 | ... |
| 6068 | do_cleanups (old); |
| 6069 | @} |
| 6070 | @end smallexample |
| 6071 | |
| 6072 | @noindent |
| 6073 | will call @code{c()} and @code{b()} but will not call @code{a()}. The |
| 6074 | cleanup that calls @code{a()} will remain in the cleanup chain, and will |
| 6075 | be done later unless otherwise discarded.@refill |
| 6076 | |
| 6077 | Your function should explicitly do or discard the cleanups it creates. |
| 6078 | Failing to do this leads to non-deterministic behavior since the caller |
| 6079 | will arbitrarily do or discard your functions cleanups. This need leads |
| 6080 | to two common cleanup styles. |
| 6081 | |
| 6082 | The first style is try/finally. Before it exits, your code-block calls |
| 6083 | @code{do_cleanups} with the old cleanup chain and thus ensures that your |
| 6084 | code-block's cleanups are always performed. For instance, the following |
| 6085 | code-segment avoids a memory leak problem (even when @code{error} is |
| 6086 | called and a forced stack unwind occurs) by ensuring that the |
| 6087 | @code{xfree} will always be called: |
| 6088 | |
| 6089 | @smallexample |
| 6090 | struct cleanup *old = make_cleanup (null_cleanup, 0); |
| 6091 | data = xmalloc (sizeof blah); |
| 6092 | make_cleanup (xfree, data); |
| 6093 | ... blah blah ... |
| 6094 | do_cleanups (old); |
| 6095 | @end smallexample |
| 6096 | |
| 6097 | The second style is try/except. Before it exits, your code-block calls |
| 6098 | @code{discard_cleanups} with the old cleanup chain and thus ensures that |
| 6099 | any created cleanups are not performed. For instance, the following |
| 6100 | code segment, ensures that the file will be closed but only if there is |
| 6101 | an error: |
| 6102 | |
| 6103 | @smallexample |
| 6104 | FILE *file = fopen ("afile", "r"); |
| 6105 | struct cleanup *old = make_cleanup (close_file, file); |
| 6106 | ... blah blah ... |
| 6107 | discard_cleanups (old); |
| 6108 | return file; |
| 6109 | @end smallexample |
| 6110 | |
| 6111 | Some functions, e.g., @code{fputs_filtered()} or @code{error()}, specify |
| 6112 | that they ``should not be called when cleanups are not in place''. This |
| 6113 | means that any actions you need to reverse in the case of an error or |
| 6114 | interruption must be on the cleanup chain before you call these |
| 6115 | functions, since they might never return to your code (they |
| 6116 | @samp{longjmp} instead). |
| 6117 | |
| 6118 | @section Per-architecture module data |
| 6119 | @cindex per-architecture module data |
| 6120 | @cindex multi-arch data |
| 6121 | @cindex data-pointer, per-architecture/per-module |
| 6122 | |
| 6123 | The multi-arch framework includes a mechanism for adding module |
| 6124 | specific per-architecture data-pointers to the @code{struct gdbarch} |
| 6125 | architecture object. |
| 6126 | |
| 6127 | A module registers one or more per-architecture data-pointers using: |
| 6128 | |
| 6129 | @deftypefn {Architecture Function} {struct gdbarch_data *} gdbarch_data_register_pre_init (gdbarch_data_pre_init_ftype *@var{pre_init}) |
| 6130 | @var{pre_init} is used to, on-demand, allocate an initial value for a |
| 6131 | per-architecture data-pointer using the architecture's obstack (passed |
| 6132 | in as a parameter). Since @var{pre_init} can be called during |
| 6133 | architecture creation, it is not parameterized with the architecture. |
| 6134 | and must not call modules that use per-architecture data. |
| 6135 | @end deftypefn |
| 6136 | |
| 6137 | @deftypefn {Architecture Function} {struct gdbarch_data *} gdbarch_data_register_post_init (gdbarch_data_post_init_ftype *@var{post_init}) |
| 6138 | @var{post_init} is used to obtain an initial value for a |
| 6139 | per-architecture data-pointer @emph{after}. Since @var{post_init} is |
| 6140 | always called after architecture creation, it both receives the fully |
| 6141 | initialized architecture and is free to call modules that use |
| 6142 | per-architecture data (care needs to be taken to ensure that those |
| 6143 | other modules do not try to call back to this module as that will |
| 6144 | create in cycles in the initialization call graph). |
| 6145 | @end deftypefn |
| 6146 | |
| 6147 | These functions return a @code{struct gdbarch_data} that is used to |
| 6148 | identify the per-architecture data-pointer added for that module. |
| 6149 | |
| 6150 | The per-architecture data-pointer is accessed using the function: |
| 6151 | |
| 6152 | @deftypefn {Architecture Function} {void *} gdbarch_data (struct gdbarch *@var{gdbarch}, struct gdbarch_data *@var{data_handle}) |
| 6153 | Given the architecture @var{arch} and module data handle |
| 6154 | @var{data_handle} (returned by @code{gdbarch_data_register_pre_init} |
| 6155 | or @code{gdbarch_data_register_post_init}), this function returns the |
| 6156 | current value of the per-architecture data-pointer. If the data |
| 6157 | pointer is @code{NULL}, it is first initialized by calling the |
| 6158 | corresponding @var{pre_init} or @var{post_init} method. |
| 6159 | @end deftypefn |
| 6160 | |
| 6161 | The examples below assume the following definitions: |
| 6162 | |
| 6163 | @smallexample |
| 6164 | struct nozel @{ int total; @}; |
| 6165 | static struct gdbarch_data *nozel_handle; |
| 6166 | @end smallexample |
| 6167 | |
| 6168 | A module can extend the architecture vector, adding additional |
| 6169 | per-architecture data, using the @var{pre_init} method. The module's |
| 6170 | per-architecture data is then initialized during architecture |
| 6171 | creation. |
| 6172 | |
| 6173 | In the below, the module's per-architecture @emph{nozel} is added. An |
| 6174 | architecture can specify its nozel by calling @code{set_gdbarch_nozel} |
| 6175 | from @code{gdbarch_init}. |
| 6176 | |
| 6177 | @smallexample |
| 6178 | static void * |
| 6179 | nozel_pre_init (struct obstack *obstack) |
| 6180 | @{ |
| 6181 | struct nozel *data = OBSTACK_ZALLOC (obstack, struct nozel); |
| 6182 | return data; |
| 6183 | @} |
| 6184 | @end smallexample |
| 6185 | |
| 6186 | @smallexample |
| 6187 | extern void |
| 6188 | set_gdbarch_nozel (struct gdbarch *gdbarch, int total) |
| 6189 | @{ |
| 6190 | struct nozel *data = gdbarch_data (gdbarch, nozel_handle); |
| 6191 | data->total = nozel; |
| 6192 | @} |
| 6193 | @end smallexample |
| 6194 | |
| 6195 | A module can on-demand create architecture dependent data structures |
| 6196 | using @code{post_init}. |
| 6197 | |
| 6198 | In the below, the nozel's total is computed on-demand by |
| 6199 | @code{nozel_post_init} using information obtained from the |
| 6200 | architecture. |
| 6201 | |
| 6202 | @smallexample |
| 6203 | static void * |
| 6204 | nozel_post_init (struct gdbarch *gdbarch) |
| 6205 | @{ |
| 6206 | struct nozel *data = GDBARCH_OBSTACK_ZALLOC (gdbarch, struct nozel); |
| 6207 | nozel->total = gdbarch@dots{} (gdbarch); |
| 6208 | return data; |
| 6209 | @} |
| 6210 | @end smallexample |
| 6211 | |
| 6212 | @smallexample |
| 6213 | extern int |
| 6214 | nozel_total (struct gdbarch *gdbarch) |
| 6215 | @{ |
| 6216 | struct nozel *data = gdbarch_data (gdbarch, nozel_handle); |
| 6217 | return data->total; |
| 6218 | @} |
| 6219 | @end smallexample |
| 6220 | |
| 6221 | @section Wrapping Output Lines |
| 6222 | @cindex line wrap in output |
| 6223 | |
| 6224 | @findex wrap_here |
| 6225 | Output that goes through @code{printf_filtered} or @code{fputs_filtered} |
| 6226 | or @code{fputs_demangled} needs only to have calls to @code{wrap_here} |
| 6227 | added in places that would be good breaking points. The utility |
| 6228 | routines will take care of actually wrapping if the line width is |
| 6229 | exceeded. |
| 6230 | |
| 6231 | The argument to @code{wrap_here} is an indentation string which is |
| 6232 | printed @emph{only} if the line breaks there. This argument is saved |
| 6233 | away and used later. It must remain valid until the next call to |
| 6234 | @code{wrap_here} or until a newline has been printed through the |
| 6235 | @code{*_filtered} functions. Don't pass in a local variable and then |
| 6236 | return! |
| 6237 | |
| 6238 | It is usually best to call @code{wrap_here} after printing a comma or |
| 6239 | space. If you call it before printing a space, make sure that your |
| 6240 | indentation properly accounts for the leading space that will print if |
| 6241 | the line wraps there. |
| 6242 | |
| 6243 | Any function or set of functions that produce filtered output must |
| 6244 | finish by printing a newline, to flush the wrap buffer, before switching |
| 6245 | to unfiltered (@code{printf}) output. Symbol reading routines that |
| 6246 | print warnings are a good example. |
| 6247 | |
| 6248 | @section Memory Management |
| 6249 | |
| 6250 | @value{GDBN} does not use the functions @code{malloc}, @code{realloc}, |
| 6251 | @code{calloc}, @code{free} and @code{asprintf}. |
| 6252 | |
| 6253 | @value{GDBN} uses the functions @code{xmalloc}, @code{xrealloc} and |
| 6254 | @code{xcalloc} when allocating memory. Unlike @code{malloc} et.al.@: |
| 6255 | these functions do not return when the memory pool is empty. Instead, |
| 6256 | they unwind the stack using cleanups. These functions return |
| 6257 | @code{NULL} when requested to allocate a chunk of memory of size zero. |
| 6258 | |
| 6259 | @emph{Pragmatics: By using these functions, the need to check every |
| 6260 | memory allocation is removed. These functions provide portable |
| 6261 | behavior.} |
| 6262 | |
| 6263 | @value{GDBN} does not use the function @code{free}. |
| 6264 | |
| 6265 | @value{GDBN} uses the function @code{xfree} to return memory to the |
| 6266 | memory pool. Consistent with ISO-C, this function ignores a request to |
| 6267 | free a @code{NULL} pointer. |
| 6268 | |
| 6269 | @emph{Pragmatics: On some systems @code{free} fails when passed a |
| 6270 | @code{NULL} pointer.} |
| 6271 | |
| 6272 | @value{GDBN} can use the non-portable function @code{alloca} for the |
| 6273 | allocation of small temporary values (such as strings). |
| 6274 | |
| 6275 | @emph{Pragmatics: This function is very non-portable. Some systems |
| 6276 | restrict the memory being allocated to no more than a few kilobytes.} |
| 6277 | |
| 6278 | @value{GDBN} uses the string function @code{xstrdup} and the print |
| 6279 | function @code{xstrprintf}. |
| 6280 | |
| 6281 | @emph{Pragmatics: @code{asprintf} and @code{strdup} can fail. Print |
| 6282 | functions such as @code{sprintf} are very prone to buffer overflow |
| 6283 | errors.} |
| 6284 | |
| 6285 | |
| 6286 | @section Compiler Warnings |
| 6287 | @cindex compiler warnings |
| 6288 | |
| 6289 | With few exceptions, developers should avoid the configuration option |
| 6290 | @samp{--disable-werror} when building @value{GDBN}. The exceptions |
| 6291 | are listed in the file @file{gdb/MAINTAINERS}. The default, when |
| 6292 | building with @sc{gcc}, is @samp{--enable-werror}. |
| 6293 | |
| 6294 | This option causes @value{GDBN} (when built using GCC) to be compiled |
| 6295 | with a carefully selected list of compiler warning flags. Any warnings |
| 6296 | from those flags are treated as errors. |
| 6297 | |
| 6298 | The current list of warning flags includes: |
| 6299 | |
| 6300 | @table @samp |
| 6301 | @item -Wall |
| 6302 | Recommended @sc{gcc} warnings. |
| 6303 | |
| 6304 | @item -Wdeclaration-after-statement |
| 6305 | |
| 6306 | @sc{gcc} 3.x (and later) and @sc{c99} allow declarations mixed with |
| 6307 | code, but @sc{gcc} 2.x and @sc{c89} do not. |
| 6308 | |
| 6309 | @item -Wpointer-arith |
| 6310 | |
| 6311 | @item -Wformat-nonliteral |
| 6312 | Non-literal format strings, with a few exceptions, are bugs - they |
| 6313 | might contain unintended user-supplied format specifiers. |
| 6314 | Since @value{GDBN} uses the @code{format printf} attribute on all |
| 6315 | @code{printf} like functions this checks not just @code{printf} calls |
| 6316 | but also calls to functions such as @code{fprintf_unfiltered}. |
| 6317 | |
| 6318 | @item -Wno-pointer-sign |
| 6319 | In version 4.0, GCC began warning about pointer argument passing or |
| 6320 | assignment even when the source and destination differed only in |
| 6321 | signedness. However, most @value{GDBN} code doesn't distinguish |
| 6322 | carefully between @code{char} and @code{unsigned char}. In early 2006 |
| 6323 | the @value{GDBN} developers decided correcting these warnings wasn't |
| 6324 | worth the time it would take. |
| 6325 | |
| 6326 | @item -Wno-unused-parameter |
| 6327 | Due to the way that @value{GDBN} is implemented many functions have |
| 6328 | unused parameters. Consequently this warning is avoided. The macro |
| 6329 | @code{ATTRIBUTE_UNUSED} is not used as it leads to false negatives --- |
| 6330 | it is not an error to have @code{ATTRIBUTE_UNUSED} on a parameter that |
| 6331 | is being used. |
| 6332 | |
| 6333 | @item -Wno-unused |
| 6334 | @itemx -Wno-switch |
| 6335 | @itemx -Wno-char-subscripts |
| 6336 | These are warnings which might be useful for @value{GDBN}, but are |
| 6337 | currently too noisy to enable with @samp{-Werror}. |
| 6338 | |
| 6339 | @end table |
| 6340 | |
| 6341 | @section Internal Error Recovery |
| 6342 | |
| 6343 | During its execution, @value{GDBN} can encounter two types of errors. |
| 6344 | User errors and internal errors. User errors include not only a user |
| 6345 | entering an incorrect command but also problems arising from corrupt |
| 6346 | object files and system errors when interacting with the target. |
| 6347 | Internal errors include situations where @value{GDBN} has detected, at |
| 6348 | run time, a corrupt or erroneous situation. |
| 6349 | |
| 6350 | When reporting an internal error, @value{GDBN} uses |
| 6351 | @code{internal_error} and @code{gdb_assert}. |
| 6352 | |
| 6353 | @value{GDBN} must not call @code{abort} or @code{assert}. |
| 6354 | |
| 6355 | @emph{Pragmatics: There is no @code{internal_warning} function. Either |
| 6356 | the code detected a user error, recovered from it and issued a |
| 6357 | @code{warning} or the code failed to correctly recover from the user |
| 6358 | error and issued an @code{internal_error}.} |
| 6359 | |
| 6360 | @section Command Names |
| 6361 | |
| 6362 | GDB U/I commands are written @samp{foo-bar}, not @samp{foo_bar}. |
| 6363 | |
| 6364 | @section Clean Design and Portable Implementation |
| 6365 | |
| 6366 | @cindex design |
| 6367 | In addition to getting the syntax right, there's the little question of |
| 6368 | semantics. Some things are done in certain ways in @value{GDBN} because long |
| 6369 | experience has shown that the more obvious ways caused various kinds of |
| 6370 | trouble. |
| 6371 | |
| 6372 | @cindex assumptions about targets |
| 6373 | You can't assume the byte order of anything that comes from a target |
| 6374 | (including @var{value}s, object files, and instructions). Such things |
| 6375 | must be byte-swapped using @code{SWAP_TARGET_AND_HOST} in |
| 6376 | @value{GDBN}, or one of the swap routines defined in @file{bfd.h}, |
| 6377 | such as @code{bfd_get_32}. |
| 6378 | |
| 6379 | You can't assume that you know what interface is being used to talk to |
| 6380 | the target system. All references to the target must go through the |
| 6381 | current @code{target_ops} vector. |
| 6382 | |
| 6383 | You can't assume that the host and target machines are the same machine |
| 6384 | (except in the ``native'' support modules). In particular, you can't |
| 6385 | assume that the target machine's header files will be available on the |
| 6386 | host machine. Target code must bring along its own header files -- |
| 6387 | written from scratch or explicitly donated by their owner, to avoid |
| 6388 | copyright problems. |
| 6389 | |
| 6390 | @cindex portability |
| 6391 | Insertion of new @code{#ifdef}'s will be frowned upon. It's much better |
| 6392 | to write the code portably than to conditionalize it for various |
| 6393 | systems. |
| 6394 | |
| 6395 | @cindex system dependencies |
| 6396 | New @code{#ifdef}'s which test for specific compilers or manufacturers |
| 6397 | or operating systems are unacceptable. All @code{#ifdef}'s should test |
| 6398 | for features. The information about which configurations contain which |
| 6399 | features should be segregated into the configuration files. Experience |
| 6400 | has proven far too often that a feature unique to one particular system |
| 6401 | often creeps into other systems; and that a conditional based on some |
| 6402 | predefined macro for your current system will become worthless over |
| 6403 | time, as new versions of your system come out that behave differently |
| 6404 | with regard to this feature. |
| 6405 | |
| 6406 | Adding code that handles specific architectures, operating systems, |
| 6407 | target interfaces, or hosts, is not acceptable in generic code. |
| 6408 | |
| 6409 | @cindex portable file name handling |
| 6410 | @cindex file names, portability |
| 6411 | One particularly notorious area where system dependencies tend to |
| 6412 | creep in is handling of file names. The mainline @value{GDBN} code |
| 6413 | assumes Posix semantics of file names: absolute file names begin with |
| 6414 | a forward slash @file{/}, slashes are used to separate leading |
| 6415 | directories, case-sensitive file names. These assumptions are not |
| 6416 | necessarily true on non-Posix systems such as MS-Windows. To avoid |
| 6417 | system-dependent code where you need to take apart or construct a file |
| 6418 | name, use the following portable macros: |
| 6419 | |
| 6420 | @table @code |
| 6421 | @findex HAVE_DOS_BASED_FILE_SYSTEM |
| 6422 | @item HAVE_DOS_BASED_FILE_SYSTEM |
| 6423 | This preprocessing symbol is defined to a non-zero value on hosts |
| 6424 | whose filesystems belong to the MS-DOS/MS-Windows family. Use this |
| 6425 | symbol to write conditional code which should only be compiled for |
| 6426 | such hosts. |
| 6427 | |
| 6428 | @findex IS_DIR_SEPARATOR |
| 6429 | @item IS_DIR_SEPARATOR (@var{c}) |
| 6430 | Evaluates to a non-zero value if @var{c} is a directory separator |
| 6431 | character. On Unix and GNU/Linux systems, only a slash @file{/} is |
| 6432 | such a character, but on Windows, both @file{/} and @file{\} will |
| 6433 | pass. |
| 6434 | |
| 6435 | @findex IS_ABSOLUTE_PATH |
| 6436 | @item IS_ABSOLUTE_PATH (@var{file}) |
| 6437 | Evaluates to a non-zero value if @var{file} is an absolute file name. |
| 6438 | For Unix and GNU/Linux hosts, a name which begins with a slash |
| 6439 | @file{/} is absolute. On DOS and Windows, @file{d:/foo} and |
| 6440 | @file{x:\bar} are also absolute file names. |
| 6441 | |
| 6442 | @findex FILENAME_CMP |
| 6443 | @item FILENAME_CMP (@var{f1}, @var{f2}) |
| 6444 | Calls a function which compares file names @var{f1} and @var{f2} as |
| 6445 | appropriate for the underlying host filesystem. For Posix systems, |
| 6446 | this simply calls @code{strcmp}; on case-insensitive filesystems it |
| 6447 | will call @code{strcasecmp} instead. |
| 6448 | |
| 6449 | @findex DIRNAME_SEPARATOR |
| 6450 | @item DIRNAME_SEPARATOR |
| 6451 | Evaluates to a character which separates directories in |
| 6452 | @code{PATH}-style lists, typically held in environment variables. |
| 6453 | This character is @samp{:} on Unix, @samp{;} on DOS and Windows. |
| 6454 | |
| 6455 | @findex SLASH_STRING |
| 6456 | @item SLASH_STRING |
| 6457 | This evaluates to a constant string you should use to produce an |
| 6458 | absolute filename from leading directories and the file's basename. |
| 6459 | @code{SLASH_STRING} is @code{"/"} on most systems, but might be |
| 6460 | @code{"\\"} for some Windows-based ports. |
| 6461 | @end table |
| 6462 | |
| 6463 | In addition to using these macros, be sure to use portable library |
| 6464 | functions whenever possible. For example, to extract a directory or a |
| 6465 | basename part from a file name, use the @code{dirname} and |
| 6466 | @code{basename} library functions (available in @code{libiberty} for |
| 6467 | platforms which don't provide them), instead of searching for a slash |
| 6468 | with @code{strrchr}. |
| 6469 | |
| 6470 | Another way to generalize @value{GDBN} along a particular interface is with an |
| 6471 | attribute struct. For example, @value{GDBN} has been generalized to handle |
| 6472 | multiple kinds of remote interfaces---not by @code{#ifdef}s everywhere, but |
| 6473 | by defining the @code{target_ops} structure and having a current target (as |
| 6474 | well as a stack of targets below it, for memory references). Whenever |
| 6475 | something needs to be done that depends on which remote interface we are |
| 6476 | using, a flag in the current target_ops structure is tested (e.g., |
| 6477 | @code{target_has_stack}), or a function is called through a pointer in the |
| 6478 | current target_ops structure. In this way, when a new remote interface |
| 6479 | is added, only one module needs to be touched---the one that actually |
| 6480 | implements the new remote interface. Other examples of |
| 6481 | attribute-structs are BFD access to multiple kinds of object file |
| 6482 | formats, or @value{GDBN}'s access to multiple source languages. |
| 6483 | |
| 6484 | Please avoid duplicating code. For example, in @value{GDBN} 3.x all |
| 6485 | the code interfacing between @code{ptrace} and the rest of |
| 6486 | @value{GDBN} was duplicated in @file{*-dep.c}, and so changing |
| 6487 | something was very painful. In @value{GDBN} 4.x, these have all been |
| 6488 | consolidated into @file{infptrace.c}. @file{infptrace.c} can deal |
| 6489 | with variations between systems the same way any system-independent |
| 6490 | file would (hooks, @code{#if defined}, etc.), and machines which are |
| 6491 | radically different don't need to use @file{infptrace.c} at all. |
| 6492 | |
| 6493 | All debugging code must be controllable using the @samp{set debug |
| 6494 | @var{module}} command. Do not use @code{printf} to print trace |
| 6495 | messages. Use @code{fprintf_unfiltered(gdb_stdlog, ...}. Do not use |
| 6496 | @code{#ifdef DEBUG}. |
| 6497 | |
| 6498 | @node Porting GDB |
| 6499 | |
| 6500 | @chapter Porting @value{GDBN} |
| 6501 | @cindex porting to new machines |
| 6502 | |
| 6503 | Most of the work in making @value{GDBN} compile on a new machine is in |
| 6504 | specifying the configuration of the machine. Porting a new |
| 6505 | architecture to @value{GDBN} can be broken into a number of steps. |
| 6506 | |
| 6507 | @itemize @bullet |
| 6508 | |
| 6509 | @item |
| 6510 | Ensure a @sc{bfd} exists for executables of the target architecture in |
| 6511 | the @file{bfd} directory. If one does not exist, create one by |
| 6512 | modifying an existing similar one. |
| 6513 | |
| 6514 | @item |
| 6515 | Implement a disassembler for the target architecture in the @file{opcodes} |
| 6516 | directory. |
| 6517 | |
| 6518 | @item |
| 6519 | Define the target architecture in the @file{gdb} directory |
| 6520 | (@pxref{Adding a New Target, , Adding a New Target}). Add the pattern |
| 6521 | for the new target to @file{configure.tgt} with the names of the files |
| 6522 | that contain the code. By convention the target architecture |
| 6523 | definition for an architecture @var{arch} is placed in |
| 6524 | @file{@var{arch}-tdep.c}. |
| 6525 | |
| 6526 | Within @file{@var{arch}-tdep.c} define the function |
| 6527 | @code{_initialize_@var{arch}_tdep} which calls |
| 6528 | @code{gdbarch_register} to create the new @code{@w{struct |
| 6529 | gdbarch}} for the architecture. |
| 6530 | |
| 6531 | @item |
| 6532 | If a new remote target is needed, consider adding a new remote target |
| 6533 | by defining a function |
| 6534 | @code{_initialize_remote_@var{arch}}. However if at all possible |
| 6535 | use the @value{GDBN} @emph{Remote Serial Protocol} for this and implement |
| 6536 | the server side protocol independently with the target. |
| 6537 | |
| 6538 | @item |
| 6539 | If desired implement a simulator in the @file{sim} directory. This |
| 6540 | should create the library @file{libsim.a} implementing the interface |
| 6541 | in @file{remote-sim.h} (found in the @file{include} directory). |
| 6542 | |
| 6543 | @item |
| 6544 | Build and test. If desired, lobby the @sc{gdb} steering group to |
| 6545 | have the new port included in the main distribution! |
| 6546 | |
| 6547 | @item |
| 6548 | Add a description of the new architecture to the main @value{GDBN} user |
| 6549 | guide (@pxref{Configuration Specific Information, , Configuration |
| 6550 | Specific Information, gdb, Debugging with @value{GDBN}}). |
| 6551 | |
| 6552 | @end itemize |
| 6553 | |
| 6554 | @node Versions and Branches |
| 6555 | @chapter Versions and Branches |
| 6556 | |
| 6557 | @section Versions |
| 6558 | |
| 6559 | @value{GDBN}'s version is determined by the file |
| 6560 | @file{gdb/version.in} and takes one of the following forms: |
| 6561 | |
| 6562 | @table @asis |
| 6563 | @item @var{major}.@var{minor} |
| 6564 | @itemx @var{major}.@var{minor}.@var{patchlevel} |
| 6565 | an official release (e.g., 6.2 or 6.2.1) |
| 6566 | @item @var{major}.@var{minor}.@var{patchlevel}.@var{YYYY}@var{MM}@var{DD} |
| 6567 | a snapshot taken at @var{YYYY}-@var{MM}-@var{DD}-gmt (e.g., |
| 6568 | 6.1.50.20020302, 6.1.90.20020304, or 6.1.0.20020308) |
| 6569 | @item @var{major}.@var{minor}.@var{patchlevel}.@var{YYYY}@var{MM}@var{DD}-cvs |
| 6570 | a @sc{cvs} check out drawn on @var{YYYY}-@var{MM}-@var{DD} (e.g., |
| 6571 | 6.1.50.20020302-cvs, 6.1.90.20020304-cvs, or 6.1.0.20020308-cvs) |
| 6572 | @item @var{major}.@var{minor}.@var{patchlevel}.@var{YYYY}@var{MM}@var{DD} (@var{vendor}) |
| 6573 | a vendor specific release of @value{GDBN}, that while based on@* |
| 6574 | @var{major}.@var{minor}.@var{patchlevel}.@var{YYYY}@var{MM}@var{DD}, |
| 6575 | may include additional changes |
| 6576 | @end table |
| 6577 | |
| 6578 | @value{GDBN}'s mainline uses the @var{major} and @var{minor} version |
| 6579 | numbers from the most recent release branch, with a @var{patchlevel} |
| 6580 | of 50. At the time each new release branch is created, the mainline's |
| 6581 | @var{major} and @var{minor} version numbers are updated. |
| 6582 | |
| 6583 | @value{GDBN}'s release branch is similar. When the branch is cut, the |
| 6584 | @var{patchlevel} is changed from 50 to 90. As draft releases are |
| 6585 | drawn from the branch, the @var{patchlevel} is incremented. Once the |
| 6586 | first release (@var{major}.@var{minor}) has been made, the |
| 6587 | @var{patchlevel} is set to 0 and updates have an incremented |
| 6588 | @var{patchlevel}. |
| 6589 | |
| 6590 | For snapshots, and @sc{cvs} check outs, it is also possible to |
| 6591 | identify the @sc{cvs} origin: |
| 6592 | |
| 6593 | @table @asis |
| 6594 | @item @var{major}.@var{minor}.50.@var{YYYY}@var{MM}@var{DD} |
| 6595 | drawn from the @sc{head} of mainline @sc{cvs} (e.g., 6.1.50.20020302) |
| 6596 | @item @var{major}.@var{minor}.90.@var{YYYY}@var{MM}@var{DD} |
| 6597 | @itemx @var{major}.@var{minor}.91.@var{YYYY}@var{MM}@var{DD} @dots{} |
| 6598 | drawn from a release branch prior to the release (e.g., |
| 6599 | 6.1.90.20020304) |
| 6600 | @item @var{major}.@var{minor}.0.@var{YYYY}@var{MM}@var{DD} |
| 6601 | @itemx @var{major}.@var{minor}.1.@var{YYYY}@var{MM}@var{DD} @dots{} |
| 6602 | drawn from a release branch after the release (e.g., 6.2.0.20020308) |
| 6603 | @end table |
| 6604 | |
| 6605 | If the previous @value{GDBN} version is 6.1 and the current version is |
| 6606 | 6.2, then, substituting 6 for @var{major} and 1 or 2 for @var{minor}, |
| 6607 | here's an illustration of a typical sequence: |
| 6608 | |
| 6609 | @smallexample |
| 6610 | <HEAD> |
| 6611 | | |
| 6612 | 6.1.50.20020302-cvs |
| 6613 | | |
| 6614 | +--------------------------. |
| 6615 | | <gdb_6_2-branch> |
| 6616 | | | |
| 6617 | 6.2.50.20020303-cvs 6.1.90 (draft #1) |
| 6618 | | | |
| 6619 | 6.2.50.20020304-cvs 6.1.90.20020304-cvs |
| 6620 | | | |
| 6621 | 6.2.50.20020305-cvs 6.1.91 (draft #2) |
| 6622 | | | |
| 6623 | 6.2.50.20020306-cvs 6.1.91.20020306-cvs |
| 6624 | | | |
| 6625 | 6.2.50.20020307-cvs 6.2 (release) |
| 6626 | | | |
| 6627 | 6.2.50.20020308-cvs 6.2.0.20020308-cvs |
| 6628 | | | |
| 6629 | 6.2.50.20020309-cvs 6.2.1 (update) |
| 6630 | | | |
| 6631 | 6.2.50.20020310-cvs <branch closed> |
| 6632 | | |
| 6633 | 6.2.50.20020311-cvs |
| 6634 | | |
| 6635 | +--------------------------. |
| 6636 | | <gdb_6_3-branch> |
| 6637 | | | |
| 6638 | 6.3.50.20020312-cvs 6.2.90 (draft #1) |
| 6639 | | | |
| 6640 | @end smallexample |
| 6641 | |
| 6642 | @section Release Branches |
| 6643 | @cindex Release Branches |
| 6644 | |
| 6645 | @value{GDBN} draws a release series (6.2, 6.2.1, @dots{}) from a |
| 6646 | single release branch, and identifies that branch using the @sc{cvs} |
| 6647 | branch tags: |
| 6648 | |
| 6649 | @smallexample |
| 6650 | gdb_@var{major}_@var{minor}-@var{YYYY}@var{MM}@var{DD}-branchpoint |
| 6651 | gdb_@var{major}_@var{minor}-branch |
| 6652 | gdb_@var{major}_@var{minor}-@var{YYYY}@var{MM}@var{DD}-release |
| 6653 | @end smallexample |
| 6654 | |
| 6655 | @emph{Pragmatics: To help identify the date at which a branch or |
| 6656 | release is made, both the branchpoint and release tags include the |
| 6657 | date that they are cut (@var{YYYY}@var{MM}@var{DD}) in the tag. The |
| 6658 | branch tag, denoting the head of the branch, does not need this.} |
| 6659 | |
| 6660 | @section Vendor Branches |
| 6661 | @cindex vendor branches |
| 6662 | |
| 6663 | To avoid version conflicts, vendors are expected to modify the file |
| 6664 | @file{gdb/version.in} to include a vendor unique alphabetic identifier |
| 6665 | (an official @value{GDBN} release never uses alphabetic characters in |
| 6666 | its version identifier). E.g., @samp{6.2widgit2}, or @samp{6.2 (Widgit |
| 6667 | Inc Patch 2)}. |
| 6668 | |
| 6669 | @section Experimental Branches |
| 6670 | @cindex experimental branches |
| 6671 | |
| 6672 | @subsection Guidelines |
| 6673 | |
| 6674 | @value{GDBN} permits the creation of branches, cut from the @sc{cvs} |
| 6675 | repository, for experimental development. Branches make it possible |
| 6676 | for developers to share preliminary work, and maintainers to examine |
| 6677 | significant new developments. |
| 6678 | |
| 6679 | The following are a set of guidelines for creating such branches: |
| 6680 | |
| 6681 | @table @emph |
| 6682 | |
| 6683 | @item a branch has an owner |
| 6684 | The owner can set further policy for a branch, but may not change the |
| 6685 | ground rules. In particular, they can set a policy for commits (be it |
| 6686 | adding more reviewers or deciding who can commit). |
| 6687 | |
| 6688 | @item all commits are posted |
| 6689 | All changes committed to a branch shall also be posted to |
| 6690 | @email{gdb-patches@@sourceware.org, the @value{GDBN} patches |
| 6691 | mailing list}. While commentary on such changes are encouraged, people |
| 6692 | should remember that the changes only apply to a branch. |
| 6693 | |
| 6694 | @item all commits are covered by an assignment |
| 6695 | This ensures that all changes belong to the Free Software Foundation, |
| 6696 | and avoids the possibility that the branch may become contaminated. |
| 6697 | |
| 6698 | @item a branch is focused |
| 6699 | A focused branch has a single objective or goal, and does not contain |
| 6700 | unnecessary or irrelevant changes. Cleanups, where identified, being |
| 6701 | be pushed into the mainline as soon as possible. |
| 6702 | |
| 6703 | @item a branch tracks mainline |
| 6704 | This keeps the level of divergence under control. It also keeps the |
| 6705 | pressure on developers to push cleanups and other stuff into the |
| 6706 | mainline. |
| 6707 | |
| 6708 | @item a branch shall contain the entire @value{GDBN} module |
| 6709 | The @value{GDBN} module @code{gdb} should be specified when creating a |
| 6710 | branch (branches of individual files should be avoided). @xref{Tags}. |
| 6711 | |
| 6712 | @item a branch shall be branded using @file{version.in} |
| 6713 | The file @file{gdb/version.in} shall be modified so that it identifies |
| 6714 | the branch @var{owner} and branch @var{name}, e.g., |
| 6715 | @samp{6.2.50.20030303_owner_name} or @samp{6.2 (Owner Name)}. |
| 6716 | |
| 6717 | @end table |
| 6718 | |
| 6719 | @subsection Tags |
| 6720 | @anchor{Tags} |
| 6721 | |
| 6722 | To simplify the identification of @value{GDBN} branches, the following |
| 6723 | branch tagging convention is strongly recommended: |
| 6724 | |
| 6725 | @table @code |
| 6726 | |
| 6727 | @item @var{owner}_@var{name}-@var{YYYYMMDD}-branchpoint |
| 6728 | @itemx @var{owner}_@var{name}-@var{YYYYMMDD}-branch |
| 6729 | The branch point and corresponding branch tag. @var{YYYYMMDD} is the |
| 6730 | date that the branch was created. A branch is created using the |
| 6731 | sequence: @anchor{experimental branch tags} |
| 6732 | @smallexample |
| 6733 | cvs rtag @var{owner}_@var{name}-@var{YYYYMMDD}-branchpoint gdb |
| 6734 | cvs rtag -b -r @var{owner}_@var{name}-@var{YYYYMMDD}-branchpoint \ |
| 6735 | @var{owner}_@var{name}-@var{YYYYMMDD}-branch gdb |
| 6736 | @end smallexample |
| 6737 | |
| 6738 | @item @var{owner}_@var{name}-@var{yyyymmdd}-mergepoint |
| 6739 | The tagged point, on the mainline, that was used when merging the branch |
| 6740 | on @var{yyyymmdd}. To merge in all changes since the branch was cut, |
| 6741 | use a command sequence like: |
| 6742 | @smallexample |
| 6743 | cvs rtag @var{owner}_@var{name}-@var{yyyymmdd}-mergepoint gdb |
| 6744 | cvs update \ |
| 6745 | -j@var{owner}_@var{name}-@var{YYYYMMDD}-branchpoint |
| 6746 | -j@var{owner}_@var{name}-@var{yyyymmdd}-mergepoint |
| 6747 | @end smallexample |
| 6748 | @noindent |
| 6749 | Similar sequences can be used to just merge in changes since the last |
| 6750 | merge. |
| 6751 | |
| 6752 | @end table |
| 6753 | |
| 6754 | @noindent |
| 6755 | For further information on @sc{cvs}, see |
| 6756 | @uref{http://www.gnu.org/software/cvs/, Concurrent Versions System}. |
| 6757 | |
| 6758 | @node Start of New Year Procedure |
| 6759 | @chapter Start of New Year Procedure |
| 6760 | @cindex new year procedure |
| 6761 | |
| 6762 | At the start of each new year, the following actions should be performed: |
| 6763 | |
| 6764 | @itemize @bullet |
| 6765 | @item |
| 6766 | Rotate the ChangeLog file |
| 6767 | |
| 6768 | The current @file{ChangeLog} file should be renamed into |
| 6769 | @file{ChangeLog-YYYY} where YYYY is the year that has just passed. |
| 6770 | A new @file{ChangeLog} file should be created, and its contents should |
| 6771 | contain a reference to the previous ChangeLog. The following should |
| 6772 | also be preserved at the end of the new ChangeLog, in order to provide |
| 6773 | the appropriate settings when editing this file with Emacs: |
| 6774 | @smallexample |
| 6775 | Local Variables: |
| 6776 | mode: change-log |
| 6777 | left-margin: 8 |
| 6778 | fill-column: 74 |
| 6779 | version-control: never |
| 6780 | coding: utf-8 |
| 6781 | End: |
| 6782 | @end smallexample |
| 6783 | |
| 6784 | @item |
| 6785 | Add an entry for the newly created ChangeLog file (@file{ChangeLog-YYYY}) |
| 6786 | in @file{gdb/config/djgpp/fnchange.lst}. |
| 6787 | |
| 6788 | @item |
| 6789 | Update the copyright year in the startup message |
| 6790 | |
| 6791 | Update the copyright year in: |
| 6792 | @itemize @bullet |
| 6793 | @item |
| 6794 | file @file{top.c}, function @code{print_gdb_version} |
| 6795 | @item |
| 6796 | file @file{gdbserver/server.c}, function @code{gdbserver_version} |
| 6797 | @item |
| 6798 | file @file{gdbserver/gdbreplay.c}, function @code{gdbreplay_version} |
| 6799 | @end itemize |
| 6800 | |
| 6801 | @item |
| 6802 | Run the @file{copyright.sh} script to add the new year in the copyright |
| 6803 | notices of most source files. This script requires Emacs 22 or later to |
| 6804 | be installed. |
| 6805 | |
| 6806 | @item |
| 6807 | The new year also needs to be added manually in all other files that |
| 6808 | are not already taken care of by the @file{copyright.sh} script: |
| 6809 | @itemize @bullet |
| 6810 | @item |
| 6811 | @file{*.s} |
| 6812 | @item |
| 6813 | @file{*.f} |
| 6814 | @item |
| 6815 | @file{*.f90} |
| 6816 | @item |
| 6817 | @file{*.igen} |
| 6818 | @item |
| 6819 | @file{*.ac} |
| 6820 | @item |
| 6821 | @file{*.texi} |
| 6822 | @item |
| 6823 | @file{*.texinfo} |
| 6824 | @item |
| 6825 | @file{*.tex} |
| 6826 | @item |
| 6827 | @file{*.defs} |
| 6828 | @item |
| 6829 | @file{*.1} |
| 6830 | @end itemize |
| 6831 | |
| 6832 | @end itemize |
| 6833 | |
| 6834 | @node Releasing GDB |
| 6835 | |
| 6836 | @chapter Releasing @value{GDBN} |
| 6837 | @cindex making a new release of gdb |
| 6838 | |
| 6839 | @section Branch Commit Policy |
| 6840 | |
| 6841 | The branch commit policy is pretty slack. @value{GDBN} releases 5.0, |
| 6842 | 5.1 and 5.2 all used the below: |
| 6843 | |
| 6844 | @itemize @bullet |
| 6845 | @item |
| 6846 | The @file{gdb/MAINTAINERS} file still holds. |
| 6847 | @item |
| 6848 | Don't fix something on the branch unless/until it is also fixed in the |
| 6849 | trunk. If this isn't possible, mentioning it in the @file{gdb/PROBLEMS} |
| 6850 | file is better than committing a hack. |
| 6851 | @item |
| 6852 | When considering a patch for the branch, suggested criteria include: |
| 6853 | Does it fix a build? Does it fix the sequence @kbd{break main; run} |
| 6854 | when debugging a static binary? |
| 6855 | @item |
| 6856 | The further a change is from the core of @value{GDBN}, the less likely |
| 6857 | the change will worry anyone (e.g., target specific code). |
| 6858 | @item |
| 6859 | Only post a proposal to change the core of @value{GDBN} after you've |
| 6860 | sent individual bribes to all the people listed in the |
| 6861 | @file{MAINTAINERS} file @t{;-)} |
| 6862 | @end itemize |
| 6863 | |
| 6864 | @emph{Pragmatics: Provided updates are restricted to non-core |
| 6865 | functionality there is little chance that a broken change will be fatal. |
| 6866 | This means that changes such as adding a new architectures or (within |
| 6867 | reason) support for a new host are considered acceptable.} |
| 6868 | |
| 6869 | |
| 6870 | @section Obsoleting code |
| 6871 | |
| 6872 | Before anything else, poke the other developers (and around the source |
| 6873 | code) to see if there is anything that can be removed from @value{GDBN} |
| 6874 | (an old target, an unused file). |
| 6875 | |
| 6876 | Obsolete code is identified by adding an @code{OBSOLETE} prefix to every |
| 6877 | line. Doing this means that it is easy to identify something that has |
| 6878 | been obsoleted when greping through the sources. |
| 6879 | |
| 6880 | The process is done in stages --- this is mainly to ensure that the |
| 6881 | wider @value{GDBN} community has a reasonable opportunity to respond. |
| 6882 | Remember, everything on the Internet takes a week. |
| 6883 | |
| 6884 | @enumerate |
| 6885 | @item |
| 6886 | Post the proposal on @email{gdb@@sourceware.org, the GDB mailing |
| 6887 | list} Creating a bug report to track the task's state, is also highly |
| 6888 | recommended. |
| 6889 | @item |
| 6890 | Wait a week or so. |
| 6891 | @item |
| 6892 | Post the proposal on @email{gdb-announce@@sourceware.org, the GDB |
| 6893 | Announcement mailing list}. |
| 6894 | @item |
| 6895 | Wait a week or so. |
| 6896 | @item |
| 6897 | Go through and edit all relevant files and lines so that they are |
| 6898 | prefixed with the word @code{OBSOLETE}. |
| 6899 | @item |
| 6900 | Wait until the next GDB version, containing this obsolete code, has been |
| 6901 | released. |
| 6902 | @item |
| 6903 | Remove the obsolete code. |
| 6904 | @end enumerate |
| 6905 | |
| 6906 | @noindent |
| 6907 | @emph{Maintainer note: While removing old code is regrettable it is |
| 6908 | hopefully better for @value{GDBN}'s long term development. Firstly it |
| 6909 | helps the developers by removing code that is either no longer relevant |
| 6910 | or simply wrong. Secondly since it removes any history associated with |
| 6911 | the file (effectively clearing the slate) the developer has a much freer |
| 6912 | hand when it comes to fixing broken files.} |
| 6913 | |
| 6914 | |
| 6915 | |
| 6916 | @section Before the Branch |
| 6917 | |
| 6918 | The most important objective at this stage is to find and fix simple |
| 6919 | changes that become a pain to track once the branch is created. For |
| 6920 | instance, configuration problems that stop @value{GDBN} from even |
| 6921 | building. If you can't get the problem fixed, document it in the |
| 6922 | @file{gdb/PROBLEMS} file. |
| 6923 | |
| 6924 | @subheading Prompt for @file{gdb/NEWS} |
| 6925 | |
| 6926 | People always forget. Send a post reminding them but also if you know |
| 6927 | something interesting happened add it yourself. The @code{schedule} |
| 6928 | script will mention this in its e-mail. |
| 6929 | |
| 6930 | @subheading Review @file{gdb/README} |
| 6931 | |
| 6932 | Grab one of the nightly snapshots and then walk through the |
| 6933 | @file{gdb/README} looking for anything that can be improved. The |
| 6934 | @code{schedule} script will mention this in its e-mail. |
| 6935 | |
| 6936 | @subheading Refresh any imported files. |
| 6937 | |
| 6938 | A number of files are taken from external repositories. They include: |
| 6939 | |
| 6940 | @itemize @bullet |
| 6941 | @item |
| 6942 | @file{texinfo/texinfo.tex} |
| 6943 | @item |
| 6944 | @file{config.guess} et.@: al.@: (see the top-level @file{MAINTAINERS} |
| 6945 | file) |
| 6946 | @item |
| 6947 | @file{etc/standards.texi}, @file{etc/make-stds.texi} |
| 6948 | @end itemize |
| 6949 | |
| 6950 | @subheading Check the ARI |
| 6951 | |
| 6952 | @uref{http://sourceware.org/gdb/ari,,A.R.I.} is an @code{awk} script |
| 6953 | (Awk Regression Index ;-) that checks for a number of errors and coding |
| 6954 | conventions. The checks include things like using @code{malloc} instead |
| 6955 | of @code{xmalloc} and file naming problems. There shouldn't be any |
| 6956 | regressions. |
| 6957 | |
| 6958 | @subsection Review the bug data base |
| 6959 | |
| 6960 | Close anything obviously fixed. |
| 6961 | |
| 6962 | @subsection Check all cross targets build |
| 6963 | |
| 6964 | The targets are listed in @file{gdb/MAINTAINERS}. |
| 6965 | |
| 6966 | |
| 6967 | @section Cut the Branch |
| 6968 | |
| 6969 | @subheading Create the branch |
| 6970 | |
| 6971 | @smallexample |
| 6972 | $ u=5.1 |
| 6973 | $ v=5.2 |
| 6974 | $ V=`echo $v | sed 's/\./_/g'` |
| 6975 | $ D=`date -u +%Y-%m-%d` |
| 6976 | $ echo $u $V $D |
| 6977 | 5.1 5_2 2002-03-03 |
| 6978 | $ echo cvs -f -d :ext:sourceware.org:/cvs/src rtag \ |
| 6979 | -D $D-gmt gdb_$V-$D-branchpoint insight |
| 6980 | cvs -f -d :ext:sourceware.org:/cvs/src rtag |
| 6981 | -D 2002-03-03-gmt gdb_5_2-2002-03-03-branchpoint insight |
| 6982 | $ ^echo ^^ |
| 6983 | ... |
| 6984 | $ echo cvs -f -d :ext:sourceware.org:/cvs/src rtag \ |
| 6985 | -b -r gdb_$V-$D-branchpoint gdb_$V-branch insight |
| 6986 | cvs -f -d :ext:sourceware.org:/cvs/src rtag \ |
| 6987 | -b -r gdb_5_2-2002-03-03-branchpoint gdb_5_2-branch insight |
| 6988 | $ ^echo ^^ |
| 6989 | ... |
| 6990 | $ |
| 6991 | @end smallexample |
| 6992 | |
| 6993 | @itemize @bullet |
| 6994 | @item |
| 6995 | By using @kbd{-D YYYY-MM-DD-gmt}, the branch is forced to an exact |
| 6996 | date/time. |
| 6997 | @item |
| 6998 | The trunk is first tagged so that the branch point can easily be found. |
| 6999 | @item |
| 7000 | Insight, which includes @value{GDBN}, is tagged at the same time. |
| 7001 | @item |
| 7002 | @file{version.in} gets bumped to avoid version number conflicts. |
| 7003 | @item |
| 7004 | The reading of @file{.cvsrc} is disabled using @file{-f}. |
| 7005 | @end itemize |
| 7006 | |
| 7007 | @subheading Update @file{version.in} |
| 7008 | |
| 7009 | @smallexample |
| 7010 | $ u=5.1 |
| 7011 | $ v=5.2 |
| 7012 | $ V=`echo $v | sed 's/\./_/g'` |
| 7013 | $ echo $u $v$V |
| 7014 | 5.1 5_2 |
| 7015 | $ cd /tmp |
| 7016 | $ echo cvs -f -d :ext:sourceware.org:/cvs/src co \ |
| 7017 | -r gdb_$V-branch src/gdb/version.in |
| 7018 | cvs -f -d :ext:sourceware.org:/cvs/src co |
| 7019 | -r gdb_5_2-branch src/gdb/version.in |
| 7020 | $ ^echo ^^ |
| 7021 | U src/gdb/version.in |
| 7022 | $ cd src/gdb |
| 7023 | $ echo $u.90-0000-00-00-cvs > version.in |
| 7024 | $ cat version.in |
| 7025 | 5.1.90-0000-00-00-cvs |
| 7026 | $ cvs -f commit version.in |
| 7027 | @end smallexample |
| 7028 | |
| 7029 | @itemize @bullet |
| 7030 | @item |
| 7031 | @file{0000-00-00} is used as a date to pump prime the version.in update |
| 7032 | mechanism. |
| 7033 | @item |
| 7034 | @file{.90} and the previous branch version are used as fairly arbitrary |
| 7035 | initial branch version number. |
| 7036 | @end itemize |
| 7037 | |
| 7038 | |
| 7039 | @subheading Update the web and news pages |
| 7040 | |
| 7041 | Something? |
| 7042 | |
| 7043 | @subheading Tweak cron to track the new branch |
| 7044 | |
| 7045 | The file @file{gdbadmin/cron/crontab} contains gdbadmin's cron table. |
| 7046 | This file needs to be updated so that: |
| 7047 | |
| 7048 | @itemize @bullet |
| 7049 | @item |
| 7050 | A daily timestamp is added to the file @file{version.in}. |
| 7051 | @item |
| 7052 | The new branch is included in the snapshot process. |
| 7053 | @end itemize |
| 7054 | |
| 7055 | @noindent |
| 7056 | See the file @file{gdbadmin/cron/README} for how to install the updated |
| 7057 | cron table. |
| 7058 | |
| 7059 | The file @file{gdbadmin/ss/README} should also be reviewed to reflect |
| 7060 | any changes. That file is copied to both the branch/ and current/ |
| 7061 | snapshot directories. |
| 7062 | |
| 7063 | |
| 7064 | @subheading Update the NEWS and README files |
| 7065 | |
| 7066 | The @file{NEWS} file needs to be updated so that on the branch it refers |
| 7067 | to @emph{changes in the current release} while on the trunk it also |
| 7068 | refers to @emph{changes since the current release}. |
| 7069 | |
| 7070 | The @file{README} file needs to be updated so that it refers to the |
| 7071 | current release. |
| 7072 | |
| 7073 | @subheading Post the branch info |
| 7074 | |
| 7075 | Send an announcement to the mailing lists: |
| 7076 | |
| 7077 | @itemize @bullet |
| 7078 | @item |
| 7079 | @email{gdb-announce@@sourceware.org, GDB Announcement mailing list} |
| 7080 | @item |
| 7081 | @email{gdb@@sourceware.org, GDB Discussion mailing list} and |
| 7082 | @email{gdb-testers@@sourceware.org, GDB Testers mailing list} |
| 7083 | @end itemize |
| 7084 | |
| 7085 | @emph{Pragmatics: The branch creation is sent to the announce list to |
| 7086 | ensure that people people not subscribed to the higher volume discussion |
| 7087 | list are alerted.} |
| 7088 | |
| 7089 | The announcement should include: |
| 7090 | |
| 7091 | @itemize @bullet |
| 7092 | @item |
| 7093 | The branch tag. |
| 7094 | @item |
| 7095 | How to check out the branch using CVS. |
| 7096 | @item |
| 7097 | The date/number of weeks until the release. |
| 7098 | @item |
| 7099 | The branch commit policy still holds. |
| 7100 | @end itemize |
| 7101 | |
| 7102 | @section Stabilize the branch |
| 7103 | |
| 7104 | Something goes here. |
| 7105 | |
| 7106 | @section Create a Release |
| 7107 | |
| 7108 | The process of creating and then making available a release is broken |
| 7109 | down into a number of stages. The first part addresses the technical |
| 7110 | process of creating a releasable tar ball. The later stages address the |
| 7111 | process of releasing that tar ball. |
| 7112 | |
| 7113 | When making a release candidate just the first section is needed. |
| 7114 | |
| 7115 | @subsection Create a release candidate |
| 7116 | |
| 7117 | The objective at this stage is to create a set of tar balls that can be |
| 7118 | made available as a formal release (or as a less formal release |
| 7119 | candidate). |
| 7120 | |
| 7121 | @subsubheading Freeze the branch |
| 7122 | |
| 7123 | Send out an e-mail notifying everyone that the branch is frozen to |
| 7124 | @email{gdb-patches@@sourceware.org}. |
| 7125 | |
| 7126 | @subsubheading Establish a few defaults. |
| 7127 | |
| 7128 | @smallexample |
| 7129 | $ b=gdb_5_2-branch |
| 7130 | $ v=5.2 |
| 7131 | $ t=/sourceware/snapshot-tmp/gdbadmin-tmp |
| 7132 | $ echo $t/$b/$v |
| 7133 | /sourceware/snapshot-tmp/gdbadmin-tmp/gdb_5_2-branch/5.2 |
| 7134 | $ mkdir -p $t/$b/$v |
| 7135 | $ cd $t/$b/$v |
| 7136 | $ pwd |
| 7137 | /sourceware/snapshot-tmp/gdbadmin-tmp/gdb_5_2-branch/5.2 |
| 7138 | $ which autoconf |
| 7139 | /home/gdbadmin/bin/autoconf |
| 7140 | $ |
| 7141 | @end smallexample |
| 7142 | |
| 7143 | @noindent |
| 7144 | Notes: |
| 7145 | |
| 7146 | @itemize @bullet |
| 7147 | @item |
| 7148 | Check the @code{autoconf} version carefully. You want to be using the |
| 7149 | version documented in the toplevel @file{README-maintainer-mode} file. |
| 7150 | It is very unlikely that the version of @code{autoconf} installed in |
| 7151 | system directories (e.g., @file{/usr/bin/autoconf}) is correct. |
| 7152 | @end itemize |
| 7153 | |
| 7154 | @subsubheading Check out the relevant modules: |
| 7155 | |
| 7156 | @smallexample |
| 7157 | $ for m in gdb insight |
| 7158 | do |
| 7159 | ( mkdir -p $m && cd $m && cvs -q -f -d /cvs/src co -P -r $b $m ) |
| 7160 | done |
| 7161 | $ |
| 7162 | @end smallexample |
| 7163 | |
| 7164 | @noindent |
| 7165 | Note: |
| 7166 | |
| 7167 | @itemize @bullet |
| 7168 | @item |
| 7169 | The reading of @file{.cvsrc} is disabled (@file{-f}) so that there isn't |
| 7170 | any confusion between what is written here and what your local |
| 7171 | @code{cvs} really does. |
| 7172 | @end itemize |
| 7173 | |
| 7174 | @subsubheading Update relevant files. |
| 7175 | |
| 7176 | @table @file |
| 7177 | |
| 7178 | @item gdb/NEWS |
| 7179 | |
| 7180 | Major releases get their comments added as part of the mainline. Minor |
| 7181 | releases should probably mention any significant bugs that were fixed. |
| 7182 | |
| 7183 | Don't forget to include the @file{ChangeLog} entry. |
| 7184 | |
| 7185 | @smallexample |
| 7186 | $ emacs gdb/src/gdb/NEWS |
| 7187 | ... |
| 7188 | c-x 4 a |
| 7189 | ... |
| 7190 | c-x c-s c-x c-c |
| 7191 | $ cp gdb/src/gdb/NEWS insight/src/gdb/NEWS |
| 7192 | $ cp gdb/src/gdb/ChangeLog insight/src/gdb/ChangeLog |
| 7193 | @end smallexample |
| 7194 | |
| 7195 | @item gdb/README |
| 7196 | |
| 7197 | You'll need to update: |
| 7198 | |
| 7199 | @itemize @bullet |
| 7200 | @item |
| 7201 | The version. |
| 7202 | @item |
| 7203 | The update date. |
| 7204 | @item |
| 7205 | Who did it. |
| 7206 | @end itemize |
| 7207 | |
| 7208 | @smallexample |
| 7209 | $ emacs gdb/src/gdb/README |
| 7210 | ... |
| 7211 | c-x 4 a |
| 7212 | ... |
| 7213 | c-x c-s c-x c-c |
| 7214 | $ cp gdb/src/gdb/README insight/src/gdb/README |
| 7215 | $ cp gdb/src/gdb/ChangeLog insight/src/gdb/ChangeLog |
| 7216 | @end smallexample |
| 7217 | |
| 7218 | @emph{Maintainer note: Hopefully the @file{README} file was reviewed |
| 7219 | before the initial branch was cut so just a simple substitute is needed |
| 7220 | to get it updated.} |
| 7221 | |
| 7222 | @emph{Maintainer note: Other projects generate @file{README} and |
| 7223 | @file{INSTALL} from the core documentation. This might be worth |
| 7224 | pursuing.} |
| 7225 | |
| 7226 | @item gdb/version.in |
| 7227 | |
| 7228 | @smallexample |
| 7229 | $ echo $v > gdb/src/gdb/version.in |
| 7230 | $ cat gdb/src/gdb/version.in |
| 7231 | 5.2 |
| 7232 | $ emacs gdb/src/gdb/version.in |
| 7233 | ... |
| 7234 | c-x 4 a |
| 7235 | ... Bump to version ... |
| 7236 | c-x c-s c-x c-c |
| 7237 | $ cp gdb/src/gdb/version.in insight/src/gdb/version.in |
| 7238 | $ cp gdb/src/gdb/ChangeLog insight/src/gdb/ChangeLog |
| 7239 | @end smallexample |
| 7240 | |
| 7241 | @end table |
| 7242 | |
| 7243 | @subsubheading Do the dirty work |
| 7244 | |
| 7245 | This is identical to the process used to create the daily snapshot. |
| 7246 | |
| 7247 | @smallexample |
| 7248 | $ for m in gdb insight |
| 7249 | do |
| 7250 | ( cd $m/src && gmake -f src-release $m.tar ) |
| 7251 | done |
| 7252 | @end smallexample |
| 7253 | |
| 7254 | If the top level source directory does not have @file{src-release} |
| 7255 | (@value{GDBN} version 5.3.1 or earlier), try these commands instead: |
| 7256 | |
| 7257 | @smallexample |
| 7258 | $ for m in gdb insight |
| 7259 | do |
| 7260 | ( cd $m/src && gmake -f Makefile.in $m.tar ) |
| 7261 | done |
| 7262 | @end smallexample |
| 7263 | |
| 7264 | @subsubheading Check the source files |
| 7265 | |
| 7266 | You're looking for files that have mysteriously disappeared. |
| 7267 | @kbd{distclean} has the habit of deleting files it shouldn't. Watch out |
| 7268 | for the @file{version.in} update @kbd{cronjob}. |
| 7269 | |
| 7270 | @smallexample |
| 7271 | $ ( cd gdb/src && cvs -f -q -n update ) |
| 7272 | M djunpack.bat |
| 7273 | ? gdb-5.1.91.tar |
| 7274 | ? proto-toplev |
| 7275 | @dots{} lots of generated files @dots{} |
| 7276 | M gdb/ChangeLog |
| 7277 | M gdb/NEWS |
| 7278 | M gdb/README |
| 7279 | M gdb/version.in |
| 7280 | @dots{} lots of generated files @dots{} |
| 7281 | $ |
| 7282 | @end smallexample |
| 7283 | |
| 7284 | @noindent |
| 7285 | @emph{Don't worry about the @file{gdb.info-??} or |
| 7286 | @file{gdb/p-exp.tab.c}. They were generated (and yes @file{gdb.info-1} |
| 7287 | was also generated only something strange with CVS means that they |
| 7288 | didn't get suppressed). Fixing it would be nice though.} |
| 7289 | |
| 7290 | @subsubheading Create compressed versions of the release |
| 7291 | |
| 7292 | @smallexample |
| 7293 | $ cp */src/*.tar . |
| 7294 | $ cp */src/*.bz2 . |
| 7295 | $ ls -F |
| 7296 | gdb/ gdb-5.2.tar insight/ insight-5.2.tar |
| 7297 | $ for m in gdb insight |
| 7298 | do |
| 7299 | bzip2 -v -9 -c $m-$v.tar > $m-$v.tar.bz2 |
| 7300 | gzip -v -9 -c $m-$v.tar > $m-$v.tar.gz |
| 7301 | done |
| 7302 | $ |
| 7303 | @end smallexample |
| 7304 | |
| 7305 | @noindent |
| 7306 | Note: |
| 7307 | |
| 7308 | @itemize @bullet |
| 7309 | @item |
| 7310 | A pipe such as @kbd{bunzip2 < xxx.bz2 | gzip -9 > xxx.gz} is not since, |
| 7311 | in that mode, @code{gzip} does not know the name of the file and, hence, |
| 7312 | can not include it in the compressed file. This is also why the release |
| 7313 | process runs @code{tar} and @code{bzip2} as separate passes. |
| 7314 | @end itemize |
| 7315 | |
| 7316 | @subsection Sanity check the tar ball |
| 7317 | |
| 7318 | Pick a popular machine (Solaris/PPC?) and try the build on that. |
| 7319 | |
| 7320 | @smallexample |
| 7321 | $ bunzip2 < gdb-5.2.tar.bz2 | tar xpf - |
| 7322 | $ cd gdb-5.2 |
| 7323 | $ ./configure |
| 7324 | $ make |
| 7325 | @dots{} |
| 7326 | $ ./gdb/gdb ./gdb/gdb |
| 7327 | GNU gdb 5.2 |
| 7328 | @dots{} |
| 7329 | (gdb) b main |
| 7330 | Breakpoint 1 at 0x80732bc: file main.c, line 734. |
| 7331 | (gdb) run |
| 7332 | Starting program: /tmp/gdb-5.2/gdb/gdb |
| 7333 | |
| 7334 | Breakpoint 1, main (argc=1, argv=0xbffff8b4) at main.c:734 |
| 7335 | 734 catch_errors (captured_main, &args, "", RETURN_MASK_ALL); |
| 7336 | (gdb) print args |
| 7337 | $1 = @{argc = 136426532, argv = 0x821b7f0@} |
| 7338 | (gdb) |
| 7339 | @end smallexample |
| 7340 | |
| 7341 | @subsection Make a release candidate available |
| 7342 | |
| 7343 | If this is a release candidate then the only remaining steps are: |
| 7344 | |
| 7345 | @enumerate |
| 7346 | @item |
| 7347 | Commit @file{version.in} and @file{ChangeLog} |
| 7348 | @item |
| 7349 | Tweak @file{version.in} (and @file{ChangeLog} to read |
| 7350 | @var{L}.@var{M}.@var{N}-0000-00-00-cvs so that the version update |
| 7351 | process can restart. |
| 7352 | @item |
| 7353 | Make the release candidate available in |
| 7354 | @uref{ftp://sourceware.org/pub/gdb/snapshots/branch} |
| 7355 | @item |
| 7356 | Notify the relevant mailing lists ( @email{gdb@@sourceware.org} and |
| 7357 | @email{gdb-testers@@sourceware.org} that the candidate is available. |
| 7358 | @end enumerate |
| 7359 | |
| 7360 | @subsection Make a formal release available |
| 7361 | |
| 7362 | (And you thought all that was required was to post an e-mail.) |
| 7363 | |
| 7364 | @subsubheading Install on sware |
| 7365 | |
| 7366 | Copy the new files to both the release and the old release directory: |
| 7367 | |
| 7368 | @smallexample |
| 7369 | $ cp *.bz2 *.gz ~ftp/pub/gdb/old-releases/ |
| 7370 | $ cp *.bz2 *.gz ~ftp/pub/gdb/releases |
| 7371 | @end smallexample |
| 7372 | |
| 7373 | @noindent |
| 7374 | Clean up the releases directory so that only the most recent releases |
| 7375 | are available (e.g.@: keep 5.2 and 5.2.1 but remove 5.1): |
| 7376 | |
| 7377 | @smallexample |
| 7378 | $ cd ~ftp/pub/gdb/releases |
| 7379 | $ rm @dots{} |
| 7380 | @end smallexample |
| 7381 | |
| 7382 | @noindent |
| 7383 | Update the file @file{README} and @file{.message} in the releases |
| 7384 | directory: |
| 7385 | |
| 7386 | @smallexample |
| 7387 | $ vi README |
| 7388 | @dots{} |
| 7389 | $ rm -f .message |
| 7390 | $ ln README .message |
| 7391 | @end smallexample |
| 7392 | |
| 7393 | @subsubheading Update the web pages. |
| 7394 | |
| 7395 | @table @file |
| 7396 | |
| 7397 | @item htdocs/download/ANNOUNCEMENT |
| 7398 | This file, which is posted as the official announcement, includes: |
| 7399 | @itemize @bullet |
| 7400 | @item |
| 7401 | General announcement. |
| 7402 | @item |
| 7403 | News. If making an @var{M}.@var{N}.1 release, retain the news from |
| 7404 | earlier @var{M}.@var{N} release. |
| 7405 | @item |
| 7406 | Errata. |
| 7407 | @end itemize |
| 7408 | |
| 7409 | @item htdocs/index.html |
| 7410 | @itemx htdocs/news/index.html |
| 7411 | @itemx htdocs/download/index.html |
| 7412 | These files include: |
| 7413 | @itemize @bullet |
| 7414 | @item |
| 7415 | Announcement of the most recent release. |
| 7416 | @item |
| 7417 | News entry (remember to update both the top level and the news directory). |
| 7418 | @end itemize |
| 7419 | These pages also need to be regenerate using @code{index.sh}. |
| 7420 | |
| 7421 | @item download/onlinedocs/ |
| 7422 | You need to find the magic command that is used to generate the online |
| 7423 | docs from the @file{.tar.bz2}. The best way is to look in the output |
| 7424 | from one of the nightly @code{cron} jobs and then just edit accordingly. |
| 7425 | Something like: |
| 7426 | |
| 7427 | @smallexample |
| 7428 | $ ~/ss/update-web-docs \ |
| 7429 | ~ftp/pub/gdb/releases/gdb-5.2.tar.bz2 \ |
| 7430 | $PWD/www \ |
| 7431 | /www/sourceware/htdocs/gdb/download/onlinedocs \ |
| 7432 | gdb |
| 7433 | @end smallexample |
| 7434 | |
| 7435 | @item download/ari/ |
| 7436 | Just like the online documentation. Something like: |
| 7437 | |
| 7438 | @smallexample |
| 7439 | $ /bin/sh ~/ss/update-web-ari \ |
| 7440 | ~ftp/pub/gdb/releases/gdb-5.2.tar.bz2 \ |
| 7441 | $PWD/www \ |
| 7442 | /www/sourceware/htdocs/gdb/download/ari \ |
| 7443 | gdb |
| 7444 | @end smallexample |
| 7445 | |
| 7446 | @end table |
| 7447 | |
| 7448 | @subsubheading Shadow the pages onto gnu |
| 7449 | |
| 7450 | Something goes here. |
| 7451 | |
| 7452 | |
| 7453 | @subsubheading Install the @value{GDBN} tar ball on GNU |
| 7454 | |
| 7455 | At the time of writing, the GNU machine was @kbd{gnudist.gnu.org} in |
| 7456 | @file{~ftp/gnu/gdb}. |
| 7457 | |
| 7458 | @subsubheading Make the @file{ANNOUNCEMENT} |
| 7459 | |
| 7460 | Post the @file{ANNOUNCEMENT} file you created above to: |
| 7461 | |
| 7462 | @itemize @bullet |
| 7463 | @item |
| 7464 | @email{gdb-announce@@sourceware.org, GDB Announcement mailing list} |
| 7465 | @item |
| 7466 | @email{info-gnu@@gnu.org, General GNU Announcement list} (but delay it a |
| 7467 | day or so to let things get out) |
| 7468 | @item |
| 7469 | @email{bug-gdb@@gnu.org, GDB Bug Report mailing list} |
| 7470 | @end itemize |
| 7471 | |
| 7472 | @subsection Cleanup |
| 7473 | |
| 7474 | The release is out but you're still not finished. |
| 7475 | |
| 7476 | @subsubheading Commit outstanding changes |
| 7477 | |
| 7478 | In particular you'll need to commit any changes to: |
| 7479 | |
| 7480 | @itemize @bullet |
| 7481 | @item |
| 7482 | @file{gdb/ChangeLog} |
| 7483 | @item |
| 7484 | @file{gdb/version.in} |
| 7485 | @item |
| 7486 | @file{gdb/NEWS} |
| 7487 | @item |
| 7488 | @file{gdb/README} |
| 7489 | @end itemize |
| 7490 | |
| 7491 | @subsubheading Tag the release |
| 7492 | |
| 7493 | Something like: |
| 7494 | |
| 7495 | @smallexample |
| 7496 | $ d=`date -u +%Y-%m-%d` |
| 7497 | $ echo $d |
| 7498 | 2002-01-24 |
| 7499 | $ ( cd insight/src/gdb && cvs -f -q update ) |
| 7500 | $ ( cd insight/src && cvs -f -q tag gdb_5_2-$d-release ) |
| 7501 | @end smallexample |
| 7502 | |
| 7503 | Insight is used since that contains more of the release than |
| 7504 | @value{GDBN}. |
| 7505 | |
| 7506 | @subsubheading Mention the release on the trunk |
| 7507 | |
| 7508 | Just put something in the @file{ChangeLog} so that the trunk also |
| 7509 | indicates when the release was made. |
| 7510 | |
| 7511 | @subsubheading Restart @file{gdb/version.in} |
| 7512 | |
| 7513 | If @file{gdb/version.in} does not contain an ISO date such as |
| 7514 | @kbd{2002-01-24} then the daily @code{cronjob} won't update it. Having |
| 7515 | committed all the release changes it can be set to |
| 7516 | @file{5.2.0_0000-00-00-cvs} which will restart things (yes the @kbd{_} |
| 7517 | is important - it affects the snapshot process). |
| 7518 | |
| 7519 | Don't forget the @file{ChangeLog}. |
| 7520 | |
| 7521 | @subsubheading Merge into trunk |
| 7522 | |
| 7523 | The files committed to the branch may also need changes merged into the |
| 7524 | trunk. |
| 7525 | |
| 7526 | @subsubheading Revise the release schedule |
| 7527 | |
| 7528 | Post a revised release schedule to @email{gdb@@sourceware.org, GDB |
| 7529 | Discussion List} with an updated announcement. The schedule can be |
| 7530 | generated by running: |
| 7531 | |
| 7532 | @smallexample |
| 7533 | $ ~/ss/schedule `date +%s` schedule |
| 7534 | @end smallexample |
| 7535 | |
| 7536 | @noindent |
| 7537 | The first parameter is approximate date/time in seconds (from the epoch) |
| 7538 | of the most recent release. |
| 7539 | |
| 7540 | Also update the schedule @code{cronjob}. |
| 7541 | |
| 7542 | @section Post release |
| 7543 | |
| 7544 | Remove any @code{OBSOLETE} code. |
| 7545 | |
| 7546 | @node Testsuite |
| 7547 | |
| 7548 | @chapter Testsuite |
| 7549 | @cindex test suite |
| 7550 | |
| 7551 | The testsuite is an important component of the @value{GDBN} package. |
| 7552 | While it is always worthwhile to encourage user testing, in practice |
| 7553 | this is rarely sufficient; users typically use only a small subset of |
| 7554 | the available commands, and it has proven all too common for a change |
| 7555 | to cause a significant regression that went unnoticed for some time. |
| 7556 | |
| 7557 | The @value{GDBN} testsuite uses the DejaGNU testing framework. The |
| 7558 | tests themselves are calls to various @code{Tcl} procs; the framework |
| 7559 | runs all the procs and summarizes the passes and fails. |
| 7560 | |
| 7561 | @section Using the Testsuite |
| 7562 | |
| 7563 | @cindex running the test suite |
| 7564 | To run the testsuite, simply go to the @value{GDBN} object directory (or to the |
| 7565 | testsuite's objdir) and type @code{make check}. This just sets up some |
| 7566 | environment variables and invokes DejaGNU's @code{runtest} script. While |
| 7567 | the testsuite is running, you'll get mentions of which test file is in use, |
| 7568 | and a mention of any unexpected passes or fails. When the testsuite is |
| 7569 | finished, you'll get a summary that looks like this: |
| 7570 | |
| 7571 | @smallexample |
| 7572 | === gdb Summary === |
| 7573 | |
| 7574 | # of expected passes 6016 |
| 7575 | # of unexpected failures 58 |
| 7576 | # of unexpected successes 5 |
| 7577 | # of expected failures 183 |
| 7578 | # of unresolved testcases 3 |
| 7579 | # of untested testcases 5 |
| 7580 | @end smallexample |
| 7581 | |
| 7582 | To run a specific test script, type: |
| 7583 | @example |
| 7584 | make check RUNTESTFLAGS='@var{tests}' |
| 7585 | @end example |
| 7586 | where @var{tests} is a list of test script file names, separated by |
| 7587 | spaces. |
| 7588 | |
| 7589 | If you use GNU make, you can use its @option{-j} option to run the |
| 7590 | testsuite in parallel. This can greatly reduce the amount of time it |
| 7591 | takes for the testsuite to run. In this case, if you set |
| 7592 | @code{RUNTESTFLAGS} then, by default, the tests will be run serially |
| 7593 | even under @option{-j}. You can override this and force a parallel run |
| 7594 | by setting the @code{make} variable @code{FORCE_PARALLEL} to any |
| 7595 | non-empty value. Note that the parallel @kbd{make check} assumes |
| 7596 | that you want to run the entire testsuite, so it is not compatible |
| 7597 | with some dejagnu options, like @option{--directory}. |
| 7598 | |
| 7599 | The ideal test run consists of expected passes only; however, reality |
| 7600 | conspires to keep us from this ideal. Unexpected failures indicate |
| 7601 | real problems, whether in @value{GDBN} or in the testsuite. Expected |
| 7602 | failures are still failures, but ones which have been decided are too |
| 7603 | hard to deal with at the time; for instance, a test case might work |
| 7604 | everywhere except on AIX, and there is no prospect of the AIX case |
| 7605 | being fixed in the near future. Expected failures should not be added |
| 7606 | lightly, since you may be masking serious bugs in @value{GDBN}. |
| 7607 | Unexpected successes are expected fails that are passing for some |
| 7608 | reason, while unresolved and untested cases often indicate some minor |
| 7609 | catastrophe, such as the compiler being unable to deal with a test |
| 7610 | program. |
| 7611 | |
| 7612 | When making any significant change to @value{GDBN}, you should run the |
| 7613 | testsuite before and after the change, to confirm that there are no |
| 7614 | regressions. Note that truly complete testing would require that you |
| 7615 | run the testsuite with all supported configurations and a variety of |
| 7616 | compilers; however this is more than really necessary. In many cases |
| 7617 | testing with a single configuration is sufficient. Other useful |
| 7618 | options are to test one big-endian (Sparc) and one little-endian (x86) |
| 7619 | host, a cross config with a builtin simulator (powerpc-eabi, |
| 7620 | mips-elf), or a 64-bit host (Alpha). |
| 7621 | |
| 7622 | If you add new functionality to @value{GDBN}, please consider adding |
| 7623 | tests for it as well; this way future @value{GDBN} hackers can detect |
| 7624 | and fix their changes that break the functionality you added. |
| 7625 | Similarly, if you fix a bug that was not previously reported as a test |
| 7626 | failure, please add a test case for it. Some cases are extremely |
| 7627 | difficult to test, such as code that handles host OS failures or bugs |
| 7628 | in particular versions of compilers, and it's OK not to try to write |
| 7629 | tests for all of those. |
| 7630 | |
| 7631 | DejaGNU supports separate build, host, and target machines. However, |
| 7632 | some @value{GDBN} test scripts do not work if the build machine and |
| 7633 | the host machine are not the same. In such an environment, these scripts |
| 7634 | will give a result of ``UNRESOLVED'', like this: |
| 7635 | |
| 7636 | @smallexample |
| 7637 | UNRESOLVED: gdb.base/example.exp: This test script does not work on a remote host. |
| 7638 | @end smallexample |
| 7639 | |
| 7640 | @section Testsuite Parameters |
| 7641 | |
| 7642 | Several variables exist to modify the behavior of the testsuite. |
| 7643 | |
| 7644 | @itemize @bullet |
| 7645 | |
| 7646 | @item @code{TRANSCRIPT} |
| 7647 | |
| 7648 | Sometimes it is convenient to get a transcript of the commands which |
| 7649 | the testsuite sends to @value{GDBN}. For example, if @value{GDBN} |
| 7650 | crashes during testing, a transcript can be used to more easily |
| 7651 | reconstruct the failure when running @value{GDBN} under @value{GDBN}. |
| 7652 | |
| 7653 | You can instruct the @value{GDBN} testsuite to write transcripts by |
| 7654 | setting the DejaGNU variable @code{TRANSCRIPT} (to any value) |
| 7655 | before invoking @code{runtest} or @kbd{make check}. The transcripts |
| 7656 | will be written into DejaGNU's output directory. One transcript will |
| 7657 | be made for each invocation of @value{GDBN}; they will be named |
| 7658 | @file{transcript.@var{n}}, where @var{n} is an integer. The first |
| 7659 | line of the transcript file will show how @value{GDBN} was invoked; |
| 7660 | each subsequent line is a command sent as input to @value{GDBN}. |
| 7661 | |
| 7662 | @smallexample |
| 7663 | make check RUNTESTFLAGS=TRANSCRIPT=y |
| 7664 | @end smallexample |
| 7665 | |
| 7666 | Note that the transcript is not always complete. In particular, tests |
| 7667 | of completion can yield partial command lines. |
| 7668 | |
| 7669 | @item @code{GDB} |
| 7670 | |
| 7671 | Sometimes one wishes to test a different @value{GDBN} than the one in the build |
| 7672 | directory. For example, one may wish to run the testsuite on |
| 7673 | @file{/usr/bin/gdb}. |
| 7674 | |
| 7675 | @smallexample |
| 7676 | make check RUNTESTFLAGS=GDB=/usr/bin/gdb |
| 7677 | @end smallexample |
| 7678 | |
| 7679 | @item @code{GDBSERVER} |
| 7680 | |
| 7681 | When testing a different @value{GDBN}, it is often useful to also test a |
| 7682 | different gdbserver. |
| 7683 | |
| 7684 | @smallexample |
| 7685 | make check RUNTESTFLAGS="GDB=/usr/bin/gdb GDBSERVER=/usr/bin/gdbserver" |
| 7686 | @end smallexample |
| 7687 | |
| 7688 | @item @code{INTERNAL_GDBFLAGS} |
| 7689 | |
| 7690 | When running the testsuite normally one doesn't want whatever is in |
| 7691 | @file{~/.gdbinit} to interfere with the tests, therefore the test harness |
| 7692 | passes @option{-nx} to @value{GDBN}. One also doesn't want any windowed |
| 7693 | version of @value{GDBN}, e.g., @command{gdbtui}, to run. |
| 7694 | This is achieved via @code{INTERNAL_GDBFLAGS}. |
| 7695 | |
| 7696 | @smallexample |
| 7697 | set INTERNAL_GDBFLAGS "-nw -nx" |
| 7698 | @end smallexample |
| 7699 | |
| 7700 | This is all well and good, except when testing an installed @value{GDBN} |
| 7701 | that has been configured with @option{--with-system-gdbinit}. Here one |
| 7702 | does not want @file{~/.gdbinit} loaded but one may want the system |
| 7703 | @file{.gdbinit} file loaded. This can be achieved by pointing @code{$HOME} |
| 7704 | at a directory without a @file{.gdbinit} and by overriding |
| 7705 | @code{INTERNAL_GDBFLAGS} and removing @option{-nx}. |
| 7706 | |
| 7707 | @smallexample |
| 7708 | cd testsuite |
| 7709 | HOME=`pwd` runtest \ |
| 7710 | GDB=/usr/bin/gdb \ |
| 7711 | GDBSERVER=/usr/bin/gdbserver \ |
| 7712 | INTERNAL_GDBFLAGS=-nw |
| 7713 | @end smallexample |
| 7714 | |
| 7715 | @end itemize |
| 7716 | |
| 7717 | There are two ways to run the testsuite and pass additional parameters |
| 7718 | to DejaGnu. The first is with @kbd{make check} and specifying the |
| 7719 | makefile variable @samp{RUNTESTFLAGS}. |
| 7720 | |
| 7721 | @smallexample |
| 7722 | make check RUNTESTFLAGS=TRANSCRIPT=y |
| 7723 | @end smallexample |
| 7724 | |
| 7725 | The second is to cd to the @file{testsuite} directory and invoke the DejaGnu |
| 7726 | @command{runtest} command directly. |
| 7727 | |
| 7728 | @smallexample |
| 7729 | cd testsuite |
| 7730 | make site.exp |
| 7731 | runtest TRANSCRIPT=y |
| 7732 | @end smallexample |
| 7733 | |
| 7734 | @section Testsuite Configuration |
| 7735 | @cindex Testsuite Configuration |
| 7736 | |
| 7737 | It is possible to adjust the behavior of the testsuite by defining |
| 7738 | the global variables listed below, either in a @file{site.exp} file, |
| 7739 | or in a board file. |
| 7740 | |
| 7741 | @itemize @bullet |
| 7742 | |
| 7743 | @item @code{gdb_test_timeout} |
| 7744 | |
| 7745 | Defining this variable changes the default timeout duration used during |
| 7746 | communication with @value{GDBN}. More specifically, the global variable |
| 7747 | used during testing is @code{timeout}, but this variable gets reset to |
| 7748 | @code{gdb_test_timeout} at the beginning of each testcase, making sure |
| 7749 | that any local change to @code{timeout} in a testcase does not affect |
| 7750 | subsequent testcases. |
| 7751 | |
| 7752 | This global variable comes in handy when the debugger is slower than |
| 7753 | normal due to the testing environment, triggering unexpected @code{TIMEOUT} |
| 7754 | test failures. Examples include when testing on a remote machine, or |
| 7755 | against a system where communications are slow. |
| 7756 | |
| 7757 | If not specifically defined, this variable gets automatically defined |
| 7758 | to the same value as @code{timeout} during the testsuite initialization. |
| 7759 | The default value of the timeout is defined in the file |
| 7760 | @file{gdb/testsuite/config/unix.exp} that is part of the @value{GDBN} |
| 7761 | test suite@footnote{If you are using a board file, it could override |
| 7762 | the test-suite default; search the board file for "timeout".}. |
| 7763 | |
| 7764 | @end itemize |
| 7765 | |
| 7766 | @section Testsuite Organization |
| 7767 | |
| 7768 | @cindex test suite organization |
| 7769 | The testsuite is entirely contained in @file{gdb/testsuite}. While the |
| 7770 | testsuite includes some makefiles and configury, these are very minimal, |
| 7771 | and used for little besides cleaning up, since the tests themselves |
| 7772 | handle the compilation of the programs that @value{GDBN} will run. The file |
| 7773 | @file{testsuite/lib/gdb.exp} contains common utility procs useful for |
| 7774 | all @value{GDBN} tests, while the directory @file{testsuite/config} contains |
| 7775 | configuration-specific files, typically used for special-purpose |
| 7776 | definitions of procs like @code{gdb_load} and @code{gdb_start}. |
| 7777 | |
| 7778 | The tests themselves are to be found in @file{testsuite/gdb.*} and |
| 7779 | subdirectories of those. The names of the test files must always end |
| 7780 | with @file{.exp}. DejaGNU collects the test files by wildcarding |
| 7781 | in the test directories, so both subdirectories and individual files |
| 7782 | get chosen and run in alphabetical order. |
| 7783 | |
| 7784 | The following table lists the main types of subdirectories and what they |
| 7785 | are for. Since DejaGNU finds test files no matter where they are |
| 7786 | located, and since each test file sets up its own compilation and |
| 7787 | execution environment, this organization is simply for convenience and |
| 7788 | intelligibility. |
| 7789 | |
| 7790 | @table @file |
| 7791 | @item gdb.base |
| 7792 | This is the base testsuite. The tests in it should apply to all |
| 7793 | configurations of @value{GDBN} (but generic native-only tests may live here). |
| 7794 | The test programs should be in the subset of C that is valid K&R, |
| 7795 | ANSI/ISO, and C@t{++} (@code{#ifdef}s are allowed if necessary, for instance |
| 7796 | for prototypes). |
| 7797 | |
| 7798 | @item gdb.@var{lang} |
| 7799 | Language-specific tests for any language @var{lang} besides C. Examples are |
| 7800 | @file{gdb.cp} and @file{gdb.java}. |
| 7801 | |
| 7802 | @item gdb.@var{platform} |
| 7803 | Non-portable tests. The tests are specific to a specific configuration |
| 7804 | (host or target), such as HP-UX or eCos. Example is @file{gdb.hp}, for |
| 7805 | HP-UX. |
| 7806 | |
| 7807 | @item gdb.@var{compiler} |
| 7808 | Tests specific to a particular compiler. As of this writing (June |
| 7809 | 1999), there aren't currently any groups of tests in this category that |
| 7810 | couldn't just as sensibly be made platform-specific, but one could |
| 7811 | imagine a @file{gdb.gcc}, for tests of @value{GDBN}'s handling of GCC |
| 7812 | extensions. |
| 7813 | |
| 7814 | @item gdb.@var{subsystem} |
| 7815 | Tests that exercise a specific @value{GDBN} subsystem in more depth. For |
| 7816 | instance, @file{gdb.disasm} exercises various disassemblers, while |
| 7817 | @file{gdb.stabs} tests pathways through the stabs symbol reader. |
| 7818 | @end table |
| 7819 | |
| 7820 | @section Writing Tests |
| 7821 | @cindex writing tests |
| 7822 | |
| 7823 | In many areas, the @value{GDBN} tests are already quite comprehensive; you |
| 7824 | should be able to copy existing tests to handle new cases. |
| 7825 | |
| 7826 | You should try to use @code{gdb_test} whenever possible, since it |
| 7827 | includes cases to handle all the unexpected errors that might happen. |
| 7828 | However, it doesn't cost anything to add new test procedures; for |
| 7829 | instance, @file{gdb.base/exprs.exp} defines a @code{test_expr} that |
| 7830 | calls @code{gdb_test} multiple times. |
| 7831 | |
| 7832 | Only use @code{send_gdb} and @code{gdb_expect} when absolutely |
| 7833 | necessary. Even if @value{GDBN} has several valid responses to |
| 7834 | a command, you can use @code{gdb_test_multiple}. Like @code{gdb_test}, |
| 7835 | @code{gdb_test_multiple} recognizes internal errors and unexpected |
| 7836 | prompts. |
| 7837 | |
| 7838 | Do not write tests which expect a literal tab character from @value{GDBN}. |
| 7839 | On some operating systems (e.g.@: OpenBSD) the TTY layer expands tabs to |
| 7840 | spaces, so by the time @value{GDBN}'s output reaches expect the tab is gone. |
| 7841 | |
| 7842 | The source language programs do @emph{not} need to be in a consistent |
| 7843 | style. Since @value{GDBN} is used to debug programs written in many different |
| 7844 | styles, it's worth having a mix of styles in the testsuite; for |
| 7845 | instance, some @value{GDBN} bugs involving the display of source lines would |
| 7846 | never manifest themselves if the programs used GNU coding style |
| 7847 | uniformly. |
| 7848 | |
| 7849 | @node Hints |
| 7850 | |
| 7851 | @chapter Hints |
| 7852 | |
| 7853 | Check the @file{README} file, it often has useful information that does not |
| 7854 | appear anywhere else in the directory. |
| 7855 | |
| 7856 | @menu |
| 7857 | * Getting Started:: Getting started working on @value{GDBN} |
| 7858 | * Debugging GDB:: Debugging @value{GDBN} with itself |
| 7859 | @end menu |
| 7860 | |
| 7861 | @node Getting Started |
| 7862 | |
| 7863 | @section Getting Started |
| 7864 | |
| 7865 | @value{GDBN} is a large and complicated program, and if you first starting to |
| 7866 | work on it, it can be hard to know where to start. Fortunately, if you |
| 7867 | know how to go about it, there are ways to figure out what is going on. |
| 7868 | |
| 7869 | This manual, the @value{GDBN} Internals manual, has information which applies |
| 7870 | generally to many parts of @value{GDBN}. |
| 7871 | |
| 7872 | Information about particular functions or data structures are located in |
| 7873 | comments with those functions or data structures. If you run across a |
| 7874 | function or a global variable which does not have a comment correctly |
| 7875 | explaining what is does, this can be thought of as a bug in @value{GDBN}; feel |
| 7876 | free to submit a bug report, with a suggested comment if you can figure |
| 7877 | out what the comment should say. If you find a comment which is |
| 7878 | actually wrong, be especially sure to report that. |
| 7879 | |
| 7880 | Comments explaining the function of macros defined in host, target, or |
| 7881 | native dependent files can be in several places. Sometimes they are |
| 7882 | repeated every place the macro is defined. Sometimes they are where the |
| 7883 | macro is used. Sometimes there is a header file which supplies a |
| 7884 | default definition of the macro, and the comment is there. This manual |
| 7885 | also documents all the available macros. |
| 7886 | @c (@pxref{Host Conditionals}, @pxref{Target |
| 7887 | @c Conditionals}, @pxref{Native Conditionals}, and @pxref{Obsolete |
| 7888 | @c Conditionals}) |
| 7889 | |
| 7890 | Start with the header files. Once you have some idea of how |
| 7891 | @value{GDBN}'s internal symbol tables are stored (see @file{symtab.h}, |
| 7892 | @file{gdbtypes.h}), you will find it much easier to understand the |
| 7893 | code which uses and creates those symbol tables. |
| 7894 | |
| 7895 | You may wish to process the information you are getting somehow, to |
| 7896 | enhance your understanding of it. Summarize it, translate it to another |
| 7897 | language, add some (perhaps trivial or non-useful) feature to @value{GDBN}, use |
| 7898 | the code to predict what a test case would do and write the test case |
| 7899 | and verify your prediction, etc. If you are reading code and your eyes |
| 7900 | are starting to glaze over, this is a sign you need to use a more active |
| 7901 | approach. |
| 7902 | |
| 7903 | Once you have a part of @value{GDBN} to start with, you can find more |
| 7904 | specifically the part you are looking for by stepping through each |
| 7905 | function with the @code{next} command. Do not use @code{step} or you |
| 7906 | will quickly get distracted; when the function you are stepping through |
| 7907 | calls another function try only to get a big-picture understanding |
| 7908 | (perhaps using the comment at the beginning of the function being |
| 7909 | called) of what it does. This way you can identify which of the |
| 7910 | functions being called by the function you are stepping through is the |
| 7911 | one which you are interested in. You may need to examine the data |
| 7912 | structures generated at each stage, with reference to the comments in |
| 7913 | the header files explaining what the data structures are supposed to |
| 7914 | look like. |
| 7915 | |
| 7916 | Of course, this same technique can be used if you are just reading the |
| 7917 | code, rather than actually stepping through it. The same general |
| 7918 | principle applies---when the code you are looking at calls something |
| 7919 | else, just try to understand generally what the code being called does, |
| 7920 | rather than worrying about all its details. |
| 7921 | |
| 7922 | @cindex command implementation |
| 7923 | A good place to start when tracking down some particular area is with |
| 7924 | a command which invokes that feature. Suppose you want to know how |
| 7925 | single-stepping works. As a @value{GDBN} user, you know that the |
| 7926 | @code{step} command invokes single-stepping. The command is invoked |
| 7927 | via command tables (see @file{command.h}); by convention the function |
| 7928 | which actually performs the command is formed by taking the name of |
| 7929 | the command and adding @samp{_command}, or in the case of an |
| 7930 | @code{info} subcommand, @samp{_info}. For example, the @code{step} |
| 7931 | command invokes the @code{step_command} function and the @code{info |
| 7932 | display} command invokes @code{display_info}. When this convention is |
| 7933 | not followed, you might have to use @code{grep} or @kbd{M-x |
| 7934 | tags-search} in emacs, or run @value{GDBN} on itself and set a |
| 7935 | breakpoint in @code{execute_command}. |
| 7936 | |
| 7937 | @cindex @code{bug-gdb} mailing list |
| 7938 | If all of the above fail, it may be appropriate to ask for information |
| 7939 | on @code{bug-gdb}. But @emph{never} post a generic question like ``I was |
| 7940 | wondering if anyone could give me some tips about understanding |
| 7941 | @value{GDBN}''---if we had some magic secret we would put it in this manual. |
| 7942 | Suggestions for improving the manual are always welcome, of course. |
| 7943 | |
| 7944 | @node Debugging GDB |
| 7945 | |
| 7946 | @section Debugging @value{GDBN} with itself |
| 7947 | @cindex debugging @value{GDBN} |
| 7948 | |
| 7949 | If @value{GDBN} is limping on your machine, this is the preferred way to get it |
| 7950 | fully functional. Be warned that in some ancient Unix systems, like |
| 7951 | Ultrix 4.2, a program can't be running in one process while it is being |
| 7952 | debugged in another. Rather than typing the command @kbd{@w{./gdb |
| 7953 | ./gdb}}, which works on Suns and such, you can copy @file{gdb} to |
| 7954 | @file{gdb2} and then type @kbd{@w{./gdb ./gdb2}}. |
| 7955 | |
| 7956 | When you run @value{GDBN} in the @value{GDBN} source directory, it will read a |
| 7957 | @file{.gdbinit} file that sets up some simple things to make debugging |
| 7958 | gdb easier. The @code{info} command, when executed without a subcommand |
| 7959 | in a @value{GDBN} being debugged by gdb, will pop you back up to the top level |
| 7960 | gdb. See @file{.gdbinit} for details. |
| 7961 | |
| 7962 | If you use emacs, you will probably want to do a @code{make TAGS} after |
| 7963 | you configure your distribution; this will put the machine dependent |
| 7964 | routines for your local machine where they will be accessed first by |
| 7965 | @kbd{M-.} |
| 7966 | |
| 7967 | Also, make sure that you've either compiled @value{GDBN} with your local cc, or |
| 7968 | have run @code{fixincludes} if you are compiling with gcc. |
| 7969 | |
| 7970 | @section Submitting Patches |
| 7971 | |
| 7972 | @cindex submitting patches |
| 7973 | Thanks for thinking of offering your changes back to the community of |
| 7974 | @value{GDBN} users. In general we like to get well designed enhancements. |
| 7975 | Thanks also for checking in advance about the best way to transfer the |
| 7976 | changes. |
| 7977 | |
| 7978 | The @value{GDBN} maintainers will only install ``cleanly designed'' patches. |
| 7979 | This manual summarizes what we believe to be clean design for @value{GDBN}. |
| 7980 | |
| 7981 | If the maintainers don't have time to put the patch in when it arrives, |
| 7982 | or if there is any question about a patch, it goes into a large queue |
| 7983 | with everyone else's patches and bug reports. |
| 7984 | |
| 7985 | @cindex legal papers for code contributions |
| 7986 | The legal issue is that to incorporate substantial changes requires a |
| 7987 | copyright assignment from you and/or your employer, granting ownership |
| 7988 | of the changes to the Free Software Foundation. You can get the |
| 7989 | standard documents for doing this by sending mail to @code{gnu@@gnu.org} |
| 7990 | and asking for it. We recommend that people write in "All programs |
| 7991 | owned by the Free Software Foundation" as "NAME OF PROGRAM", so that |
| 7992 | changes in many programs (not just @value{GDBN}, but GAS, Emacs, GCC, |
| 7993 | etc) can be |
| 7994 | contributed with only one piece of legalese pushed through the |
| 7995 | bureaucracy and filed with the FSF. We can't start merging changes until |
| 7996 | this paperwork is received by the FSF (their rules, which we follow |
| 7997 | since we maintain it for them). |
| 7998 | |
| 7999 | Technically, the easiest way to receive changes is to receive each |
| 8000 | feature as a small context diff or unidiff, suitable for @code{patch}. |
| 8001 | Each message sent to me should include the changes to C code and |
| 8002 | header files for a single feature, plus @file{ChangeLog} entries for |
| 8003 | each directory where files were modified, and diffs for any changes |
| 8004 | needed to the manuals (@file{gdb/doc/gdb.texinfo} or |
| 8005 | @file{gdb/doc/gdbint.texinfo}). If there are a lot of changes for a |
| 8006 | single feature, they can be split down into multiple messages. |
| 8007 | |
| 8008 | In this way, if we read and like the feature, we can add it to the |
| 8009 | sources with a single patch command, do some testing, and check it in. |
| 8010 | If you leave out the @file{ChangeLog}, we have to write one. If you leave |
| 8011 | out the doc, we have to puzzle out what needs documenting. Etc., etc. |
| 8012 | |
| 8013 | The reason to send each change in a separate message is that we will not |
| 8014 | install some of the changes. They'll be returned to you with questions |
| 8015 | or comments. If we're doing our job correctly, the message back to you |
| 8016 | will say what you have to fix in order to make the change acceptable. |
| 8017 | The reason to have separate messages for separate features is so that |
| 8018 | the acceptable changes can be installed while one or more changes are |
| 8019 | being reworked. If multiple features are sent in a single message, we |
| 8020 | tend to not put in the effort to sort out the acceptable changes from |
| 8021 | the unacceptable, so none of the features get installed until all are |
| 8022 | acceptable. |
| 8023 | |
| 8024 | If this sounds painful or authoritarian, well, it is. But we get a lot |
| 8025 | of bug reports and a lot of patches, and many of them don't get |
| 8026 | installed because we don't have the time to finish the job that the bug |
| 8027 | reporter or the contributor could have done. Patches that arrive |
| 8028 | complete, working, and well designed, tend to get installed on the day |
| 8029 | they arrive. The others go into a queue and get installed as time |
| 8030 | permits, which, since the maintainers have many demands to meet, may not |
| 8031 | be for quite some time. |
| 8032 | |
| 8033 | Please send patches directly to |
| 8034 | @email{gdb-patches@@sourceware.org, the @value{GDBN} maintainers}. |
| 8035 | |
| 8036 | @section Build Script |
| 8037 | |
| 8038 | @cindex build script |
| 8039 | |
| 8040 | The script @file{gdb_buildall.sh} builds @value{GDBN} with flag |
| 8041 | @option{--enable-targets=all} set. This builds @value{GDBN} with all supported |
| 8042 | targets activated. This helps testing @value{GDBN} when doing changes that |
| 8043 | affect more than one architecture and is much faster than using |
| 8044 | @file{gdb_mbuild.sh}. |
| 8045 | |
| 8046 | After building @value{GDBN} the script checks which architectures are |
| 8047 | supported and then switches the current architecture to each of those to get |
| 8048 | information about the architecture. The test results are stored in log files |
| 8049 | in the directory the script was called from. |
| 8050 | |
| 8051 | @include observer.texi |
| 8052 | |
| 8053 | @node GNU Free Documentation License |
| 8054 | @appendix GNU Free Documentation License |
| 8055 | @include fdl.texi |
| 8056 | |
| 8057 | @node Index |
| 8058 | @unnumbered Index |
| 8059 | |
| 8060 | @printindex cp |
| 8061 | |
| 8062 | @bye |