This is the mail archive of the gdb-patches@sourceware.org mailing list for the GDB project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

[MI tracepoints 9/9] documentation


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

Thanks,

-- 
Vladimir Prus
CodeSourcery
vladimir@codesourcery.com
(650) 331-3385 x722
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 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]