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

[Eli Zaretskii]

> From: felix.willgerodt@intel.com
> Cc: markus.t.metzger@intel.com, Felix Willgerodt <felix.willgerodt@intel.com>
> Date: Wed, 29 May 2019 10:47:53 +0200
> 
> +* GDB now supports printing of ptwrite payloads from the Intel Processor
> +  Trace during 'record instruction-history', 'record  function-call-history',
                                                       ^^
Extra blank.

> +  all stepping commands and in  Python.  Printing is customizable via a
                          ^
A comma missing there.
> +use of the PTWRITE instruction. PTWRITE is a x86 instruction that allows to
                                 ^^
Two spaces between sentences, please.

> +The @value{NGCC} built-in functions for it are:
> +@smallexample
> +void __builtin_ia32_ptwrite32 (unsigned)
> +void __builtin_ia32_ptwrite64 (unsigned long long)
> +@end smallexample

Should there be a semi-colon at the end of each function prototype?

> +as auxiliary information into the execution history.  Auxiliary information
> +is by default printed during 'record instruction-history',
> +'record function-call-history' and all stepping commands and is accessible

The two "record" commands should be in @code and without quotes.
Also, please add a comma before the last "and".

> +in Python as a @code{RecordAuxiliary} object. 
> +
> +@exdent Sample program:
> +@smallexample
> +void
> +ptwrite64 (unsigned long long value)
> +@{
> +  __builtin_ia32_ptwrite64 (value);
> +@}
> +
> +int
> +main (void)
> +@{
> +  ptwrite64 (0x42);
> +  return 0; /* break here.  */
> +@}
> +@end smallexample
> +
> +@exdent @value{GDBN} output after recording the sample program in pt format:
> +@smallexample
> +(gdb) record instruction-history 12,14
> +12         0x000000000040074c <ptwrite64+16>:	ptwrite %rbx
> +13         [payload: 0x42]
> +14         0x0000000000400751 <ptwrite64+21>:	mov    -0x8(%rbp),%rbx
> +(gdb) record function-call-history
> +1       main
> +2       ptwrite64
> +                [payload: 0x42]
> +3       main
> +@end smallexample

Long examples such as the two above should use @group to avoid being
split between two pages in an unfortunate place.

> +auxiliary information. A custom Python function can be registered via
                        ^^
Two spaces.

> +@code{gdb.ptwrite.register_listener()} as the @dfn{ptwrite listener function}.

Every term you put in @dfn should have an index entry, as this is
generally terminology people will later look up in the manual.

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

If "IP" stands for "instruction pointer", I think that we prefer "PC"
instead.

> +@table @code
> +
> +@item register_listener (@var{listener})
> +Used to register the ptwrite listener.  The listener can be any callable
> +object that accepts two arguments.   It can return a string, which will be
                                     ^^^
Extra space.

> +printed by @value{GDBN} during the aforementioned commands, or @code{None},
> +resulting in no output.  @code{None} can also be registered to deactivate
> +printing.
> +
> +@item get_listener ()
> +Returns the currently active ptwrite listener function.
> +
> +@item default_listener (@var{payload}, @var{ip})
> +The listener function active by default.
> +@end table

Why is this a @table, and not a series of @defun's?

> +threads. The listener can however distinguish between multiple threads
          ^^
Missing space.

> +with the help of @code{gdb.selected_thread().global_num} or similar.

Please add a cross-reference to where gdb.selected_thread is described
in the manual.

Thanks.