aboutsummaryrefslogtreecommitdiff
path: root/gdb/doc
diff options
context:
space:
mode:
authorStan Shebs <shebs@codesourcery.com>2010-03-18 21:23:35 +0000
committerStan Shebs <shebs@codesourcery.com>2010-03-18 21:23:35 +0000
commit4daf5ac07eb7f8cd187f7800785b2e5a465fc38a (patch)
treeb58639d3f486f6fff2649cf5a52e20a3d649bc37 /gdb/doc
parent576ee33af3eb7e4db87587ac57d91ea3b585896a (diff)
downloadgdb-4daf5ac07eb7f8cd187f7800785b2e5a465fc38a.zip
gdb-4daf5ac07eb7f8cd187f7800785b2e5a465fc38a.tar.gz
gdb-4daf5ac07eb7f8cd187f7800785b2e5a465fc38a.tar.bz2
2010-03-18 Stan Shebs <stan@codesourcery.com>
Pedro Alves <pedro@codesourcery.com> * target.h (struct target_ops): New method to_set_circular_trace_buffer. (target_set_circular_trace_buffer): New macro. * target.c (update_current_target): Add to_set_circular_trace_buffer, fix to_set_disconnected_tracing default behavior. * remote.c (remote_set_circular_trace_buffer): New function. (init_remote_ops): Add it to vector. * tracepoint.h (struct trace_status): New field traceframes_created, change buffer_size and buffer_free to int. * tracepoint.c (circular_trace_buffer): New global. (start_tracing): Send values of disconnected tracing and circular trace buffer settings. (set_circular_trace_buffer): New function. (parse_trace_state): Handle total space and frames created. (trace_status_command): Display total space and total frames created. (trace_save): Write out new status values. (parse_trace_status): Set traceframe_count, traceframes_created, buffer_free and buffer_size to -1 by default. (_initialize_tracepoint): New setshow for circular-trace-buffer. * NEWS: Mention the circular trace buffer option. * gdb.texinfo (Starting and Stopping Trace Experiments): Describe circular-trace-buffer. (Tracepoint Packets): Describe QTBuffer, and details of the qTStatus reply. * gdb.trace/circ.exp: Test circular-trace-buffer. * gdb.trace/tfile.exp: Update tstatus test.
Diffstat (limited to 'gdb/doc')
-rw-r--r--gdb/doc/ChangeLog7
-rw-r--r--gdb/doc/gdb.texinfo96
2 files changed, 98 insertions, 5 deletions
diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog
index 7a9590e..e85827b 100644
--- a/gdb/doc/ChangeLog
+++ b/gdb/doc/ChangeLog
@@ -1,3 +1,10 @@
+2010-03-16 Stan Shebs <stan@codesourcery.com>
+
+ * gdb.texinfo (Starting and Stopping Trace Experiments): Describe
+ circular-trace-buffer.
+ (Tracepoint Packets): Describe QTBuffer, and details of the
+ qTStatus reply.
+
2010-03-12 Stan Shebs <stan@codesourcery.com>
Nathan Sidwell <nathan@codesourcery.com>
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 53989bb..92a1237 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -9836,6 +9836,37 @@ which to specify that tracepoint. This matching-up process is
necessarily heuristic, and it may result in useless tracepoints being
created; you may simply delete them if they are of no use.
+@cindex circular trace buffer
+If your target agent supports a @dfn{circular trace buffer}, then you
+can run a trace experiment indefinitely without filling the trace
+buffer; when space runs out, the agent deletes already-collected trace
+frames, oldest first, until there is enough room to continue
+collecting. This is especially useful if your tracepoints are being
+hit too often, and your trace gets terminated prematurely because the
+buffer is full. To ask for a circular trace buffer, simply set
+@samp{circular_trace_buffer} to on. You can set this at any time,
+including during tracing; if the agent can do it, it will change
+buffer handling on the fly, otherwise it will not take effect until
+the next run.
+
+@table @code
+@item set circular-trace-buffer on
+@itemx set circular-trace-buffer off
+@kindex set circular-trace-buffer
+Choose whether a tracing run should use a linear or circular buffer
+for trace data. A linear buffer will not lose any trace data, but may
+fill up prematurely, while a circular buffer will discard old trace
+data, but it will have always room for the latest tracepoint hits.
+
+@item show circular-trace-buffer
+@kindex show circular-trace-buffer
+Show the current choice for the trace buffer. Note that this may not
+match the agent's current buffer handling, nor is it guaranteed to
+match the setting that might have been in effect during a past run,
+for instance if you are looking at frames from a trace file.
+
+@end table
+
@node Tracepoint Restrictions
@subsection Tracepoint Restrictions
@@ -30603,6 +30634,7 @@ encoded). @value{GDBN} will continue to supply the values of symbols
@end table
@item qTBuffer
+@item QTBuffer
@item QTDisconnected
@itemx QTDP
@itemx QTDV
@@ -31087,12 +31119,62 @@ continue the tracing run, while 0 tells the target to stop tracing if
@item qTStatus
Ask the stub if there is a trace experiment running right now.
-Replies:
+The reply has the form:
+
+@table @samp
+
+@item T@var{running}@r{[};@var{field}@r{]}@dots{}
+@var{running} is a single digit @code{1} if the trace is presently
+running, or @code{0} if not. It is followed by semicolon-separated
+optional fields that an agent may use to report additional status.
+
+@end table
+
+If the trace is not running, the agent may report any of several
+explanations as one of the optional fields:
+
+@table @samp
+
+@item tnotrun:0
+No trace has been run yet.
+
+@item tstop:0
+The trace was stopped by a user-originated stop command.
+
+@item tfull:0
+The trace stopped because the trace buffer filled up.
+
+@item tdisconnected:0
+The trace stopped because @value{GDBN} disconnected from the target.
+
+@item tpasscount:@var{tpnum}
+The trace stopped because tracepoint @var{tpnum} exceeded its pass count.
+
+@item tunknown:0
+The trace stopped for some other reason.
+
+@end table
+
+Additional optional fields supply statistical information. Although
+not required, they are extremely useful for users monitoring the
+progress of a trace run. If a trace has stopped, and these numbers
+are reported, they must reflect the state of the just-stopped trace.
+
@table @samp
-@item T0
-There is no trace experiment running.
-@item T1
-There is a trace experiment running.
+
+@item tframes:@var{n}
+The number of trace frames in the buffer.
+
+@item tcreated:@var{n}
+The total number of trace frames created during the run. This may
+be larger than the trace frame count, if the buffer is circular.
+
+@item tsize:@var{n}
+The total size of the trace buffer, in bytes.
+
+@item tfree:@var{n}
+The number of bytes still unused in the buffer.
+
@end table
@item qTV:@var{var}
@@ -31147,6 +31229,10 @@ in a packet; it is not an error to return fewer than were asked for.
A reply consisting of just @code{l} indicates that no bytes are
available.
+@item QTBuffer:circular:@var{value}
+This packet directs the target to use a circular trace buffer if
+@var{value} is 1, or a linear buffer if the value is 0.
+
@end table
@node Host I/O Packets