From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 9397 invoked by alias); 16 Mar 2010 13:56:19 -0000 Received: (qmail 9377 invoked by uid 22791); 16 Mar 2010 13:56:17 -0000 X-SWARE-Spam-Status: No, hits=-2.4 required=5.0 tests=AWL,BAYES_00 X-Spam-Check-By: sourceware.org Received: from mail.codesourcery.com (HELO mail.codesourcery.com) (38.113.113.100) by sourceware.org (qpsmtpd/0.43rc1) with ESMTP; Tue, 16 Mar 2010 13:56:11 +0000 Received: (qmail 31598 invoked from network); 16 Mar 2010 13:56:09 -0000 Received: from unknown (HELO wind.localnet) (vladimir@127.0.0.2) by mail.codesourcery.com with ESMTPA; 16 Mar 2010 13:56:09 -0000 From: Vladimir Prus To: Eli Zaretskii Subject: Re: [MI tracepoints 9/9] documentation Date: Tue, 16 Mar 2010 13:56:00 -0000 User-Agent: KMail/1.12.2 (Linux/2.6.31-20-generic-pae; KDE/4.3.2; i686; ; ) Cc: gdb-patches@sourceware.org References: <201003141204.12015.vladimir@codesourcery.com> <83k4te221u.fsf@gnu.org> In-Reply-To: <83k4te221u.fsf@gnu.org> MIME-Version: 1.0 Content-Type: Multipart/Mixed; boundary="Boundary-00=_334nLEJwHtuNRVA" Message-Id: <201003161656.07287.vladimir@codesourcery.com> Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sourceware.org X-SW-Source: 2010-03/txt/msg00581.txt.bz2 --Boundary-00=_334nLEJwHtuNRVA Content-Type: Text/Plain; charset="us-ascii" Content-Transfer-Encoding: 7bit Content-length: 2213 On Sunday 14 March 2010 21:25:33 Eli Zaretskii wrote: > > From: Vladimir Prus > > 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 --Boundary-00=_334nLEJwHtuNRVA Content-Type: text/x-patch; charset="UTF-8"; name="9-docs-2.diff" Content-Transfer-Encoding: 7bit Content-Disposition: attachment; filename="9-docs-2.diff" Content-length: 9081 commit 0fffda0d89eba7f94be14505ae0739354dee4e90 Author: vladimir 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 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% --Boundary-00=_334nLEJwHtuNRVA Content-Type: text/x-patch; charset="UTF-8"; name="9-delta.diff" Content-Transfer-Encoding: 7bit Content-Disposition: attachment; filename="9-delta.diff" Content-length: 7373 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 --Boundary-00=_334nLEJwHtuNRVA--