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.

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