[MI tracepoints 9/9] documentation

[MI tracepoints 9/9] documentation

[Vladimir Prus]

[-- Attachment #1: Type: Text/Plain, Size: 159 bytes --]


I believe this documents all the changes made by my prior patches. OK?

Thanks,

-- 
Vladimir Prus
CodeSourcery
vladimir@codesourcery.com
(650) 331-3385 x722

[-- Attachment #2: 9-docs.diff --]
[-- Type: text/x-patch, Size: 9157 bytes --]

commit 233e013c8a31190ab41ce59d03edb8158c07e082
Author: vladimir <vladimir@e7755896-6108-0410-9592-8049d3e74e28>
Date:   Thu Aug 6 18:54:09 2009 +0000

    MI tracepoints documentation.
    
    	gdb/doc/
    	* gdb.texinfo (GDB/MI Tracepoint): Write it.
    
    git-svn-id: svn+ssh://cugel//net/svn-internal/subversion/Repository/csl/gdb/branches/ericsson-tracing@257867 e7755896-6108-0410-9592-8049d3e74e28

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 53989bb..4a7edf4 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -23097,7 +23097,7 @@ N.A.
 @subsubheading Synopsis
 
 @smallexample
- -break-insert [ -t ] [ -h ] [ -f ] [ -d ]
+ -break-insert [ -t ] [ -h ] [ -f ] [ -d ] [ -a ]
     [ -c @var{condition} ] [ -i @var{ignore-count} ]
     [ -p @var{thread} ] [ @var{location} ]
 @end smallexample
@@ -23134,6 +23134,9 @@ an error, and won't create a breakpoint, if @var{location}
 cannot be parsed.
 @item -d
 Create a disabled breakpoint.
+@item -a
+Create a tracepoint. @xref{Tracepoints}. When this parameter
+is used together with @samp{-h}, a fast tracepoint is created.
 @end table
 
 @subsubheading Result
@@ -23271,6 +23274,20 @@ body=[]@}
 (gdb)
 @end smallexample
 
+@subheading The @code{-break-passcount} Command
+@findex -break-passcount
+
+@subsubheading Synopsis
+
+@smallexample
+ -break-passcount @var{tracepoint-number} @var{passcount}
+@end smallexample
+
+Set the passcount for tracepoint @var{tracepoint-number} to
+@var{passcount}.  If breakpoint referred to by @var{tracepoint-number}
+is not a tracepoint, error is emitted.  This corresponds to CLI
+command @samp{passcount}.
+
 @subheading The @code{-break-watch} Command
 @findex -break-watch
 
@@ -25928,37 +25945,229 @@ next-page="0x000013c0",prev-page="0x00001380",memory=[
 @node GDB/MI Tracepoint Commands
 @section @sc{gdb/mi} Tracepoint Commands
 
-The tracepoint commands are not yet implemented.
+The commands defined in this section implement MI support for
+tracepoints.  For detailed introduction, @pxref{Tracepoints}.
+
+@subheading The @code{-trace-find} Command
+@findex -trace-find
+
+@subsubheading Synopsis
+
+@smallexample
+ -trace-find @var{mode} [@var{parameters...}]
+@end smallexample
+
+Find a trace frame using criteria defined by @var{mode} and
+@var{parameters}.  The following table lists permissible
+modes and their parameters.  For details of operation, @pxref{tfind}.
+
+@table @samp
+
+@item none
+No parameters are required.  Stops examining trace frames.
+
+@item frame-number
+An integer is required as parameter.  Selects tracepoint frame with
+that index.
+
+@item tracepoint-number
+An integer is required as parameter. Finds next
+trace frame that corresponds to tracepoint with the specified number.
+
+@item pc
+An integer address is required as parameter.  Finds
+next trace frame that corresponds to any tracepoint at the specified
+address.
+
+@item pc-inside-range
+Two integer addresses are required as parameters.  Finds next trace
+frame that corresponds to a tracepoint at an address inside the
+specified range.
+
+@item pc-outside-range
+Two integer addresses are required as parameters.  Finds
+next trace frame that corresponds to a tracepoint at an address outside
+the specified range.
+
+@item line
+Line specification is required as parameter. @xref{Specify Location}.
+Finds next trace frame that corresponds to a tracepoint at
+the specified location.
 
-@c @subheading -trace-actions
+@end table
 
-@c @subheading -trace-delete
+If the @samp{none} was passed as @var{mode}, the response does not
+have fields.  Otherwise, the response may have the following fields:
 
-@c @subheading -trace-disable
+@table @samp
+@item found
+This field has either @samp{0} or @samp{1} as the value, depending
+on whether a matching tracepoint was found.
 
-@c @subheading -trace-dump
+@item traceframe
+The index of the found traceframe.  This field is present iff
+the @var{found} field has value of @samp{1}.
 
-@c @subheading -trace-enable
+@item tracepoint
+The index of the found tracepoint.  This field is present iff
+the @var{found} field has value of @samp{1}.
 
-@c @subheading -trace-exists
+@item frame
+The information about the frame corresponding to the found trace
+frame. This field is present only if a trace frame was found.
+See @xref{GDB/MI Frame Information} for description of this field.
 
-@c @subheading -trace-find
+@end table
 
-@c @subheading -trace-frame-number
+@subheading -trace-define-variable
+@findex -trace-define-variable
 
-@c @subheading -trace-info
+@subsubheading Synopsis
 
-@c @subheading -trace-insert
+@smallexample
+ -trace-define-variable @var{name} [ @var{value} ]
+@end smallexample
 
-@c @subheading -trace-list
+Creates trace variable @var{name} if it does not exist.  If
+@var{value} is specified, sets the initial value of the specified
+trace variable to that value.  Note that the @var{name} should start
+with the @samp{$} character.
 
-@c @subheading -trace-pass-count
+@subheading -trace-list-variables
+@findex -trace-list-variables
 
-@c @subheading -trace-save
+@subsubheading Synopsis
+
+@smallexample
+ -trace-list-variables
+@end smallexample
+
+Return a table of all defined trace variables. Each element of the
+table has the following fields
+
+@table @samp
+@item name
+The name of the trace variable.  This field is always present.
+
+@item initial
+The initial value.  This is a 64-bit signed integer.  This
+field is always present.
+
+@item current
+The value the trace variable has at the moment.  This is a 64-bit
+signed integer.  This field may is absent iff current value is
+not defined, for example if the trace was never run, or is
+presently running.
+
+@end table
 
-@c @subheading -trace-start
+@subsubheading Example
+
+@smallexample
+(gdb)
+-trace-list-variables
+^done,trace-variables=@{nr_rows="1",nr_cols="3",
+hdr=[@{width="15",alignment="-1",col_name="name",colhdr="Name"@},
+     @{width="11",alignment="-1",col_name="initial",colhdr="Initial"@},
+     @{width="11",alignment="-1",col_name="current",colhdr="Current"@}],
+body=[variable=@{name="$trace_timestamp",initial="0"@}
+      variable=@{name="$foo",initial="10",current="15"@}]@}
+(gdb)
+@end smallexample
+
+@subheading -trace-save
+@findex -trace-save
+
+@subsubheading Synopsis
+
+@smallexample
+ -trace-save [-r ] @var{filename}
+@end smallexample
+
+Saves the collected trace data to @var{filename}.  Without the
+@samp{-r} option, the data is download from the target and saved
+in a local file.  With the @samp{-r} option the target is asked
+to perform the save.
+
+
+@subheading -trace-start
+@findex -trace-start
+
+@subsubheading Synopsis
+
+@smallexample
+ -trace-start
+@end smallexample
+
+Starts a tracing experiments.  The result of this command does not
+have any fields.
+
+@subheading -trace-status
+@findex -trace-status
+
+@subsubheading Synopsis
+
+@smallexample
+ -trace-status
+@end smallexample
+
+Obtains the status of a tracing experiement.  The result may include
+the following fields:
+
+@table @samp
+
+@item supported
+May have a value of either @samp{0}, when no tracing operations are
+supported, @samp{1}, when all tracing operations are supported, and
+@samp{file} when examining trace file.  In the latter case, examining
+of trace frame is possible but new tracing experiement cannot be
+started.  This field is always present.
+
+@item running
+May have a value of either @samp{0} or @samp{1} depending on whether
+tracing experiement is in progress on target.  This field is present
+if @samp{supported} field is not @samp{0}.
+
+@item stop-reason
+Report the reason why the tracing was stopped last time.  This field
+may be absent iff tracing was never stopped on target yet.  The
+value of @samp{request} mean the tracing was stopped as result of
+the @code{-trace-stop} command.  The value of @samp{overflow} means
+the tracing buffer is full.  The value of @samp{disconnection} means
+tracing was automatically stopped when @value{GDBN} has disconnected.
+The value of @samp{passcount} means tracing was stopped when a
+tracepoint was passed a maximal number of times for that tracepoint.
+This field is present if @samp{supported} field is not @samp{0}.
+
+@item stopping-tracepoint
+The number of tracepoint which passcount as exceeded.  This field is
+only present iff the @samp{stop-reason} field has the value of
+@samp{passcount}.
+
+@item frames
+This field is an integer number of currently collected frames. This field is present
+if @samp{supported} field is not @samp{0}.
+
+@item buffer-size
+@itemx buffer-free
+These fields tell the current size of the tracing buffer and the
+remaining space.  These fields are present if @samp{supported} field
+is not @samp{0}.
+
+@end table
+
+@subheading -trace-stop
+@findex -trace-stop
+
+@subsubheading Synopsis
+
+@smallexample
+ -trace-stop
+@end smallexample
 
-@c @subheading -trace-stop
+Stops a tracing experiment.  The result of this command has the same
+fields as @code{-trace-status}, except that the @samp{supported} and
+@samp{running} fields are not output.
 
 
 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

Re: [MI tracepoints 9/9] documentation

[Eli Zaretskii]

> From: Vladimir Prus <vladimir@codesourcery.com>
> Date: Sun, 14 Mar 2010 12:04:11 +0300
> 
> I believe this documents all the changes made by my prior patches. OK?

Thanks.  A few comments:

>     MI tracepoints documentation.
>     
>     	gdb/doc/
>     	* gdb.texinfo (GDB/MI Tracepoint): Write it.

I'll probably get another cold shower for expressing opinions about
ChangeLog style, but I find this rather un-useful.  Why not

	* gdb.texinfo (GDB/MI Tracepoint): Document MI tracepoint
          commands.

i.e. without the header line?  Such short entries don't really need
any summary, they summarize themselves.

And btw, there's no node named "GDB/MI Tracepoint", you made changes
in more than one node with different names.

> +Create a tracepoint. @xref{Tracepoints}. When this parameter
                      ^^                  ^^
Two spaces between sentences, please (here and elsewhere).

> +@var{passcount}.  If breakpoint referred to by @var{tracepoint-number}
                        ^^^^^^^^^^
"the breakpoint"

> +tracepoints.  For detailed introduction, @pxref{Tracepoints}.

That's incorrect usage of @pxref (you should see 2 periods in the Info
output).  It should be used only in parentheses.  Please use "see
@ref" instead.

> +@smallexample
> + -trace-find @var{mode} [@var{parameters...}]
                                           ^^^
@dots{} will produce a nicer printed output here.  In any case, the
dots should be outside of @var{}.

> +modes and their parameters.  For details of operation, @pxref{tfind}.
                                                          ^^^^^^^^^^^^^
"see @ref".

> +@item pc
> +An integer address is required as parameter.

I think "An address is required as parameter", without the "integer"
part, is better.  An address is always integer in GDB, right?

> +next trace frame that corresponds to any tracepoint at the specified
> +address.
> +
> +@item pc-inside-range
> +Two integer addresses are required as parameters.

Ditto.

>                                                     Finds next trace
> +frame that corresponds to a tracepoint at an address inside the
> +specified range.

Inclusive or exclusive?

> +@item pc-outside-range
> +Two integer addresses are required as parameters.  Finds
> +next trace frame that corresponds to a tracepoint at an address outside
> +the specified range.

Ditto.

> +If the @samp{none} was passed as @var{mode}, the response does not
      ^^^
No need for "the" here.

> +@item traceframe
> +The index of the found traceframe.  This field is present iff
> +the @var{found} field has value of @samp{1}.

"found" should be in @samp, not @var: it is a literal string, not a
parameter that stands for some other string.

> +@item tracepoint
> +The index of the found tracepoint.  This field is present iff
> +the @var{found} field has value of @samp{1}.

Ditto.

> +See @xref{GDB/MI Frame Information} for description of this field.

Just "@xref" is enough, it produces "See" for you.

> +@smallexample
> + -trace-define-variable @var{name} [ @var{value} ]
> +@end smallexample
>  
> -@c @subheading -trace-list
> +Creates trace variable @var{name} if it does not exist.  If

"Create", to be consistent with the other descriptions ("find",
"return", etc.).

> +Return a table of all defined trace variables. Each element of the
> +table has the following fields

"fields:", with a colon.

> +signed integer.  This field may is absent iff current value is
                               ^^^
That "may" looks redundant.

> +@smallexample
> +(gdb)
> +-trace-list-variables
> +^done,trace-variables=@{nr_rows="1",nr_cols="3",
> +hdr=[@{width="15",alignment="-1",col_name="name",colhdr="Name"@},
> +     @{width="11",alignment="-1",col_name="initial",colhdr="Initial"@},
> +     @{width="11",alignment="-1",col_name="current",colhdr="Current"@}],
> +body=[variable=@{name="$trace_timestamp",initial="0"@}
> +      variable=@{name="$foo",initial="10",current="15"@}]@}
> +(gdb)

?? This does not match the documentation: no "name", no "initial", no
"current"...  What am I missing?

> +@samp{-r} option, the data is download from the target and saved
                                 ^^^^^^^^
"downloaded", I think.

> +May have a value of either @samp{0}, when no tracing operations are
> +supported, @samp{1}, when all tracing operations are supported, and
> +@samp{file} when examining trace file.                          ^^^

"or" instead of "and", since you said "either" above.

> +                                                              The
> +value of @samp{request} mean the tracing was stopped as result of
                           ^^^^
"means"

> +@item stopping-tracepoint
> +The number of tracepoint which passcount as exceeded.
                            ^^^^^
"whose"

> +only present iff the @samp{stop-reason} field has the value of

You need either "only" or "iff", but not both.  If you leave "only",
make "iff" be just "if".

Okay with these changes.

Re: [MI tracepoints 9/9] documentation

[Vladimir Prus]

[-- Attachment #1: Type: Text/Plain, Size: 2213 bytes --]

On Sunday 14 March 2010 21:25:33 Eli Zaretskii wrote:

> > From: Vladimir Prus <vladimir@codesourcery.com>
> > Date: Sun, 14 Mar 2010 12:04:11 +0300
> > 
> > I believe this documents all the changes made by my prior patches. OK?
> 
> Thanks.  A few comments:
> 
> >     MI tracepoints documentation.
> >     
> >     	gdb/doc/
> >     	* gdb.texinfo (GDB/MI Tracepoint): Write it.
> 
> I'll probably get another cold shower for expressing opinions about
> ChangeLog style, but I find this rather un-useful.  Why not
> 
> 	* gdb.texinfo (GDB/MI Tracepoint): Document MI tracepoint
>           commands.
> 
> i.e. without the header line?  Such short entries don't really need
> any summary, they summarize themselves.

The primary reason I use summary line everywhere is that I prefer to see
a list of commits, one per line, with sensible summary, so that I can
quickly pick a commit I care about. This is of course only important
when I am working with git, since cvs does not provide such formatting
style for logs.

I don't particularly care for this commit -- I am unlikely to ever
need it thereafter.

> > +@smallexample
> > +(gdb)
> > +-trace-list-variables
> > +^done,trace-variables=@{nr_rows="1",nr_cols="3",
> > +hdr=[@{width="15",alignment="-1",col_name="name",colhdr="Name"@},
> > +     @{width="11",alignment="-1",col_name="initial",colhdr="Initial"@},
> > +     @{width="11",alignment="-1",col_name="current",colhdr="Current"@}],
> > +body=[variable=@{name="$trace_timestamp",initial="0"@}
> > +      variable=@{name="$foo",initial="10",current="15"@}]@}
> > +(gdb)
> 
> ?? This does not match the documentation: no "name", no "initial", no
> "current"...  What am I missing?

I surely do see "name", "initial" and "current" fields above -- except
that the first variable does not have "current" -- which is OK. Maybe,
it's the "table" that confuses things -- the above hdr/body thing is
exactly what MI calls a table, and only 'body' is the actual content.

Thanks for review -- I have applied other comments pretty much as
written. Here's the revised patch that I plan to commit after the
code patches are in.


Thanks,

-- 
Vladimir Prus
CodeSourcery
vladimir@codesourcery.com
(650) 331-3385 x722

[-- Attachment #2: 9-docs-2.diff --]
[-- Type: text/x-patch, Size: 9081 bytes --]

commit 0fffda0d89eba7f94be14505ae0739354dee4e90
Author: vladimir <vladimir@e7755896-6108-0410-9592-8049d3e74e28>
Date:   Thu Aug 6 18:54:09 2009 +0000

    	* gdb.texinfo (GDB/MI Tracepoint Commands): Document MI tracepoint
              commands.

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 53989bb..9354894 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -23097,7 +23097,7 @@ N.A.
 @subsubheading Synopsis
 
 @smallexample
- -break-insert [ -t ] [ -h ] [ -f ] [ -d ]
+ -break-insert [ -t ] [ -h ] [ -f ] [ -d ] [ -a ]
     [ -c @var{condition} ] [ -i @var{ignore-count} ]
     [ -p @var{thread} ] [ @var{location} ]
 @end smallexample
@@ -23134,6 +23134,9 @@ an error, and won't create a breakpoint, if @var{location}
 cannot be parsed.
 @item -d
 Create a disabled breakpoint.
+@item -a
+Create a tracepoint.  @xref{Tracepoints}.  When this parameter
+is used together with @samp{-h}, a fast tracepoint is created.
 @end table
 
 @subsubheading Result
@@ -23271,6 +23274,20 @@ body=[]@}
 (gdb)
 @end smallexample
 
+@subheading The @code{-break-passcount} Command
+@findex -break-passcount
+
+@subsubheading Synopsis
+
+@smallexample
+ -break-passcount @var{tracepoint-number} @var{passcount}
+@end smallexample
+
+Set the passcount for tracepoint @var{tracepoint-number} to
+@var{passcount}.  If the breakpoint referred to by @var{tracepoint-number}
+is not a tracepoint, error is emitted.  This corresponds to CLI
+command @samp{passcount}.
+
 @subheading The @code{-break-watch} Command
 @findex -break-watch
 
@@ -25928,37 +25945,229 @@ next-page="0x000013c0",prev-page="0x00001380",memory=[
 @node GDB/MI Tracepoint Commands
 @section @sc{gdb/mi} Tracepoint Commands
 
-The tracepoint commands are not yet implemented.
+The commands defined in this section implement MI support for
+tracepoints.  For detailed introduction, see @ref{Tracepoints}.
+
+@subheading The @code{-trace-find} Command
+@findex -trace-find
+
+@subsubheading Synopsis
+
+@smallexample
+ -trace-find @var{mode} [@var{parameters}@dots{}]
+@end smallexample
+
+Find a trace frame using criteria defined by @var{mode} and
+@var{parameters}.  The following table lists permissible
+modes and their parameters.  For details of operation, see @ref{tfind}.
+
+@table @samp
+
+@item none
+No parameters are required.  Stops examining trace frames.
+
+@item frame-number
+An integer is required as parameter.  Selects tracepoint frame with
+that index.
+
+@item tracepoint-number
+An integer is required as parameter.  Finds next
+trace frame that corresponds to tracepoint with the specified number.
+
+@item pc
+An address is required as parameter.  Finds
+next trace frame that corresponds to any tracepoint at the specified
+address.
+
+@item pc-inside-range
+Two addresses are required as parameters.  Finds next trace
+frame that corresponds to a tracepoint at an address inside the
+specified range.  Both bounds are considered to be inside the range.
+
+@item pc-outside-range
+Two addresses are required as parameters.  Finds
+next trace frame that corresponds to a tracepoint at an address outside
+the specified range.  Both bounds are considered to be inside the range.
+
+@item line
+Line specification is required as parameter.  @xref{Specify Location}.
+Finds next trace frame that corresponds to a tracepoint at
+the specified location.
 
-@c @subheading -trace-actions
+@end table
 
-@c @subheading -trace-delete
+If @samp{none} was passed as @var{mode}, the response does not
+have fields.  Otherwise, the response may have the following fields:
 
-@c @subheading -trace-disable
+@table @samp
+@item found
+This field has either @samp{0} or @samp{1} as the value, depending
+on whether a matching tracepoint was found.
 
-@c @subheading -trace-dump
+@item traceframe
+The index of the found traceframe.  This field is present iff
+the @samp{found} field has value of @samp{1}.
 
-@c @subheading -trace-enable
+@item tracepoint
+The index of the found tracepoint.  This field is present iff
+the @samp{found} field has value of @samp{1}.
 
-@c @subheading -trace-exists
+@item frame
+The information about the frame corresponding to the found trace
+frame.  This field is present only if a trace frame was found.
+@xref{GDB/MI Frame Information} for description of this field.
 
-@c @subheading -trace-find
+@end table
 
-@c @subheading -trace-frame-number
+@subheading -trace-define-variable
+@findex -trace-define-variable
 
-@c @subheading -trace-info
+@subsubheading Synopsis
 
-@c @subheading -trace-insert
+@smallexample
+ -trace-define-variable @var{name} [ @var{value} ]
+@end smallexample
 
-@c @subheading -trace-list
+Create trace variable @var{name} if it does not exist.  If
+@var{value} is specified, sets the initial value of the specified
+trace variable to that value.  Note that the @var{name} should start
+with the @samp{$} character.
 
-@c @subheading -trace-pass-count
+@subheading -trace-list-variables
+@findex -trace-list-variables
 
-@c @subheading -trace-save
+@subsubheading Synopsis
+
+@smallexample
+ -trace-list-variables
+@end smallexample
+
+Return a table of all defined trace variables.  Each element of the
+table has the following fields:
+
+@table @samp
+@item name
+The name of the trace variable.  This field is always present.
+
+@item initial
+The initial value.  This is a 64-bit signed integer.  This
+field is always present.
+
+@item current
+The value the trace variable has at the moment.  This is a 64-bit
+signed integer.  This field is absent iff current value is
+not defined, for example if the trace was never run, or is
+presently running.
+
+@end table
 
-@c @subheading -trace-start
+@subsubheading Example
+
+@smallexample
+(gdb)
+-trace-list-variables
+^done,trace-variables=@{nr_rows="1",nr_cols="3",
+hdr=[@{width="15",alignment="-1",col_name="name",colhdr="Name"@},
+     @{width="11",alignment="-1",col_name="initial",colhdr="Initial"@},
+     @{width="11",alignment="-1",col_name="current",colhdr="Current"@}],
+body=[variable=@{name="$trace_timestamp",initial="0"@}
+      variable=@{name="$foo",initial="10",current="15"@}]@}
+(gdb)
+@end smallexample
+
+@subheading -trace-save
+@findex -trace-save
+
+@subsubheading Synopsis
+
+@smallexample
+ -trace-save [-r ] @var{filename}
+@end smallexample
+
+Saves the collected trace data to @var{filename}.  Without the
+@samp{-r} option, the data is downloaded from the target and saved
+in a local file.  With the @samp{-r} option the target is asked
+to perform the save.
+
+
+@subheading -trace-start
+@findex -trace-start
+
+@subsubheading Synopsis
+
+@smallexample
+ -trace-start
+@end smallexample
+
+Starts a tracing experiments.  The result of this command does not
+have any fields.
+
+@subheading -trace-status
+@findex -trace-status
+
+@subsubheading Synopsis
+
+@smallexample
+ -trace-status
+@end smallexample
+
+Obtains the status of a tracing experiement.  The result may include
+the following fields:
+
+@table @samp
+
+@item supported
+May have a value of either @samp{0}, when no tracing operations are
+supported, @samp{1}, when all tracing operations are supported, or
+@samp{file} when examining trace file.  In the latter case, examining
+of trace frame is possible but new tracing experiement cannot be
+started.  This field is always present.
+
+@item running
+May have a value of either @samp{0} or @samp{1} depending on whether
+tracing experiement is in progress on target.  This field is present
+if @samp{supported} field is not @samp{0}.
+
+@item stop-reason
+Report the reason why the tracing was stopped last time.  This field
+may be absent iff tracing was never stopped on target yet.  The
+value of @samp{request} means the tracing was stopped as result of
+the @code{-trace-stop} command.  The value of @samp{overflow} means
+the tracing buffer is full.  The value of @samp{disconnection} means
+tracing was automatically stopped when @value{GDBN} has disconnected.
+The value of @samp{passcount} means tracing was stopped when a
+tracepoint was passed a maximal number of times for that tracepoint.
+This field is present if @samp{supported} field is not @samp{0}.
+
+@item stopping-tracepoint
+The number of tracepoint whose passcount as exceeded.  This field is
+present iff the @samp{stop-reason} field has the value of
+@samp{passcount}.
+
+@item frames
+This field is an integer number of currently collected frames.  This
+field is present if @samp{supported} field is not @samp{0}.
+
+@item buffer-size
+@itemx buffer-free
+These fields tell the current size of the tracing buffer and the
+remaining space.  These fields are present if @samp{supported} field
+is not @samp{0}.
+
+@end table
+
+@subheading -trace-stop
+@findex -trace-stop
+
+@subsubheading Synopsis
+
+@smallexample
+ -trace-stop
+@end smallexample
 
-@c @subheading -trace-stop
+Stops a tracing experiment.  The result of this command has the same
+fields as @code{-trace-status}, except that the @samp{supported} and
+@samp{running} fields are not output.
 
 
 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

[-- Attachment #3: 9-delta.diff --]
[-- Type: text/x-patch, Size: 7373 bytes --]

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 4a7edf4..9354894 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -23135,7 +23135,7 @@ cannot be parsed.
 @item -d
 Create a disabled breakpoint.
 @item -a
-Create a tracepoint. @xref{Tracepoints}. When this parameter
+Create a tracepoint.  @xref{Tracepoints}.  When this parameter
 is used together with @samp{-h}, a fast tracepoint is created.
 @end table
 
@@ -23284,7 +23284,7 @@ body=[]@}
 @end smallexample
 
 Set the passcount for tracepoint @var{tracepoint-number} to
-@var{passcount}.  If breakpoint referred to by @var{tracepoint-number}
+@var{passcount}.  If the breakpoint referred to by @var{tracepoint-number}
 is not a tracepoint, error is emitted.  This corresponds to CLI
 command @samp{passcount}.
 
@@ -25946,7 +25946,7 @@ next-page="0x000013c0",prev-page="0x00001380",memory=[
 @section @sc{gdb/mi} Tracepoint Commands
 
 The commands defined in this section implement MI support for
-tracepoints.  For detailed introduction, @pxref{Tracepoints}.
+tracepoints.  For detailed introduction, see @ref{Tracepoints}.
 
 @subheading The @code{-trace-find} Command
 @findex -trace-find
@@ -25954,12 +25954,12 @@ tracepoints.  For detailed introduction, @pxref{Tracepoints}.
 @subsubheading Synopsis
 
 @smallexample
- -trace-find @var{mode} [@var{parameters...}]
+ -trace-find @var{mode} [@var{parameters}@dots{}]
 @end smallexample
 
 Find a trace frame using criteria defined by @var{mode} and
 @var{parameters}.  The following table lists permissible
-modes and their parameters.  For details of operation, @pxref{tfind}.
+modes and their parameters.  For details of operation, see @ref{tfind}.
 
 @table @samp
 
@@ -25971,32 +25971,32 @@ An integer is required as parameter.  Selects tracepoint frame with
 that index.
 
 @item tracepoint-number
-An integer is required as parameter. Finds next
+An integer is required as parameter.  Finds next
 trace frame that corresponds to tracepoint with the specified number.
 
 @item pc
-An integer address is required as parameter.  Finds
+An address is required as parameter.  Finds
 next trace frame that corresponds to any tracepoint at the specified
 address.
 
 @item pc-inside-range
-Two integer addresses are required as parameters.  Finds next trace
+Two addresses are required as parameters.  Finds next trace
 frame that corresponds to a tracepoint at an address inside the
-specified range.
+specified range.  Both bounds are considered to be inside the range.
 
 @item pc-outside-range
-Two integer addresses are required as parameters.  Finds
+Two addresses are required as parameters.  Finds
 next trace frame that corresponds to a tracepoint at an address outside
-the specified range.
+the specified range.  Both bounds are considered to be inside the range.
 
 @item line
-Line specification is required as parameter. @xref{Specify Location}.
+Line specification is required as parameter.  @xref{Specify Location}.
 Finds next trace frame that corresponds to a tracepoint at
 the specified location.
 
 @end table
 
-If the @samp{none} was passed as @var{mode}, the response does not
+If @samp{none} was passed as @var{mode}, the response does not
 have fields.  Otherwise, the response may have the following fields:
 
 @table @samp
@@ -26006,16 +26006,16 @@ on whether a matching tracepoint was found.
 
 @item traceframe
 The index of the found traceframe.  This field is present iff
-the @var{found} field has value of @samp{1}.
+the @samp{found} field has value of @samp{1}.
 
 @item tracepoint
 The index of the found tracepoint.  This field is present iff
-the @var{found} field has value of @samp{1}.
+the @samp{found} field has value of @samp{1}.
 
 @item frame
 The information about the frame corresponding to the found trace
-frame. This field is present only if a trace frame was found.
-See @xref{GDB/MI Frame Information} for description of this field.
+frame.  This field is present only if a trace frame was found.
+@xref{GDB/MI Frame Information} for description of this field.
 
 @end table
 
@@ -26028,7 +26028,7 @@ See @xref{GDB/MI Frame Information} for description of this field.
  -trace-define-variable @var{name} [ @var{value} ]
 @end smallexample
 
-Creates trace variable @var{name} if it does not exist.  If
+Create trace variable @var{name} if it does not exist.  If
 @var{value} is specified, sets the initial value of the specified
 trace variable to that value.  Note that the @var{name} should start
 with the @samp{$} character.
@@ -26042,8 +26042,8 @@ with the @samp{$} character.
  -trace-list-variables
 @end smallexample
 
-Return a table of all defined trace variables. Each element of the
-table has the following fields
+Return a table of all defined trace variables.  Each element of the
+table has the following fields:
 
 @table @samp
 @item name
@@ -26055,7 +26055,7 @@ field is always present.
 
 @item current
 The value the trace variable has at the moment.  This is a 64-bit
-signed integer.  This field may is absent iff current value is
+signed integer.  This field is absent iff current value is
 not defined, for example if the trace was never run, or is
 presently running.
 
@@ -26085,7 +26085,7 @@ body=[variable=@{name="$trace_timestamp",initial="0"@}
 @end smallexample
 
 Saves the collected trace data to @var{filename}.  Without the
-@samp{-r} option, the data is download from the target and saved
+@samp{-r} option, the data is downloaded from the target and saved
 in a local file.  With the @samp{-r} option the target is asked
 to perform the save.
 
@@ -26118,7 +26118,7 @@ the following fields:
 
 @item supported
 May have a value of either @samp{0}, when no tracing operations are
-supported, @samp{1}, when all tracing operations are supported, and
+supported, @samp{1}, when all tracing operations are supported, or
 @samp{file} when examining trace file.  In the latter case, examining
 of trace frame is possible but new tracing experiement cannot be
 started.  This field is always present.
@@ -26131,7 +26131,7 @@ if @samp{supported} field is not @samp{0}.
 @item stop-reason
 Report the reason why the tracing was stopped last time.  This field
 may be absent iff tracing was never stopped on target yet.  The
-value of @samp{request} mean the tracing was stopped as result of
+value of @samp{request} means the tracing was stopped as result of
 the @code{-trace-stop} command.  The value of @samp{overflow} means
 the tracing buffer is full.  The value of @samp{disconnection} means
 tracing was automatically stopped when @value{GDBN} has disconnected.
@@ -26140,13 +26140,13 @@ tracepoint was passed a maximal number of times for that tracepoint.
 This field is present if @samp{supported} field is not @samp{0}.
 
 @item stopping-tracepoint
-The number of tracepoint which passcount as exceeded.  This field is
-only present iff the @samp{stop-reason} field has the value of
+The number of tracepoint whose passcount as exceeded.  This field is
+present iff the @samp{stop-reason} field has the value of
 @samp{passcount}.
 
 @item frames
-This field is an integer number of currently collected frames. This field is present
-if @samp{supported} field is not @samp{0}.
+This field is an integer number of currently collected frames.  This
+field is present if @samp{supported} field is not @samp{0}.
 
 @item buffer-size
 @itemx buffer-free

Re: [MI tracepoints 9/9] documentation

[Tom Tromey]

>>>>> "Volodya" == Vladimir Prus <vladimir@codesourcery.com> writes:

Volodya> Thanks for review -- I have applied other comments pretty much as
Volodya> written. Here's the revised patch that I plan to commit after the
Volodya> code patches are in.

Volodya>  @item frame
Volodya>  The information about the frame corresponding to the found trace
Volodya> -frame. This field is present only if a trace frame was found.
Volodya> -See @xref{GDB/MI Frame Information} for description of this field.
Volodya> +frame.  This field is present only if a trace frame was found.
Volodya> +@xref{GDB/MI Frame Information} for description of this field.

This introduced a warning from makeinfo:

makeinfo -I ../../../src/gdb/doc/../../readline/doc -I ../../../src/gdb/doc/../mi -I ../../../src/gdb/doc \
		-o gdb.info ../../../src/gdb/doc/gdb.texinfo
../../../src/gdb/doc/gdb.texinfo:26053: warning: `.' or `,' must follow @xref, not `f'.

Tom

Re: [MI tracepoints 9/9] documentation

[Vladimir Prus]

Tom Tromey wrote:

>>>>>> "Volodya" == Vladimir Prus <vladimir@codesourcery.com> writes:
> 
> Volodya> Thanks for review -- I have applied other comments pretty much as
> Volodya> written. Here's the revised patch that I plan to commit after the
> Volodya> code patches are in.
> 
> Volodya>  @item frame
> Volodya>  The information about the frame corresponding to the found trace
> Volodya> -frame. This field is present only if a trace frame was found.
> Volodya> -See @xref{GDB/MI Frame Information} for description of this field.
> Volodya> +frame.  This field is present only if a trace frame was found.
> Volodya> +@xref{GDB/MI Frame Information} for description of this field.
> 
> This introduced a warning from makeinfo:
> 
> makeinfo -I ../../../src/gdb/doc/../../readline/doc -I ../../../src/gdb/doc/../mi -I
> ../../../src/gdb/doc \ -o gdb.info ../../../src/gdb/doc/gdb.texinfo
> ../../../src/gdb/doc/gdb.texinfo:26053: warning: `.' or `,' must follow @xref, not `f'.

Sorry -- I think I did what I was asked to do, and I don't understand what this warning
is trying to tell me. Assuming this is a valid warning, how do I fix it?

- Volodya

Re: [MI tracepoints 9/9] documentation

[Tom Tromey]

>>>>> "Volodya" == Vladimir Prus <vladimir@codesourcery.com> writes:

Volodya> Sorry -- I think I did what I was asked to do, and I don't
Volodya> understand what this warning is trying to tell me. Assuming
Volodya> this is a valid warning, how do I fix it?

According to the texinfo manual:

     Caution: A period or comma *must* follow the closing brace of an
     `@xref'.  It is required to terminate the cross reference.  This
     period or comma will appear in the output, both in the Info file
     and in the printed manual.

So I guess you ought to add a comma after the closing brace.

Tom

Re: [MI tracepoints 9/9] documentation

[Eli Zaretskii]

> From: Tom Tromey <tromey@redhat.com>
> Cc: gdb-patches@sources.redhat.com
> Date: Wed, 24 Mar 2010 15:43:42 -0600
> 
> >>>>> "Volodya" == Vladimir Prus <vladimir@codesourcery.com> writes:
> 
> Volodya> Sorry -- I think I did what I was asked to do, and I don't
> Volodya> understand what this warning is trying to tell me. Assuming
> Volodya> this is a valid warning, how do I fix it?
> 
> According to the texinfo manual:
> 
>      Caution: A period or comma *must* follow the closing brace of an
>      `@xref'.  It is required to terminate the cross reference.  This
>      period or comma will appear in the output, both in the Info file
>      and in the printed manual.
> 
> So I guess you ought to add a comma after the closing brace.

Yes.

Re: [MI tracepoints 9/9] documentation

[Vladimir Prus]

On Thursday 25 March 2010 07:05:57 Eli Zaretskii wrote:

> > From: Tom Tromey <tromey@redhat.com>
> > Cc: gdb-patches@sources.redhat.com
> > Date: Wed, 24 Mar 2010 15:43:42 -0600
> > 
> > >>>>> "Volodya" == Vladimir Prus <vladimir@codesourcery.com> writes:
> > 
> > Volodya> Sorry -- I think I did what I was asked to do, and I don't
> > Volodya> understand what this warning is trying to tell me. Assuming
> > Volodya> this is a valid warning, how do I fix it?
> > 
> > According to the texinfo manual:
> > 
> >      Caution: A period or comma *must* follow the closing brace of an
> >      `@xref'.  It is required to terminate the cross reference.  This
> >      period or comma will appear in the output, both in the Info file
> >      and in the printed manual.
> > 
> > So I guess you ought to add a comma after the closing brace.
> 
> Yes.

So, 

	@xref{GDB/MI Frame Information} for description of this field.

will become

	@xref{GDB/MI Frame Information}. for description of this field.

? I am not sure the result will be correct. What am I missing and how
do I express my original intent using texinfo?

Thanks,

-- 
Vladimir Prus
CodeSourcery
vladimir@codesourcery.com
(650) 331-3385 x722

Re: [MI tracepoints 9/9] documentation

[Vladimir Prus]

On Thursday 25 March 2010 20:30:35 Vladimir Prus wrote:

> On Thursday 25 March 2010 07:05:57 Eli Zaretskii wrote:
> 
> > > From: Tom Tromey <tromey@redhat.com>
> > > Cc: gdb-patches@sources.redhat.com
> > > Date: Wed, 24 Mar 2010 15:43:42 -0600
> > > 
> > > >>>>> "Volodya" == Vladimir Prus <vladimir@codesourcery.com> writes:
> > > 
> > > Volodya> Sorry -- I think I did what I was asked to do, and I don't
> > > Volodya> understand what this warning is trying to tell me. Assuming
> > > Volodya> this is a valid warning, how do I fix it?
> > > 
> > > According to the texinfo manual:
> > > 
> > >      Caution: A period or comma *must* follow the closing brace of an
> > >      `@xref'.  It is required to terminate the cross reference.  This
> > >      period or comma will appear in the output, both in the Info file
> > >      and in the printed manual.
> > > 
> > > So I guess you ought to add a comma after the closing brace.
> > 
> > Yes.
> 
> So, 
> 
> 	@xref{GDB/MI Frame Information} for description of this field.
> 
> will become
> 
> 	@xref{GDB/MI Frame Information}. for description of this field.
> 
> ? I am not sure the result will be correct. What am I missing and how
> do I express my original intent using texinfo?

Oh, I've confused comma and period. Is comma actually required per english
gramamar, or this is texinfo quirk?

Thanks,

-- 
Vladimir Prus
CodeSourcery
vladimir@codesourcery.com
(650) 331-3385 x722

Re: [MI tracepoints 9/9] documentation

[Stan Shebs]

Vladimir Prus wrote:
> On Thursday 25 March 2010 20:30:35 Vladimir Prus wrote:
>
>   
>> On Thursday 25 March 2010 07:05:57 Eli Zaretskii wrote:
>>
>>     
>>>> From: Tom Tromey <tromey@redhat.com>
>>>> Cc: gdb-patches@sources.redhat.com
>>>> Date: Wed, 24 Mar 2010 15:43:42 -0600
>>>>
>>>>         
>>>>>>>>> "Volodya" == Vladimir Prus <vladimir@codesourcery.com> writes:
>>>>>>>>>                   
>>>> Volodya> Sorry -- I think I did what I was asked to do, and I don't
>>>> Volodya> understand what this warning is trying to tell me. Assuming
>>>> Volodya> this is a valid warning, how do I fix it?
>>>>
>>>> According to the texinfo manual:
>>>>
>>>>      Caution: A period or comma *must* follow the closing brace of an
>>>>      `@xref'.  It is required to terminate the cross reference.  This
>>>>      period or comma will appear in the output, both in the Info file
>>>>      and in the printed manual.
>>>>
>>>> So I guess you ought to add a comma after the closing brace.
>>>>         
>>> Yes.
>>>       
>> So, 
>>
>> 	@xref{GDB/MI Frame Information} for description of this field.
>>
>> will become
>>
>> 	@xref{GDB/MI Frame Information}. for description of this field.
>>
>> ? I am not sure the result will be correct. What am I missing and how
>> do I express my original intent using texinfo?
>>     
>
> Oh, I've confused comma and period. Is comma actually required per english
> gramamar, or this is texinfo quirk?
>   
It's a little of both actually. :-) The comma is acceptable English 
usage in this context, but if the sentence and/or cross-reference are 
short, I think it reads poorly, sounding like a hesitation where no 
speaker would actually slow down.  But if the reference and sentence are 
both long, then you get a run-on sentence, and worse, possible ambiguity 
due to the juxtaposition of long cross-reference phrase and the 
remaining words of the sentence.  So the texinfo rule sacrifices some 
readability for reliability.

Stan

Re: [MI tracepoints 9/9] documentation

[Eli Zaretskii]

> Date: Thu, 25 Mar 2010 11:12:09 -0700
> From: Stan Shebs <stan@codesourcery.com>
> CC: Eli Zaretskii <eliz@gnu.org>, tromey@redhat.com, 
>  gdb-patches@sources.redhat.com
> 
> > Is comma actually required per english gramamar, or this is
> > texinfo quirk?
> >   
> It's a little of both actually. :-)

Right.  But mostly, it's a Texinfo quirk.

Re: [MI tracepoints 9/9] documentation

[Vladimir Prus]

[-- Attachment #1: Type: Text/Plain, Size: 564 bytes --]

On Thursday 25 March 2010 22:33:24 Eli Zaretskii wrote:

> > Date: Thu, 25 Mar 2010 11:12:09 -0700
> > From: Stan Shebs <stan@codesourcery.com>
> > CC: Eli Zaretskii <eliz@gnu.org>, tromey@redhat.com, 
> >  gdb-patches@sources.redhat.com
> > 
> > > Is comma actually required per english gramamar, or this is
> > > texinfo quirk?
> > >   
> > It's a little of both actually. :-)
> 
> Right.  But mostly, it's a Texinfo quirk.

Thanks for clarifying. I've checked in the below.

Thanks,

-- 
Vladimir Prus
CodeSourcery
vladimir@codesourcery.com
(650) 331-3385 x722

[-- Attachment #2: comma.diff --]
[-- Type: text/x-patch, Size: 1228 bytes --]

? .kdev4
Index: gdb/doc/ChangeLog
===================================================================
RCS file: /cvs/src/src/gdb/doc/ChangeLog,v
retrieving revision 1.1026
diff -u -p -r1.1026 ChangeLog
--- gdb/doc/ChangeLog	26 Mar 2010 01:46:28 -0000	1.1026
+++ gdb/doc/ChangeLog	26 Mar 2010 08:05:16 -0000
@@ -1,3 +1,7 @@
+2010-03-26  Vladimir Prus  <vladimir@codesourcery.com>
+
+	* gdb.texinfo (GDB/MI Tracepoint Commands): Add comma after @xref.
+
 2010-03-24  Stan Shebs  <stan@codesourcery.com>
 
 	* gdb.texinfo (Tracepoint Packets): Document trace error status.
Index: gdb/doc/gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.684
diff -u -p -r1.684 gdb.texinfo
--- gdb/doc/gdb.texinfo	26 Mar 2010 01:46:28 -0000	1.684
+++ gdb/doc/gdb.texinfo	26 Mar 2010 08:05:18 -0000
@@ -26050,7 +26050,7 @@ the @samp{found} field has value of @sam
 @item frame
 The information about the frame corresponding to the found trace
 frame.  This field is present only if a trace frame was found.
-@xref{GDB/MI Frame Information} for description of this field.
+@xref{GDB/MI Frame Information}, for description of this field.
 
 @end table
 

Re: [MI tracepoints 9/9] documentation

[Eli Zaretskii]

> From: Vladimir Prus <vladimir@codesourcery.com>
> Date: Fri, 26 Mar 2010 11:08:45 +0300
> Cc: Stan Shebs <stan@codesourcery.com>,
>  tromey@redhat.com,
>  gdb-patches@sources.redhat.com
> 
> On Thursday 25 March 2010 22:33:24 Eli Zaretskii wrote:
> 
> > > Date: Thu, 25 Mar 2010 11:12:09 -0700
> > > From: Stan Shebs <stan@codesourcery.com>
> > > CC: Eli Zaretskii <eliz@gnu.org>, tromey@redhat.com, 
> > >  gdb-patches@sources.redhat.com
> > > 
> > > > Is comma actually required per english gramamar, or this is
> > > > texinfo quirk?
> > > >   
> > > It's a little of both actually. :-)
> > 
> > Right.  But mostly, it's a Texinfo quirk.
> 
> Thanks for clarifying. I've checked in the below.

Thank you.

Just to explain a bit further, the reason for this Texinfo requirement
is that otherwise the Info browser will be unable to find the end of
hyperlinks produced from an @xref with more than one argument.  Info
file is mostly an ASCII file, so it sometimes needs to use punctuation
for this purpose.

For example, this Texinfo source:

  @xref{Define, dont-repeat}

produces this in Info:

  *Note dont-repeat: Define

It should be clear now that without some special, known in advance,
character after "Define", an Info browser would not know where the
hyperlink ends.  "Define" is the name of a node that this hyperlink
references, so the Info browser _must_ deduce it reliably.  Info uses
a comma or a period for this purpose because these leave the sentence
grammatically correct.  That is why `makeinfo' bitches at you when you
don't put a period or a comma after the right brace of an @xref.