From 4daf5ac07eb7f8cd187f7800785b2e5a465fc38a Mon Sep 17 00:00:00 2001 From: Stan Shebs Date: Thu, 18 Mar 2010 21:23:35 +0000 Subject: 2010-03-18 Stan Shebs Pedro Alves * 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. --- gdb/doc/ChangeLog | 7 ++++ gdb/doc/gdb.texinfo | 96 ++++++++++++++++++++++++++++++++++++++++++++++++++--- 2 files changed, 98 insertions(+), 5 deletions(-) (limited to 'gdb/doc') 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 + + * 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 Nathan Sidwell 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 -- cgit v1.1