Re: [PATCH v6 10/10] btrace: Extend ptwrite event decoding.

[Eli Zaretskii <eliz@gnu.org>]

> Date: Fri, 16 Sep 2022 13:36:46 +0200
> From: Felix Willgerodt via Gdb-patches <gdb-patches@sourceware.org>
> 
> --- a/gdb/NEWS
> +++ b/gdb/NEWS
> @@ -3,6 +3,12 @@
>  
>  *** Changes since GDB 12
>  
> +* GDB now supports printing of ptwrite payloads from the Intel Processor
> +  Trace during 'record instruction-history', 'record function-call-history',
> +  all stepping commands and in  Python.  Printing is customizable via a

Can we rephrase the "and in Python" part to be less confusing and
ambiguous?  (Also, there's an extraneous blank character there.)

> +If an inferior uses the instruction, @value{GDBN} by default inserts the
> +raw payload value as auxiliary information into the execution history.
> +Auxiliary information is by default printed during
> +@code{record instruction-history}, @code{record function-call-history},
> +and all stepping commands and is accessible in Python as a
                            ^
Comma missing there.

Btw, it sounds like this functionality is only available if GDB was
built with Python?  If so, I think other places where you mention this
in the manual should indicate that the feature is only available
through Python.

> +This function will be called with the ptwrite payload and PC as arguments
> +during trace decoding.                ^^^^^^^

@code{ptwrite}.

Also, please decide whether you want to use "ptwrite" in lower-case or
PTWRITE in upper-case, and please use the same convention everywhere
in the manual.

I also think talking about a "payload" obfuscates the description for
no good reason.  It's just a value of some data type supported by the
'ptwrite' instruction, right?  If so, I think "value" is much clearer
and less mysterious.

> +@findex gdb.ptwrite.register_filter
> +@defun register_filter (@var{filter})
> +Used to register the ptwrite filter.  The filter can be any callable
                        ^^^^^^^
@code{ptwrite}

> +@findex gdb.ptwrite.get_filter
> +@defun get_filter ()
> +Returns the currently active ptwrite filter function.

I think our style is to say "Return", not "Returns".

Thanks.