From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 27089 invoked by alias); 27 Sep 2007 18:27:48 -0000 Received: (qmail 27080 invoked by uid 22791); 27 Sep 2007 18:27:46 -0000 X-Spam-Check-By: sourceware.org Received: from mail.codesourcery.com (HELO mail.codesourcery.com) (65.74.133.4) by sourceware.org (qpsmtpd/0.31) with ESMTP; Thu, 27 Sep 2007 18:27:42 +0000 Received: (qmail 18666 invoked from network); 27 Sep 2007 18:27:38 -0000 Received: from unknown (HELO h38.net64.aknet.ru) (vladimir@127.0.0.2) by mail.codesourcery.com with ESMTPA; 27 Sep 2007 18:27:38 -0000 From: Vladimir Prus To: Eli Zaretskii Subject: Re: Docs and NEWS for breakpoint changes Date: Thu, 27 Sep 2007 18:27:00 -0000 User-Agent: KMail/1.9.6 Cc: gdb-patches@sources.redhat.com References: <200709262207.42508.vladimir@codesourcery.com> In-Reply-To: MIME-Version: 1.0 Content-Type: Multipart/Mixed; boundary="Boundary-00=_WY/+GMtHYKi98z/" Message-Id: <200709272227.34355.vladimir@codesourcery.com> Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sourceware.org X-SW-Source: 2007-09/txt/msg00414.txt.bz2 --Boundary-00=_WY/+GMtHYKi98z/ Content-Type: text/plain; charset="iso-8859-15" Content-Transfer-Encoding: 7bit Content-Disposition: inline Content-length: 6174 On Thursday 27 September 2007 01:12:47 Eli Zaretskii wrote: > > From: Vladimir Prus > > Date: Wed, 26 Sep 2007 22:07:42 +0400 > > Now that the code patches for my breakpoint changes are in, > > here's the doc patch and NEWS addition. > > Thanks! > > > Comments? > > A few: > > > +* Pending breakpoints where changed to not change its number when > > + resolved. ^^^ > > It's "breakpoints" (plural), so "its" is wrong. > > "where" is also wrong; you meant "were". But please don't use past > tense in NEWS, present tense is better: > > Pending breakpoints no longer change their number when their address > is resolved. > > > +* Support for breakpoints with multiple locations was implemented, > > Avoiding passive voice makes text simpler and clearer: > > GDB now supports breakpoints with multiple locations, > > (also present tense instead of past). > > > +that are not enabled. An optional @samp{(p)} suffix marks pending > > +breakpoints --- breakpoints for which address is either not yet > > +resolved, pending load of a shared library, or for which address was > > +in a shared library that was since resolved. Such breakpoint won't > > +fire until a shared library that has the symbol or line referred by > > +breakpoint is loaded. See below for details. > > I'm left confused: if the address ``was since resolved'', then why do > we still mark the breakpoint with "(p)"? Sorry, "was since resolved" should read "was since unloaded" > > For a > > +pending breakpoint that never had its address known, > > I think this is better: > > For a pending address whose address is not yet known, ^^^^^^^ Did you mean "breakpoint" instead of first "address"? > > +have @samp{} in this field -- see below for details. > ^^ > Please use "---" -- 3 dashes in a row, not 2 -- for an em-dash. > > > +For a C++ constructor, the gcc compiler generates several function > > +bodies used in different cases. > > Please use C@t{++}, it looks better in print (there are several more > instances like this one). Also, we use "@value{NGCC}" instead of a > literal "gcc" in this manual. And instead of "several function > bodies", isn't it more accurate to say "several instances of the > function body"? I'm not quite sure I see the difference; I've changed this. > > > +For a C++ template function, a given line in the function can > > +correspond to unbounded set of instantiations. > ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ > "to any number of instantiations" is better. > > > +For an inlined function, a given line can correspond to > > +several places where that function is inlined. > > "given source line" or even "a breakpoint at a given source line" will > make things clearer, I think. I went with "given source line", since at this point we're still talking about what language constructs can correspond to multiple PC values. > > +In all those cases, @value{GDBN} will associate the breakpoint > > +with all relevant locations. > > Perhaps we better say "@value{GDBN} will insert a breakpoint at all > the relevant locations". "Associate the breakpoint" leaves me > wondering what does "associate" mean in this context. You're right. > > > +A breakpoint with multiple locations is displayed in the > > +breakpoint table using several rows --- one header row, followed > > +by one row for each breakpoint location. The header row > > +has @samp{} in the address column. The rows for > > +individual locations contain the actual addresses for locations, > > +and say what functions those locations are in. The number > > +column for a location has number in the format > > +@var{breakpoint-number}.@var{location-number}. > > Example, please. A picture is worth a thousand words. I've added one. Is example with a line as long as 75 characters OK? It looked good to me in PDF and info formats, but just to check. > > +Each location can be individually enabled or disabled by passing > > +the @var{breakpoint-number}.@var{location-number} to the @code{enable} > > +or @code{disable} commands. > > Each location can be individually enabled or disabled by passing > @var{breakpoint-number}.@var{location-number} as argument to the > @code{enable} and @code{disable} commands. > > > +It's quite common to have a breakpoint inside a shared library. > > +Further, the shared library may be loaded and unloaded explicitly, > > This "further" thing does not add anything to the sentence; just > remove it. > > > +and possible repeatedly, as the program is executed. To support > ^^^^^^^^ > "and possibly repeatedly". Yes. > > > +any shared library is loaded or unloaded. Typically, you would > ^^^ > Two spaces between sentences, please. > > > +a so called @dfn{pending breakpoint} --- breakpoint that is not yet > > +resolved to address. > > "breakpoint whose address is not yet resolved". > > > +After the program is run, whenever a new shared library is loaded, > > +@value{GDBN} reevaluates all breakpoints. In case a newly loaded > > +shared library contains the symbol or line referred to by breakpoint, > > +breakpoint is resolved and becomes an ordinary breakpoint. If a > > +library is unloaded, all breakpoints it in become pending again. > > Suggest to reword slightly like this: > > After the program is run, whenever a new shared library is loaded, > @value{GDBN} reevaluates all the breakpoints. When a newly loaded > shared library contains the symbol or line referred to by some > pending breakpoint, that breakpoint is resolved and becomes an > ordinary breakpoint. When a library is unloaded, all breakpoints > that refer to its symbols or source lines become pending again. Thanks, this is better. > > +a new location will be added to the existing breakpoint. > > Suggest "a new location is added to the list of locations for the > breakpoint". Thanks for review. I attach the revised version. - Volodya --Boundary-00=_WY/+GMtHYKi98z/ Content-Type: text/x-diff; charset="iso-8859-15"; name="breakpoint_docs.diff" Content-Transfer-Encoding: 7bit Content-Disposition: attachment; filename="breakpoint_docs.diff" Content-length: 8051 Index: NEWS =================================================================== RCS file: /cvs/src/src/gdb/NEWS,v retrieving revision 1.239 diff -u -p -r1.239 NEWS --- NEWS 17 Sep 2007 19:30:05 -0000 1.239 +++ NEWS 27 Sep 2007 18:26:49 -0000 @@ -3,6 +3,13 @@ *** Changes since GDB 6.7 +* Pending breakpoints no longer change their number when their address + is resolved. + +* GDB now supports breakpoints with multiple locations, + including breakpoints on C++ constructors, inside C++ templates, + and in inlined functions. + *** Changes in GDB 6.6 * Resolved 101 resource leaks, null pointer dereferences, etc. in gdb, Index: doc/gdb.texinfo =================================================================== RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v retrieving revision 1.432 diff -u -p -r1.432 gdb.texinfo --- doc/gdb.texinfo 16 Sep 2007 14:59:30 -0000 1.432 +++ doc/gdb.texinfo 27 Sep 2007 18:26:58 -0000 @@ -2991,11 +2991,17 @@ Breakpoint, watchpoint, or catchpoint. Whether the breakpoint is marked to be disabled or deleted when hit. @item Enabled or Disabled Enabled breakpoints are marked with @samp{y}. @samp{n} marks breakpoints -that are not enabled. +that are not enabled. An optional @samp{(p)} suffix marks pending +breakpoints --- breakpoints for which address is either not yet +resolved, pending load of a shared library, or for which address was +in a shared library that was since unloaded. Such breakpoint won't +fire until a shared library that has the symbol or line referred by +breakpoint is loaded. See below for details. @item Address -Where the breakpoint is in your program, as a memory address. If the -breakpoint is pending (see below for details) on a future load of a shared library, the address -will be listed as @samp{}. +Where the breakpoint is in your program, as a memory address. For a +pending breakpoint whose address is not yet known, this field will +contain @samp{}. A breakpoint with several locations will +have @samp{} in this field --- see below for details. @item What Where the breakpoint is in the source for your program, as a file and line number. For a pending breakpoint, the original string passed to @@ -3032,23 +3038,83 @@ your program. There is nothing silly or the breakpoints are conditional, this is even useful (@pxref{Conditions, ,Break Conditions}). -@cindex pending breakpoints -If a specified breakpoint location cannot be found, it may be due to the fact -that the location is in a shared library that is yet to be loaded. In such -a case, you may want @value{GDBN} to create a special breakpoint (known as -a @dfn{pending breakpoint}) that -attempts to resolve itself in the future when an appropriate shared library -gets loaded. - -Pending breakpoints are useful to set at the start of your -@value{GDBN} session for locations that you know will be dynamically loaded -later by the program being debugged. When shared libraries are loaded, -a check is made to see if the load resolves any pending breakpoint locations. -If a pending breakpoint location gets resolved, -a regular breakpoint is created and the original pending breakpoint is removed. +It is possible that a breakpoints correspond to several locations +in your program. Examples of this situation are: + +@itemize @bullet + +@item +For a C@t{++} constructor, the gcc compiler generates several +instances of the function body, used in different cases. -@value{GDBN} provides some additional commands for controlling pending -breakpoint support: +@item +For a C@t{++} template function, a given line in the function can +correspond to any number of instantiations. + +@item +For an inlined function, a given source line can correspond to +several places where that function is inlined. + +@end itemize + +In all those cases, @value{GDBN} will insert a breakpoint at all +the relevant locations. + +A breakpoint with multiple locations is displayed in the +breakpoint table using several rows --- one header row, followed +by one row for each breakpoint location. The header row +has @samp{} in the address column. The rows for +individual locations contain the actual addresses for locations, +and say what functions those locations are in. The number +column for a location has number in the format +@var{breakpoint-number}.@var{location-number}. + +For example: +@smallexample +Num Type Disp Enb Address What +1 breakpoint keep y + stop only if i==1 + breakpoint already hit 1 time +1.1 y 0x080486a2 in void foo() at t.cc:8 +1.2 y 0x080486ca in void foo() at t.cc:8 +@end smallexample + +Each location can be individually enabled or disabled by passing +@var{breakpoint-number}.@var{location-number} as argument to the +@code{enable} and @code{disable} commands. + +@cindex pending breakpoints +It's quite common to have a breakpoint inside a shared library. +The shared library may be loaded and unloaded explicitly, +and possibly repeatedly, as the program is executed. To support +this use case, @value{GDBN} updates breakpoint locations whenever +any shared library is loaded or unloaded. Typically, you would +set a breakpoint in a shared library at the beginning of your +debugging session, when the library is not loaded, and when the +symbols from the library are not available. When you try to set +breakpoint, @value{GDBN} will ask you if you want to set +a so called @dfn{pending breakpoint} --- breakpoint whose address +is not yet resolved. + +After the program is run, whenever a new shared library is loaded, +@value{GDBN} reevaluates all the breakpoints. When a newly loaded +shared library contains the symbol or line referred to by some +pending breakpoint, that breakpoint is resolved and becomes an +ordinary breakpoint. When a library is unloaded, all breakpoints +that refer to its symbols or source lines become pending again. + +This logic works for breakpoints with multiple locations, too. For +example, if you have a breakpoint in a C@t{++} template function, and +a newly loaded shared library has an instantiation of that template, +a new location is added to the list of locations for the breakpoint. + +Except for having unresolved address, pending breakpoints do not +differ from regular breakpoints. You can set conditions or commands, +enable and disable them and perform other breakpoint operations. + +@value{GDBN} provides some additional commands for controlling what +happens when the @samp{break} command cannot resolve breakpoint +address specification to an address: @kindex set breakpoint pending @kindex show breakpoint pending @@ -3070,19 +3136,9 @@ not affect any pending breakpoints previ Show the current behavior setting for creating pending breakpoints. @end table -@cindex operations allowed on pending breakpoints -Normal breakpoint operations apply to pending breakpoints as well. You may -specify a condition for a pending breakpoint and/or commands to run when the -breakpoint is reached. You can also enable or disable -the pending breakpoint. When you specify a condition for a pending breakpoint, -the parsing of the condition will be deferred until the point where the -pending breakpoint location is resolved. Disabling a pending breakpoint -tells @value{GDBN} to not attempt to resolve the breakpoint on any subsequent -shared library load. When a pending breakpoint is re-enabled, -@value{GDBN} checks to see if the location is already resolved. -This is done because any number of shared library loads could have -occurred since the time the breakpoint was disabled and one or more -of these loads could resolve the location. +The settings above only affect the @code{break} command and its +variants. Once breakpoint is set, it will be automatically updated +as shared libraries are loaded and unloaded. @cindex automatic hardware breakpoints For some targets, @value{GDBN} can automatically decide if hardware or --Boundary-00=_WY/+GMtHYKi98z/--