diff options
Diffstat (limited to 'gdb/doc/gdb.texinfo')
| -rw-r--r-- | gdb/doc/gdb.texinfo | 96 |
1 files changed, 91 insertions, 5 deletions
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index 53989bb9b37..92a12374913 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 |