Re: RTe: Location Specs (Was: [pushed v5] gdb/manual: Introduce location specs)

[Pedro Alves <pedro@palves.net>]

On 2022-06-02 12:49, Eli Zaretskii wrote:
>> Date: Thu, 2 Jun 2022 12:10:54 +0100
>> Cc: gdb-patches@sourceware.org
>> From: Pedro Alves <pedro@palves.net>
>>
>>> A concrete code location in your program is uniquely identifiable by a
>>> set of several attributes: its source line number, the name of its
>>> source file, the fully-qualified and prototyped function in which it
>>> is defined, and an instruction address.  Because each inferior has its
>>> own address space, the inferior number is also a necessary part of
>>> these attributes.  By contrast, location specs you type will many
>>
>> I built the manual here with the patch, to read in the html form in the browser,
>> and found this paragraph very long and dense.  I find it much more readable if we have a
>> paragraph break here (line break + empty line), before "By contract".  Above we talk
>> about actual code locations.  And below we talk about location specs.  
> 
> Sure, breaking there is fine, thanks.
> 
>>>  Several @value{GDBN} commands accept arguments that specify a location
>>>  or locations of your program's code.  Since @value{GDBN} is a
>>>  source-level debugger, a location specification usually indicates some
>>> -line in the source code, but it can also indicate a function name, an
>>> -address, a label, and more.
>>> +line in some source file, but it can also do that indirectly, by
>>> +specifying a function name, an address, a label, etc.  
>>
>> This is changing the meaning of what was said.  It is now reading as if
>> the line number is what are are after, and that function, address, etc.
>> are merely means to get to the line number.  While before, we were saying that
>> usually you specify the line number, but you can also specify some
>> function, or even a precise address.  The new text gives a lot more emphasis to
>> the resolved line number.
> 
> I didn't say "number", though, I just said "line".  That's different:
> since GDB is a source-level debugger (as the text says), the location
> spec identifies some line in the source code.  But it doesn't
> necessarily do that via its number.
> 
> The point of that paragraph, as I interpret it, is to say that a
> function name, a label, or an address all identify a certain line in
> the source.

That was not my intention, as I explained in the paragraph just below:

> 
>> I think it's a difference in the interpretation of "indicate".  The original
>> text uses it to mean the arguments the user can specify (otherwise it wouldn't
>> be talking about "a label" or function _name_), while in your version you seem
>> to be using "indicate" to mean the line number you want the spec to resolve to.
>>
>> There are commands that accept location specs and want to resolve them to
>> addresses, others to lines, etc., and you can specify a line to find the address,
>> and conversely you can also specify an address to find a line.
>>
>> Maybe we should say _that_ somehow, instead of the "Since @value{GDBN} is a
>> source-level debugger, a location specification usually indicates some
>> line" sentence, which I find kind of an unnecessary assertion.  Specifying
>> function names to break at the function's entry is very usual too, for example.
> 
> I'm not sure I understand the issue.  "Indicates" was in your original
> wording:

The original text before my changes used "specifies":

 Several @value{GDBN} commands accept arguments that specify a location
 of your program's code.  Since @value{GDBN} is a source-level
 debugger, a location usually specifies some line in the source code.
 Locations may be specified using three different formats:
 linespec locations, explicit locations, or address locations.

and I wanted to extend it to give the function name, address, label, etc. examples,
other attributes one can specify.

I don't recall exactly how I got to "indicate".  To me, in something
like "-line LINENUM", LINENUM is the line indicated in the spec.  In
"-function FUNC", FUNC is the function name indicated in the spec.
I think I was just trying to avoid the repetition in "a specification specifies",
which sounds like it was a mistake, as it introduced ambiguity.  Better to
go back to "specifies".

> 
>  Several @value{GDBN} commands accept arguments that specify a location
>  or locations of your program's code.  Since @value{GDBN} is a
>  source-level debugger, a location specification usually indicates some
>  line in the source code, but it can also indicate a function name, an
>  address, a label, and more.
> 
> The changes I made to these two sentences are really exceedingly
> minor, so I wonder how could they change the meaning.  Could you point
> to the modifications which change the meaning?

I already explained in the text quoted above.  Here again, and with some emphasis:

 >> I think it's a difference in the interpretation of "indicate".  The original
 >> text uses it to mean the arguments the user can specify (otherwise it wouldn't
                                                             ^^^^^^^^^^^^^^^^^^^^^
 >> be talking about "a label" or function _name_), while in your version you seem
    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 >> to be using "indicate" to mean the line number you want the spec to resolve to.
 >>
 >> There are commands that accept location specs and want to resolve them to
 >> addresses, others to lines, etc., and you can specify a line to find the address,
 >> and conversely you can also specify an address to find a line.

> 
> If you meant what the user specifies, then I agree that perhaps
> "indicate" is not the best word, 

Yes, agreed.

> but I didn't interpret the above as
> alluding to what the user specifies, I interpreted it to what the user
> _means_ by the spec: 

Right, the word was ambiguous and I didn't realize it when I used it.  Let's
fix that.

