This is the mail archive of the
gdb-patches@sourceware.org
mailing list for the GDB project.
Re: Docs and NEWS for breakpoint changes
On Thursday 27 September 2007 01:12:47 Eli Zaretskii wrote:
> > From: Vladimir Prus <vladimir@codesourcery.com>
> > 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{<MULTIPLE>} 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{<MULTIPLE>} 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
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{<PENDING>}.
+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{<PENDING>}. A breakpoint with several locations will
+have @samp{<MULTIPLE>} 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{<MULTIPLE>} 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 <MULTIPLE>
+ stop only if i==1
+ breakpoint already hit 1 time
+1.1 y 0x080486a2 in void foo<int>() at t.cc:8
+1.2 y 0x080486ca in void foo<double>() 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