Re: [patchv2] Write bpt at the ON_STACK bpt address

[Jan Kratochvil <jan dot kratochvil at redhat dot com>]

On Sat, 28 Jul 2012 09:28:02 +0200, Eli Zaretskii wrote:
> > Date: Fri, 27 Jul 2012 20:46:33 +0200
> > From: Jan Kratochvil <jan.kratochvil@redhat.com>
> > Cc: Joel Brobecker <brobecker@adacore.com>, gdb-patches@sourceware.org,        "Maciej W. Rozycki" <macro@codesourcery.com>
> > 
> > -breakpoint should be inserted.  May return @code{NULL} to indicate that
> > -software breakpoints are not supported.
> > +breakpoint should be inserted.  The program counter (@code{*@var{pcptr}}
> > +is inferior PC register encoded on the input and it is a plain address on the
> > +output.  Function may return @code{NULL} to indicate that software breakpoints
> > +are not supported.
> 
> I suggest a slight rewording:
> 
>  On input, the program counter (@code{*@var{pcptr}} is the encoded
>  inferior's PC register.  The function returns the PC's plain address
>  in this argument, or @code{NULL} if software breakpoints are not
>  supported.
> 
> Does this catch the intent correctly?

I do not think that 'pcptr' and 'NULL' should be combined in one sentence,
these are two topics.

BTW I did not change any function behavior, I just try to better document
behavior of the existing functions.

One issue is that:
	Function may return @code{NULL} to indicate that software breakpoints
	are not supported.
This is returned as C function return value.  If NULL is returned other
parameters are irrelevant/unspecified.  And NULL is definitely unrelated to
pcptr.

The other issue, I try to better document the meaning of '*pcptr' input vs.
output value.  This is a value passed by reference.  Also it is not really the
PC register, it is just arbitrary location used for a breakpoint (therefore
pointing at code instructions).

I tried to reword it again and I ended up similar to my former proposal:
	On input, the program counter (@code{*@var{pcptr}} is encoded like the
	inferior's PC register, on output is is encoded as a plain address.
	Function may return @code{NULL} to indicate that software breakpoints
	are not supported.


Thanks,
Jan