I'm fine if you want to instead change this to talk about the resolved
line in the program, but if we do that, then we should not give emphasis
to the line, but instead do something like I said before:

 >> There are commands that accept location specs and want to resolve them to
 >> addresses, others to lines, etc., and you can specify a line to find the address,
 >> and conversely you can also specify an address to find a line.
 >>
 >> Maybe we should say _that_ somehow, instead of the "Since @value{GDBN} is a
 >> source-level debugger, a location specification usually indicates some
 >> line" sentence, which I find kind of an unnecessary assertion.  Specifying
 >> function names to break at the function's entry is very usual too, for example.

> the user always means some source-code level location.

Note the word "means" here is ambiguous.  I take it you want to say "what the user
wants the spec to resolve to."

Not always a line, no.  The user may mean an address in the program too.
Recall some commands talk about that, like "jump":

 @item jump @var{locspec}
 @itemx j @var{locspec}
 Resume execution at the address of the code location that results from
 resolving @var{locspec}.

Or e.g., if you set a break like "b *ADDR", you want it to stick to that
address.  If you set a break like "b line", you want it to stick to that line.
Even though, those two specs may well resolve to the same line at that given
moment (which may change if shared libraries are subsequently loaded, or the
program is modified and/or recompiled).

> 
>>>  @item
>>>  For a C@t{++} constructor, the @value{NGCC} compiler generates several
>>> -instances of the function body, used in different cases.
>>> +instances of the function body, used in different cases, but their
>>> +source-level names are identical, unless you qualify them.
>>
>> What do you mean by "qualify" here?
> 
> The "fully-qualified and prototyped function" part.

That's unrelated to what is being alluded to here.  This is referring to in-charge
vs not-in-charge constructors ( and I just moved the example from "Set Breaks", so
don't shoot the messenger ;-) ):

 https://sourceware.org/legacy-ml/gdb/2003-10/msg00015.html

(that message obviously predates multi-location breakpoints.)

... an implementation detail that results in a breakpoint set on a constructor,
resolves to more than one code location, even if you specify a fully-qualified and
prototyped name, because the compiler emits two (slightly different) instances
of the function body machine code, for the same source code.  E.g., using a
testcase in the testsuite that covers this:

$ gdb ./testsuite/outputs/gdb.cp/mb-ctor/mb-ctor
...
(gdb) b -qualified Derived::Derived(int) 
Breakpoint 1 at 0x11b5: -qualified Derived::Derived(int). (2 locations)
(gdb) info breakpoints 
Num     Type           Disp Enb Address            What
1       breakpoint     keep y   <MULTIPLE>         
1.1                         y   0x00000000000011b5 in Derived::Derived(int) at /home/pedro/gdb/binutils-gdb/src/gdb/testsuite/gdb.cp/mb-ctor.cc:34
1.2                         y   0x0000000000001211 in Derived::Derived(int) at /home/pedro/gdb/binutils-gdb/src/gdb/testsuite/gdb.cp/mb-ctor.cc:34

(gdb) r
Starting program: /home/pedro/gdb/binutils-gdb/build/gdb/testsuite/outputs/gdb.cp/mb-ctor/mb-ctor 

Breakpoint 1, Derived::Derived (this=0x7fffffffdac0, i=7, __in_chrg=<optimized out>, __vtt_parm=<optimized out>) at /home/pedro/gdb/binutils-gdb/src/gdb/testsuite/gdb.cp/mb-ctor.cc:34
34      Derived::Derived(int i) : Base(i)
(gdb) p $pc
$1 = (void (*)(void)) 0x555555555211 <Derived::Derived(int)+19>
(gdb) bt
#0  Derived::Derived (this=0x7fffffffdac0, i=7, __in_chrg=<optimized out>, __vtt_parm=<optimized out>) at /home/pedro/gdb/binutils-gdb/src/gdb/testsuite/gdb.cp/mb-ctor.cc:34
#1  0x000055555555531f in main () at /home/pedro/gdb/binutils-gdb/src/gdb/testsuite/gdb.cp/mb-ctor.cc:61
(gdb) c
Continuing.

Breakpoint 1, Derived::Derived (this=0x7fffffffdaa0, __vtt_parm=0x555555557cb8 <VTT for DeeplyDerived+8>, i=15, __in_chrg=<optimized out>)
    at /home/pedro/gdb/binutils-gdb/src/gdb/testsuite/gdb.cp/mb-ctor.cc:34
34      Derived::Derived(int i) : Base(i)
(gdb) p $pc
$2 = (void (*)(void)) 0x5555555551b5 <Derived::Derived(int)+19>
(gdb) bt
#0  Derived::Derived (this=0x7fffffffdaa0, __vtt_parm=0x555555557cb8 <VTT for DeeplyDerived+8>, i=15, __in_chrg=<optimized out>)
    at /home/pedro/gdb/binutils-gdb/src/gdb/testsuite/gdb.cp/mb-ctor.cc:34
#1  0x00005555555553a7 in DeeplyDerived::DeeplyDerived (this=0x7fffffffdaa0, i=15, __in_chrg=<optimized out>, __vtt_parm=<optimized out>)
    at /home/pedro/gdb/binutils-gdb/src/gdb/testsuite/gdb.cp/mb-ctor.cc:54
#2  0x0000555555555330 in main () at /home/pedro/gdb/binutils-gdb/src/gdb/testsuite/gdb.cp/mb-ctor.cc:65
(gdb)