Re: [PATCH] Document tracepoint restrictions

[Eli Zaretskii <eliz at gnu dot org>]

> Date: Thu, 11 Mar 2010 18:40:32 -0800
> From: Stan Shebs <stan@codesourcery.com>
> 
> While the savvy GDB hacker can use sekrit GDB internals knowledge to 
> surmise what will and won't work with tracepoints, normal users can 
> benefit from it being spelled out more explicitly.  This patch adds a 
> new section to the manual that explains some of the gotchas our new 
> generation of tracepoint users has experienced already.

Thanks.

> + @node Tracepoint Restrictions
> + @subsection Tracepoint Restrictions
> + 
> + There are a number of restrictions on the use of tracepoints.

As always, it is generally a good idea to have a @cindex entry whose
name is like the section name (in lower-case).

> + state variables).  Objective-C and Objective-C++ features are not
> + supported.

I'm not sure I understand the last sentence.  How are Objective-C/C++
features related to tracepoints?  Perhaps you should add some
explanation.

> + program -- particularly if a conditional branch is stepped.
           ^^^^
This should be 3 dashes in a row, and probably without spaces
surrounding it.  That way, it will look better in print.

> + collect not only the pointer, but the memory pointed to.  For example
> + @code{*ptr@@50} can be used to collect the 50 element array pointed to
> + by @code{ptr}.

A comma is missing after "For example".

> + tracepoint.  Instead you may collect the registers and a few hundred
                        ^
A comma is missing here.

> + bytes from the stack pointer with something like @code{*$esp@@300}
> + (adjust to use the name of the actual stack pointer register on your
> + target architecture, and the amount of stack you wish to capture).

Isn't it better to just use the generic $sp here?  Or are you saying
that it is not supported by tracepoints?

> + The above is not intended as an exhaustive list of restrictions.  As
> + described above, tracepoint data gathering occurs on the target
> + without interaction from GDB.  Thus the full capabilities of GDB are
> + not available during data gathering.

This should probably be moved to before the list, and rephrased
appropriately.

Okay with these changes.