* GDB/MI:: @value{GDBN}'s Machine Interface.
* Annotations:: @value{GDBN}'s annotation interface.
* JIT Interface:: Using the JIT debugging interface.
+* In-Process Agent:: In-Process Agent
* GDB Bugs:: Reporting bugs in @value{GDBN}
@end smallexample
@item
-Reads command files specified by the @samp{-x} option. @xref{Command
-Files}, for more details about @value{GDBN} command files.
+Executes commands and command files specified by the @samp{-ex} and
+@samp{-x} options in their specified order. @xref{Command Files}, for
+more details about @value{GDBN} command files.
@item
Reads the command history recorded in the @dfn{history file}.
@end table
@noindent
-If a breakpoint is conditional, @code{info break} shows the condition on
-the line following the affected breakpoint; breakpoint commands, if any,
-are listed after that. A pending breakpoint is allowed to have a condition
-specified for it. The condition is not parsed for validity until a shared
-library is loaded that allows the pending breakpoint to resolve to a
-valid location.
+If a breakpoint is conditional, there are two evaluation modes: ``host'' and
+``target''. If mode is ``host'', breakpoint condition evaluation is done by
+@value{GDBN} on the host's side. If it is ``target'', then the condition
+is evaluated by the target. The @code{info break} command shows
+the condition on the line following the affected breakpoint, together with
+its condition evaluation mode in between parentheses.
+
+Breakpoint commands, if any, are listed after that. A pending breakpoint is
+allowed to have a condition specified for it. The condition is not parsed for
+validity until a shared library is loaded that allows the pending
+breakpoint to resolve to a valid location.
@noindent
@code{info break} with a breakpoint
hits, look at the breakpoint info to see how many times the breakpoint
was hit, and then run again, ignoring one less than that number. This
will get you quickly to the last hit of that breakpoint.
+
+@noindent
+For a breakpoints with an enable count (xref) greater than 1,
+@code{info break} also displays that count.
+
@end table
@value{GDBN} allows you to set any number of breakpoints at the same place in
@code{breakpoint always-inserted} mode is off.
@end table
+@value{GDBN} handles conditional breakpoints by evaluating these conditions
+when a breakpoint breaks. If the condition is true, then the process being
+debugged stops, otherwise the process is resumed.
+
+If the target supports evaluating conditions on its end, @value{GDBN} may
+download the breakpoint, together with its conditions, to it.
+
+This feature can be controlled via the following commands:
+
+@kindex set breakpoint condition-evaluation
+@kindex show breakpoint condition-evaluation
+@table @code
+@item set breakpoint condition-evaluation host
+This option commands @value{GDBN} to evaluate the breakpoint
+conditions on the host's side. Unconditional breakpoints are sent to
+the target which in turn receives the triggers and reports them back to GDB
+for condition evaluation. This is the standard evaluation mode.
+
+@item set breakpoint condition-evaluation target
+This option commands @value{GDBN} to download breakpoint conditions
+to the target at the moment of their insertion. The target
+is responsible for evaluating the conditional expression and reporting
+breakpoint stop events back to @value{GDBN} whenever the condition
+is true. Due to limitations of target-side evaluation, some conditions
+cannot be evaluated there, e.g., conditions that depend on local data
+that is only known to the host. Examples include
+conditional expressions involving convenience variables, complex types
+that cannot be handled by the agent expression parser and expressions
+that are too long to be sent over to the target, specially when the
+target is a remote system. In these cases, the conditions will be
+evaluated by @value{GDBN}.
+
+@item set breakpoint condition-evaluation auto
+This is the default mode. If the target supports evaluating breakpoint
+conditions on its end, @value{GDBN} will download breakpoint conditions to
+the target (limitations mentioned previously apply). If the target does
+not support breakpoint condition evaluation, then @value{GDBN} will fallback
+to evaluating all these conditions on the host's side.
+@end table
+
+
@cindex negative breakpoint numbers
@cindex internal @value{GDBN} breakpoints
@value{GDBN} itself sometimes sets breakpoints in your program for
A call to @code{vfork}. This is currently only available for HP-UX
and @sc{gnu}/Linux.
+@item load @r{[}regexp@r{]}
+@itemx unload @r{[}regexp@r{]}
+The loading or unloading of a shared library. If @var{regexp} is
+given, then the catchpoint will stop only if the regular expression
+matches one of the affected libraries.
+
@end table
@item tcatch @var{event}
Disabling and enabling a breakpoint that has multiple locations
affects all of its locations.
-A breakpoint, watchpoint, or catchpoint can have any of four different
-states of enablement:
+A breakpoint, watchpoint, or catchpoint can have any of several
+different states of enablement:
@itemize @bullet
@item
Enabled once. The breakpoint stops your program, but then becomes
disabled.
@item
+Enabled for a count. The breakpoint stops your program for the next
+N times, then becomes disabled.
+@item
Enabled for deletion. The breakpoint stops your program, but
immediately after it does so it is deleted permanently. A breakpoint
set with the @code{tbreak} command starts out in this state.
Enable the specified breakpoints temporarily. @value{GDBN} disables any
of these breakpoints immediately after stopping your program.
+@item enable @r{[}breakpoints@r{]} count @var{count} @var{range}@dots{}
+Enable the specified breakpoints temporarily. @value{GDBN} records
+@var{count} with each of the specified breakpoints, and decrements a
+breakpoint's count when it is hit. When any count reaches 0,
+@value{GDBN} disables that breakpoint. If a breakpoint has an ignore
+count (@pxref{Conditions, ,Break Conditions}), that will be
+decremented to 0 before @var{count} is affected.
+
@item enable @r{[}breakpoints@r{]} delete @var{range}@dots{}
Enable the specified breakpoints to work once, then die. @value{GDBN}
deletes any of these breakpoints as soon as your program stops there.
purpose of performing side effects when a breakpoint is reached
(@pxref{Break Commands, ,Breakpoint Command Lists}).
+Breakpoint conditions can also be evaluated on the target's side if
+the target supports it. Instead of evaluating the conditions locally,
+@value{GDBN} encodes the expression into an agent expression
+(@pxref{Agent Expressions}) suitable for execution on the target,
+independently of @value{GDBN}. Global variables become raw memory
+locations, locals become stack accesses, and so forth.
+
+In this case, @value{GDBN} will only be notified of a breakpoint trigger
+when its condition evaluates to true. This mechanism may provide faster
+response times depending on the performance characteristics of the target
+since it does not need to keep @value{GDBN} informed about
+every breakpoint trigger, even those with false conditions.
+
Break conditions can be specified when a breakpoint is set, by using
@samp{if} in the arguments to the @code{break} command. @xref{Set
Breaks, ,Setting Breakpoints}. They can also be changed at any time
@end table
Sometimes you may wish that @value{GDBN} stops and gives you control
-when any of shared library events happen. Use the @code{set
-stop-on-solib-events} command for this:
+when any of shared library events happen. The best way to do this is
+to use @code{catch load} and @code{catch unload} (@pxref{Set
+Catchpoints}).
+
+@value{GDBN} also supports the the @code{set stop-on-solib-events}
+command for this. This command exists for historical reasons. It is
+less useful than setting a catchpoint, because it does not allow for
+conditions or commands as a catchpoint does.
@table @code
@item set stop-on-solib-events
@item @code{disable-randomization}
@tab @code{QDisableRandomization}
@tab @code{set disable-randomization}
+
+@item @code{conditional-breakpoints-packet}
+@tab @code{Z0 and Z1}
+@tab @code{Support for target-side breakpoint condition evaluation}
@end multitable
@node Remote Stub
@cindex MIPS boards
@value{GDBN} can use the MIPS remote debugging protocol to talk to a
MIPS board attached to a serial line. This is available when
-you configure @value{GDBN} with @samp{--target=mips-idt-ecoff}.
+you configure @value{GDBN} with @samp{--target=mips-elf}.
@need 1000
Use these @value{GDBN} commands to specify the connection to your target board:
retransmit-timeout @var{seconds}} command. The default is 3 seconds.
You can inspect both values with @code{show timeout} and @code{show
retransmit-timeout}. (These commands are @emph{only} available when
-@value{GDBN} is configured for @samp{--target=mips-idt-ecoff}.)
+@value{GDBN} is configured for @samp{--target=mips-elf}.)
The timeout set by @code{set timeout} does not apply when @value{GDBN}
is waiting for your program to stop. In that case, @value{GDBN} waits
@kindex help user-defined
@item help user-defined
-List all user-defined commands, with the first line of the documentation
-(if any) for each.
+List all user-defined commands and all python commands defined in class
+COMAND_USER. The first line of the documentation or docstring is
+included (if any).
@kindex show user
@item show user
Display the @value{GDBN} commands used to define @var{commandname} (but
not its documentation). If no @var{commandname} is given, display the
definitions for all user-defined commands.
+This does not work for user-defined python commands.
@cindex infinite recursion in user-defined commands
@kindex show max-user-call-depth
The value of @code{max-user-call-depth} controls how many recursion
levels are allowed in user-defined commands before @value{GDBN} suspects an
infinite recursion and aborts the command.
+This does not apply to user-defined python commands.
@end table
In addition to the above commands, user-defined commands frequently
>class HelloWorld (gdb.Command):
> """Greet the whole world."""
> def __init__ (self):
-> super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_OBSCURE)
+> super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_USER)
> def invoke (self, args, from_tty):
> argv = gdb.string_to_argv (args)
> if len (argv) != 0:
@kbd{help tracepoints} at the @value{GDBN} prompt to see a list of
commands in this category.
+@findex COMMAND_USER
+@findex gdb.COMMAND_USER
+@item gdb.COMMAND_USER
+The command is a general purpose command for the user, and typically
+does not fit in one of the other categories.
+Type @kbd{help user-defined} at the @value{GDBN} prompt to see
+a list of commands in this category, as well as the list of gdb macros
+(@pxref{Sequences}).
+
@findex COMMAND_OBSCURE
@findex gdb.COMMAND_OBSCURE
@item gdb.COMMAND_OBSCURE
"""Greet the whole world."""
def __init__ (self):
- super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_OBSCURE)
+ super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_USER)
def invoke (self, arg, from_tty):
print "Hello, World!"
detailed technical information on @value{GDBN}'s book-keeping of the
stack.
+A @code{gdb.Block} is iterable. The iterator returns the symbols
+(@pxref{Symbols In Python}) local to the block.
+
The following block-related functions are available in the @code{gdb}
module:
@code{False} if not. A block object can become invalid if the block it
refers to doesn't exist anymore in the inferior. All other
@code{gdb.Block} methods will throw an exception if it is invalid at
-the time the method is called. This method is also made available to
-the Python iterator object that @code{gdb.Block} provides in an iteration
-context and via the Python @code{iter} built-in function.
+the time the method is called. The block's validity is also checked
+during iteration over symbols of the block.
@end defun
@end table
Python}. This attribute is not writable.
@end defvar
+@defvar Symbol.line
+The line number in the source code at which the symbol was defined.
+This is an integer.
+@end defvar
+
@defvar Symbol.name
The name of the symbol as a string. This attribute is not writable.
@end defvar
@code{gdb} module and described later in this chapter.
@end defvar
+@defvar Symbol.needs_frame
+This is @code{True} if evaluating this symbol's value requires a frame
+(@pxref{Frames In Python}) and @code{False} otherwise. Typically,
+local variables will require a frame, but other symbols will not.
+@end defvar
+
@defvar Symbol.is_argument
@code{True} if the symbol is an argument of a function.
@end defvar
All other @code{gdb.Symbol} methods will throw an exception if it is
invalid at the time the method is called.
@end defun
+
+@defun Symbol.value (@r{[}frame@r{]})
+Compute the value of the symbol, as a @code{gdb.Value}. For
+functions, this computes the address of the function, cast to the
+appropriate type. If the symbol requires a frame in order to compute
+its value, then @var{frame} must be given. If @var{frame} is not
+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
directories mentioned in the value of @code{debug-file-directory}.
Finally, if this file does not exist, then @value{GDBN} will look for
-a file named @file{@var{data-directory}/python/auto-load/@var{real-name}}, where
+a file named @file{@var{data-directory}/auto-load/@var{real-name}}, where
@var{data-directory} is @value{GDBN}'s data directory (available via
@code{show data-directory}, @pxref{Data Files}), and @var{real-name}
is the object file's real name, as described above.
A signal was received by the inferior.
@item solib-event
The inferior has stopped due to a library being loaded or unloaded.
-This can only happen when @code{stop-on-solib-events} (@pxref{Files})
-is set.
+This can happen when @code{stop-on-solib-events} (@pxref{Files}) is
+set or when a @code{catch load} or @code{catch unload} catchpoint is
+in use (@pxref{Set Catchpoints}).
@item fork
The inferior has forked. This is reported when @code{catch fork}
(@pxref{Set Catchpoints}) has been used.
frame. Both have a callback (@code{target_read}) to read bytes off the
target's address space.
+@node In-Process Agent
+@chapter In-Process Agent
+@cindex debugging agent
+The traditional debugging model is conceptually low-speed, but works fine,
+because most bugs can be reproduced in debugging-mode execution. However,
+as multi-core or many-core processors are becoming mainstream, and
+multi-threaded programs become more and more popular, there should be more
+and more bugs that only manifest themselves at normal-mode execution, for
+example, thread races, because debugger's interference with the program's
+timing may conceal the bugs. On the other hand, in some applications,
+it is not feasible for the debugger to interrupt the program's execution
+long enough for the developer to learn anything helpful about its behavior.
+If the program's correctness depends on its real-time behavior, delays
+introduced by a debugger might cause the program to fail, even when the
+code itself is correct. It is useful to be able to observe the program's
+behavior without interrupting it.
+
+Therefore, traditional debugging model is too intrusive to reproduce
+some bugs. In order to reduce the interference with the program, we can
+reduce the number of operations performed by debugger. The
+@dfn{In-Process Agent}, a shared library, is running within the same
+process with inferior, and is able to perform some debugging operations
+itself. As a result, debugger is only involved when necessary, and
+performance of debugging can be improved accordingly. Note that
+interference with program can be reduced but can't be removed completely,
+because the in-process agent will still stop or slow down the program.
+
+The in-process agent can interpret and execute Agent Expressions
+(@pxref{Agent Expressions}) during performing debugging operations. The
+agent expressions can be used for different purposes, such as collecting
+data in tracepoints, and condition evaluation in breakpoints.
+
+@anchor{Control Agent}
+You can control whether the in-process agent is used as an aid for
+debugging with the following commands:
+
+@table @code
+@kindex set agent on
+@item set agent on
+Causes the in-process agent to perform some operations on behalf of the
+debugger. Just which operations requested by the user will be done
+by the in-process agent depends on the its capabilities. For example,
+if you request to evaluate breakpoint conditions in the in-process agent,
+and the in-process agent has such capability as well, then breakpoint
+conditions will be evaluated in the in-process agent.
+
+@kindex set agent off
+@item set agent off
+Disables execution of debugging operations by the in-process agent. All
+of the operations will be performed by @value{GDBN}.
+
+@kindex show agent
+@item show agent
+Display the current setting of execution of debugging operations by
+the in-process agent.
+@end table
+
@node GDB Bugs
@chapter Reporting Bugs in @value{GDBN}
@cindex bugs in @value{GDBN}
signal @samp{0}, regardless of whether the target uses some other signal
as an implementation detail.
+The stub must support @samp{vCont} if it reports support for
+multiprocess extensions (@pxref{multiprocess extensions}). Note that in
+this case @samp{vCont} actions can be specified to apply to all threads
+in a process by using the @samp{p@var{pid}.-1} form of the
+@var{thread-id}.
+
Reply:
@xref{Stop Reply Packets}, for the reply specifications.
stub is allowed to delay erase operation until the @samp{vFlashDone}
packet is received.
-The stub must support @samp{vCont} if it reports support for
-multiprocess extensions (@pxref{multiprocess extensions}). Note that in
-this case @samp{vCont} actions can be specified to apply to all threads
-in a process by using the @samp{p@var{pid}.-1} form of the
-@var{thread-id}.
-
Reply:
@table @samp
@item OK
be implemented in an idempotent way.}
@item z0,@var{addr},@var{kind}
-@itemx Z0,@var{addr},@var{kind}
+@itemx Z0,@var{addr},@var{kind}@r{[};@var{cond_list}@dots{}@r{]}
@cindex @samp{z0} packet
@cindex @samp{Z0} packet
Insert (@samp{Z0}) or remove (@samp{z0}) a memory breakpoint at address
the breakpoint in bytes that should be inserted. E.g., the @sc{arm}
and @sc{mips} can insert either a 2 or 4 byte breakpoint. Some
architectures have additional meanings for @var{kind};
+@var{cond_list} is an optional list of conditional expressions in bytecode
+form that should be evaluated on the target's side. These are the
+conditions that should be taken into consideration when deciding if
+the breakpoint trigger should be reported back to @var{GDBN}.
+
+The @var{cond_list} parameter is comprised of a series of expressions,
+concatenated without separators. Each expression has the following form:
+
+@table @samp
+
+@item X @var{len},@var{expr}
+@var{len} is the length of the bytecode expression and @var{expr} is the
+actual conditional expression in bytecode form.
+
+@end table
+
see @ref{Architecture-Specific Protocol Details}.
@emph{Implementation note: It is possible for a target to copy or move
@end table
@item z1,@var{addr},@var{kind}
-@itemx Z1,@var{addr},@var{kind}
+@itemx Z1,@var{addr},@var{kind}@r{[};@var{cond_list}@dots{}@r{]}
@cindex @samp{z1} packet
@cindex @samp{Z1} packet
Insert (@samp{Z1}) or remove (@samp{z1}) a hardware breakpoint at
A hardware breakpoint is implemented using a mechanism that is not
dependant on being able to modify the target's memory. @var{kind}
-has the same meaning as in @samp{Z0} packets.
+and @var{cond_list} have the same meaning as in @samp{Z0} packets.
@emph{Implementation note: A hardware breakpoint is not affected by code
movement.}
@table @samp
+@item QAgent:1
+@item QAgent:0
+Turn on or off the agent as a helper to perform some debugging operations
+delegated from @value{GDBN} (@pxref{Control Agent}).
+
@item QAllow:@var{op}:@var{val}@dots{}
@cindex @samp{QAllow} packet
Specify which operations @value{GDBN} expects to request of the
@tab @samp{-}
@tab No
+@item @samp{ConditionalBreakpoints}
+@tab No
+@tab @samp{-}
+@tab No
+
@item @samp{ConditionalTracepoints}
@tab No
@tab @samp{-}
@tab @samp{-}
@tab No
+@item @samp{QAgent}
+@tab No
+@tab @samp{-}
+@tab No
+
@item @samp{QAllow}
@tab No
@tab @samp{-}
The remote stub understands the @samp{qXfer:osdata:read} packet
((@pxref{qXfer osdata read}).
+@item ConditionalBreakpoints
+The target accepts and implements evaluation of conditional expressions
+defined for breakpoints. The target will only report breakpoint triggers
+when such conditions are true (@pxref{Conditions, ,Break Conditions}).
+
@item ConditionalTracepoints
The remote stub accepts and implements conditional expressions defined
for tracepoints (@pxref{Tracepoint Conditions}).
The remote stub understands the @samp{QTDPsrc} packet that supplies
the source form of tracepoint definitions.
+@item QAgent
+The remote stub understands the @samp{QAgent} packet.
+
@item QAllow
The remote stub understands the @samp{QAllow} packet.
contain registers @samp{f0} through @samp{f31}, @samp{fcsr}, and
@samp{fir}. They may be 32-bit or 64-bit depending on the target.
+The @samp{org.gnu.gdb.mips.dsp} feature is optional. It should
+contain registers @samp{hi1} through @samp{hi3}, @samp{lo1} through
+@samp{lo3}, and @samp{dspctl}. The @samp{dspctl} register should
+be 32-bit and the rest may be 32-bit or 64-bit depending on the target.
+
The @samp{org.gnu.gdb.mips.linux} feature is optional. It should
contain a single register, @samp{restart}, which is used by the
Linux kernel to control restartable syscalls.
projects / deliverable / binutils-gdb.git / blobdiff