@c readline appendices use @vindex, @findex and @ftable,
@c annotate.texi and gdbmi use @findex.
@syncodeindex vr fn
-@syncodeindex fn fn
@c !!set GDB manual's edition---not the same as GDB version!
@c This is updated by GNU Press.
@table @code
@kindex target record
+@kindex target record-full
+@kindex target record-btrace
@kindex record
+@kindex record full
+@kindex record btrace
@kindex rec
-@item target record
-This command starts the process record and replay target. The process
-record and replay target can only debug a process that is already
-running. Therefore, you need first to start the process with the
-@kbd{run} or @kbd{start} commands, and then start the recording with
-the @kbd{target record} command.
+@kindex rec full
+@kindex rec btrace
+@item record @var{method}
+This command starts the process record and replay target. The
+recording method can be specified as parameter. Without a parameter
+the command uses the @code{full} recording method. The following
+recording methods are available:
-Both @code{record} and @code{rec} are aliases of @code{target record}.
+@table @code
+@item full
+Full record/replay recording using @value{GDBN}'s software record and
+replay implementation. This method allows replaying and reverse
+execution.
+
+@item btrace
+Hardware-supported instruction recording. This method does not allow
+replaying and reverse execution.
+
+This recording method may not be available on all processors.
+@end table
+
+The process record and replay target can only debug a process that is
+already running. Therefore, you need first to start the process with
+the @kbd{run} or @kbd{start} commands, and then start the recording
+with the @kbd{record @var{method}} command.
+
+Both @code{record @var{method}} and @code{rec @var{method}} are
+aliases of @code{target record-@var{method}}.
@cindex displaced stepping, and process record and replay
Displaced stepping (@pxref{Maintenance Commands,, displaced stepping})
@cindex non-stop mode, and process record and replay
@cindex asynchronous execution, and process record and replay
If the inferior is in the non-stop mode (@pxref{Non-Stop Mode}) or in
-the asynchronous execution mode (@pxref{Background Execution}), the
-process record and replay target cannot be started because it doesn't
-support these two modes.
+the asynchronous execution mode (@pxref{Background Execution}), not
+all recording methods are available. The @code{full} recording method
+does not support these two modes.
@kindex record stop
@kindex rec s
Default filename is @file{gdb_record.@var{process_id}}, where
@var{process_id} is the process ID of the inferior.
+This command may not be available for all recording methods.
+
@kindex record restore
@item record restore @var{filename}
Restore the execution log from a file @file{@var{filename}}.
File must have been created with @code{record save}.
-@kindex set record insn-number-max
-@item set record insn-number-max @var{limit}
-Set the limit of instructions to be recorded. Default value is 200000.
+@kindex set record full
+@item set record full insn-number-max @var{limit}
+Set the limit of instructions to be recorded for the @code{full}
+recording method. Default value is 200000.
If @var{limit} is a positive number, then @value{GDBN} will start
deleting instructions from the log once the number of the record
instructions from the execution log. The number of recorded
instructions is unlimited in this case.
-@kindex show record insn-number-max
-@item show record insn-number-max
-Show the limit of instructions to be recorded.
+@kindex show record full
+@item show record full insn-number-max
+Show the limit of instructions to be recorded with the @code{full}
+recording method.
-@kindex set record stop-at-limit
-@item set record stop-at-limit
-Control the behavior when the number of recorded instructions reaches
-the limit. If ON (the default), @value{GDBN} will stop when the limit
-is reached for the first time and ask you whether you want to stop the
-inferior or continue running it and recording the execution log. If
-you decide to continue recording, each new recorded instruction will
-cause the oldest one to be deleted.
+@item set record full stop-at-limit
+Control the behavior of the @code{full} recording method when the
+number of recorded instructions reaches the limit. If ON (the
+default), @value{GDBN} will stop when the limit is reached for the
+first time and ask you whether you want to stop the inferior or
+continue running it and recording the execution log. If you decide
+to continue recording, each new recorded instruction will cause the
+oldest one to be deleted.
If this option is OFF, @value{GDBN} will automatically delete the
oldest record to make room for each new one, without asking.
-@kindex show record stop-at-limit
-@item show record stop-at-limit
+@item show record full stop-at-limit
Show the current setting of @code{stop-at-limit}.
-@kindex set record memory-query
-@item set record memory-query
+@item set record full memory-query
Control the behavior when @value{GDBN} is unable to record memory
-changes caused by an instruction. If ON, @value{GDBN} will query
-whether to stop the inferior in that case.
+changes caused by an instruction for the @code{full} recording method.
+If ON, @value{GDBN} will query whether to stop the inferior in that
+case.
If this option is OFF (the default), @value{GDBN} will automatically
ignore the effect of such instructions on memory. Later, when
instruction as not accessible, and it will not affect the replay
results.
-@kindex show record memory-query
-@item show record memory-query
+@item show record full memory-query
Show the current setting of @code{memory-query}.
@kindex info record
@item info record
-Show various statistics about the state of process record and its
-in-memory execution log buffer, including:
+Show various statistics about the recording depending on the recording
+method:
+
+@table @code
+@item full
+For the @code{full} recording method, it shows the state of process
+record and its in-memory execution log buffer, including:
@itemize @bullet
@item
Maximum number of instructions that may be contained in the execution log.
@end itemize
+@item btrace
+For the @code{btrace} recording method, it shows the number of
+instructions that have been recorded and the number of blocks of
+sequential control-flow that is formed by the recorded instructions.
+@end table
+
@kindex record delete
@kindex rec del
@item record delete
subsequent execution log and begin to record a new execution log starting
from the current address. This means you will abandon the previously
recorded ``future'' and begin recording a new ``future''.
+
+@kindex record instruction-history
+@kindex rec instruction-history
+@item record instruction-history
+Disassembles instructions from the recorded execution log. By
+default, ten instructions are disassembled. This can be changed using
+the @code{set record instruction-history-size} command. Instructions
+are printed in execution order. There are several ways to specify
+what part of the execution log to disassemble:
+
+@table @code
+@item record instruction-history @var{insn}
+Disassembles ten instructions starting from instruction number
+@var{insn}.
+
+@item record instruction-history @var{insn}, +/-@var{n}
+Disassembles @var{n} instructions around instruction number
+@var{insn}. If @var{n} is preceded with @code{+}, disassembles
+@var{n} instructions after instruction number @var{insn}. If
+@var{n} is preceded with @code{-}, disassembles @var{n}
+instructions before instruction number @var{insn}.
+
+@item record instruction-history
+Disassembles ten more instructions after the last disassembly.
+
+@item record instruction-history -
+Disassembles ten more instructions before the last disassembly.
+
+@item record instruction-history @var{begin} @var{end}
+Disassembles instructions beginning with instruction number
+@var{begin} until instruction number @var{end}. The instruction
+number @var{end} is not included.
+@end table
+
+This command may not be available for all recording methods.
+
+@kindex set record
+@item set record instruction-history-size
+Define how many instructions to disassemble in the @code{record
+instruction-history} command. The default value is 10.
+
+@kindex show record
+@item show record instruction-history-size
+Show how many instructions to disassemble in the @code{record
+instruction-history} command.
+
+@kindex record function-call-history
+@kindex rec function-call-history
+@item record function-call-history
+Prints the execution history at function granularity. It prints one
+line for each sequence of instructions that belong to the same
+function giving the name of that function, the source lines
+for this instruction sequence (if the @code{/l} modifier is
+specified), and the instructions numbers that form the sequence (if
+the @code{/i} modifier is specified).
+
+@smallexample
+(@value{GDBP}) @b{list 1, 10}
+1 void foo (void)
+2 @{
+3 @}
+4
+5 void bar (void)
+6 @{
+7 ...
+8 foo ();
+9 ...
+10 @}
+(@value{GDBP}) @b{record function-call-history /l}
+1 foo.c:6-8 bar
+2 foo.c:2-3 foo
+3 foo.c:9-10 bar
+@end smallexample
+
+By default, ten lines are printed. This can be changed using the
+@code{set record function-call-history-size} command. Functions are
+printed in execution order. There are several ways to specify what
+to print:
+
+@table @code
+@item record function-call-history @var{func}
+Prints ten functions starting from function number @var{func}.
+
+@item record function-call-history @var{func}, +/-@var{n}
+Prints @var{n} functions around function number @var{func}. If
+@var{n} is preceded with @code{+}, prints @var{n} functions after
+function number @var{func}. If @var{n} is preceded with @code{-},
+prints @var{n} functions before function number @var{func}.
+
+@item record function-call-history
+Prints ten more functions after the last ten-line print.
+
+@item record function-call-history -
+Prints ten more functions before the last ten-line print.
+
+@item record function-call-history @var{begin} @var{end}
+Prints functions beginning with function number @var{begin} until
+function number @var{end}. The function number @var{end} is not
+included.
+@end table
+
+This command may not be available for all recording methods.
+
+@item set record function-call-history-size
+Define how many lines to print in the
+@code{record function-call-history} command. The default value is 10.
+
+@item show record function-call-history-size
+Show how many lines to print in the
+@code{record function-call-history} command.
@end table
Display the current limit on backtrace levels.
@end table
+You can control how file names are displayed.
+
+@table @code
+@item set filename-display
+@itemx set filename-display relative
+@cindex filename-display
+Display file names relative to the compilation directory. This is the default.
+
+@item set filename-display basename
+Display only basename of a filename.
+
+@item set filename-display absolute
+Display an absolute filename.
+
+@item show filename-display
+Show the current way to display filenames.
+@end table
+
@node Selection
@section Selecting a Frame
End of assembler dump.
@end smallexample
+Addresses cannot be specified as a linespec (@pxref{Specify Location}).
+So, for example, if you want to disassemble function @code{bar}
+in file @file{foo.c}, you must type @samp{disassemble 'foo.c'::bar}
+and not @samp{disassemble foo.c:bar}.
+
Some architectures have more than one commonly-used set of instruction
mnemonics or other syntax.
@end table
+@table @code
+@item set trace-buffer-size @var{n}
+@kindex set trace-buffer-size
+Request that the target use a trace buffer of @var{n} bytes. Not all
+targets will honor the request; they may have a compiled-in size for
+the trace buffer, or some other limitation. Set to a value of
+@code{-1} to let the target use whatever size it likes. This is also
+the default.
+
+@item show trace-buffer-size
+@kindex show trace-buffer-size
+Show the current requested size for the trace buffer. Note that this
+will only match the actual size if the target supports size-setting,
+and was able to handle the requested size. For instance, if the
+target can only change buffer size between runs, this variable will
+not reflect the change until the next run starts. Use @code{tstatus}
+to get a report of the actual buffer size.
+@end table
+
@table @code
@item set trace-user @var{text}
@kindex set trace-user
all uses of @value{GDBN} with the architecture, both native and cross.
@menu
+* AArch64::
* i386::
* Alpha::
* MIPS::
* PowerPC::
@end menu
+@node AArch64
+@subsection AArch64
+@cindex AArch64 support
+
+When @value{GDBN} is debugging the AArch64 architecture, it provides the
+following special commands:
+
+@table @code
+@item set debug aarch64
+@kindex set debug aarch64
+This command determines whether AArch64 architecture-specific debugging
+messages are to be displayed.
+
+@item show debug aarch64
+Show whether AArch64 debugging messages are displayed.
+
+@end table
+
@node i386
@subsection x86 Architecture-specific Issues
@cindex OS ABI
@kindex set osabi
@kindex show osabi
+@cindex Newlib OS ABI and its influence on the longjmp handling
One @value{GDBN} configuration can debug binaries for multiple operating
system targets, either via remote debugging or native emulation.
not have the same identifying marks that the standard C library for your
platform provides.
+When @value{GDBN} is debugging the AArch64 architecture, it provides a
+``Newlib'' OS ABI. This is useful for handling @code{setjmp} and
+@code{longjmp} when debugging binaries that use the @sc{newlib} C library.
+The ``Newlib'' OS ABI can be selected by @code{set osabi Newlib}.
+
@table @code
@item show osabi
Show the OS ABI currently in use.
The following attributes are provided:
-@table @code
@defvar Value.address
If this object is addressable, this read-only attribute holds a
@code{gdb.Value} object representing the address. Otherwise,
fetched when the value is needed, or when the @code{fetch_lazy}
method is invoked.
@end defvar
-@end table
The following methods are provided:
-@table @code
@defun Value.__init__ (@var{val})
Many Python values can be converted directly to a @code{gdb.Value} via
this object initializer. Specifically:
This method does not return a value.
@end defun
-@end table
@node Types In Python
@subsubsection Types In Python
An instance of @code{Type} has the following attributes:
-@table @code
@defvar Type.code
The type code for this type. The type code will be one of the
@code{TYPE_CODE_} constants defined below.
languages have this concept. If this type has no tag name, then
@code{None} is returned.
@end defvar
-@end table
The following methods are provided:
-@table @code
@defun Type.fields ()
For structure and union types, this method returns the fields. Range
types have two fields, the minimum and maximum values. Enum types
If @var{block} is given, then @var{name} is looked up in that scope.
Otherwise, it is searched for globally.
@end defun
-@end table
Each type has a code, which indicates what category this type falls
A @code{gdb.Inferior} object has the following attributes:
-@table @code
@defvar Inferior.num
ID of inferior, as assigned by GDB.
@end defvar
Boolean signaling whether the inferior was created using `attach', or
started by @value{GDBN} itself.
@end defvar
-@end table
A @code{gdb.Inferior} object has the following methods:
-@table @code
@defun Inferior.is_valid ()
Returns @code{True} if the @code{gdb.Inferior} object is valid,
@code{False} if not. A @code{gdb.Inferior} object will become invalid
containing the address where the pattern was found, or @code{None} if
the pattern could not be found.
@end defun
-@end table
@node Events In Python
@subsubsection Events In Python
@code{gdb.events} module which dispatches particular events. A registry
provides methods to register and unregister event handlers:
-@table @code
@defun EventRegistry.connect (object)
Add the given callable @var{object} to the registry. This object will be
called when an event corresponding to this registry occurs.
Remove the given @var{object} from the registry. Once removed, the object
will no longer receive notifications of events.
@end defun
-@end table
Here is an example:
Examples of these events are @code{gdb.BreakpointEvent} and
@code{gdb.ContinueEvent}.
-@table @code
@defvar ThreadEvent.inferior_thread
In non-stop mode this attribute will be set to the specific thread which was
involved in the emitted event. Otherwise, it will be set to @code{None}.
@end defvar
-@end table
Emits @code{gdb.ContinueEvent} which extends @code{gdb.ThreadEvent}.
@item events.exited
Emits @code{events.ExitedEvent} which indicates that the inferior has exited.
@code{events.ExitedEvent} has two attributes:
-@table @code
@defvar ExitedEvent.exit_code
An integer representing the exit code, if available, which the inferior
has returned. (The exit code could be unavailable if, for example,
@defvar ExitedEvent inferior
A reference to the inferior which triggered the @code{exited} event.
@end defvar
-@end table
@item events.stop
Emits @code{gdb.StopEvent} which extends @code{gdb.ThreadEvent}.
This event indicates that the inferior or one of its threads has received as
signal. @code{gdb.SignalEvent} has the following attributes:
-@table @code
@defvar SignalEvent.stop_signal
A string representing the signal received by the inferior. A list of possible
signal values can be obtained by running the command @code{info signals} in
the @value{GDBN} command prompt.
@end defvar
-@end table
Also emits @code{gdb.BreakpointEvent} which extends @code{gdb.StopEvent}.
@code{gdb.BreakpointEvent} event indicates that one or more breakpoints have
been hit, and has the following attributes:
-@table @code
@defvar BreakpointEvent.breakpoints
A sequence containing references to all the breakpoints (type
@code{gdb.Breakpoint}) that were hit.
This function is maintained for backward compatibility and is now deprecated
in favor of the @code{gdb.BreakpointEvent.breakpoints} attribute.
@end defvar
-@end table
@item events.new_objfile
Emits @code{gdb.NewObjFileEvent} which indicates that a new object file has
been loaded by @value{GDBN}. @code{gdb.NewObjFileEvent} has one attribute:
-@table @code
@defvar NewObjFileEvent.new_objfile
A reference to the object file (@code{gdb.Objfile}) which has been loaded.
@xref{Objfiles In Python}, for details of the @code{gdb.Objfile} object.
@end defvar
-@end table
@end table
A @code{gdb.InferiorThread} object has the following attributes:
-@table @code
@defvar InferiorThread.name
The name of the thread. If the user specified a name using
@code{thread name}, then this returns that name. Otherwise, if an
Either the LWPID or TID may be 0, which indicates that the operating system
does not use that identifier.
@end defvar
-@end table
A @code{gdb.InferiorThread} object has the following methods:
-@table @code
@defun InferiorThread.is_valid ()
Returns @code{True} if the @code{gdb.InferiorThread} object is valid,
@code{False} if not. A @code{gdb.InferiorThread} object will become
@defun InferiorThread.is_exited ()
Return a Boolean indicating whether the thread is exited.
@end defun
-@end table
@node Commands In Python
@subsubsection Commands In Python
A @code{gdb.Frame} object has the following methods:
-@table @code
@defun Frame.is_valid ()
Returns true if the @code{gdb.Frame} object is valid, false if not.
A frame object can become invalid if the frame it refers to doesn't
Set this frame to be the selected frame. @xref{Stack, ,Examining the
Stack}.
@end defun
-@end table
@node Blocks In Python
@subsubsection Accessing frame blocks from Python.
A @code{gdb.Block} object has the following methods:
-@table @code
@defun Block.is_valid ()
Returns @code{True} if the @code{gdb.Block} object is valid,
@code{False} if not. A block object can become invalid if the block it
the time the method is called. The block's validity is also checked
during iteration over symbols of the block.
@end defun
-@end table
A @code{gdb.Block} object has the following attributes:
-@table @code
@defvar Block.start
The start address of the block. This attribute is not writable.
@end defvar
@code{True} if the @code{gdb.Block} object is a static block,
@code{False} if not. This attribute is not writable.
@end defvar
-@end table
@node Symbols In Python
@subsubsection Python representation of Symbols.
A @code{gdb.Symbol} object has the following attributes:
-@table @code
@defvar Symbol.type
The type of the symbol or @code{None} if no type is recorded.
This attribute is represented as a @code{gdb.Type} object.
@defvar Symbol.is_variable
@code{True} if the symbol is a variable.
@end defvar
-@end table
A @code{gdb.Symbol} object has the following methods:
-@table @code
@defun Symbol.is_valid ()
Returns @code{True} if the @code{gdb.Symbol} object is valid,
@code{False} if not. A @code{gdb.Symbol} object can become invalid if
given, or if @var{frame} is invalid, then this method will throw an
exception.
@end defun
-@end table
The available domain categories in @code{gdb.Symbol} are represented
as constants in the @code{gdb} module:
A @code{gdb.Symtab_and_line} object has the following attributes:
-@table @code
@defvar Symtab_and_line.symtab
The symbol table object (@code{gdb.Symtab}) for this frame.
This attribute is not writable.
Indicates the current line number for this object. This
attribute is not writable.
@end defvar
-@end table
A @code{gdb.Symtab_and_line} object has the following methods:
-@table @code
@defun Symtab_and_line.is_valid ()
Returns @code{True} if the @code{gdb.Symtab_and_line} object is valid,
@code{False} if not. A @code{gdb.Symtab_and_line} object can become
@code{gdb.Symtab_and_line} methods will throw an exception if it is
invalid at the time the method is called.
@end defun
-@end table
A @code{gdb.Symtab} object has the following attributes:
-@table @code
@defvar Symtab.filename
The symbol table's source filename. This attribute is not writable.
@end defvar
The symbol table's backing object file. @xref{Objfiles In Python}.
This attribute is not writable.
@end defvar
-@end table
A @code{gdb.Symtab} object has the following methods:
-@table @code
@defun Symtab.is_valid ()
Returns @code{True} if the @code{gdb.Symtab} object is valid,
@code{False} if not. A @code{gdb.Symtab} object can become invalid if
Return the static block of the underlying symbol table.
@xref{Blocks In Python}.
@end defun
-@end table
@node Breakpoints In Python
@subsubsection Manipulating breakpoints using Python
Return the name (string value) of the architecture.
@end defun
+@defun Architecture.disassemble (@var{start_pc} @r{[}, @var{end_pc} @r{[}, @var{count}@r{]]})
+Return a list of disassembled instructions starting from the memory
+address @var{start_pc}. The optional arguments @var{end_pc} and
+@var{count} determine the number of instructions in the returned list.
+If both the optional arguments @var{end_pc} and @var{count} are
+specified, then a list of at most @var{count} disassembled instructions
+whose start address falls in the closed memory address interval from
+@var{start_pc} to @var{end_pc} are returned. If @var{end_pc} is not
+specified, but @var{count} is specified, then @var{count} number of
+instructions starting from the address @var{start_pc} are returned. If
+@var{count} is not specified but @var{end_pc} is specified, then all
+instructions whose start address falls in the closed memory address
+interval from @var{start_pc} to @var{end_pc} are returned. If neither
+@var{end_pc} nor @var{count} are specified, then a single instruction at
+@var{start_pc} is returned. For all of these cases, each element of the
+returned list is a Python @code{dict} with the following string keys:
+
+@table @code
+
+@item addr
+The value corresponding to this key is a Python long integer capturing
+the memory address of the instruction.
+
+@item asm
+The value corresponding to this key is a string value which represents
+the instruction with assembly language mnemonics. The assembly
+language flavor used is the same as that specified by the current CLI
+variable @code{disassembly-flavor}. @xref{Machine Code}.
+
+@item length
+The value corresponding to this key is the length (integer value) of the
+instruction in bytes.
+
+@end table
+@end defun
+
@node Python Auto-loading
@subsection Python Auto-loading
@cindex Python auto-loading
@var{tfnum}. The number of the tracepoint associated with this trace
frame is @var{tpnum}.
-@item =tsv-created,name=@var{name},value=@var{value}
+@item =tsv-created,name=@var{name},initial=@var{initial}
Reports that the new trace state variable @var{name} is created with
-value @var{value}.
+initial value @var{initial}.
@item =tsv-deleted,name=@var{name}
@itemx =tsv-deleted
Reports that the trace state variable @var{name} is deleted or all
trace state variables are deleted.
+@item =tsv-modified,name=@var{name},initial=@var{initial}[,current=@var{current}]
+Reports that the trace state variable @var{name} is modified with
+the initial value @var{initial}. The current value @var{current} of
+trace state variable is optional and is reported if the current
+value of trace state variable is known.
+
@item =breakpoint-created,bkpt=@{...@}
@itemx =breakpoint-modified,bkpt=@{...@}
@itemx =breakpoint-deleted,id=@var{number}
tracing will continue after @value{GDBN} disconnects, @code{0} means
that the trace run will stop.
+@item trace-file
+The filename of the trace file being examined. This field is
+optional, and only present when examining a trace file.
+
@end table
@subsubheading @value{GDBN} Command
MS-Windows shared libraries (@pxref{Shared Libraries})
@item
Traceframe info (@pxref{Traceframe Info Format})
+@item
+Branch trace (@pxref{Branch Trace Format})
@end itemize
@item zlib
* Memory Map Format::
* Thread List Format::
* Traceframe Info Format::
+* Branch Trace Format::
@end menu
@node Overview
the register's value
@item E @var{NN}
for an error
-@item
+@item @w{}
Indicating an unrecognized @var{query}.
@end table
@item vCont@r{[};@var{action}@dots{}@r{]}
The @samp{vCont} packet is supported. Each @var{action} is a supported
command in the @samp{vCont} packet.
-@item
+@item @w{}
The @samp{vCont} packet is not supported.
@end table
@table @samp
@item OK
success
-@item
+@item @w{}
not supported
@item E @var{NN}
for an error
@table @samp
@item OK
success
-@item
+@item @w{}
not supported
@item E @var{NN}
for an error
@table @samp
@item OK
success
-@item
+@item @w{}
not supported
@item E @var{NN}
for an error
@table @samp
@item OK
success
-@item
+@item @w{}
not supported
@item E @var{NN}
for an error
@table @samp
@item OK
success
-@item
+@item @w{}
not supported
@item E @var{NN}
for an error
@item E @var{nn}
An error occurred. @var{nn} are hex digits.
-@item
+@item @w{}
An empty reply indicates that @samp{QDisableRandomization} is not supported
by the stub.
@end table
@item E @var{nn}
An error occurred. @var{nn} are hex digits.
-@item
+@item @w{}
An empty reply indicates that @samp{qGetTLSAddr} is not supported by the stub.
@end table
An error occured. This means that either the thread was not found, or the
address could not be retrieved.
-@item
+@item @w{}
An empty reply indicates that @samp{qGetTIBAddr} is not supported by the stub.
@end table
@item E @var{nn}
An error occurred. @var{nn} are hex digits.
-@item
+@item @w{}
An empty reply indicates that @samp{QNonStop} is not supported by
the stub.
@end table
@item E @var{nn}
An error occurred. @var{nn} are hex digits.
-@item
+@item @w{}
An empty reply indicates that @samp{QPassSignals} is not supported by
the stub.
@end table
@item E @var{nn}
An error occurred. @var{nn} are hex digits.
-@item
+@item @w{}
An empty reply indicates that @samp{QProgramSignals} is not supported
by the stub.
@end table
A command response with the hex encoded output string @var{OUTPUT}.
@item E @var{NN}
Indicate a badly formed request.
-@item
+@item @w{}
An empty reply indicates that @samp{qRcmd} is not recognized.
@end table
The pattern was found at @var{address}.
@item E @var{NN}
A badly formed request or an error was encountered while searching memory.
-@item
+@item @w{}
An empty reply indicates that @samp{qSearch:memory} is not recognized.
@end table
@value{GDBN} acknowledges this reponse,
but neither the stub nor @value{GDBN} shall send or expect further
@samp{+}/@samp{-} acknowledgments in the current connection.
-@item
+@item @w{}
An empty reply indicates that the stub does not support no-acknowledgment mode.
@end table
The stub supports or does not support each returned @var{stubfeature},
depending on the form of each @var{stubfeature} (see below for the
possible forms).
-@item
+@item @w{}
An empty reply indicates that @samp{qSupported} is not recognized,
or that no features needed to be reported to @value{GDBN}.
@end table
@tab @samp{-}
@tab Yes
+@item @samp{qXfer:btrace:read}
+@tab No
+@tab @samp{-}
+@tab Yes
+
@item @samp{qXfer:features:read}
@tab No
@tab @samp{-}
@tab @samp{-}
@tab Yes
+@item @samp{Qbtrace:off}
+@tab Yes
+@tab @samp{-}
+@tab Yes
+
+@item @samp{Qbtrace:bts}
+@tab Yes
+@tab @samp{-}
+@tab Yes
+
@item @samp{QNonStop}
@tab No
@tab @samp{-}
@tab @samp{-}
@tab No
+@item @samp{QTBuffer:size}
+@tab No
+@tab @samp{-}
+@tab No
+
@item @samp{tracenz}
@tab No
@tab @samp{-}
The remote stub understands the @samp{qXfer:auxv:read} packet
(@pxref{qXfer auxiliary vector read}).
+@item qXfer:btrace:read
+The remote stub understands the @samp{qXfer:btrace:read}
+packet (@pxref{qXfer btrace read}).
+
@item qXfer:features:read
The remote stub understands the @samp{qXfer:features:read} packet
(@pxref{qXfer target description read}).
@samp{QTDisable} (@pxref{QTDisable}) packets that allow tracepoints
to be enabled and disabled while a trace experiment is running.
+@item QTBuffer:size
+The remote stub supports the @samp{QTBuffer:size} (@pxref{QTBuffer-size})
+packet that allows to change the size of the trace buffer.
+
@item tracenz
@cindex string tracing, in remote protocol
The remote stub supports the @samp{tracenz} bytecode for collecting strings.
The remote stub supports running a breakpoint's command list itself,
rather than reporting the hit to @value{GDBN}.
+@item Qbtrace:off
+The remote stub understands the @samp{Qbtrace:off} packet.
+
+@item Qbtrace:bts
+The remote stub understands the @samp{Qbtrace:bts} packet.
+
@end table
@item qSymbol::
This packet is not probed by default; the remote stub must request it,
by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
+@item qXfer:btrace:read:@var{annex}:@var{offset},@var{length}
+@anchor{qXfer btrace read}
+
+Return a description of the current branch trace.
+@xref{Branch Trace Format}. The annex part of the generic @samp{qXfer}
+packet may have one of the following values:
+
+@table @code
+@item all
+Returns all available branch trace.
+
+@item new
+Returns all available branch trace if the branch trace changed since
+the last read request.
+@end table
+
+This packet is not probed by default; the remote stub must request it
+by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
+
@item qXfer:features:read:@var{annex}:@var{offset},@var{length}
@anchor{qXfer target description read}
Access the @dfn{target description}. @xref{Target Descriptions}. The
The offset was invalid, or there was an error encountered reading the data.
@var{nn} is a hex-encoded @code{errno} value.
-@item
+@item @w{}
An empty reply indicates the @var{object} string was not recognized by
the stub, or that the object does not support reading.
@end table
The offset was invalid, or there was an error encountered writing the data.
@var{nn} is a hex-encoded @code{errno} value.
-@item
+@item @w{}
An empty reply indicates the @var{object} string was not
recognized by the stub, or that the object does not support writing.
@end table
A badly formed request or an error was encountered.
@end table
+@item Qbtrace:bts
+Enable branch tracing for the current thread using bts tracing.
+
+Reply:
+@table @samp
+@item OK
+Branch tracing has been enabled.
+@item E.errtext
+A badly formed request or an error was encountered.
+@end table
+
+@item Qbtrace:off
+Disable branch tracing for the current thread.
+
+Reply:
+@table @samp
+@item OK
+Branch tracing has been disabled.
+@item E.errtext
+A badly formed request or an error was encountered.
+@end table
+
@end table
@node Architecture-Specific Protocol Details
The packet was understood and carried out.
@item qRelocInsn
@xref{Tracepoint Packets,,Relocate instruction reply packet}.
-@item
+@item @w{}
The packet was not recognized.
@end table
The packet was understood and carried out.
@item qRelocInsn
@xref{Tracepoint Packets,,Relocate instruction reply packet}.
-@item
+@item @w{}
The packet was not recognized.
@end table
that a fast tracepoint may be placed on any instruction regardless of size.
@item E
An error has occurred.
-@item
+@item @w{}
An empty reply indicates that the request is not supported by the stub.
@end table
(lower case letter @samp{L}) denotes end of list.
@item E @var{nn}
An error occurred. @var{nn} are hex digits.
-@item
+@item @w{}
An empty reply indicates that the request is not supported by the
stub.
@end table
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.
+@item QTBuffer:size:@var{size}
+@anchor{QTBuffer-size}
+@cindex @samp{QTBuffer size} packet
+This packet directs the target to make the trace buffer be of size
+@var{size} if possible. A value of @code{-1} tells the target to
+use whatever size it prefers.
+
@item QTNotes:@r{[}@var{type}:@var{text}@r{]}@r{[};@var{type}:@var{text}@r{]}@dots{}
@cindex @samp{QTNotes} packet
This packet adds optional textual notes to the trace run. Allowable
documentation for the interpretation of @var{result} and
@var{attachment}.
-@item
+@item @w{}
An empty response indicates that this operation is not recognized.
@end table
length CDATA #REQUIRED>
@end smallexample
+@node Branch Trace Format
+@section Branch Trace Format
+@cindex branch trace format
+
+In order to display the branch trace of an inferior thread,
+@value{GDBN} needs to obtain the list of branches. This list is
+represented as list of sequential code blocks that are connected via
+branches. The code in each block has been executed sequentially.
+
+This list is obtained using the @samp{qXfer:btrace:read}
+(@pxref{qXfer btrace read}) packet and is an XML document.
+
+@value{GDBN} must be linked with the Expat library to support XML
+traceframe info discovery. @xref{Expat}.
+
+The top-level structure of the document is shown below:
+
+@smallexample
+<?xml version="1.0"?>
+<!DOCTYPE btrace
+ PUBLIC "+//IDN gnu.org//DTD GDB Branch Trace V1.0//EN"
+ "http://sourceware.org/gdb/gdb-btrace.dtd">
+<btrace>
+ block...
+</btrace>
+@end smallexample
+
+@itemize
+
+@item
+A block of sequentially executed instructions starting at @var{begin}
+and ending at @var{end}:
+
+@smallexample
+<block begin="@var{begin}" end="@var{end}"/>
+@end smallexample
+
+@end itemize
+
+The formal DTD for the branch trace format is given below:
+
+@smallexample
+<!ELEMENT btrace (block)* >
+<!ATTLIST btrace version CDATA #FIXED "1.0">
+
+<!ELEMENT block EMPTY>
+<!ATTLIST block begin CDATA #REQUIRED
+ end CDATA #REQUIRED>
+@end smallexample
+
@include agentexpr.texi
@node Target Descriptions
registers using the capitalization used in the description.
@menu
+* AArch64 Features::
* ARM Features::
* i386 Features::
* MIPS Features::
@end menu
+@node AArch64 Features
+@subsection AArch64 Features
+@cindex target descriptions, AArch64 features
+
+The @samp{org.gnu.gdb.aarch64.core} feature is required for AArch64
+targets. It should contain registers @samp{x0} through @samp{x30},
+@samp{sp}, @samp{pc}, and @samp{cpsr}.
+
+The @samp{org.gnu.gdb.aarch64.fpu} feature is optional. If present,
+it should contain registers @samp{v0} through @samp{v31}, @samp{fpsr},
+and @samp{fpcr}.
+
@node ARM Features
@subsection ARM Features
@cindex target descriptions, ARM features
projects / deliverable / binutils-gdb.git / blobdiff