This is the mail archive of the
gdb-patches@sourceware.org
mailing list for the GDB project.
Re: [MI tracepoints 9/9] documentation
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
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 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
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